Ui Theme Reference

---
name: ui-theme-reference
description: >
  Canonical design token registry — colors, typography, spacing, sizing, border radius,
  shadows, z-index, breakpoints, motion, and focus tokens. Used by ui-best-practices
  rules and all agents that implement or review UI components. Includes CSS variable
  template for quick project setup.
---

# UI Theme Reference

> Configurable design token registry used by `ui-best-practices` rules.
> Every hardcoded value in the best practices MUST reference a token defined here.
> To customize: override values below or generate via `/pwdev-uiux:theme create`.

---

## How to Use

Rules in the `ui-best-practices` skill reference tokens as `theme.<section>.<token>`.
When implementing, map these tokens to your stack:

| Stack | Token format | File |
|-------|-------------|------|
| shadcn-vue | `hsl(var(--<token>))` | `src/assets/index.css` |
| shadcn-react | `hsl(var(--<token>))` | `src/app/globals.css` |
| primevue | `var(--p-<token>)` | `src/assets/theme.css` |
| tailwind-only | Tailwind config `theme.extend` | `tailwind.config.ts` |
| custom | Any CSS variable scheme | project-specific |

---

## 1. Colors

### 1.1 Surfaces

| Token | Light | Dark | Usage |
|-------|-------|------|-------|
| `--background` | `#F9FAFB` · `210 20% 98%` | `#0A0F1A` · `222 84% 5%` | Page background |
| `--foreground` | `#1D2939` · `220 26% 16%` | `#F0F4F8` · `210 40% 96%` | Primary text |
| `--card` | `#FFFFFF` · `0 0% 100%` | `#111827` · `222 47% 11%` | Card / surface background |
| `--card-foreground` | `#1D2939` · `220 26% 16%` | `#F0F4F8` · `210 40% 96%` | Text on cards |
| `--popover` | `#FFFFFF` · `0 0% 100%` | `#111827` · `222 47% 11%` | Popover / dropdown bg |
| `--popover-foreground` | `#1D2939` · `220 26% 16%` | `#F0F4F8` · `210 40% 96%` | Text on popovers |

### 1.2 Text Hierarchy

| Token | Light | Dark | Usage |
|-------|-------|------|-------|
| `--foreground` | `#1D2939` | `#F0F4F8` | Primary text, headings |
| `--muted-foreground` | `#667085` | `#94A3B8` | Secondary text, labels, placeholders |

### 1.3 Interactive

| Token | Light | Dark | Usage |
|-------|-------|------|-------|
| `--primary` | *brand color* | *brand color (adjusted)* | Buttons, links, focus rings |
| `--primary-foreground` | `#FFFFFF` | `#FFFFFF` | Text on primary backgrounds |
| `--secondary` | `#F1F5F9` | `#1E293B` | Secondary buttons, subtle actions |
| `--secondary-foreground` | `#1D2939` | `#F0F4F8` | Text on secondary backgrounds |
| `--accent` | `#F1F5F9` | `#1E293B` | Hover highlights, active states |
| `--accent-foreground` | `#1D2939` | `#F0F4F8` | Text on accent backgrounds |

### 1.4 Feedback

| Token | Light | Dark | Usage |
|-------|-------|------|-------|
| `--success` | `#039855` | `#34D399` | Positive states, confirmations |
| `--success-foreground` | `#FFFFFF` | `#022C22` | Text on success backgrounds |
| `--warning` | `#F79009` | `#FBBF24` | Alerts, caution states |
| `--warning-foreground` | `#422006` | `#422006` | Text on warning backgrounds |
| `--destructive` | `#D92D20` | `#FCA5A5` | Errors, delete actions |
| `--destructive-foreground` | `#FFFFFF` | `#450A0A` | Text on destructive backgrounds |
| `--info` | `#2563EB` | `#60A5FA` | Informational, tips |
| `--info-foreground` | `#FFFFFF` | `#172554` | Text on info backgrounds |

### 1.5 Structure

| Token | Light | Dark | Usage |
|-------|-------|------|-------|
| `--border` | `#EAECF0` | `#1E293B` | Dividers, separators |
| `--input` | `#D0D5DD` | `#334155` | Input borders |
| `--ring` | *primary* | *primary* | Focus ring color |
| `--muted` | `#F1F5F9` | `#1E293B` | Muted backgrounds (badges, tags) |

### 1.6 Reserved Semantic Colors

These colors carry universal meaning. **Never repurpose them** for decorative or categorical use:

