Color Palette Generation

Status: Production Ready ✅ Last Updated: 2026-01-14 Standard: Tailwind v4 @theme syntax

Quick Start

Generate complete palette from brand hex:

// Input: Brand hex
const brandColor = "#0D9488" // Teal-600

// Output: 11-shade scale + semantic tokens + dark mode
primary-50:  #F0FDFA (lightest)
primary-500: #14B8A6 (brand)
primary-950: #042F2E (darkest)

background: #FFFFFF
foreground: #0F172A
primary: #14B8A6

Use the reference files to generate shades, map semantics, and check contrast.

Color Scale Overview

Standard 11-Shade Scale

Shade	Lightness	Use Case
50	97%	Subtle backgrounds
100	94%	Hover states
200	87%	Borders, dividers
300	75%	Disabled states
400	62%	Placeholder text
500	48%	Brand color
600	40%	Primary actions
700	33%	Hover on primary
800	27%	Active states
900	20%	Text on light bg
950	10%	Darkest accents

Key principle: Shade 500 represents your brand color. Other shades maintain hue/saturation while varying lightness.

Hex to HSL Conversion

Convert brand hex to HSL for shade generation:

// Example: #0D9488 → hsl(174, 84%, 29%)
// H (Hue): 174deg
// S (Saturation): 84%
// L (Lightness): 29%

Generate shades by keeping hue constant, adjusting lightness:

Lighter shades (50-400): Reduce saturation slightly
Mid shades (500-600): Full saturation
Darker shades (700-950): Full saturation

See references/shade-generation.md for conversion formula.

Semantic Token Mapping

Map shade scale to semantic tokens for components:

Light Mode

--background: white
--foreground: primary-950
--card: white
--card-foreground: primary-900
--muted: primary-50
--muted-foreground: primary-600
--border: primary-200
--primary: primary-600
--primary-foreground: white

Dark Mode

--background: primary-950
--foreground: primary-50
--card: primary-900
--card-foreground: primary-50
--muted: primary-800
--muted-foreground: primary-400
--border: primary-800
--primary: primary-500
--primary-foreground: white

Pattern: Invert lightness while preserving relationships. See references/semantic-mapping.md.

Dark Mode Pattern

Swap light and dark shades:

Light Mode	Dark Mode
50 (97% L)	950 (10% L)
100 (94% L)	900 (20% L)
200 (87% L)	800 (27% L)
500 (brand)	500 (brand, slightly brighter)

Preserve brand identity: Keep hue/saturation consistent, only invert lightness.

CSS pattern:

:root {
  --background: white;
  --foreground: hsl(var(--primary-950));
}

.dark {
  --background: hsl(var(--primary-950));
  --foreground: hsl(var(--primary-50));
}

Contrast Checking

WCAG minimum ratios:

Text (AA): 4.5:1 normal, 3:1 large (18px+)
UI Elements: 3:1 (buttons, borders)

Quick check pairs:

primary-600 text on white background
white text on primary-600 background
primary-900 text on primary-50 background

Formula:

contrast = (lighter + 0.05) / (darker + 0.05)
// Where lighter/darker are relative luminance values

See references/contrast-checking.md for full formula and fix patterns.

Quick Reference

Generate Complete Palette

Convert brand hex to HSL
Generate 11 shades (50-950) by varying lightness
Map shades to semantic tokens
Create dark mode variants (invert lightness)
Check contrast for text pairs

Tailwind v4 Output

Use @theme directive:

@theme {
  --color-primary-50: #F0FDFA;
  --color-primary-500: #14B8A6;
  --color-primary-950: #042F2E;

  --color-background: #FFFFFF;
  --color-foreground: var(--color-primary-950);
}

Common Adjustments

Too vibrant at light shades: Reduce saturation by 10-20%
Poor contrast on primary: Use shade 700+ for text
Dark mode too dark: Use shade 900 instead of 950 for backgrounds
Brand color too light/dark: Adjust to shade 500-600 range

Resources

File	Purpose
`references/shade-generation.md`	Hex→HSL conversion, lightness values
`references/semantic-mapping.md`	Token mapping for light/dark modes
`references/dark-mode-palette.md`	Inversion patterns, shade swapping
`references/contrast-checking.md`	WCAG formulas, quick check table
`templates/tailwind-colors.css`	Complete CSS output template
`rules/color-palette.md`	Common mistakes and corrections

Token Efficiency

Without skill: ~8-12k tokens trial-and-error for palette generation With skill: ~3-4k tokens using references Savings: ~65%

Errors prevented:

Poor contrast ratios (accessibility violations)
Inconsistent shade scales
Broken dark mode (wrong lightness values)
Raw Tailwind colors instead of semantic tokens
Missing foreground pairs for backgrounds

Examples

Brand Color: Teal (#0D9488)

@theme {
  /* Shade scale */
  --color-primary-50: #F0FDFA;
  --color-primary-100: #CCFBF1;
  --color-primary-200: #99F6E4;
  --color-primary-300: #5EEAD4;
  --color-primary-400: #2DD4BF;
  --color-primary-500: #14B8A6;
  --color-primary-600: #0D9488;
  --color-primary-700: #0F766E;
  --color-primary-800: #115E59;
  --color-primary-900: #134E4A;
  --color-primary-950: #042F2E;

  /* Light mode semantics */
  --color-background: #FFFFFF;
  --color-foreground: var(--color-primary-950);
  --color-primary: var(--color-primary-600);
  --color-primary-foreground: #FFFFFF;
}

.dark {
  /* Dark mode overrides */
  --color-background: var(--color-primary-950);
  --color-foreground: var(--color-primary-50);
  --color-primary: var(--color-primary-500);
}

Brand Color: Purple (#7C3AED)

@theme {
  --color-primary-50: #FAF5FF;
  --color-primary-500: #A855F7;
  --color-primary-950: #3B0764;

  --color-background: #FFFFFF;
  --color-foreground: var(--color-primary-950);
  --color-primary: var(--color-primary-600);
}

Next Steps: Use references/shade-generation.md to convert your brand hex to HSL and generate the 11-shade scale.

color-palette