Why CSS Rules Matter More Than You Think
CSS is where AI assistants cause the most subtle damage. The code 'works' — the page looks right on the developer's screen. But it's built on magic numbers, overly specific selectors, non-responsive layouts, and patterns that break the moment someone adds a new component or views on a different screen size.
The core problem: AI generates CSS by solving the immediate visual problem — making this element look like that. It doesn't consider the design system, the responsive breakpoints, the specificity graph, or how the styles will interact with existing CSS. Every AI-generated style is an island that may conflict with the mainland.
Your CLAUDE.md must specify which styling approach your project uses. The rules for Tailwind, CSS Modules, and vanilla CSS are fundamentally different — and the AI needs to know which one before writing a single line of styling code.
Rule 1: Tailwind CSS Patterns
The rule: 'This project uses Tailwind CSS. All styling uses Tailwind utility classes — never write custom CSS unless the utility doesn't exist. Never use @apply in component files — it defeats the purpose of utility-first. Use the design system's spacing scale (p-4, m-6) — never arbitrary values like p-[13px] unless truly necessary. Use responsive prefixes (sm:, md:, lg:) for responsive design, not media queries.'
For component patterns: 'Group utility classes logically: layout (flex, grid) → spacing (p, m) → sizing (w, h) → typography (text, font) → colors (bg, text, border) → effects (shadow, rounded). Extract repeated class combinations into component-level abstractions (React components, not @apply).'
For dark mode: 'Use Tailwind's dark: variant for all color-related classes. Design for light mode first, add dark: overrides. Use semantic color tokens from your tailwind.config (bg-surface, text-muted) instead of raw colors (bg-gray-100, text-gray-600) to support theming.'
- Utility classes only — no custom CSS, no @apply in components
- Design system spacing — p-4 not p-[13px], use the scale
- Responsive prefixes: sm: md: lg: — not media queries
- Group classes: layout → spacing → sizing → typography → colors → effects
- dark: variant for all colors — semantic tokens over raw colors
The AI must know whether you use Tailwind, CSS Modules, or vanilla CSS before writing any styles. This single declaration changes every styling decision it makes.
Rule 2: CSS Modules Patterns
The rule: 'This project uses CSS Modules. Every component has a co-located .module.css file. Use camelCase for class names: .headerContainer not .header-container. Never use global CSS except in a single global stylesheet for resets and CSS custom properties. Never use !important — fix specificity issues at the source.'
For composition: 'Use composes for sharing styles between modules: composes: baseButton from "./shared.module.css". Use CSS custom properties (--color-primary) for values that change with themes or contexts. Keep selectors flat — no nesting beyond one level.'
For responsive design: 'Define breakpoints as CSS custom properties. Use mobile-first media queries: start with the mobile layout, add complexity with min-width breakpoints. Put all media queries at the end of the module file, not inline with each class.'
Rule 3: Responsive Design
AI assistants generate CSS that looks perfect on a desktop viewport and breaks on everything else. Without explicit responsive rules, the AI doesn't think about mobile, tablet, or different aspect ratios.
The rule: 'Design mobile-first. Start with the narrowest layout, add complexity with wider breakpoints. Use relative units (rem, %, vh/vw) instead of fixed pixels for dimensions that should scale. Use min() and clamp() for fluid typography and spacing. Test at 320px, 768px, 1024px, and 1440px widths — every layout must work at all four.'
For layout: 'Use CSS Grid for 2D layouts (page structure, card grids). Use Flexbox for 1D layouts (navigation bars, card interiors). Never use float for layout. Use gap instead of margin for spacing between grid/flex children. Use container queries where supported for component-level responsiveness.'
AI generates desktop-only CSS by default. Rule: 'Test at 320px, 768px, 1024px, 1440px.' Mobile-first with min-width breakpoints ensures layouts work everywhere.
Rule 4: Design System Compliance
The rule: 'All styling must use the design system's tokens. Use spacing tokens (--space-1 through --space-12) for all margins and padding. Use color tokens (--color-primary, --color-surface, --color-muted) for all colors. Use typography tokens (--font-size-sm, --font-weight-medium) for all text styles. Never use raw hex colors, pixel values, or font sizes that aren't in the design system.'
For new components: 'Before creating new styles, check if an existing component or pattern covers the need. If a new pattern is genuinely needed, propose it as a design system addition — don't create a one-off style that diverges from the system.'
Design system compliance is where AI rules provide the most leverage for visual consistency. Without this rule, the AI generates a unique color palette for every component.
Rule 5: CSS Anti-Patterns to Prevent
The rule: 'Never use !important — it's a symptom of a specificity problem, not a solution. Never use inline styles in JSX/HTML unless dynamically computed (e.g., transform values). Never use z-index without a defined z-index scale. Never set height on elements that contain text — let content determine height. Never use position: absolute for layout — use Grid or Flexbox.'
For specificity: 'Keep specificity flat. One class per selector is ideal. Avoid nesting selectors beyond one level. Never use ID selectors for styling. If you need to override a style, increase specificity by adding a more specific parent class — never use !important.'
For animations: 'Use transform and opacity for animations — they're GPU-accelerated. Never animate layout properties (width, height, top, left) — they cause reflow. Use prefers-reduced-motion to respect user accessibility preferences. Keep animations under 300ms for UI interactions.'
- Never !important — fix specificity at the source
- Never inline styles unless dynamically computed
- z-index scale: define layers (0, 10, 20, 30, 40, 50) — no arbitrary values
- No height on text containers — content determines height
- Animate transform/opacity only — never width/height/top/left
- prefers-reduced-motion respect — accessibility is not optional
Animating width, height, top, or left causes reflow — the browser recalculates layout every frame. Use transform and opacity only — they're GPU-accelerated and silky smooth.
Complete CSS Rules Template
Pick the section that matches your styling approach. Every project should also include the responsive and anti-pattern rules.
- Declare approach: Tailwind / CSS Modules / vanilla CSS — AI must know which
- Tailwind: utilities only, no @apply, design system spacing, responsive prefixes
- CSS Modules: camelCase classes, flat selectors, composes for sharing
- Mobile-first responsive: relative units, clamp(), test at 4 breakpoints
- Design system tokens for all colors, spacing, typography — no raw values
- No !important, no inline styles, no float layout, no arbitrary z-index
- GPU animations only (transform, opacity) — prefers-reduced-motion
- Stylelint in CI — enforce token usage and specificity limits