@pcoi/tokens 0.1.0

package/build/tokens.scss

@@ -0,0 +1,270 @@
+// @pcoi/tokens — SCSS Variables
+// Generated 2026-03-03
+
+// Color Primitives
+$pcoi-color-bg: #0C0C14;
+$pcoi-color-bg-alt: #111120;
+$pcoi-color-bg-card: #16162A;
+$pcoi-color-bg-card-hover: #1C1C38;
+$pcoi-color-surface: #1A1A2E;
+$pcoi-color-accent: #D4A44C;
+$pcoi-color-accent-hover: #E0B560;
+$pcoi-color-text-primary: #E8E8F0;
+$pcoi-color-text-secondary: #9595B0;
+$pcoi-color-text-muted: #8585A0;
+$pcoi-color-success: #3DA87A;
+$pcoi-color-error: #E05252;
+$pcoi-color-warning: #E8943A;
+$pcoi-color-info: #5B8BD4;
+$pcoi-color-white: #FFFFFF;
+$pcoi-color-black: #000000;
+$pcoi-color-border: rgba(255, 255, 255, 0.35);
+$pcoi-color-border-hover: rgba(255, 255, 255, 0.45);
+$pcoi-color-border-soft: rgba(255, 255, 255, 0.06);
+$pcoi-color-border-soft-hover: rgba(255, 255, 255, 0.12);
+$pcoi-color-accent-glow: rgba(212, 164, 76, 0.15);
+$pcoi-color-accent-dim: rgba(212, 164, 76, 0.08);
+$pcoi-color-highlight: rgba(212, 164, 76, 0.06);
+$pcoi-color-nav-scrolled-bg: rgba(12, 12, 20, 0.92);
+$pcoi-color-ghost-hover-bg: rgba(255, 255, 255, 0.03);
+$pcoi-color-ghost-hover-border: rgba(255, 255, 255, 0.35);
+$pcoi-color-focus-border: rgba(212, 164, 76, 0.55);
+$pcoi-color-focus-glow: rgba(212, 164, 76, 0.08);
+$pcoi-color-accent-border-subtle: rgba(212, 164, 76, 0.58);
+$pcoi-color-accent-border-dim: rgba(212, 164, 76, 0.52);
+$pcoi-color-grid-line: rgba(255, 255, 255, 0.02);
+
+// Spacing
+$pcoi-spacing-0: 0px;
+$pcoi-spacing-4: 4px;
+$pcoi-spacing-5: 5px;
+$pcoi-spacing-6: 6px;
+$pcoi-spacing-8: 8px;
+$pcoi-spacing-10: 10px;
+$pcoi-spacing-12: 12px;
+$pcoi-spacing-14: 14px;
+$pcoi-spacing-16: 16px;
+$pcoi-spacing-20: 20px;
+$pcoi-spacing-22: 22px;
+$pcoi-spacing-24: 24px;
+$pcoi-spacing-28: 28px;
+$pcoi-spacing-32: 32px;
+$pcoi-spacing-36: 36px;
+$pcoi-spacing-40: 40px;
+$pcoi-spacing-48: 48px;
+$pcoi-spacing-60: 60px;
+$pcoi-spacing-64: 64px;
+$pcoi-spacing-72: 72px;
+$pcoi-spacing-80: 80px;
+$pcoi-spacing-100: 100px;
+$pcoi-spacing-120: 120px;
+
+// Radius
+$pcoi-radius-sm: 6px;
+$pcoi-radius-md: 12px;
+$pcoi-radius-lg: 20px;
+$pcoi-radius-xl: 28px;
+$pcoi-radius-full: 9999px;
+
+// Typography
+$pcoi-font-family-sans: 'Inter', -apple-system, BlinkMacSystemFont, 'Segoe UI', sans-serif;
+$pcoi-font-family-mono: 'JetBrains Mono', 'Fira Code', monospace;
+$pcoi-font-weight-light: 300;
+$pcoi-font-weight-regular: 400;
+$pcoi-font-weight-medium: 500;
+$pcoi-font-weight-semibold: 600;
+$pcoi-font-weight-bold: 700;
+$pcoi-font-weight-extrabold: 800;
+$pcoi-font-size-xs: 0.7rem;
+$pcoi-font-size-sm: 0.75rem;
+$pcoi-font-size-caption: 0.8rem;
+$pcoi-font-size-body-sm: 0.85rem;
+$pcoi-font-size-nav: 0.875rem;
+$pcoi-font-size-body: 0.9rem;
+$pcoi-font-size-body-default: 0.95rem;
+$pcoi-font-size-body-lg: 1rem;
+$pcoi-font-size-lead: 1.05rem;
+$pcoi-font-size-sub: 1.1rem;
+$pcoi-font-size-h3: 1.15rem;
+$pcoi-font-size-h3-lg: 1.2rem;
+$pcoi-font-size-logo: 1.35rem;
+$pcoi-font-size-callout: 1.35rem;
+$pcoi-font-size-close-sm: 1.25rem;
+$pcoi-font-size-close-lg: 1.5rem;
+$pcoi-font-size-h2-sm: 2.25rem;
+$pcoi-font-size-h2: 2.5rem;
+$pcoi-font-size-h1: 2.75rem;
+$pcoi-font-size-display: 4rem;
+$pcoi-font-lineHeight-none: 1;
+$pcoi-font-lineHeight-tight: 1.1;
+$pcoi-font-lineHeight-heading: 1.2;
+$pcoi-font-lineHeight-snug: 1.3;
+$pcoi-font-lineHeight-body-sm: 1.5;
+$pcoi-font-lineHeight-body: 1.6;
+$pcoi-font-lineHeight-step: 1.65;
+$pcoi-font-lineHeight-relaxed: 1.7;
+$pcoi-font-letterSpacing-tight: -0.03em;
+$pcoi-font-letterSpacing-heading: -0.02em;
+$pcoi-font-letterSpacing-normal: 0em;
+$pcoi-font-letterSpacing-logo: 0.04em;
+$pcoi-font-letterSpacing-label: 0.06em;
+$pcoi-font-letterSpacing-badge: 0.08em;
+$pcoi-font-letterSpacing-section: 0.1em;
+
+// Effects
+$pcoi-effect-shadow-btn-primary-hover: 0 8px 30px rgba(212, 164, 76, 0.25);
+$pcoi-effect-shadow-nav-scrolled: 0 1px 0 rgba(255, 255, 255, 0.06);
+$pcoi-effect-shadow-mobile-menu: 0 12px 40px rgba(0, 0, 0, 0.6);
+$pcoi-effect-shadow-focus-ring: 0 0 0 3px rgba(212, 164, 76, 0.08);
+$pcoi-effect-shadow-focus-ring-error: 0 0 0 3px rgba(224, 82, 82, 0.08);
+$pcoi-effect-shadow-elevated: 0 8px 32px rgba(0, 0, 0, 0.4);
+$pcoi-effect-blur-nav-backdrop: 20px;
+$pcoi-effect-transition-fast: 0.2s ease;
+$pcoi-effect-transition-medium: 0.3s ease;
+$pcoi-effect-transition-slow: 0.6s ease;
+$pcoi-effect-opacity-disabled: 0.5;
+$pcoi-effect-transform-hover-lift: translateY(-2px);
+$pcoi-effect-transform-hover-lift-sm: translateY(-1px);
+$pcoi-effect-transform-fade-in-offset: translateY(24px);
+$pcoi-effect-transform-parallax-factor: 0.15;
+$pcoi-effect-transform-press-scale: scale(0.985);
+$pcoi-effect-transform-press-scale-input: scale(0.99);
+$pcoi-effect-transform-press-scale-control: scale(0.95);
+$pcoi-effect-transform-press-scale-track: scale(0.975);
+$pcoi-effect-transform-press-scale-icon: scale(0.925);
+$pcoi-effect-transform-toggle-thumb-on: scale(1.15);
+
+// Layout
+$pcoi-layout-container-max: 1200px;
+$pcoi-layout-container-narrow: 800px;
+$pcoi-layout-container-cta: 680px;
+$pcoi-layout-container-callout: 600px;
+$pcoi-layout-container-chamath: 640px;
+$pcoi-layout-container-hero-sub: 520px;
+$pcoi-layout-container-compare: 900px;
+$pcoi-layout-container-wide: 1100px;
+$pcoi-layout-container-modal: 520px;
+$pcoi-layout-container-toast-min: 280px;
+$pcoi-layout-container-toast-max: 420px;
+$pcoi-layout-container-compare-scroll: 500px;
+$pcoi-layout-container-document: 900px;
+$pcoi-layout-nav-height: 72px;
+$pcoi-layout-breakpoint-desktop: 1025px;
+$pcoi-layout-breakpoint-tablet: 1024px;
+$pcoi-layout-breakpoint-mobile: 768px;
+$pcoi-layout-breakpoint-small: 480px;
+$pcoi-layout-zIndex-base: 1;
+$pcoi-layout-zIndex-content: 1;
+$pcoi-layout-zIndex-mobile-menu: 100;
+$pcoi-layout-zIndex-nav: 1000;
+$pcoi-layout-zIndex-dropdown: 200;
+$pcoi-layout-zIndex-modal: 500;
+$pcoi-layout-zIndex-toast: 600;
+$pcoi-layout-component-control-box: 18px;
+$pcoi-layout-component-radio-dot: 8px;
+$pcoi-layout-component-toggle-track-w: 40px;
+$pcoi-layout-component-toggle-track-h: 22px;
+$pcoi-layout-component-toggle-thumb: 16px;
+$pcoi-layout-component-toggle-thumb-inset: 3px;
+$pcoi-layout-component-toggle-thumb-travel: 18px;
+$pcoi-layout-component-toggle-check-w: 4px;
+$pcoi-layout-component-toggle-check-h: 7px;
+$pcoi-layout-component-toggle-check-stroke: 1.5px;
+$pcoi-layout-component-icon-box: 52px;
+$pcoi-layout-component-step-number: 48px;
+$pcoi-layout-component-hamburger: 28px;
+$pcoi-layout-component-hamburger-bar-offset: 7px;
+$pcoi-layout-component-accent-line-w: 60px;
+$pcoi-layout-component-accent-border-w: 3px;
+$pcoi-layout-component-bullet: 8px;
+
+// Sizing
+$pcoi-sizing-height-xs: 24px;
+$pcoi-sizing-height-sm: 32px;
+$pcoi-sizing-height-md: 40px;
+$pcoi-sizing-height-lg: 48px;
+$pcoi-sizing-height-xl: 64px;
+$pcoi-sizing-height-2xl: 80px;
+
+// Semantic Spacing
+$pcoi-semantic-spacing-section-y: {spacing.80};
+$pcoi-semantic-spacing-section-y-lg: {spacing.120};
+$pcoi-semantic-spacing-component-gap: {spacing.40};
+$pcoi-semantic-spacing-card-padding: {spacing.36};
+$pcoi-semantic-spacing-card-gap: {spacing.20};
+$pcoi-semantic-spacing-form-gap: {spacing.20};
+$pcoi-semantic-spacing-form-padding: {spacing.40};
+$pcoi-semantic-spacing-input-x: {spacing.16};
+$pcoi-semantic-spacing-input-y: {spacing.12};
+$pcoi-semantic-spacing-btn-x: {spacing.24};
+$pcoi-semantic-spacing-btn-y: {spacing.10};
+$pcoi-semantic-spacing-btn-x-lg: {spacing.36};
+$pcoi-semantic-spacing-btn-y-lg: {spacing.16};
+$pcoi-semantic-spacing-nav-height: {spacing.72};
+$pcoi-semantic-spacing-stack-sm: {spacing.8};
+$pcoi-semantic-spacing-stack-md: {spacing.16};
+$pcoi-semantic-spacing-stack-lg: {spacing.32};
+$pcoi-semantic-spacing-inline-sm: {spacing.8};
+$pcoi-semantic-spacing-inline-md: {spacing.16};
+
+// Semantic Radius
+$pcoi-semantic-radius-btn: {radius.sm};
+$pcoi-semantic-radius-input: {radius.sm};
+$pcoi-semantic-radius-card: {radius.md};
+$pcoi-semantic-radius-panel: {radius.lg};
+$pcoi-semantic-radius-badge: {radius.full};
+$pcoi-semantic-radius-avatar: {radius.full};
+
+// Semantic Sizing
+$pcoi-semantic-sizing-input-height: {sizing.height.md};
+$pcoi-semantic-sizing-btn-height: {sizing.height.md};
+$pcoi-semantic-sizing-btn-height-lg: {sizing.height.lg};
+$pcoi-semantic-sizing-btn-height-nav: {sizing.height.sm};
+$pcoi-semantic-sizing-textarea-min-height: {sizing.height.2xl};
+$pcoi-semantic-sizing-badge-height: {sizing.height.xs};
+$pcoi-semantic-sizing-step-number: {sizing.height.lg};
+$pcoi-semantic-sizing-icon-box: 52px;
+
+// Semantic Typography
+$pcoi-semantic-type-heading-font: {font.family.sans};
+$pcoi-semantic-type-body-font: {font.family.sans};
+$pcoi-semantic-type-mono-font: {font.family.mono};
+$pcoi-semantic-type-display-size: clamp(2.5rem, 5vw, 4rem);
+$pcoi-semantic-type-section-title-size: clamp(1.75rem, 3.5vw, 2.75rem);
+$pcoi-semantic-type-section-title-sm-size: clamp(1.75rem, 3.5vw, 2.5rem);
+$pcoi-semantic-type-section-title-xs-size: clamp(1.5rem, 3vw, 2.25rem);
+$pcoi-semantic-type-heading-md-size: {font.size.h3};
+$pcoi-semantic-type-heading-sm-size: {font.size.sub};
+$pcoi-semantic-type-step-title-size: {font.size.h3-lg};
+$pcoi-semantic-type-card-subtitle-size: {font.size.lead};
+$pcoi-semantic-type-body-size: {font.size.body-default};
+$pcoi-semantic-type-body-lg-size: {font.size.body-lg};
+$pcoi-semantic-type-body-compact-size: {font.size.body};
+$pcoi-semantic-type-body-sm-size: {font.size.body-sm};
+$pcoi-semantic-type-nav-size: {font.size.nav};
+$pcoi-semantic-type-label-size: {font.size.caption};
+$pcoi-semantic-type-section-label-size: {font.size.sm};
+$pcoi-semantic-type-badge-size: {font.size.xs};
+$pcoi-semantic-type-callout-size: {font.size.callout};
+$pcoi-semantic-type-logo-size: {font.size.logo};
+$pcoi-semantic-type-close-sm-size: {font.size.close-sm};
+$pcoi-semantic-type-close-lg-size: {font.size.close-lg};
+$pcoi-semantic-type-display-weight: {font.weight.extrabold};
+$pcoi-semantic-type-heading-weight: {font.weight.bold};
+$pcoi-semantic-type-emphasis-weight: {font.weight.semibold};
+$pcoi-semantic-type-label-weight: {font.weight.medium};
+$pcoi-semantic-type-body-weight: {font.weight.regular};
+$pcoi-semantic-type-callout-weight: {font.weight.light};
+$pcoi-semantic-type-display-line-height: {font.lineHeight.tight};
+$pcoi-semantic-type-heading-line-height: {font.lineHeight.heading};
+$pcoi-semantic-type-body-line-height: {font.lineHeight.body};
+$pcoi-semantic-type-body-compact-line-height: {font.lineHeight.body-sm};
+$pcoi-semantic-type-step-line-height: {font.lineHeight.step};
+$pcoi-semantic-type-relaxed-line-height: {font.lineHeight.relaxed};
+$pcoi-semantic-type-none-line-height: {font.lineHeight.none};
+$pcoi-semantic-type-display-letter-spacing: {font.letterSpacing.tight};
+$pcoi-semantic-type-heading-letter-spacing: {font.letterSpacing.heading};
+$pcoi-semantic-type-label-letter-spacing: {font.letterSpacing.label};
+$pcoi-semantic-type-section-label-letter-spacing: {font.letterSpacing.section};
+$pcoi-semantic-type-badge-letter-spacing: {font.letterSpacing.badge};
+$pcoi-semantic-type-logo-letter-spacing: {font.letterSpacing.logo};

