Cursor Rules for Tailwind: Tokens, Layouts, and Accessibility

Cursor rules for Tailwind CSS tell the assistant which tokens to use, how to build responsive layouts, which utility combinations are approved for reuse, and what accessibility checks to run before finishing a UI task. Without them, the assistant picks arbitrary values from Tailwind's full scale and skips the checks that would catch missing keyboard support or low contrast.

fenbs keeps the design decisions that sit behind the rules: which spacing scale the team agreed on, why a particular color was chosen for interactive elements, and what the accessibility standard requires for your audience. The rule encodes the outcome; fenbs records the reasoning.

What Tailwind rules should cover

Tailwind gives assistants thousands of utility classes to choose from. Without a rule, they choose freely: sometimes from your design tokens, sometimes from raw values, sometimes mixing both in the same component. A focused rule reduces that surface to the choices your design system has already made.

• Token usage: which color, spacing, and typography tokens to use and which raw values to avoid.
• Responsive breakpoints: the names and usage order for your breakpoints (sm:, md:, lg:).
• Component patterns: the approved class combinations for common elements (buttons, inputs, cards).
• Dark mode: whether you use the dark: variant and how it relates to your token definitions.
• Accessibility: which checks to run before a UI task is done (aria-label, contrast, focus visibility).

Design token usage

Tailwind v4 defines tokens in a CSS file rather than tailwind.config.js. If your project uses custom tokens for brand colors, spacing, and typography, the rule should name them and tell the assistant to use them instead of the default scale. An assistant that does not know the token names will reach for text-blue-600 when the correct class is text-brand-primary.

The rule can also state which defaults to avoid. If your design system never uses Tailwind's default red palette directly (because you have a color-error token), saying so prevents the assistant from introducing inconsistent usage that looks correct but conflicts with a theme change later.

---
description: Tailwind CSS conventions
globs: "**/*.tsx,**/*.jsx,**/*.html,**/*.css"
alwaysApply: false
---

## Tokens
- Use design tokens defined in `src/app/globals.css` for color, spacing, and typography.
- Prefer `text-brand-primary` over `text-blue-600`; use token names, not raw scale values.
- Do not use arbitrary values (`text-[#abc123]`) unless no token fits and you add a comment.

## Responsive design
- Build mobile-first: base classes first, then `sm:`, `md:`, `lg:` overrides.
- Use `container mx-auto px-4` for page-width content; do not invent custom max widths.

## Component patterns
- Buttons: `btn-primary` and `btn-secondary` utility classes (defined in globals.css).
- Form inputs: use the `input-base` class plus any state modifier.

## Accessibility
- Every interactive element needs a visible focus style; check with keyboard navigation.
- Images need `alt` text; decorative images need `alt=""`.
- Color contrast must meet WCAG AA for text against background tokens.

## Completion check
- Test the component at mobile, tablet, and desktop viewport widths.
- Run a keyboard-only walkthrough for any new interactive element.

Arbitrary values in Tailwind — the text-[#abc123] and w-[347px] syntax — are occasionally necessary for values that fall outside the standard scale. A rule that requires a comment when an arbitrary value is used makes them visible without forbidding them entirely. That visibility lets reviewers decide whether the value should become a token or whether the context genuinely required it.

Responsive layouts mobile-first

Custom utilities defined with @layer utilities in your CSS file bridge the gap between Tailwind's standard scale and project-specific patterns that recur often enough to name. A rule that lists those custom utilities — btn-primary, input-base, card-surface — tells the assistant they exist and prevents it from reconstructing the same combination of classes in-line each time it appears.

Tailwind's default approach is mobile-first: base classes apply to all sizes and breakpoint prefixes add overrides for larger screens. An assistant that ignores this writes desktop-first layouts that are difficult to make responsive after the fact. A rule that states the approach and names the breakpoints keeps every new component consistent.

Phone browsers are the primary target for fenbs and many web products. A layout that breaks on a 375-pixel screen is a bug even if it looks fine on a desktop. The completion check in the rule should include a viewport-width test.

Accessibility checks

Tailwind does not prevent accessibility mistakes. An assistant can build a visually correct button with no type attribute and no keyboard focus style. A rule that lists specific checks, such as visible focus, sufficient contrast, and alt text on images, makes those requirements impossible to miss.

Focus styles deserve specific mention in the rule. Tailwind removes the browser default outline on interactive elements when you apply outline-none or focus:outline-none. If your design system has not provided a replacement, that element is now unreachable for keyboard users. The rule should either name the approved focus style or require that removing a default comes with an explicit replacement in the same class list.

WCAG AA is a reasonable standard for most products and a legal requirement in many US contexts. Stating it in the rule gives the assistant a concrete target for contrast decisions rather than relying on aesthetic judgment. See the Web Content Accessibility Guidelines↗ (opens in a new tab) for the specific criteria.

How to set up Tailwind rules with fenbs

1. Create a free account and add your project.
2. Record approved design decisions in fenbs: color token choices, accessibility standard, any component patterns that were approved after discussion.
3. Place the .cursor/rules/tailwind.mdc file at the project root and adjust the globs and token names to match your CSS file.
4. Connect Cursor via Integrations and ask it to read the project context before starting any UI work.
5. After each UI task, record any new component pattern or token decision in fenbs before ending the session.

For more examples of CSS and UI rules, see cursor rules examples and cursor rules for AI projects. For managing multiple rule files, see cursor rules hierarchy. For comparing Cursor with other code editors, see Cursor vs VS Code.