| Color | Meaning | Allowed usage |
|-------|---------|---------------|
| Green (`--success`) | Good / positive / complete | Success states, positive KPIs, completion |
| Orange (`--warning`) | Caution / attention needed | Warnings, pending actions, approaching limits |
| Red (`--destructive`) | Bad / error / danger | Errors, failures, destructive actions, negative KPIs |

For categorical/chart colors, use the chart palette below.

### 1.7 Chart Palette

Dedicated colors for data visualization — independent from feedback semantics:

| Token | Default | Usage |
|-------|---------|-------|
| `--chart-1` | `#2563EB` | Primary data series |
| `--chart-2` | `#7C3AED` | Secondary data series |
| `--chart-3` | `#0891B2` | Tertiary data series |
| `--chart-4` | `#C026D3` | Fourth data series |
| `--chart-5` | `#EA580C` | Fifth data series |
| `--chart-muted` | `#D1D5DB` | De-emphasized / comparison series |

---

## 2. Typography

### 2.1 Font Stack

| Token | Default | Fallbacks |
|-------|---------|-----------|
| `--font-sans` | `Inter` | `system-ui, -apple-system, sans-serif` |
| `--font-mono` | `JetBrains Mono` | `ui-monospace, monospace` |

### 2.2 Type Scale

Progressive scale — adjacent levels must not skip more than one step:

| Token | Size | Line Height | Weight | Usage |
|-------|------|-------------|--------|-------|
| `--text-xs` | `12px` | `16px` | 400 | Footnotes, badges, captions (minimum allowed) |
| `--text-sm` | `14px` | `20px` | 400 | **Default body text**, form labels |
| `--text-base` | `16px` | `24px` | 400 | Emphasized body, card titles |
| `--text-lg` | `18px` | `28px` | 500 | Section headings |
| `--text-xl` | `20px` | `28px` | 600 | Page sub-titles |
| `--text-2xl` | `24px` | `32px` | 600 | Page titles |
| `--text-3xl` | `30px` | `36px` | 700 | Hero headings |
| `--text-4xl` | `36px` | `40px` | 700 | Display / marketing headings |

**Constraint:** never jump more than 2 steps between adjacent text elements (e.g., `text-3xl` → `text-sm` is forbidden; use `text-3xl` → `text-xl` → `text-base` → `text-sm`).

### 2.3 Font Weight Scale

| Token | Value | Usage |
|-------|-------|-------|
| `--font-normal` | `400` | Body text |
| `--font-medium` | `500` | Labels, nav items |
| `--font-semibold` | `600` | Headings, emphasis |
| `--font-bold` | `700` | Hero, display text |

---

## 3. Spacing

Base unit: **4px**. All spacing must be a multiple of 4.

| Token | Value | Tailwind | Typical Usage |
|-------|-------|----------|---------------|
| `--space-0.5` | `2px` | `gap-0.5` | Micro adjustments only |
| `--space-1` | `4px` | `gap-1` | Icon ↔ label gap |
| `--space-1.5` | `6px` | `gap-1.5` | Compact inline gap |
| `--space-2` | `8px` | `gap-2` | Internal gap, small padding |
| `--space-3` | `12px` | `gap-3` | Badge padding, compact lists |
| `--space-4` | `16px` | `gap-4, p-4` | Default card padding (min) |
| `--space-5` | `20px` | `gap-5` | Medium card padding |
| `--space-6` | `24px` | `gap-6, p-6` | Default card padding (max), section gaps |
| `--space-8` | `32px` | `gap-8, p-8` | Large section padding |
| `--space-10` | `40px` | `gap-10` | Page-level vertical spacing |
| `--space-12` | `48px` | `gap-12` | Major section dividers |
| `--space-16` | `64px` | `gap-16` | Page top/bottom margins |

### Card Padding Rule

| Card context | Recommended padding |
|--------------|-------------------|
| Compact (sidebar, list items) | `--space-3` to `--space-4` (12–16px) |
| Standard (content cards) | `--space-4` to `--space-6` (16–24px) |
| Featured / hero cards | `--space-6` to `--space-8` (24–32px) |
| **Ceiling** | Never exceed `--space-8` (32px) in cards |

---

## 4. Sizing

### 4.1 Interactive Elements

| Token | Value | Usage |
|-------|-------|-------|
| `--height-input` | `40px` | Inputs, selects, single-line controls |
| `--height-button` | `40px` | All buttons (must match input height) |
| `--height-button-sm` | `32px` | Compact buttons (tables, toolbars) |
| `--height-button-lg` | `48px` | Hero CTAs, prominent actions |
| `--min-touch-target` | `44px` | Minimum tap area on touch devices (WCAG 2.5.8) |

### 4.2 Content Width