package/package.json

@@ -0,0 +1,29 @@
+{
+  "name": "@pcoi/tokens",
+  "version": "0.1.0",
+  "description": "PCOI Design System — Foundation tokens (colors, spacing, typography, effects)",
+  "main": "build/index.js",
+  "module": "build/index.mjs",
+  "types": "build/index.d.ts",
+  "files": [
+    "build/**/*",
+    "src/**/*"
+  ],
+  "exports": {
+    ".": {
+      "import": "./build/index.mjs",
+      "require": "./build/index.js",
+      "types": "./build/index.d.ts"
+    },
+    "./css": "./build/tokens.css",
+    "./scss": "./build/tokens.scss",
+    "./json": "./build/tokens.json"
+  },
+  "scripts": {
+    "build": "node build-tokens.js",
+    "clean": "rm -rf build"
+  },
+  "keywords": ["design-tokens", "pcoi", "design-system"],
+  "license": "MIT",
+  "sideEffects": false
+}

package/src/color/light.json

@@ -0,0 +1,52 @@
+{
+  "$description": "Light theme overrides — only values that differ from the dark (default) theme.",
+
+  "color": {
+    "$type": "color",
+    "bg":               { "$value": "#F5F5FA", "$description": "Page background — cool light grey" },
+    "bg-alt":           { "$value": "#EEEEF6", "$description": "Alternating section background" },
+    "bg-card":          { "$value": "#FFFFFF", "$description": "Card and panel background — pure white" },
+    "bg-card-hover":    { "$value": "#F8F8FD", "$description": "Card background on hover" },
+    "surface":          { "$value": "#FFFFFF", "$description": "Forms, callouts, elevated containers" },
+    "accent":           { "$value": "#A8801E", "$description": "Brand gold — darkened for WCAG AA 3:1 toggle/4.5:1 button text on light" },
+    "accent-hover":     { "$value": "#A07520", "$description": "Accent gold on hover — richer" },
+    "text-primary":     { "$value": "#1A1A2E", "$description": "Primary text — dark navy" },
+    "text-secondary":   { "$value": "#4A4A68", "$description": "Secondary text — medium grey-blue" },
+    "text-muted":       { "$value": "#6A6A86", "$description": "Muted text — darkened for WCAG AA 4.5:1 on light backgrounds" },
+    "success":          { "$value": "#1B6B4A", "$description": "Success green — darker for light bg" },
+    "error":            { "$value": "#C03C3C", "$description": "Error red — darker for light bg" },
+    "warning":          { "$value": "#C07828", "$description": "Warning amber — darker for light bg" },
+    "info":             { "$value": "#4068B8", "$description": "Info blue — darker for light bg" },
+    "border":           { "$value": "rgba(0, 0, 0, 0.45)", "$description": "Default border — black at 45% for WCAG AA 3:1 on light backgrounds" },
+    "border-hover":     { "$value": "rgba(0, 0, 0, 0.55)", "$description": "Hovered border — black at 55% for WCAG AA 3:1+ on light backgrounds" },
+    "border-soft":      { "$value": "rgba(0, 0, 0, 0.10)", "$description": "Soft decorative border — cards, panels (no WCAG contrast required)" },
+    "border-soft-hover":{ "$value": "rgba(0, 0, 0, 0.18)", "$description": "Soft decorative border on hover — cards, panels" },
+    "accent-glow":      { "$value": "rgba(184, 137, 42, 0.15)", "$description": "Accent glow for shadows" },
+    "accent-dim":       { "$value": "rgba(184, 137, 42, 0.06)", "$description": "Accent-tinted background" },
+    "highlight":        { "$value": "rgba(184, 137, 42, 0.04)", "$description": "Subtle accent highlight" },
+    "nav-scrolled-bg":  { "$value": "rgba(245, 245, 250, 0.92)", "$description": "Nav bg on scroll — semi-transparent light" },
+    "ghost-hover-bg":   { "$value": "rgba(0, 0, 0, 0.04)", "$description": "Ghost button hover background" },
+    "ghost-hover-border": { "$value": "rgba(0, 0, 0, 0.45)", "$description": "Ghost button hover border — WCAG AA 3:1 on light backgrounds" },
+    "focus-border":     { "$value": "rgba(120, 90, 10, 0.70)", "$description": "Input focus border — darker gold at 70% for WCAG AA 3:1+ on light backgrounds" },
+    "focus-glow":       { "$value": "rgba(184, 137, 42, 0.12)", "$description": "Input focus outer ring glow" },
+    "accent-border-subtle": { "$value": "rgba(80, 60, 5, 0.65)", "$description": "Accent border — darker gold at 65% for WCAG AA 3:1 on light backgrounds" },
+    "accent-border-dim":    { "$value": "rgba(80, 60, 5, 0.60)", "$description": "Accent border dim — darker gold at 60% for WCAG AA 3:1 on light backgrounds" },
+    "grid-line":        { "$value": "rgba(0, 0, 0, 0.04)", "$description": "Background grid lines" }
+  },
+
+  "semantic-overrides": {
+    "$description": "Semantic tokens with hardcoded values that need light-theme adjustment",
+    "text-on-accent":     { "$value": "#1A1A2E", "cssVar": "--pcoi-semantic-text-on-accent", "$description": "Dark text on accent backgrounds (buttons)" },
+    "action-primary-text":{ "$value": "#1A1A2E", "cssVar": "--pcoi-semantic-action-primary-text", "$description": "Primary button text stays dark on gold" },
+    "action-toggle-thumb":{ "$value": "#FFFFFF", "cssVar": "--pcoi-semantic-action-toggle-thumb", "$description": "Toggle thumb stays white" },
+    "text-accent":        { "$value": "#7A5C1A", "cssVar": "--pcoi-semantic-text-accent",         "$description": "Darker gold for WCAG AA 4.5:1 text on light backgrounds" },
+    "text-warning":       { "$value": "#9A5E18", "cssVar": "--pcoi-semantic-text-warning",        "$description": "Darker amber for WCAG AA 4.5:1 text on light backgrounds" }
+  },
+
+  "effect-overrides": {
+    "$description": "Effect tokens that need light-theme adjustment",
+    "shadow-nav-scrolled": { "$value": "0 1px 0 rgba(0, 0, 0, 0.08)", "cssVar": "--pcoi-effect-shadow-nav-scrolled", "$description": "Nav hairline — dark instead of light" },
+    "shadow-mobile-menu":  { "$value": "0 12px 40px rgba(0, 0, 0, 0.12)", "cssVar": "--pcoi-effect-shadow-mobile-menu", "$description": "Lighter mobile menu shadow" },
+    "shadow-elevated":     { "$value": "0 8px 32px rgba(0, 0, 0, 0.10)", "cssVar": "--pcoi-effect-shadow-elevated", "$description": "Lighter elevated shadow for modals" }
+  }
+}

