Comprehensive rules for defining, implementing, and validating color palettes in modern CSS/SCSS and CSS-in-JS design systems with strong accessibility guarantees.
Your design system's color chaos ends here. These Cursor Rules transform fragmented, accessibility-nightmare color implementations into bulletproof, WCAG-compliant design token systems that scale across your entire product ecosystem.
You've seen it: designers manually copying hex values into component files, different contrast ratios across similar UI patterns, and that moment when your "accessible" blue-on-blue combination fails WCAG audits right before launch. Your team burns hours debugging visual inconsistencies that stem from one fundamental problem: no systematic approach to color implementation.
Every manual color decision creates technical debt. Every hardcoded hex value becomes a maintenance burden. Every accessibility violation discovered late in development costs exponentially more to fix.
These advanced Cursor Rules establish a complete color system methodology that:
The system treats color as infrastructure, not decoration—every color decision maps to a semantic token with guaranteed accessibility properties.
/* Scattered across 47 component files */
.button-primary { background: #0066ff; }
.link-active { color: #0070f3; }
.status-info { background: #1976d2; }
/* Different blues, no contrast validation, zero consistency */
// Single source of truth
:root {
--color-primary-500: oklch(0.6 0.2 250);
--color-primary-600: color-mix(in oklch, var(--color-primary-500) 92%, black);
--surface-interactive: var(--color-primary-500);
--text-on-interactive: var(--color-neutral-50);
}
.button-primary {
background: var(--surface-interactive);
color: var(--text-on-interactive);
/* Guaranteed 4.5:1 contrast ratio */
}
Time Savings: Reduce color-related debugging by 80% and eliminate manual contrast checking entirely.
Automated SCSS functions and CI validation catch accessibility violations before they reach production:
@function ensure-contrast($foreground, $background, $ratio: 4.5) {
@if contrast($foreground, $background) < $ratio {
@error "Contrast ratio #{contrast($foreground, $background)} fails WCAG AA";
}
@return $foreground;
}
CSS custom properties enable real-time theme changes without JavaScript repaints:
[data-theme="dark"] {
--surface-base: var(--color-neutral-900);
--text-base: var(--color-neutral-100);
}
Single token file exports to Tailwind, Styled-Components, and vanilla CSS:
// Build pipeline generates all formats
const tokens = require('./tokens/colors.json');
export const tailwindColors = transformForTailwind(tokens);
export const scTheme = transformForStyledComponents(tokens);
export const cssVariables = transformForCSS(tokens);
Instead of hunting through Figma for the "correct" blue, you reference semantic tokens:
const Button = styled.button`
background: var(--surface-interactive);
color: var(--text-on-interactive);
border: 1px solid var(--border-interactive);
&:hover {
background: var(--surface-interactive-hover);
}
&:disabled {
opacity: var(--opacity-disabled);
/* Non-color accessibility cue included */
}
`;
Result: Component implementation that's consistent, accessible, and themeable by default.
No more manual color picker testing. Your CI pipeline validates every color combination:
# .github/workflows/accessibility.yml
- name: Validate Color Contrast
run: |
npm run test:contrast
npm run pa11y:colors
# Fails build if any combination < 4.5:1 ratio
Result: Ship with confidence knowing every text/background pair meets WCAG AA standards.
Adding new brand colors becomes a structured process:
// tokens/colors.json
{
"semantic": {
"success": {
"base": { "value": "oklch(0.7 0.15 145)" },
"hover": { "value": "oklch(0.65 0.15 145)" },
"text": { "value": "oklch(0.25 0.08 145)" }
}
}
}
Build scripts automatically generate all framework exports and validate contrast ratios.
npm install sass polished @sbalev/accessibility-check
npm install -D stylelint stylelint-a11y
src/
├── tokens/
│ ├── colors.json # Master palette
│ └── build/
│ ├── scss.js # SCSS export
│ └── tailwind.js # Tailwind export
└── styles/
├── _tokens.scss # Generated variables
└── base.scss # Base styles
// tokens/build/scss.js
const tokens = require('../colors.json');
function buildSCSS(tokens) {
return Object.entries(tokens.semantic)
.map(([name, value]) => `$color-${name}: ${value.base.value};`)
.join('\n');
}
Copy the provided Cursor Rules into your .cursorrules file. The AI will now:
These Cursor Rules don't just organize your colors—they eliminate an entire category of bugs, accessibility issues, and design inconsistencies. You'll spend less time debugging visual problems and more time building features that matter.
Your design system becomes a competitive advantage when color works systematically across every component, theme, and user preference. Stop treating color as an afterthought and start treating it as the infrastructure it should be.
Ready to implement bulletproof color systems? Add these rules to your project and watch your color-related development friction disappear.
You are an expert in CSS, SCSS, CSS-in-JS (Styled-Components/Tailwind), Design-Token pipelines, WCAG 2.2 accessibility, and AI-powered adaptive color frameworks.
Key Principles
- Restrict core palettes to 3–4 primary hues; apply the 60/30/10 ratio (60 % base, 30 % secondary, 10 % accents).
- Color communicates hierarchy, state, and calls-to-action—never decoration only.
- Every text/background pair must meet WCAG AA contrast (≥ 4.5:1 body, ≥ 3:1 large text). Target AAA (7:1) when feasible.
- Never rely on color alone; pair with iconography, labels, or patterns.
- All brand colors must map to design-token names to guarantee consistency across products.
- Build themes with CSS custom properties (light, dark, high-contrast) that can be swapped at runtime without repaint-thrash.
CSS / SCSS
- Declare tokens in a dedicated _colors.scss (SCSS) or :root block (CSS):
```scss
// core tokens
$color-primary-500: #0066ff;
$color-primary-600: darken($color-primary-500, 8%);
:root {
--color-primary-500: #0066ff;
--color-primary-600: color-mix(in srgb, var(--color-primary-500) 92%, black);
}
```
- Use HSL or OKLCH for new tokens to enable perceptual lightness tweaks.
- Function & variable naming: <role>-<hue>-<scale> (e.g., `--surface-neutral-100`). Avoid generic names like `--blue`.
- Keep palettes source-of-truth in tokens; component files only reference tokens, never raw hex.
- Follow cascade layering: `@layer tokens, base, utilities, components, overrides`.
- Prefer `color-mix()` & `oklch()` over manual hex manip for predictable accessibility.
- SCSS helper: `contrast($c1, $c2, $threshold: 4.5)` throws at compile-time when ratio < threshold.
Error Handling & Validation
- Automate contrast checks in CI via `@sbalev/accessibility-check` or `pa11y`.
- Lint tokens with `stylelint-a11y` and a custom rule that fails builds on < 4.5:1 ratio.
- Write unit tests for JS theme objects:
```ts
expect(getContrast(theme.text, theme.bg)).toBeGreaterThanOrEqual(4.5);
```
- Validate new palettes through moderated user testing (5 participants min) & color-blind simulators.
- Early-return strategy inside adaptive-theme functions: if user sets `prefers-contrast: more`, switch to high-contrast palette before other logic executes.
Framework-Specific Rules
Tailwind
- Extend tailwind.config.js only from token file:
```js
const tokens = require('./build/tokens');
module.exports = {
theme: { colors: tokens.tailwind },
darkMode: 'class',
};
```
- Avoid extending default colors; shadowing causes maintenance drift.
Styled-Components / Emotion
- Store theme in a serialisable object:
```ts
export const lightTheme = {
surface: tokens.surface.base,
onSurface: tokens.text.base,
} as const;
```
- Use `polished` `readableColor()` for runtime contrast assertion and throw descriptive errors.
Additional Sections
Accessibility & Testing
- Incorporate Storybook a11y addon; block merge if any story violates contrast.
- Run A/B tests only after palette passes WCAG checks to avoid bias.
- Include questionnaires for emotional response (SAM scale) during user studies.
Adaptive / AI Color Systems
- Provide `detectAmbientLight()` util; if lux < 40, auto-switch to dark theme (respecting user opt-out in localStorage).
- Cache computed palettes in `localStorage` to avoid repetitive AI calls.
Performance
- Assign colors via CSS variables; browser repaints only affected descendants, not the full DOM.
- Prefer `prefers-color-scheme` media query to JavaScript for first-paint theme selection.
Security
- Sanitize any user-generated palette before injection to prevent CSS injection (`/[^#0-9a-fA-F]/`).
- Whitelist token names when exposing to theming APIs, never evaluate arbitrary JS.
Common Pitfalls & Anti-Patterns
- DO NOT hard-code hex values in component styles.
- Avoid light-on-light combos like #aaa on #fff; readability plummets even if ratio passes theory.
- Skip “all-grey” disabled buttons; add opacity & icon change for non-color cues.
Tooling Cheat-Sheet
- Adobe Color: palette exploration & WCAG contrast display.
- Coolors CLI: export to CSS vars.
- Venngage Accessible Palette: quick AA/AAA verification.
- Colormind & Khroma: AI suggestions as starting points, never final authority.
Directory Convention (example)
- tokens/
• colors.json – master palette
• build-scripts/
– export-scss.js – emits _colors.scss
– export-tailwind.js – emits tailwind tokens
- styles/
• _colors.scss – imported first
• base.scss – typography, reset
• components/
End of rule set.