| Token | Value | Usage |
|-------|-------|-------|
| `--max-w-form` | `560px` | Form containers (onboarding, settings) |
| `--max-w-button` | `400px` | Max button width in wide forms |
| `--max-w-content` | `768px` | Article/text-heavy content |
| `--max-w-page` | `1280px` | Page container |

### 4.3 Textarea Height

| Context | Rows | Approx Height |
|---------|------|---------------|
| Short input (tagline, slug) | 2 | `~56px` |
| Medium input (description) | 4–5 | `~112px` |
| Long input (feedback, notes) | 6–8 | `~168px` |

Always enable auto-resize to grow with content.

---

## 5. Border Radius

| Token | Value | Usage |
|-------|-------|-------|
| `--radius` | `8px` *(configurable)* | Base radius — defines product personality |
| `--radius-sm` | `calc(var(--radius) - 4px)` | Badges, small elements |
| `--radius-md` | `calc(var(--radius) - 2px)` | Inputs, buttons |
| `--radius-lg` | `var(--radius)` | Cards, modals |
| `--radius-xl` | `calc(var(--radius) + 4px)` | Feature cards, large containers |
| `--radius-full` | `9999px` | Avatars, pills, tags |

### Personality Guide

| Brand Style | `--radius` value |
|-------------|-----------------|
| Modern / trendy | `12px–16px` |
| Neutral / corporate (safe default) | `8px` |
| Enterprise / dense | `4px` |
| Sharp / editorial | `0px–2px` |

---

## 6. Shadows

All shadows use `#000000` with controlled opacity. No colored shadows.

| Token | Value | Usage |
|-------|-------|-------|
| `--shadow-xs` | `0 1px 2px rgba(0,0,0,0.05)` | Subtle lift (inputs, badges) |
| `--shadow-sm` | `0 2px 4px rgba(0,0,0,0.06)` | Cards at rest |
| `--shadow-md` | `0 4px 16px rgba(0,0,0,0.08)` | Elevated cards, dropdowns |
| `--shadow-lg` | `0 8px 24px rgba(0,0,0,0.10)` | Modals, popovers |
| `--shadow-xl` | `0 16px 48px rgba(0,0,0,0.12)` | Command palette, overlays |

**Constraints:**
- Minimum opacity: `0.05` (below is invisible)
- Maximum opacity: `0.12` (above feels heavy)
- Never use colored shadows
- Never use gradients as shadow replacements

---

## 7. Z-Index Scale

Managed scale to prevent z-index wars:

| Token | Value | Usage |
|-------|-------|-------|
| `--z-base` | `0` | Default stacking |
| `--z-dropdown` | `10` | Dropdowns, tooltips |
| `--z-sticky` | `20` | Sticky headers, fixed navs |
| `--z-drawer` | `30` | Side drawers, panels |
| `--z-modal` | `40` | Modals, dialogs |
| `--z-popover` | `50` | Popovers over modals |
| `--z-toast` | `60` | Toast notifications |
| `--z-command` | `70` | Command palette (Cmd+K) |
| `--z-overlay` | `80` | Full-screen overlays |

---

## 8. Breakpoints

| Token | Value | Tailwind | Usage |
|-------|-------|----------|-------|
| `--bp-sm` | `640px` | `sm:` | Large phones landscape |
| `--bp-md` | `768px` | `md:` | Tablets |
| `--bp-lg` | `1024px` | `lg:` | Small laptops |
| `--bp-xl` | `1280px` | `xl:` | Desktops |
| `--bp-2xl` | `1536px` | `2xl:` | Large screens |

### Navigation Breakpoint Rules

| Viewport | Max nav items | Menu style |
|----------|--------------|------------|
| `< md` | 4 visible | Bottom bar or hamburger |
| `md–lg` | 5–6 visible | Top bar or compact sidebar |
| `≥ lg` | Unlimited | Full sidebar |

---

## 9. Motion & Animation

| Token | Value | Usage |
|-------|-------|-------|
| `--duration-instant` | `100ms` | Hover color changes, opacity |
| `--duration-fast` | `150ms` | Button press, toggle switch |
| `--duration-normal` | `200ms` | Dropdown open, tooltip appear |
| `--duration-slow` | `300ms` | Drawer slide, modal enter |
| `--duration-slower` | `500ms` | Page transitions, skeleton fade |
| `--ease-default` | `cubic-bezier(0.4, 0, 0.2, 1)` | General purpose easing |
| `--ease-in` | `cubic-bezier(0.4, 0, 1, 1)` | Elements leaving the screen |
| `--ease-out` | `cubic-bezier(0, 0, 0.2, 1)` | Elements entering the screen |