package/src/color/primitives.json

@@ -0,0 +1,130 @@
+{
+  "color": {
+    "$type": "color",
+    "$description": "Tier 1: Primitive color values. Never apply directly to designs.",
+    "bg": {
+      "$value": "#0C0C14",
+      "$description": "Primary page background — deep navy-black"
+    },
+    "bg-alt": {
+      "$value": "#111120",
+      "$description": "Alternating section background — slightly lighter"
+    },
+    "bg-card": {
+      "$value": "#16162A",
+      "$description": "Card and panel background"
+    },
+    "bg-card-hover": {
+      "$value": "#1C1C38",
+      "$description": "Card background on hover state"
+    },
+    "surface": {
+      "$value": "#1A1A2E",
+      "$description": "Elevated surface — forms, callouts, input containers"
+    },
+    "accent": {
+      "$value": "#D4A44C",
+      "$description": "Brand gold — primary accent color"
+    },
+    "accent-hover": {
+      "$value": "#E0B560",
+      "$description": "Accent gold on hover — lighter/warmer"
+    },
+    "text-primary": {
+      "$value": "#E8E8F0",
+      "$description": "Primary text — off-white with slight blue tint"
+    },
+    "text-secondary": {
+      "$value": "#9595B0",
+      "$description": "Secondary text — muted lavender-grey"
+    },
+    "text-muted": {
+      "$value": "#8585A0",
+      "$description": "Muted text — placeholders, footnotes (WCAG AA compliant on surface)"
+    },
+    "success": {
+      "$value": "#3DA87A",
+      "$description": "Success/confirmation green — WCAG AA 4.5:1+ on dark backgrounds"
+    },
+    "error": {
+      "$value": "#E05252",
+      "$description": "Error/destructive red — validation errors, alerts"
+    },
+    "warning": {
+      "$value": "#E8943A",
+      "$description": "Warning amber — caution states, deprecation notices"
+    },
+    "info": {
+      "$value": "#5B8BD4",
+      "$description": "Informational blue — tips, help text, neutral alerts"
+    },
+    "white": {
+      "$value": "#FFFFFF",
+      "$description": "Pure white — used in alpha calculations"
+    },
+    "black": {
+      "$value": "#000000",
+      "$description": "Pure black — used in shadow calculations"
+    },
+    "border": {
+      "$value": "rgba(255, 255, 255, 0.35)",
+      "$description": "Default border — white at 35% for WCAG AA 3:1 on dark backgrounds"
+    },
+    "border-hover": {
+      "$value": "rgba(255, 255, 255, 0.45)",
+      "$description": "Hovered border — white at 45% for WCAG AA 3:1+ on dark backgrounds"
+    },
+    "border-soft": {
+      "$value": "rgba(255, 255, 255, 0.06)",
+      "$description": "Soft decorative border — cards, panels (no WCAG contrast required)"
+    },
+    "border-soft-hover": {
+      "$value": "rgba(255, 255, 255, 0.12)",
+      "$description": "Soft decorative border on hover — cards, panels"
+    },
+    "accent-glow": {
+      "$value": "rgba(212, 164, 76, 0.15)",
+      "$description": "Accent glow for shadows and overlays"
+    },
+    "accent-dim": {
+      "$value": "rgba(212, 164, 76, 0.08)",
+      "$description": "Accent-tinted background — badges, icon boxes, step numbers"
+    },
+    "highlight": {
+      "$value": "rgba(212, 164, 76, 0.06)",
+      "$description": "Subtle accent highlight — comparison column bg"
+    },
+    "nav-scrolled-bg": {
+      "$value": "rgba(12, 12, 20, 0.92)",
+      "$description": "Navigation background on scroll — semi-transparent dark"
+    },
+    "ghost-hover-bg": {
+      "$value": "rgba(255, 255, 255, 0.03)",
+      "$description": "Ghost button hover background"
+    },
+    "ghost-hover-border": {
+      "$value": "rgba(255, 255, 255, 0.35)",
+      "$description": "Ghost button hover border — WCAG AA 3:1 on dark backgrounds"
+    },
+    "focus-border": {
+      "$value": "rgba(212, 164, 76, 0.55)",
+      "$description": "Input focus border — accent at 55% for WCAG AA 3:1+ visibility"
+    },
+    "focus-glow": {
+      "$value": "rgba(212, 164, 76, 0.08)",
+      "$description": "Input focus outer ring glow"
+    },
+    "accent-border-subtle": {
+      "$value": "rgba(212, 164, 76, 0.58)",
+      "$description": "Accent border — badges, principle hover — WCAG AA 3:1"
+    },
+    "accent-border-dim": {
+      "$value": "rgba(212, 164, 76, 0.52)",
+      "$description": "Accent border dim — step number circles — WCAG AA 3:1"
+    },
+    "grid-line": {
+      "$value": "rgba(255, 255, 255, 0.02)",
+      "$description": "Hero background grid lines"
+    }
+  }
+}

