@su-record/vibe 3.2.62 → 4.0.0

package/skills/vibe.ui-ux-pro-max/reference/color-and-contrast.md

@@ -1,517 +0,0 @@
-# Color & Contrast — Deep Reference Guide
-
-A systematic reference for building accessible, perceptually consistent color systems in web UI. Covers the modern OKLCH color space, token architecture, dark mode strategy, and WCAG compliance patterns.
-
----
-
-## OKLCH Color Space
-
-### Why OKLCH Over HSL or HEX
-
-The legacy HSL color space is perceptually non-uniform: a yellow at `hsl(60, 100%, 50%)` and a blue at `hsl(240, 100%, 50%)` have the same nominal lightness value, but the yellow reads dramatically brighter to the human eye. This creates real problems when you want consistent contrast across a palette.
-
-OKLCH solves this. It maps color to how the human visual system actually perceives brightness, chroma, and hue. Two colors with the same `L` value in OKLCH will appear equally bright to a viewer, regardless of their hue. This makes predictable contrast possible without manual adjustments per hue.
-
-### Syntax
-
-```css
-/* oklch(Lightness Chroma Hue) */
-color: oklch(0.62 0.19 145);
-
-/* With alpha */
-color: oklch(0.62 0.19 145 / 0.8);
-```
-
-- **L** — Lightness, range `0` (black) to `1` (white)
-- **C** — Chroma (saturation intensity), roughly `0` to `0.37` in displayable sRGB
-- **H** — Hue angle in degrees, `0–360`
-
-### Browser Support
-
-OKLCH is supported in all modern browsers (Chrome 111+, Safari 15.4+, Firefox 113+). For older targets, provide an `@supports` fallback:
-
-```css
-:root {
-  --color-primary: #2563eb; /* fallback */
-}
-
-@supports (color: oklch(0 0 0)) {
-  :root {
-    --color-primary: oklch(0.55 0.22 264);
-  }
-}
-```
-
-### Perceptual Uniformity in Practice
-
-When generating a 9-step scale (see Palette Generation), OKLCH lets you space lightness values linearly and get visually even steps. With HSL you would need to hand-tune each step because yellow and purple consume lightness differently.
-
-```ts
-// Generate a 9-step lightness scale for a given hue/chroma
-function generateScale(hue: number, chroma: number): string[] {
-  const steps = [0.95, 0.88, 0.78, 0.66, 0.55, 0.44, 0.33, 0.22, 0.12];
-  return steps.map((l) => `oklch(${l} ${chroma} ${hue})`);
-}
-```
-
----
-
-## Tinted Neutrals
-
-### The Problem with Pure Gray
-
-Pure gray (`oklch(L 0 0)`) is chromatic dead weight. It has no relationship to your brand and often reads as clinical or cold, especially in large neutral areas like backgrounds, sidebars, and cards.
-
-Tinted neutrals solve this by adding a tiny amount of chroma — just enough to feel cohesive with the brand, invisible to untrained eyes, but felt as warmth or coolness throughout the UI.
-
-### How to Create Tinted Neutrals
-
-Start from your primary brand hue. Drop the chroma to `0.01–0.04` (barely perceptible). Use the same hue angle as your primary color.
-
-```css
-:root {
-  /* Brand primary: oklch(0.55 0.22 264) — blue-violet */
-  /* Neutral scale with matching hue, near-zero chroma */
-  --neutral-50:  oklch(0.97 0.01 264);
-  --neutral-100: oklch(0.93 0.01 264);
-  --neutral-200: oklch(0.86 0.02 264);
-  --neutral-300: oklch(0.76 0.02 264);
-  --neutral-400: oklch(0.62 0.02 264);
-  --neutral-500: oklch(0.50 0.02 264);
-  --neutral-600: oklch(0.40 0.02 264);
-  --neutral-700: oklch(0.30 0.02 264);
-  --neutral-800: oklch(0.20 0.02 264);
-  --neutral-900: oklch(0.12 0.01 264);
-}
-```
-
-### DO / DON'T — Tinted Neutrals
-
-**DO** use the same hue angle as your primary for harmonious tinting.
-
-**DON'T** use a complementary hue for neutrals — it creates subtle visual tension and makes the palette look unintentional.
-
-**DO** keep chroma below `0.04` for backgrounds and surfaces. Higher values stop reading as neutrals.
-
-**DON'T** use `oklch(L 0 0)` for any neutral in a branded UI — it feels detached and clinical.
-
-### Tailwind Configuration
-
-```ts
-// tailwind.config.ts
-import type { Config } from "tailwindcss";
-
-export default {
-  theme: {
-    extend: {
-      colors: {
-        neutral: {
-          50:  "oklch(0.97 0.01 264)",
-          100: "oklch(0.93 0.01 264)",
-          // ...
-          900: "oklch(0.12 0.01 264)",
-        },
-      },
-    },
-  },
-} satisfies Config;
-```
-
----
-
-## 60-30-10 Rule
-
-### The Principle
-
-The 60-30-10 rule is a composition framework borrowed from interior design and applied to UI color allocation:
-
-- **60% — Dominant**: Backgrounds, surfaces, large containers. Usually neutrals.
-- **30% — Secondary**: Text, borders, cards, secondary surfaces. Mid-range neutrals or a secondary brand color.
-- **10% — Accent**: CTAs, active states, highlights, key icons. Your primary brand color.
-
-This ratio creates visual hierarchy naturally. The accent color has impact precisely because it is rare.
-
-### Applied to a React Layout
-
-```tsx
-// Tailwind + React example
-export function AppShell({ children }: { children: React.ReactNode }) {
-  return (
-    // 60% — dominant neutral background
-    <div className="min-h-screen bg-neutral-50 dark:bg-neutral-950">
-      {/* 30% — secondary surface */}
-      <nav className="bg-neutral-100 dark:bg-neutral-900 border-b border-neutral-200 dark:border-neutral-800">
-        <div className="max-w-7xl mx-auto px-4 flex items-center justify-between h-14">
-          <span className="text-neutral-900 dark:text-neutral-100 font-semibold">
-            Brand
-          </span>
-          {/* 10% — accent CTA */}
-          <button className="bg-primary-600 hover:bg-primary-700 text-white px-4 py-1.5 rounded-md text-sm font-medium">
-            Get Started
-          </button>
-        </div>
-      </nav>
-      <main className="max-w-7xl mx-auto px-4 py-8">{children}</main>
-    </div>
-  );
-}
-```
-
-### DO / DON'T — 60-30-10
-
-**DO** use the accent color only for the single most important interactive element per view. One primary CTA per screen is the ideal application of that 10%.
-
-**DON'T** use your accent color for decorative elements, illustrations, or informational icons. It trains users to ignore it.
-
-**DO** let the 30% tier handle text. Mid-neutral text on a neutral background is readable and calm.
-
-**DON'T** fill large surfaces (60% territory) with a saturated color. This exhausts the eye and leaves nowhere for emphasis to land.
-
----
-
-## Dark Mode
-
-### Not an Inversion
-
-The most common dark mode mistake is inverting the light palette. Inversion produces washed-out, oversaturated text and poor contrast because the perceptual math doesn't hold in reverse.
-
-Dark mode requires a separate token set that is designed for dark surfaces, not derived from light surfaces.
-
-### Surface Elevation with Lighter Shades
-
-In dark mode, elevation is conveyed through progressively lighter surface colors, not shadows. This mirrors how light scatters in physical space.
-
-```css
-[data-theme="dark"] {
-  /* Base surface — darkest */
-  --surface-base:    oklch(0.12 0.01 264);
-
-  /* Elevation 1 — cards, panels */
-  --surface-raised:  oklch(0.16 0.01 264);
-
-  /* Elevation 2 — modals, popovers */
-  --surface-overlay: oklch(0.20 0.01 264);
-
-  /* Elevation 3 — tooltips, dropdowns */
-  --surface-float:   oklch(0.24 0.01 264);
-
-  /* Text */
-  --text-primary:    oklch(0.93 0.01 264);
-  --text-secondary:  oklch(0.68 0.02 264);
-  --text-disabled:   oklch(0.45 0.01 264);
-
-  /* Accent — slightly desaturated for dark context */
-  --color-primary:   oklch(0.65 0.18 264);
-}
-```
-
-### Token-Based Dark Mode in React + Tailwind
-
-```tsx
-// Use CSS custom properties via Tailwind's `[var()]` escape hatch
-// or configure Tailwind with semantic token names
-
-// tailwind.config.ts (semantic tokens)
-export default {
-  theme: {
-    extend: {
-      colors: {
-        surface: {
-          base:    "var(--surface-base)",
-          raised:  "var(--surface-raised)",
-          overlay: "var(--surface-overlay)",
-        },
-        text: {
-          primary:   "var(--text-primary)",
-          secondary: "var(--text-secondary)",
-        },
-      },
-    },
-  },
-};
-
-// Component usage — zero dark: variants needed
-function Card({ children }: { children: React.ReactNode }) {
-  return (
-    <div className="bg-surface-raised rounded-xl p-6 text-text-primary">
-      {children}
-    </div>
-  );
-}
-```
-
-### DO / DON'T — Dark Mode
-
-**DO** define a separate token layer for dark mode. Map the same semantic names (`--text-primary`, `--surface-base`) to different raw values.
-
-**DON'T** rely on Tailwind's `dark:` utility for every color declaration. It creates a proliferation of `dark:` variants that are hard to audit. Use CSS custom properties with a `[data-theme]` attribute instead.
-
----
-
-## Accessibility — WCAG 2.1 AA
-
-### Contrast Ratios
-
-WCAG 2.1 Level AA defines two thresholds:
-
-| Target | Minimum Ratio |
-|---|---|
-| Normal text (< 18pt / < 14pt bold) | 4.5:1 |
-| Large text (≥ 18pt / ≥ 14pt bold) | 3:1 |
-| UI components (borders, icons, controls) | 3:1 |
-| Decorative elements, disabled states | No requirement |
-
-### Checking Contrast in OKLCH
-
-OKLCH's lightness channel gives a rough guide, but actual contrast must be computed against WCAG's relative luminance formula. Use a tool like `culori` in your design token pipeline:
-
-```ts
-import { wcagContrast, oklch, formatHex } from "culori";
-
-function assertContrast(
-  fg: string,
-  bg: string,
-  threshold: 4.5 | 3
-): void {
-  const ratio = wcagContrast(fg, bg);
-  if (ratio < threshold) {
-    throw new Error(
-      `Contrast ${ratio.toFixed(2)}:1 fails WCAG AA (${threshold}:1) — ${fg} on ${bg}`
-    );
-  }
-}
-
-// Run in CI or during token generation
-assertContrast("oklch(0.93 0.01 264)", "oklch(0.12 0.01 264)", 4.5);
-```
-
-### Designing for Contrast at Token Definition Time
-
-Rather than checking contrast after the fact, build contrast in during palette generation. Steps 700–900 pass AA on white backgrounds; steps 50–300 pass AA on dark backgrounds. The mid-range (400–600) is unreliable — use with caution and always verify.
-
-```css
-/* Reliable pairings for AA compliance */
-.text-on-light  { color: var(--primary-700); } /* ~7:1 on white */
-.text-on-dark   { color: var(--primary-200); } /* ~8:1 on --neutral-900 */
-.badge-accent   { color: var(--primary-800); background: var(--primary-100); }
-```
-
-### Non-Text Contrast (UI Components)
-
-Focus rings, form borders, icon buttons, and toggle tracks must meet 3:1 against adjacent backgrounds. This is commonly missed.
-
-```tsx
-// Accessible focus ring — visible on both light and dark
-function FocusableButton({ children }: { children: React.ReactNode }) {
-  return (
-    <button
-      className={[
-        "px-4 py-2 rounded-md font-medium",
-        "bg-primary-600 text-white",
-        // Focus ring: 3px offset with neutral contrast to surface
-        "focus-visible:outline focus-visible:outline-2",
-        "focus-visible:outline-offset-2 focus-visible:outline-primary-500",
-      ].join(" ")}
-    >
-      {children}
-    </button>
-  );
-}
-```
-
----
-
-## Palette Generation
-
-### 9-Step Lightness Scale
-
-A well-formed palette for any hue uses 9 steps (50–900 in Tailwind convention, or 1–9 in index convention). The scale follows a non-linear lightness curve to account for perceptual compression at the extremes.
-
-```ts
-// Recommended OKLCH lightness values per step
-const LIGHTNESS_SCALE: Record<string, number> = {
-  "50":  0.97,
-  "100": 0.93,
-  "200": 0.85,
-  "300": 0.74,
-  "400": 0.62,
-  "500": 0.52,
-  "600": 0.44,
-  "700": 0.36,
-  "800": 0.26,
-  "900": 0.16,
-};
-
-function buildPalette(
-  hue: number,
-  chroma: number
-): Record<string, string> {
-  return Object.fromEntries(
-    Object.entries(LIGHTNESS_SCALE).map(([step, l]) => [
-      step,
-      `oklch(${l} ${chroma} ${hue})`,
-    ])
-  );
-}
-
-const blue = buildPalette(264, 0.20);
-// { "50": "oklch(0.97 0.20 264)", "100": "oklch(0.93 0.20 264)", ... }
-```
-
-### Semantic Colors
-
-Semantic colors communicate meaning independent of brand. They should be generated from dedicated hues, not borrowed from the brand palette:
-
-| Semantic Role | Recommended Hue (OKLCH) | Rationale |
-|---|---|---|
-| Success | `145` (green) | Universal positive association |
-| Error | `25` (red-orange) | High visibility, culturally universal |
-| Warning | `85` (amber) | Distinct from success, readable |
-| Info | `230` (cyan-blue) | Neutral, informational |
-
-```css
-:root {
-  /* Success */
-  --success-50:  oklch(0.97 0.05 145);
-  --success-500: oklch(0.52 0.18 145);
-  --success-700: oklch(0.36 0.16 145);
-
-  /* Error */
-  --error-50:  oklch(0.97 0.05 25);
-  --error-500: oklch(0.52 0.21 25);
-  --error-700: oklch(0.36 0.19 25);
-
-  /* Warning */
-  --warning-50:  oklch(0.97 0.06 85);
-  --warning-500: oklch(0.72 0.17 85);
-  --warning-700: oklch(0.50 0.14 85);
-
-  /* Info */
-  --info-50:  oklch(0.97 0.04 230);
-  --info-500: oklch(0.55 0.17 230);
-  --info-700: oklch(0.38 0.15 230);
-}
-```
-
-### Chroma Guidance by Use Case
-
-- **Brand accent**: `0.18–0.25` — vivid, intentional
-- **Semantic colors**: `0.14–0.22` — communicative but not alarming
-- **Tinted neutrals**: `0.01–0.04` — imperceptible tinting
-- **Disabled states**: `0.01–0.02` — visually receded
-
----
-
-## Color Tokens
-
-### The Token Hierarchy
-
-A robust token system has three layers:
-
-1. **Primitive tokens** — Raw palette values. Named by position, not role.
-2. **Semantic tokens** — Role-based references to primitives. Context-aware.
-3. **Component tokens** — Component-specific overrides of semantic tokens. Optional.
-
-```css
-/* Layer 1: Primitives */
-:root {
-  --primitive-blue-500: oklch(0.52 0.20 264);
-  --primitive-blue-700: oklch(0.36 0.19 264);
-  --primitive-neutral-50: oklch(0.97 0.01 264);
-  --primitive-neutral-900: oklch(0.12 0.01 264);
-}
-
-/* Layer 2: Semantic tokens (light mode default) */
-:root {
-  --color-primary:        var(--primitive-blue-600);
-  --color-primary-hover:  var(--primitive-blue-700);
-  --surface-page:         var(--primitive-neutral-50);
-  --text-body:            var(--primitive-neutral-900);
-  --text-muted:           var(--primitive-neutral-500);
-  --border-default:       var(--primitive-neutral-200);
-}
-
-/* Layer 2: Semantic tokens (dark mode) */
-[data-theme="dark"] {
-  --color-primary:       var(--primitive-blue-400);
-  --color-primary-hover: var(--primitive-blue-300);
-  --surface-page:        var(--primitive-neutral-950);
-  --text-body:           var(--primitive-neutral-50);
-  --text-muted:          var(--primitive-neutral-400);
-  --border-default:      var(--primitive-neutral-800);
-}
-```
-
-### Systematic Naming Convention
-
-Use a `[category]-[variant]-[state]` structure:
-
-```
---color-primary          → base primary
---color-primary-hover    → interactive state
---color-primary-active   → pressed state
---color-primary-disabled → disabled state
---surface-page           → page background
---surface-raised         → card/panel
---text-body              → default body text
---text-heading           → heading text
---text-muted             → secondary/helper text
---border-default         → standard border
---border-focus           → focus ring
-```
-
-### Wiring Tokens into Tailwind
-
-```ts
-// tailwind.config.ts — wire semantic tokens to Tailwind utilities
-export default {
-  theme: {
-    extend: {
-      colors: {
-        primary: {
-          DEFAULT: "var(--color-primary)",
-          hover:   "var(--color-primary-hover)",
-        },
-        surface: {
-          page:   "var(--surface-page)",
-          raised: "var(--surface-raised)",
-        },
-        text: {
-          body:    "var(--text-body)",
-          muted:   "var(--text-muted)",
-          heading: "var(--text-heading)",
-        },
-        border: {
-          DEFAULT: "var(--border-default)",
-          focus:   "var(--border-focus)",
-        },
-      },
-    },
-  },
-};
-```
-
-This setup means components never reference primitive tokens directly. A design decision like "make the brand warmer" changes one variable in the primitive layer and propagates everywhere.
-
-### DO / DON'T — Color Tokens
-
-**DO** reference semantic tokens in components, never primitives. `bg-surface-raised` is correct; `bg-neutral-100` in a component is a smell.
-
-**DON'T** create tokens for every one-off use. If a color is used fewer than three times, it doesn't need a token — use an inline value or compose from existing tokens.
-
-**DO** version your token file if it is shared across multiple projects or exported as a package. Breaking token renames are a semver concern.
-
----
-
-## Quick Reference Checklist
-
-Before shipping any new UI surface, verify:
-
-- [ ] All text passes WCAG AA contrast (4.5:1 normal, 3:1 large)
-- [ ] All interactive UI elements (borders, icons) pass 3:1 non-text contrast
-- [ ] Focus rings are visible on both light and dark backgrounds
-- [ ] Dark mode uses a separate token set, not CSS filter inversion
-- [ ] Accent color accounts for no more than ~10% of visible surface area
-- [ ] Semantic color tokens are used in components (not primitives)
-- [ ] Color palette was generated in OKLCH for perceptual uniformity
-- [ ] Tinted neutrals share hue angle with primary brand color