**Constraint:** always respect `prefers-reduced-motion: reduce` — disable or minimize all animations.

---

## 10. Focus & Accessibility

| Token | Value | Usage |
|-------|-------|-------|
| `--ring-width` | `2px` | Focus ring thickness |
| `--ring-offset` | `2px` | Gap between element and focus ring |
| `--ring-color` | `var(--ring)` | Focus ring color (defaults to primary) |

### Contrast Requirements (WCAG AA)

| Element Type | Minimum Ratio |
|-------------|---------------|
| Normal text (< 18px) | **4.5:1** |
| Large text (≥ 18px or ≥ 14px bold) | **3:1** |
| UI components (borders, icons) | **3:1** |
| Non-text contrast (graphs, charts) | **3:1** |

---

## CSS Variable Template

Minimal starter for any project — copy and customize:

```css
@layer base {
  :root {
    /* Surfaces */
    --background: 210 20% 98%;
    --foreground: 220 26% 16%;
    --card: 0 0% 100%;
    --card-foreground: 220 26% 16%;
    --popover: 0 0% 100%;
    --popover-foreground: 220 26% 16%;
    --muted: 210 40% 96%;
    --muted-foreground: 215 16% 47%;

    /* Interactive */
    --primary: 221 83% 53%;       /* ← your brand color */
    --primary-foreground: 0 0% 100%;
    --secondary: 210 40% 96%;
    --secondary-foreground: 220 26% 16%;
    --accent: 210 40% 96%;
    --accent-foreground: 220 26% 16%;

    /* Feedback */
    --destructive: 0 72% 51%;
    --destructive-foreground: 0 0% 100%;
    --success: 160 84% 39%;
    --success-foreground: 0 0% 100%;
    --warning: 32 95% 44%;
    --warning-foreground: 26 83% 14%;
    --info: 221 83% 53%;
    --info-foreground: 0 0% 100%;

    /* Structure */
    --border: 220 13% 91%;
    --input: 218 14% 86%;
    --ring: var(--primary);

    /* Geometry */
    --radius: 0.5rem;

    /* Shadows */
    --shadow-sm: 0 2px 4px rgba(0,0,0,0.06);
    --shadow-md: 0 4px 16px rgba(0,0,0,0.08);
    --shadow-lg: 0 8px 24px rgba(0,0,0,0.10);

    /* Motion */
    --duration-fast: 150ms;
    --duration-normal: 200ms;
    --duration-slow: 300ms;

    /* Focus */
    --ring-width: 2px;
    --ring-offset: 2px;
  }

  .dark {
    --background: 222 84% 5%;
    --foreground: 210 40% 96%;
    --card: 222 47% 11%;
    --card-foreground: 210 40% 96%;
    --popover: 222 47% 11%;
    --popover-foreground: 210 40% 96%;
    --muted: 217 33% 17%;
    --muted-foreground: 215 20% 65%;

    --primary: 217 91% 60%;
    --primary-foreground: 222 47% 11%;
    --secondary: 217 33% 17%;
    --secondary-foreground: 210 40% 96%;
    --accent: 217 33% 17%;
    --accent-foreground: 210 40% 96%;

    --destructive: 0 63% 31%;
    --destructive-foreground: 210 40% 98%;
    --success: 142 69% 58%;
    --success-foreground: 144 61% 10%;
    --warning: 48 96% 53%;
    --warning-foreground: 22 78% 10%;
    --info: 217 91% 60%;
    --info-foreground: 222 47% 11%;

    --border: 217 33% 17%;
    --input: 217 33% 17%;
    --ring: 224 76% 48%;

    --shadow-sm: 0 2px 4px rgba(0,0,0,0.20);
    --shadow-md: 0 4px 16px rgba(0,0,0,0.25);
    --shadow-lg: 0 8px 24px rgba(0,0,0,0.30);
  }

  @media (prefers-reduced-motion: reduce) {
    *, *::before, *::after {
      animation-duration: 0.01ms !important;
      transition-duration: 0.01ms !important;
    }
  }
}
```

---

## Integration with Plugin Commands

| Command | How it uses this reference |
|---------|--------------------------|
| `/pwdev-uiux:theme create` | Generates a customized version of the CSS template above |
| `/pwdev-uiux:theme validate` | Checks all foreground/background pairs against contrast requirements |
| `/pwdev-uiux:theme from-figma` | Maps Figma variables to this token structure |
| `/pwdev-uiux:scan` | Audits existing UI against these tokens |
| `/pwdev-uiux:push-to-figma tokens` | Syncs these tokens to Figma variables |