package/src/color/semantics.json

@@ -0,0 +1,90 @@
+{
+  "semantic": {
+    "$description": "Tier 2/3: Semantic tokens that reference primitives. Apply ONLY these to designs and code.",
+
+    "bg": {
+      "$type": "color",
+      "$description": "Background semantics",
+      "default":       { "$value": "{color.bg}",            "$description": "Page-level background" },
+      "alt":           { "$value": "{color.bg-alt}",        "$description": "Alternating dark sections (.section-dark)" },
+      "card":          { "$value": "{color.bg-card}",       "$description": "Card and panel fills" },
+      "card-hover":    { "$value": "{color.bg-card-hover}", "$description": "Card fills on hover" },
+      "surface":       { "$value": "{color.surface}",       "$description": "Forms, callouts, elevated containers" },
+      "nav-scrolled":  { "$value": "{color.nav-scrolled-bg}", "$description": "Navbar after scroll" },
+      "overlay":       { "$value": "rgba(0, 0, 0, 0.6)",      "$description": "Modal/dialog backdrop overlay" }
+    },
+
+    "text": {
+      "$type": "color",
+      "$description": "Text color semantics",
+      "primary":   { "$value": "{color.text-primary}",   "$description": "Headings, body, primary content" },
+      "secondary": { "$value": "{color.text-secondary}", "$description": "Descriptions, supporting text, nav links" },
+      "muted":     { "$value": "{color.text-muted}",     "$description": "Placeholders, footnotes, timestamps" },
+      "accent":       { "$value": "{color.accent}",          "$description": "Badges, labels, section labels, emphasis" },
+      "accent-hover": { "$value": "{color.accent-hover}",  "$description": "Accent text on hover (links, interactive)" },
+      "on-accent":    { "$value": "{color.bg}",             "$description": "Text on accent-colored backgrounds" },
+      "success":   { "$value": "{color.success}",        "$description": "Success message text" },
+      "error":     { "$value": "{color.error}",          "$description": "Error message text and required indicators" },
+      "warning":   { "$value": "{color.warning}",        "$description": "Warning message text" },
+      "info":      { "$value": "{color.info}",            "$description": "Info message text" }
+    },
+
+    "action": {
+      "$type": "color",
+      "$description": "Interactive/button semantics",
+      "primary-bg":          { "$value": "{color.accent}",        "$description": "Primary button background" },
+      "primary-bg-hover":    { "$value": "{color.accent-hover}",  "$description": "Primary button hover background" },
+      "primary-text":        { "$value": "{color.bg}",            "$description": "Primary button text (dark on gold)" },
+      "ghost-bg":            { "$value": "transparent",           "$description": "Ghost button default background" },
+      "ghost-bg-hover":      { "$value": "{color.ghost-hover-bg}", "$description": "Ghost button hover background" },
+      "ghost-border":        { "$value": "{color.border-hover}",  "$description": "Ghost button border" },
+      "ghost-border-hover":  { "$value": "{color.ghost-hover-border}", "$description": "Ghost button hover border" },
+      "ghost-text":          { "$value": "{color.text-secondary}", "$description": "Ghost button text" },
+      "ghost-text-hover":    { "$value": "{color.text-primary}",  "$description": "Ghost button hover text" },
+      "toggle-bg":           { "$value": "{color.border-hover}",   "$description": "Toggle track background in off state" },
+      "toggle-bg-on":        { "$value": "{color.accent}",         "$description": "Toggle track background in on state" },
+      "toggle-thumb":        { "$value": "#FFFFFF",                 "$description": "Toggle thumb (circle) color" },
+      "success":             { "$value": "{color.success}",       "$description": "Form submission success state" },
+      "error":               { "$value": "{color.error}",         "$description": "Validation errors, destructive actions" },
+      "warning":             { "$value": "{color.warning}",       "$description": "Caution states, deprecation notices" },
+      "info":                { "$value": "{color.info}",          "$description": "Informational tips and neutral alerts" },
+      "success-bg":          { "$value": "rgba(42, 125, 95, 0.08)",  "$description": "Subtle success background tint for badges and status indicators" },
+      "error-bg":            { "$value": "rgba(224, 82, 82, 0.08)", "$description": "Subtle error background tint for invalid form fields" },
+      "warning-bg":          { "$value": "rgba(232, 148, 58, 0.08)", "$description": "Subtle warning background tint for badges and status indicators" },
+      "info-bg":             { "$value": "rgba(91, 139, 212, 0.08)", "$description": "Subtle info background tint for badges and status indicators" }
+    },
+
+    "border": {
+      "$type": "color",
+      "$description": "Border semantics",
+      "default":       { "$value": "{color.border}",              "$description": "Default card/section borders" },
+      "hover":         { "$value": "{color.border-hover}",        "$description": "Borders on hover state" },
+      "card":          { "$value": "{color.border-soft}",         "$description": "Soft decorative card border — no WCAG requirement" },
+      "card-hover":    { "$value": "{color.border-soft-hover}",   "$description": "Soft decorative card border on hover" },
+      "accent-subtle": { "$value": "{color.accent-border-subtle}","$description": "Accent-tinted borders (principle hover)" },
+      "accent-dim":    { "$value": "{color.accent-border-dim}",   "$description": "Dim accent borders (step numbers)" },
+      "nav":           { "$value": "{color.border}",              "$description": "Nav scrolled bottom border" },
+      "input-hover":   { "$value": "{color.border-hover}",      "$description": "Form input border on hover" },
+      "success":       { "$value": "{color.success}",          "$description": "Success state border" },
+      "error":         { "$value": "{color.error}",              "$description": "Invalid form field border" },
+      "warning":       { "$value": "{color.warning}",          "$description": "Warning state border" },
+      "info":          { "$value": "{color.info}",              "$description": "Info state border" }
+    },
+
+    "surface": {
+      "$type": "color",
+      "$description": "Surface fill semantics",
+      "accent-dim":   { "$value": "{color.accent-dim}",   "$description": "Icon boxes, badges, step number bg, comparison highlight" },
+      "accent-glow":  { "$value": "{color.accent-glow}",  "$description": "Shadow glow on accent actions" },
+      "highlight":    { "$value": "{color.highlight}",     "$description": "Subtle highlight backgrounds" },
+      "elevated":     { "$value": "{color.bg-card}",      "$description": "Elevated surface for modals, dropdowns" }
+    },
+
+    "focus": {
+      "$type": "color",
+      "$description": "Focus state semantics",
+      "border": { "$value": "{color.focus-border}", "$description": "Input focus border color" },
+      "glow":   { "$value": "{color.focus-glow}",   "$description": "Input focus outer ring (box-shadow)" }
+    }
+  }
+}