.cursorrules (deprecated)

1# Tailwind CSS Component Development — Cursor Rules
2 
3You are an expert frontend developer building reusable UI components with Tailwind CSS, following utility-first principles and modern component design patterns.
4 
5## Code Style
6 
7- Use utility classes directly in HTML/JSX. Avoid custom CSS except for animations, complex gradients, or truly unique styles.
8- Order utility classes consistently: layout (display, position) -> sizing (width, height) -> spacing (margin, padding) -> typography (font, text) -> colors (bg, text, border) -> effects (shadow, opacity) -> transitions/animations.
9- Use Prettier with `prettier-plugin-tailwindcss` to auto-sort classes.
10- Use full class names. Never use arbitrary values (`w-[137px]`) when a design token exists. Check the spacing/sizing scale first.
11- Use semantic class grouping with line breaks for readability when a component has many classes.
12- Prefer Tailwind's design tokens (spacing scale, color palette, font sizes) over arbitrary values for consistency.
13- Use `@apply` sparingly — only in component CSS files for styles that are genuinely repeated across many elements and can't be abstracted into a component.
14 
15## Component Design
16 
17- Build components as composable primitives: Button, Card, Badge, Input, Modal, Dropdown, Avatar, Alert.
18- Use variant patterns with props/classes: `variant="primary"`, `size="lg"`, `rounded="full"`.
19- Implement compound component patterns for complex UI: `<Card><Card.Header /><Card.Body /><Card.Footer /></Card>`.
20- Design mobile-first: start with mobile styles, add responsive modifiers for larger screens.
21- Every interactive component must have visible focus states for keyboard navigation.
22- Support dark mode with the `dark:` variant. Design both light and dark modes simultaneously.
23 
24## Responsive Design
25 
26- Use mobile-first approach: default styles are mobile, add `sm:`, `md:`, `lg:`, `xl:`, `2xl:` for larger screens.
27- Common breakpoints: `sm:640px`, `md:768px`, `lg:1024px`, `xl:1280px`, `2xl:1536px`.
28- Use `container` with `mx-auto` and responsive padding for page-level content width.
29- Use CSS Grid (`grid`, `grid-cols-*`) for page layouts. Use Flexbox (`flex`) for component layouts.
30- Stack elements vertically on mobile, switch to horizontal on desktop: `flex flex-col md:flex-row`.
31- Hide/show elements with responsive display: `hidden md:block`, `block md:hidden`.
32- Prefer `max-w-*` constraints over fixed widths for content readability.
33- Test all components at every breakpoint. Never assume desktop-only usage.
34 
35## Color System
36 
37- Use Tailwind's color scale: `50` (lightest) through `950` (darkest). Use `500` as the base.
38- Define semantic color aliases in `tailwind.config.js` for brand consistency:
39```js
40  colors: {
41    primary: colors.blue,
42    secondary: colors.slate,
43    success: colors.green,
44    danger: colors.red,
45    warning: colors.amber,
46  }
47```
48- Use opacity modifiers for subtle backgrounds: `bg-primary-500/10`, `bg-black/50`.
49- Ensure color contrast meets WCAG AA standards: 4.5:1 for normal text, 3:1 for large text.
50- Dark mode: use `dark:` prefix. Swap `50-100` backgrounds with `800-900`, `800-900` text with `100-200`.
51- Use `ring-*` utilities for focus indicators. Default to `ring-2 ring-offset-2 ring-primary-500`.
52 
53## Typography
54 
55- Use Tailwind's type scale consistently: `text-xs` through `text-9xl`.
56- Set base font with `font-sans`, `font-serif`, or `font-mono`. Configure custom fonts in `tailwind.config.js`.
57- Use `leading-*` (line-height) and `tracking-*` (letter-spacing) for typography tuning.
58- Prose content: use `@tailwindcss/typography` plugin with `prose` class for rendered markdown/HTML.
59- Truncate long text with `truncate` (single line) or `line-clamp-*` (multi-line).
60- Use responsive font sizes for headings: `text-2xl md:text-3xl lg:text-4xl`.
61 
62## Spacing and Layout
63 
64- Use Tailwind's spacing scale consistently: `0, 0.5, 1, 1.5, 2, 2.5, 3, 3.5, 4, 5, 6, 7, 8, 9, 10, 11, 12, 14, 16, 20, 24, ...`.
65- Use `gap-*` for spacing between flex/grid children instead of margin on individual items.
66- Use `space-x-*` and `space-y-*` for consistent spacing between sibling elements.
67- Use `p-*` for padding, `m-*` for margin. Use directional variants: `px-*`, `py-*`, `pt-*`, `mr-*`.
68- Use negative margins (`-mt-*`) sparingly for overlapping effects.
69- Standardize section spacing: `py-12 md:py-16 lg:py-20` for major page sections.
70- Use `divide-*` utilities for borders between list items instead of manual border classes.
71 
72## Interactive States
73 
74- Always define hover states for clickable elements: `hover:bg-primary-600`.
75- Define focus-visible states for keyboard navigation: `focus-visible:ring-2 focus-visible:ring-primary-500 focus-visible:outline-none`.
76- Use `active:` for pressed states: `active:scale-95` or `active:bg-primary-700`.
77- Use `disabled:` for disabled states: `disabled:opacity-50 disabled:cursor-not-allowed`.
78- Use `transition-*` for smooth state changes: `transition-colors duration-150`, `transition-all duration-200`.
79- Group hover effects with `group` and `group-hover:`: parent has `group`, child has `group-hover:text-primary-500`.
80- Use `peer` and `peer-*` for sibling-based styling (form validation, checkbox-label patterns).
81 
82## Component Patterns
83 
84### Button
85```html
86<button class="inline-flex items-center justify-center gap-2 rounded-lg bg-primary-600 px-4 py-2.5 text-sm font-semibold text-white shadow-sm transition-colors hover:bg-primary-700 focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-primary-500 focus-visible:ring-offset-2 active:bg-primary-800 disabled:opacity-50 disabled:cursor-not-allowed">
87```
88 
89### Card
90```html
91<div class="rounded-xl border border-gray-200 bg-white p-6 shadow-sm dark:border-gray-700 dark:bg-gray-800">
92```
93 
94### Input
95```html
96<input class="block w-full rounded-lg border border-gray-300 bg-white px-3 py-2 text-sm text-gray-900 placeholder:text-gray-400 focus:border-primary-500 focus:outline-none focus:ring-1 focus:ring-primary-500 disabled:bg-gray-50 disabled:text-gray-500 dark:border-gray-600 dark:bg-gray-700 dark:text-white" />
97```
98 
99## Tailwind Configuration
100 
101- Extend the default theme rather than overriding it. Use `theme.extend` in `tailwind.config.js`.
102- Define custom colors, fonts, and spacing in the config for brand consistency.
103- Use the `@tailwindcss/forms` plugin for better form element defaults.
104- Use the `@tailwindcss/typography` plugin for prose content styling.
105- Configure `content` paths to include all files that use Tailwind classes.
106- Use CSS custom properties in `tailwind.config.js` for dynamic theming.
107 
108## Accessibility
109 
110- Use semantic HTML elements: `<button>` for actions, `<a>` for navigation, `<nav>` for navigation groups.
111- Provide visible focus indicators on all interactive elements with `focus-visible:ring-*`.
112- Use `sr-only` class for screen-reader-only text when visual context is sufficient for sighted users.
113- Ensure sufficient color contrast. Use Tailwind's darker shades for text on light backgrounds.
114- Add `aria-label` for icon-only buttons: `<button aria-label="Close menu">`.
115- Use `role` attributes when semantic HTML alone is insufficient.
116- Test with keyboard navigation: Tab, Enter, Escape, Arrow keys must work correctly.
117- Support `prefers-reduced-motion` with `motion-safe:` and `motion-reduce:` variants.
118 
119## Performance
120 
121- Use PurgeCSS (built into Tailwind) to remove unused classes. Ensure `content` config is correct.
122- Avoid dynamically constructing class names with string concatenation — Tailwind can't purge them.
123```
124  BAD:  `bg-${color}-500`
125  GOOD: Use a mapping object: `{ primary: 'bg-blue-500', danger: 'bg-red-500' }`
126```
127- Use `clsx` or `tailwind-merge` for conditional class composition in components.
128- Minimize custom CSS. Every custom style is CSS that Tailwind's purge can't optimize.
129- Use `will-change-*` utilities sparingly and only for elements that actually animate.
130 
131## Animation
132 
133- Use built-in transitions: `transition-colors`, `transition-opacity`, `transition-transform`, `transition-all`.
134- Use built-in animations: `animate-spin`, `animate-ping`, `animate-pulse`, `animate-bounce`.
135- Define custom animations in `tailwind.config.js` under `theme.extend.animation` and `theme.extend.keyframes`.
136- Keep animations subtle and purposeful. Duration should be 150-300ms for most UI transitions.
137- Respect `prefers-reduced-motion`: use `motion-safe:animate-*` to conditionally apply animations.
138