A comprehensive Guideline-Rules set for building highly responsive, accessible, and performant web design-system components.
You're building design systems that need to work flawlessly across every device, viewport, and accessibility requirement. But you're spending too much time debugging layout shifts, accessibility violations, and performance bottlenecks instead of shipping features.
Modern responsive development hits you with a perfect storm of complexity:
Each responsive component becomes a multi-day engineering effort instead of a focused development sprint.
These Cursor Rules transform your responsive design system development into a streamlined, automated workflow. You get enterprise-grade responsive patterns, accessibility compliance, and performance optimization built into every component from day one.
The rules establish a complete mobile-first development environment with TypeScript strict mode, automated accessibility testing, and performance budgets that prevent regressions before they reach production.
Component Development Speed: 60-70% faster responsive component creation with pre-configured TypeScript patterns, Tailwind utility mappings, and automated testing setups that eliminate repetitive boilerplate.
Quality Assurance Automation: Zero accessibility violations in production through axe-core integration and automated WCAG 2.2 AA compliance checking on every commit.
Performance Guarantee: Built-in performance budgets ensure <100KB critical resources and <2s LCP on 3G connections without manual optimization effort.
Cross-Device Consistency: Playwright-powered visual regression testing across iPhone SE, Pixel 7, iPad, and desktop viewports catches layout issues before code review.
Instead of manually configuring breakpoints and writing media queries:
// Before: Manual responsive configuration
const Button = ({ size }: { size: string }) => {
return <button className={`btn ${size === 'large' ? 'btn-lg' : 'btn-sm'}`} />
}
// After: Adaptive props with full TypeScript safety
<Button size={{base:'sm', md:'lg'}} variant="primary" />
Your components automatically handle responsive behavior with type-safe adaptive props and mobile-first Tailwind utilities.
Rather than retrofitting accessibility after development:
// Automated accessibility testing runs on every component
<nav aria-label="Primary" className="sr-only md:not-sr-only" />
Every component ships with WCAG 2.2 AA compliance, proper ARIA labels, and 4.5:1 contrast ratios validated automatically.
Skip manual performance audits with built-in optimization patterns:
// Automatic lazy loading and responsive images
<picture>
<source srcSet="hero-mobile.avif" media="(max-width: 768px)" />
<img src="hero-desktop.webp" loading="lazy" />
</picture>
Save the rules as .cursorrules in your project root. The configuration automatically sets up:
npm install -D @axe-core/playwright @playwright/test
npx tailwindcss init -p
The rules guide Cursor to generate proper component file structure:
src/components/
├─ Button/
├─ Button.tsx # Main component
├─ Button.styles.ts # Tailwind variants
├─ Button.helpers.ts # Pure functions
└─ __tests__/ # Test files
When you create new components, Cursor automatically:
Configure your CI pipeline to run the integrated testing:
{
"scripts": {
"test:a11y": "axe --exit",
"test:visual": "playwright test --reporter=html",
"build:perf": "lighthouse-ci"
}
}
Week 1: Component development accelerates 2-3x with automated responsive patterns and TypeScript safety eliminating manual configuration.
Week 2: Zero accessibility violations in code review as axe-core integration catches issues during development instead of post-deployment.
Month 1: Design system reaches 95%+ component test coverage with automated cross-device visual regression testing requiring no manual QA effort.
Quarter 1: Team ships responsive features 40% faster while maintaining consistently high Core Web Vitals scores across all viewport sizes.
Long-term: Design system becomes the productivity multiplier for your entire frontend organization, with new developers productive on responsive development from day one.
Stop treating responsive development like a manual craft. These Cursor Rules transform it into an automated, reliable, and fast development workflow that scales with your team's ambitions.
Your responsive TypeScript design system revolution starts with a single .cursorrules file.
You are an expert in TypeScript, React 18+, Tailwind CSS, CSS Grid/Flexbox, HTML5, Node.js tooling.
Technology Stack Declaration
- Primary: TypeScript + React functional components
- Styling: Tailwind CSS utility classes augmented by CSS Modules for edge-cases
- Tooling: Vite + ESLint + Prettier + Jest + Testing Library + Playwright
- Build: Node.js 18 LTS, ES2022 modules, optional SSR with Next.js 14
- Accessibility tooling: axe-core, Lighthouse, Google Mobile-Friendly Audit API
Key Principles
- Mobile-first: author base styles for 320 px width and layer up via min-width media queries.
- Declarative UI: stateless functional components ≥ 95 % of the codebase.
- Design Tokens: expose spacing, breakpoints, colors as typed TS constants and CSS custom properties.
- Composition over inheritance; prefer small composable hooks/helpers.
- Performance budget: <100 KB total critical CSS/JS for first paint, <2 s LCP on 3G.
- Accessibility is non-negotiable; every component must pass WCAG 2.2 AA.
TypeScript / JavaScript Rules
- Strict mode (`"strict": true`) and isolatedModules on.
- All public props/interfaces exported from `types.ts`; external surfaces never use `any` or `unknown` without narrowing.
- Prefer union literals for adaptive sizing, e.g. `type Screen = 'sm' | 'md' | 'lg' | 'xl'`.
- Component file layout:
├─ MyComponent.tsx – public wrapper (exports)
├─ MyComponent.styles.ts – Tailwind class maps / tw variants
├─ MyComponent.helpers.ts – pure functions (no DOM access)
├─ __tests__/
- Put error/edge-case branches first, then happy path:
```ts
if (!containerRef.current) return null; // early return avoids nested blocks
```
- No `console.log` in production; wrap in `invariant()` util which strips in prod builds.
CSS / Styling Rules
- Use Tailwind breakpoints: `sm(640)`, `md(768)`, `lg(1024)`, `xl(1280)`, `2xl(1536)`; keep custom additions in `tailwind.config.js`.
- Use relative units: `rem` for font/spacing, `%`/`fr` for grids; never fixed `px` except hairlines.
- Grid first: default to CSS Grid for page/layout containers; Flexbox for 1-D alignment.
- Constrain max line-length: `max-w-prose` for text blocks.
- Use `clamp()` for fluid typography: `text-[clamp(1rem,2vw+1rem,1.5rem)]`.
Error Handling & Validation
- Continuous visual regression tests at each breakpoint with Playwright’s screenshot diff.
- Axe-core run on every CI commit; PR fails if ≥ 1 serious violation.
- Responsive regression hook:
```ts
import { useWindowSize } from '@/hooks/useWindowSize';
if (width < 320) throw new UXError('Viewport too small to render safely');
```
- Log device-specific errors to Sentry with `navigator.userAgent` context.
React Framework-Specific Rules
- Functional components only; memoize via `React.memo` + `useCallback`.
- SSR-safe code: guard `window`/`document` access inside `useEffect`.
- Hydration mismatch guard: supply identical classNames server & client.
- State: use `useReducer` for complex UI states; co-locate with component.
- Provide adaptive props:
```tsx
<Button size={{base:'sm', md:'lg'}} variant="primary" />
```
- Always supply accessible name/role; example:
```tsx
<nav aria-label="Primary" className="sr-only md:not-sr-only" />
```
Testing
- Unit: Jest + Testing Library; assert style changes via `toHaveStyle`.
- E2E: Playwright across iPhone SE, Pixel 7, iPad, Desktop 1280-px.
- Performance: Lighthouse CI budget config checked in repository.
Performance Optimization
- Enable `import('./heavy').then()` lazy chunks at ≥ lg breakpoint only.
- Use `next/image` or `<picture>` with `srcset`, `sizes` + AVIF/WEBP.
- Prefer CSS `aspect-ratio` over JS resize listeners.
- Implement IntersectionObserver-based lazy loading for off-screen cards.
Accessibility & UX
- Minimum tap target 48 × 48 CSS px.
- Maintain 4.5:1 contrast ratio; store contrast tests in Storybook docs.
- Motion reduction: respect `prefers-reduced-motion`; gate animations.
Documentation & Design Tokens
- Every component story shows breakpoints with viewport addon.
- Export Figma tokens via `figma-tokens` sync to JSON → Tailwind config.
- Document known limitations & fallbacks (e.g., CSS subgrid not in Safari ≤ 16).
Common Pitfalls & Anti-Patterns
- Avoid device-specific hacks (`@media (device-width: …)`).
- Never hide content with `display:none` just to re-show later; impacts a11y readers.
- Don’t over-nest flex/grid containers; flatten to max 3 levels.