PixelPilot uiux-tokens.instructions.md

UI/UX Tokens & Design System

Brand token system, 3-tier token architecture (Figma-aligned), CSS variables, gradient rules, font pairings, shadow/elevation tokens, animation tokens.

---

TOKEN ARCHITECTURE — 3 Tiers (Figma-aligned, W3C standard)

Based on Figma Variables best practice: Primitive → Semantic → Component. Only semantic tokens go in components. Never use primitives directly in UI.

Tier 1 — PRIMITIVE (raw values, never applied directly)
  --primitive-blue-500: #3B82F6
  --primitive-space-4:  16px

Tier 2 — SEMANTIC (how/where to use — these are your CSS vars)
  --accent:   var(--primitive-blue-500)   → "the primary action color"
  --space-4:  var(--primitive-space-4)    → "standard spacing unit"

Tier 3 — COMPONENT (optional, large teams / complex systems)
  --btn-bg:         var(--accent)
  --btn-bg-hover:   color-mix(in srgb, var(--accent) 85%, black)

For most projects: Tier 1 + Tier 2 is enough. Add Tier 3 only when the same semantic token is used differently in many components.

---

STEP 1 — Brand Token System (CONSISTENCY ACROSS ALL PAGES)

This is the #1 consistency rule. Define ALL tokens once in :root / a global CSS file / theme provider. Import it on every page. Never redefine brand colors inline.

Token Architecture

/* ================================================
   BRAND TOKEN FILE — tokens.css (import everywhere)
   One file. All pages. Never override.
   ================================================ */

:root {
  /* FONTS — set once, use everywhere */
  --font-display: 'YOUR_DISPLAY_FONT', serif;
  --font-body:    'YOUR_BODY_FONT', sans-serif;
  --font-mono:    'YOUR_MONO_FONT', monospace;

  /* TYPE SCALE — never use raw px in components */
  --text-xs:   0.75rem;
  --text-sm:   0.875rem;
  --text-base: 1rem;
  --text-lg:   1.125rem;
  --text-xl:   1.25rem;
  --text-2xl:  1.5rem;
  --text-3xl:  1.875rem;
  --text-4xl:  2.25rem;
  --text-5xl:  3rem;
  --text-6xl:  3.75rem;
  --text-hero: clamp(3rem, 8vw, 8rem);

  /* SPACING — 8px grid, never use arbitrary values */
  --space-1: 4px;   --space-2: 8px;   --space-3: 12px;
  --space-4: 16px;  --space-6: 24px;  --space-8: 32px;
  --space-12: 48px; --space-16: 64px; --space-20: 80px;
  --space-24: 96px; --space-30: 120px;--space-40: 160px;

  /* RADIUS — set per design language, never change per-page */
  --radius-sm: Xpx;  /* set from table below */
  --radius-md: Xpx;
  --radius-lg: Xpx;
  --radius-full: 9999px;

  /* EASING */
  --ease-spring:  cubic-bezier(0.34, 1.56, 0.64, 1);
  --ease-out:     cubic-bezier(0.16, 1, 0.3, 1);
  --ease-sharp:   cubic-bezier(0.4, 0, 0.2, 1);
  --ease-luxury:  cubic-bezier(0.25, 0.1, 0, 1);

  /* LAYOUT */
  --container-max:    1280px; /* set per language */
  --container-gutter: 24px;   /* set per language, responsive */
  --section-space-sm: 48px;   /* mobile */
  --section-space-md: 64px;   /* tablet */
  --section-space-lg: 96px;   /* desktop */

  /* TRANSITIONS */
  --transition-fast:   150ms var(--ease-sharp);
  --transition-base:   250ms var(--ease-out);
  --transition-slow:   400ms var(--ease-luxury);
  --transition-spring: 350ms var(--ease-spring);

  /* MICRO-INTERACTION TOKENS */
  --transition-micro:    100ms ease;
  --transition-tactile:  250ms cubic-bezier(0.2, 0.9, 0.4, 1.1);
  --transition-reveal:   600ms var(--ease-out);

  /* ANIMATION DURATION TOKENS */
  --duration-instant:  100ms;
  --duration-fast:     200ms;
  --duration-base:     350ms;
  --duration-slow:     600ms;
  --duration-lazy:     900ms;

  /* ELEVATION (shadow) TOKENS — values set per language below */
  --shadow-sm:  0 1px 3px rgba(0,0,0,0.08), 0 1px 2px rgba(0,0,0,0.04);
  --shadow-md:  0 4px 16px rgba(0,0,0,0.10), 0 2px 4px rgba(0,0,0,0.06);
  --shadow-lg:  0 12px 40px rgba(0,0,0,0.14), 0 4px 8px rgba(0,0,0,0.06);
  --shadow-xl:  0 24px 64px rgba(0,0,0,0.18), 0 8px 16px rgba(0,0,0,0.08);
  --shadow-inner: inset 0 2px 8px rgba(0,0,0,0.08);
  --shadow-none:  none;

  /* THIRD-PARTY BRAND COLORS (v10.1) — use for social share, integrations */
  --brand-twitter:          #1DA1F2;
  --brand-twitter-hover:    #1a8cd8;
  --brand-linkedin:         #0A66C2;
  --brand-linkedin-hover:   #095196;
  --brand-facebook:         #1877F2;
  --brand-facebook-hover:   #166fe5;
  --brand-whatsapp:         #25D366;
  --brand-whatsapp-hover:   #22c35e;
  --brand-youtube:          #FF0000;
  --brand-youtube-hover:    #cc0000;
  --brand-instagram:        #E4405F;
  --brand-instagram-hover:  #d62e4c;
  --brand-github:           #181717;
  --brand-github-hover:     #333333;
  --brand-discord:          #5865F2;
  --brand-discord-hover:    #4752c4;
}

/* THEME COLORS — both modes, always together */
[data-theme="light"] {
  --bg:          #XXXXXX;  /* fill from table below */
  --surface:     #XXXXXX;
  --surface-up:  #XXXXXX;
  --text:        #XXXXXX;
  --text-2:      #XXXXXX;
  --muted:       #XXXXXX;
  --border:      rgba(X,X,X,0.XX);
  --accent:      #XXXXXX;
  --accent-h:    #XXXXXX;  /* hover state */
  --overlay:     rgba(X,X,X,0.XX);
  --gradient:    /* set from gradient table below */;
}
[data-theme="dark"] { /* same tokens, dark values */ }