UI Theme Reference

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:

1. Colors

1.1 Surfaces

1.2 Text Hierarchy

1.3 Interactive

1.4 Feedback

1.5 Structure

1.6 Reserved Semantic Colors

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

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

1.7 Chart Palette

Dedicated colors for data visualization — independent from feedback semantics:

2. Typography

2.1 Font Stack

2.2 Type Scale

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

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

3. Spacing

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

Card Padding Rule

4. Sizing

4.1 Interactive Elements

4.2 Content Width

4.3 Textarea Height

Always enable auto-resize to grow with content.

5. Border Radius

Personality Guide

6. Shadows

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

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:

8. Breakpoints

Navigation Breakpoint Rules

9. Motion & Animation

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

10. Focus & Accessibility

Contrast Requirements (WCAG AA)

CSS Variable Template

Minimal starter for any project — copy and customize:

@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