@fpkit/acss 3.9.0 → 4.1.0

package/src/styles/index.css

@@ -1,4 +1,236 @@
 @charset "UTF-8";
+/**
+ * Color Tokens - Main Export
+ *
+ * This file exports the complete color token system.
+ * Import order matters: primitives must load before semantic tokens.
+ *
+ * Usage in main index.scss:
+ * @use "./sass/tokens";
+ */
+/* Tier 1: Primitive color scales (foundation) */
+/**
+ * Color Primitives - Foundation Layer (Tier 1)
+ *
+ * Raw color values that form the foundation of the design system.
+ * All colors are WCAG AA compliant (4.5:1 for text, 3:1 for UI components).
+ *
+ * Pattern: --color-{hue}-{scale}
+ * Scale: 50 (lightest) to 900 (darkest)
+ *
+ * Industry-standard palette based on accessible color scales.
+ * No rebeccapurple or purple colors per project requirements.
+ */
+:root {
+  /* ========================================
+     Neutral Scale (Grays)
+     Purpose: Text, borders, surfaces, backgrounds
+     ======================================== */
+  --color-neutral-0: #ffffff; /* Pure white - Surfaces, text inverse */
+  --color-neutral-50: #fafafa; /* Off-white - Secondary surfaces */
+  --color-neutral-100: #f5f5f5; /* Light gray - Disabled backgrounds, tertiary surfaces */
+  --color-neutral-200: #e5e5e5; /* Border subtle - Light borders, dividers */
+  --color-neutral-300: #d4d4d4; /* Border default - Standard borders */
+  --color-neutral-400: #a3a3a3; /* Border interactive - Hover borders, interactive elements */
+  --color-neutral-500: #737373; /* Text disabled - Disabled text, placeholders */
+  --color-neutral-600: #525252; /* Text tertiary - Less emphasized text */
+  --color-neutral-700: #404040; /* Text secondary - Secondary text */
+  --color-neutral-800: #262626; /* Text primary - Body text, primary content */
+  --color-neutral-900: #171717; /* Text emphasis - Headings, emphasized text */
+  /* ========================================
+     Blue Scale (Primary/Info)
+     Purpose: Primary brand, focus states, links, info messages
+     WCAG: 4.5:1+ contrast ratios verified
+     ======================================== */
+  --color-blue-100: #dbeafe; /* Info background light - Subtle info backgrounds */
+  --color-blue-200: #bfdbfe; /* Info background - Info alert backgrounds */
+  --color-blue-300: #93c5fd; /* Info border light - Light info borders */
+  --color-blue-400: #60a5fa; /* Info hover - Hover states for info elements */
+  --color-blue-500: #3b82f6; /* Info default - Standard info color */
+  --color-blue-600: #2563eb; /* Primary default - Primary brand color */
+  --color-blue-700: #1d4ed8; /* Primary hover - Primary button hover */
+  --color-blue-800: #1e40af; /* Primary active - Primary button active/pressed */
+  --color-blue-900: #1e3a8a; /* Info text - Dark text on info backgrounds (WCAG AAA: 12.6:1) */
+  /* ========================================
+     Green Scale (Success)
+     Purpose: Success states, positive feedback, valid inputs
+     WCAG: 4.5:1+ contrast ratios verified
+     ======================================== */
+  --color-green-100: #dcfce7; /* Success background light - Subtle success backgrounds */
+  --color-green-200: #bbf7d0; /* Success background - Success alert backgrounds */
+  --color-green-300: #86efac; /* Success border light - Light success borders */
+  --color-green-400: #4ade80; /* Success hover - Hover states for success elements */
+  --color-green-500: #22c55e; /* Success default - Standard success color */
+  --color-green-600: #16a34a; /* Success border - Success borders, checkmarks */
+  --color-green-700: #15803d; /* Success dark - Dark success emphasis */
+  --color-green-800: #166534; /* Success text - Dark text on success backgrounds (WCAG AAA: 8.3:1) */
+  --color-green-900: #14532d; /* Success emphasis - Highest contrast success text */
+  /* ========================================
+     Red Scale (Error/Danger)
+     Purpose: Errors, destructive actions, invalid inputs, alerts
+     WCAG: 4.5:1+ contrast ratios verified
+     ======================================== */
+  --color-red-100: #fee2e2; /* Error background light - Subtle error backgrounds */
+  --color-red-200: #fecaca; /* Error background - Error alert backgrounds */
+  --color-red-300: #fca5a5; /* Error border light - Light error borders */
+  --color-red-400: #f87171; /* Error hover - Hover states for error elements */
+  --color-red-500: #ef4444; /* Error default - Standard error color */
+  --color-red-600: #dc2626; /* Error border - Error borders, icons */
+  --color-red-700: #b91c1c; /* Error dark - Dark error emphasis */
+  --color-red-800: #991b1b; /* Error text - Dark text on error backgrounds (WCAG AAA: 10.3:1) */
+  --color-red-900: #7f1d1d; /* Error emphasis - Highest contrast error text */
+  /* ========================================
+     Amber Scale (Warning)
+     Purpose: Warnings, cautions, pending states
+     WCAG: 4.5:1+ contrast ratios verified
+     ======================================== */
+  --color-amber-100: #fef3c7; /* Warning background light - Subtle warning backgrounds */
+  --color-amber-200: #fde68a; /* Warning background - Warning alert backgrounds */
+  --color-amber-300: #fcd34d; /* Warning border light - Light warning borders */
+  --color-amber-400: #fbbf24; /* Warning hover - Hover states for warning elements */
+  --color-amber-500: #f59e0b; /* Warning default - Standard warning color */
+  --color-amber-600: #d97706; /* Warning border - Warning borders, icons */
+  --color-amber-700: #b45309; /* Warning dark - Dark warning emphasis */
+  --color-amber-800: #92400e; /* Warning text - Dark text on warning backgrounds (WCAG AAA: 9.8:1) */
+  --color-amber-900: #78350f; /* Warning emphasis - Highest contrast warning text */
+  /* ========================================
+     Cyan Scale (Info Alternative)
+     Purpose: Alternative info states, highlights, accents
+     WCAG: 4.5:1+ contrast ratios verified
+     Note: Used instead of purple/rebeccapurple per requirements
+     ======================================== */
+  --color-cyan-100: #cffafe; /* Info alt background light - Subtle cyan backgrounds */
+  --color-cyan-200: #a5f3fc; /* Info alt background - Cyan alert backgrounds */
+  --color-cyan-300: #67e8f9; /* Info alt border light - Light cyan borders */
+  --color-cyan-400: #22d3ee; /* Info alt hover - Hover states for cyan elements */
+  --color-cyan-500: #06b6d4; /* Info alt default - Standard cyan color */
+  --color-cyan-600: #0891b2; /* Info alt border - Cyan borders, icons */
+  --color-cyan-700: #0e7490; /* Info alt dark - Dark cyan emphasis */
+  --color-cyan-800: #155e75; /* Info alt text - Dark text on cyan backgrounds (WCAG AAA: 7.2:1) */
+  --color-cyan-900: #164e63; /* Info alt emphasis - Highest contrast cyan text */
+}
+
+/* Tier 2: Semantic color mappings (purpose-based) */
+/**
+ * Color Semantic Tokens - Purpose Layer (Tier 2)
+ *
+ * Intent-based color mappings for common use cases.
+ * All semantic tokens reference primitive tokens (Tier 1).
+ *
+ * Pattern: --color-{purpose}-{variant}
+ *
+ * This layer provides meaning to colors and enables easy theming.
+ * To theme the application, override these semantic tokens.
+ */
+:root {
+  /* ========================================
+     Brand Colors
+     Purpose: Primary and secondary brand identity
+     ======================================== */
+  /* Primary brand color - Main CTAs, primary buttons, primary links */
+  --color-primary: var(--color-blue-600); /* #2563eb */
+  --color-primary-hover: var(--color-blue-700); /* #1d4ed8 */
+  --color-primary-active: var(--color-blue-800); /* #1e40af */
+  --color-primary-light: var(--color-blue-100); /* #dbeafe */
+  /* Secondary brand color - Secondary actions, alternative emphasis */
+  --color-secondary: var(--color-neutral-700); /* #404040 */
+  --color-secondary-hover: var(--color-neutral-800); /* #262626 */
+  --color-secondary-light: var(--color-neutral-100); /* #f5f5f5 */
+  /* ========================================
+     State Colors - Success
+     Purpose: Positive feedback, valid inputs, confirmations
+     ======================================== */
+  --color-success: var(--color-green-600); /* #16a34a */
+  --color-success-bg: var(--color-green-100); /* #dcfce7 */
+  --color-success-border: var(--color-green-600); /* #16a34a */
+  --color-success-text: var(--color-green-800); /* #166534 */
+  --color-success-hover: var(--color-green-700); /* #15803d */
+  /* ========================================
+     State Colors - Error
+     Purpose: Errors, validation failures, destructive actions
+     ======================================== */
+  --color-error: var(--color-red-600); /* #dc2626 */
+  --color-error-bg: var(--color-red-100); /* #fee2e2 */
+  --color-error-border: var(--color-red-600); /* #dc2626 */
+  --color-error-text: var(--color-red-800); /* #991b1b */
+  --color-error-hover: var(--color-red-700); /* #b91c1c */
+  /* ========================================
+     State Colors - Warning
+     Purpose: Warnings, cautions, pending actions
+     ======================================== */
+  --color-warning: var(--color-amber-600); /* #d97706 */
+  --color-warning-bg: var(--color-amber-100); /* #fef3c7 */
+  --color-warning-border: var(--color-amber-600); /* #d97706 */
+  --color-warning-text: var(--color-amber-800); /* #92400e */
+  --color-warning-hover: var(--color-amber-700); /* #b45309 */
+  /* ========================================
+     State Colors - Info
+     Purpose: Informational messages, tips, notices
+     ======================================== */
+  --color-info: var(--color-blue-500); /* #3b82f6 */
+  --color-info-bg: var(--color-blue-100); /* #dbeafe */
+  --color-info-border: var(--color-blue-500); /* #3b82f6 */
+  --color-info-text: var(--color-blue-900); /* #1e3a8a */
+  --color-info-hover: var(--color-blue-600); /* #2563eb */
+  /* ========================================
+     UI Surface Colors
+     Purpose: Backgrounds, containers, cards, modals
+     ======================================== */
+  --color-surface: var(--color-neutral-0); /* #ffffff - Primary background */
+  --color-surface-secondary: var(--color-neutral-50); /* #fafafa - Secondary background */
+  --color-surface-tertiary: var(--color-neutral-100); /* #f5f5f5 - Tertiary background */
+  --color-surface-elevated: var(--color-neutral-0); /* #ffffff - Cards, modals, raised elements */
+  --color-surface-overlay: rgba(0, 0, 0, 0.5); /* Modal overlay, backdrop */
+  /* ========================================
+     Border Colors
+     Purpose: Borders, dividers, separators, outlines
+     ======================================== */
+  --color-border: var(--color-neutral-300); /* #d4d4d4 - Default borders */
+  --color-border-subtle: var(--color-neutral-200); /* #e5e5e5 - Subtle borders, dividers */
+  --color-border-strong: var(--color-neutral-400); /* #a3a3a3 - Emphasized borders */
+  --color-border-interactive: var(--color-neutral-400); /* #a3a3a3 - Hover borders on inputs */
+  /* ========================================
+     Text Colors
+     Purpose: Body text, headings, labels, captions
+     ======================================== */
+  --color-text: var(--color-neutral-800); /* #262626 - Primary body text */
+  --color-text-secondary: var(--color-neutral-700); /* #404040 - Secondary text, labels */
+  --color-text-tertiary: var(--color-neutral-600); /* #525252 - Tertiary text, captions */
+  --color-text-disabled: var(--color-neutral-500); /* #737373 - Disabled text */
+  --color-text-inverse: var(--color-neutral-0); /* #ffffff - Text on dark backgrounds */
+  /* ========================================
+     Interactive States
+     Purpose: Focus, hover, active, disabled states
+     ======================================== */
+  --color-focus: var(--color-blue-600); /* #2563eb - Focus outlines (WCAG 3:1 contrast) */
+  --color-focus-ring: var(--color-blue-600); /* #2563eb - Focus rings on inputs */
+  --color-hover-overlay: rgba(0, 0, 0, 0.05); /* Subtle hover overlay on buttons */
+  --color-active-overlay: rgba(0, 0, 0, 0.1); /* Active/pressed overlay on buttons */
+  --color-disabled-bg: var(--color-neutral-100); /* #f5f5f5 - Disabled backgrounds */
+  --color-disabled-text: var(--color-neutral-500); /* #737373 - Disabled text */
+  /* ========================================
+     Link Colors
+     Purpose: Hyperlinks, navigation links
+     ======================================== */
+  --color-link: var(--color-blue-700); /* #1d4ed8 - Default link color */
+  --color-link-hover: var(--color-blue-800); /* #1e40af - Link hover state */
+  --color-link-visited: var(--color-blue-900); /* #1e3a8a - Visited link color */
+  --color-link-active: var(--color-blue-800); /* #1e40af - Link active/pressed state */
+  /* ========================================
+     Validation Colors
+     Purpose: Form validation, required fields
+     ======================================== */
+  --color-required: var(--color-red-600); /* #dc2626 - Required field indicators */
+  --color-valid: var(--color-green-600); /* #16a34a - Valid input indicators */
+  --color-invalid: var(--color-red-600); /* #dc2626 - Invalid input indicators */
+  /* ========================================
+     Skip Link & Accessibility
+     Purpose: Skip navigation, accessibility utilities
+     ======================================== */
+  --color-skip-link-bg: var(--color-neutral-100); /* #f5f5f5 - Skip link background */
+  --color-skip-link-text: var(--color-text); /* Inherits default text color */
+}
+
 *,
 *::before,
 *::after {
@@ -311,7 +543,7 @@ body > a[href^="#"] {
   z-index: 100;
   transition: top 0.3s;
   border-radius: 0;
-  background-color: var(--color-skip-link-bg, #f5f5f5);
+  background-color: var(--color-skip-link-bg, var(--color-neutral-100));
 }
 body > a[href^="#"]:focus {
   top: 0;
@@ -371,7 +603,7 @@ blockquote {
   --blockquote-padding: 1rem;
   --blockquote-border-width: 0.3125rem;
   --blockquote-border-style: solid;
-  --blockquote-border-color: var(--color-border, #d3d3d3);
+  --blockquote-border-color: var(--color-border);
   padding: var(--blockquote-padding);
   border-left: var(--blockquote-border-width) var(--blockquote-border-style) var(--blockquote-border-color);
 }
@@ -394,7 +626,7 @@ h6 {
 
 hr {
   --hr-border-width: 0.0625rem;
-  --hr-border-color: var(--color-border-subtle, #d3d3d3);
+  --hr-border-color: var(--color-border-subtle);
   --hr-margin-block: 1.5rem;
   --hr-border-style: solid;
   border: none;
@@ -424,6 +656,16 @@ h6:has(span:first-of-type) > span {
   --title-6: var(--h6);
 }
 
+/**
+ * Utilities - Main Export
+ *
+ * This file exports all utility classes.
+ * Utilities are loaded after tokens and base styles, before components.
+ *
+ * Usage in main index.scss:
+ * @use "./sass/utilities";
+ */
+/* Existing utilities */
 /**
  * Disabled State Utility Styles
  *
@@ -483,6 +725,179 @@ h6:has(span:first-of-type) > span {
   outline-color: var(--focus-color, currentColor);
 }
 
+/* New color utilities (semantic only) */
+/**
+ * Text Color Utilities
+ *
+ * Semantic text color utility classes for quick styling.
+ * All utilities reference semantic tokens (Tier 2), not primitives.
+ *
+ * Usage:
+ * <p class="text-primary">Primary text</p>
+ * <span class="text-error">Error message</span>
+ */
+/* ========================================
+   Brand Text Colors
+   ======================================== */
+.text-primary {
+  color: var(--color-primary);
+}
+
+.text-secondary {
+  color: var(--color-secondary);
+}
+
+/* ========================================
+   State Text Colors
+   ======================================== */
+.text-success {
+  color: var(--color-success-text);
+}
+
+.text-error {
+  color: var(--color-error-text);
+}
+
+.text-warning {
+  color: var(--color-warning-text);
+}
+
+.text-info {
+  color: var(--color-info-text);
+}
+
+/* ========================================
+   Text Hierarchy Colors
+   ======================================== */
+.text-muted {
+  color: var(--color-text-tertiary);
+}
+
+.text-disabled {
+  color: var(--color-text-disabled);
+}
+
+.text-inverse {
+  color: var(--color-text-inverse);
+}
+
+/**
+ * Background Color Utilities
+ *
+ * Semantic background color utility classes for quick styling.
+ * All utilities reference semantic tokens (Tier 2), not primitives.
+ *
+ * Usage:
+ * <div class="bg-primary">Primary background</div>
+ * <div class="bg-success">Success background</div>
+ */
+/* ========================================
+   Brand Backgrounds
+   ======================================== */
+.bg-primary {
+  background-color: var(--color-primary);
+}
+
+.bg-primary-light {
+  background-color: var(--color-primary-light);
+}
+
+.bg-secondary {
+  background-color: var(--color-secondary-light);
+}
+
+/* ========================================
+   State Backgrounds
+   ======================================== */
+.bg-success {
+  background-color: var(--color-success-bg);
+}
+
+.bg-error {
+  background-color: var(--color-error-bg);
+}
+
+.bg-warning {
+  background-color: var(--color-warning-bg);
+}
+
+.bg-info {
+  background-color: var(--color-info-bg);
+}
+
+/* ========================================
+   Surface Backgrounds
+   ======================================== */
+.bg-surface {
+  background-color: var(--color-surface);
+}
+
+.bg-surface-secondary {
+  background-color: var(--color-surface-secondary);
+}
+
+.bg-transparent {
+  background-color: transparent;
+}
+
+/**
+ * Border Color Utilities
+ *
+ * Semantic border color utility classes for quick styling.
+ * All utilities reference semantic tokens (Tier 2), not primitives.
+ *
+ * Note: These utilities only set border-color.
+ * You may need to set border-width and border-style separately.
+ *
+ * Usage:
+ * <div class="border-primary" style="border: 1px solid;">
+ * <div class="border-error" style="border-width: 2px; border-style: solid;">
+ */
+/* ========================================
+   Brand Borders
+   ======================================== */
+.border-primary {
+  border-color: var(--color-primary);
+}
+
+.border-secondary {
+  border-color: var(--color-secondary);
+}
+
+/* ========================================
+   State Borders
+   ======================================== */
+.border-success {
+  border-color: var(--color-success-border);
+}
+
+.border-error {
+  border-color: var(--color-error-border);
+}
+
+.border-warning {
+  border-color: var(--color-warning-border);
+}
+
+.border-info {
+  border-color: var(--color-info-border);
+}
+
+/* ========================================
+   UI Borders
+   ======================================== */
+.border-default {
+  border-color: var(--color-border);
+}
+
+.border-subtle {
+  border-color: var(--color-border-subtle);
+}
+
+.border-transparent {
+  border-color: transparent;
+}
+
 button {
   --btn-size-xs: 0.6875rem;
   --btn-size-sm: 0.8125rem;
@@ -491,7 +906,7 @@ button {
   --btn-pill: 100rem;
   --btn-fs: var(--btn-size-md);
   --btn-height: calc(var(--btn-fs) * 2.25);
-  --btn-bg: lightgray;
+  --btn-bg: var(--color-neutral-300);
   --btn-width: max-content;
   font-size: var(--btn-fs);
   font-weight: var(--btn-fw, 500);
@@ -516,12 +931,12 @@ button {
   line-height: 0cap;
 }
 button[type] {
-  background-color: var(--btn-bg, var(--neutral-300));
+  background-color: var(--btn-bg, var(--color-neutral-300));
   --btn-border: solid var(--btn-sg);
 }
 button[type=submit], button[style*=submit] {
-  --btn-bg: var(--primary-500, royal-blue);
-  --btn-color: white;
+  --btn-bg: var(--color-primary);
+  --btn-color: var(--color-text-inverse);
 }
 button[disabled], button[aria-disabled=true] {
   cursor: var(--btn-cursor, not-allowed);
@@ -546,12 +961,12 @@ button:focus-visible {
 }
 button[type=reset] {
   --btn-bg: transparent;
-  --btn-color: gray;
-  --btn-border: gray thin solid;
+  --btn-color: var(--color-text-secondary);
+  --btn-border: var(--color-border) thin solid;
 }
 button[type=submit] {
-  --btn-bg: var(--primary-700, blue);
-  --btn-color: #fff;
+  --btn-bg: var(--color-primary);
+  --btn-color: var(--color-text-inverse);
   --btn-border: none;
 }
 button[data-fp-btn~=pill], button[data-btn~=pill], button[data-style~=pill] {
@@ -625,15 +1040,15 @@ p[role=note],
 small > span,
 [data-tag] {
   /* Variant color tokens - WCAG AA compliant colors */
-  --beta: #fbbf24; /* Amber: 6.94:1 contrast with black */
-  --stable: #0f7c3e; /* Dark green: 4.56:1 contrast with white */
-  --production: #1e3a8a; /* Dark blue: 8.59:1 contrast with white */
+  --beta: var(--color-amber-400); /* Amber: 6.94:1 contrast with black */
+  --stable: var(--color-green-700); /* Dark green: 4.56:1 contrast with white */
+  --production: var(--color-blue-900); /* Dark blue: 8.59:1 contrast with white */
   /* Tag component tokens */
   --tag-padding-inline: 0.7rem; /* Horizontal padding (11.2px at 16px base) */
   --tag-padding-block: 0.2rem; /* Vertical padding (3.2px at 16px base) */
   --tag-fs: 0.8rem; /* Font size (12.8px at 16px base) */
   --tag-radius: 99rem; /* Fully rounded pill shape */
-  --tag-bg: lightgray; /* Default background color */
+  --tag-bg: var(--color-neutral-300); /* Default background color */
   --tag-fw: 500; /* Medium font weight */
   --tag-color: currentColor; /* Default text color (inherits) */
   --tag-display: inline-block; /* Display type */
@@ -677,7 +1092,7 @@ p[role=note][data-tag~=alpha],
 [role=note][data-tag~=alpha],
 small > span[data-tag~=alpha],
 [data-tag][data-tag~=alpha] {
-  --tag-color: #000000; /* Black: maximum contrast with amber background */
+  --tag-color: var(--color-neutral-900); /* Black: maximum contrast with amber background */
   --tag-bg: var(--beta);
   /* Visual indicator beyond color - warning symbol */
 }
@@ -694,7 +1109,7 @@ p[role=note][data-tag~=beta],
 [role=note][data-tag~=beta],
 small > span[data-tag~=beta],
 [data-tag][data-tag~=beta] {
-  --tag-color: #000000; /* Black: maximum contrast with amber background */
+  --tag-color: var(--color-neutral-900); /* Black: maximum contrast with amber background */
   --tag-bg: var(--beta);
   /* Visual indicator beyond color - warning symbol */
 }
@@ -711,7 +1126,7 @@ p[role=note][data-tag~=stable],
 [role=note][data-tag~=stable],
 small > span[data-tag~=stable],
 [data-tag][data-tag~=stable] {
-  --tag-color: #ffffff; /* White: 4.56:1 contrast with dark green */
+  --tag-color: var(--color-text-inverse); /* White: 4.56:1 contrast with dark green */
   --tag-bg: var(--stable);
   /* Visual indicator beyond color - checkmark symbol */
 }
@@ -806,20 +1221,20 @@ figure:has(img[alt]) > figcaption {
 
 :root {
   --card-padding: 1.5rem;
-  --card-bg: var(--color-surface, #ffffff);
+  --card-bg: var(--color-surface);
   --card-radius: calc(var(--card-padding) / 4);
   --card-gap: 1rem;
   --card-header-padding: 1rem 1.5rem;
-  --card-header-bg: var(--color-surface-secondary, #f8f9fa);
+  --card-header-bg: var(--color-surface-secondary);
   --card-header-border-bottom-width: 0.0625rem;
   --card-header-border-bottom-style: solid;
-  --card-header-border-bottom-color: var(--color-border, #dee2e6);
+  --card-header-border-bottom-color: var(--color-border);
   --card-body-padding: 1.5rem;
   --card-footer-padding: 1rem 1.5rem;
-  --card-footer-bg: var(--color-surface-secondary, #f8f9fa);
+  --card-footer-bg: var(--color-surface-secondary);
   --card-footer-border-top-width: 0.0625rem;
   --card-footer-border-top-style: solid;
-  --card-footer-border-top-color: var(--color-border, #dee2e6);
+  --card-footer-border-top-color: var(--color-border);
 }
 
 [data-card],
@@ -828,7 +1243,7 @@ figure:has(img[alt]) > figcaption {
   flex-direction: column;
   gap: var(--card-gap);
   border-radius: var(--card-radius);
-  border: var(--card-border, 0.0625rem solid rgba(0, 0, 0, 0.08));
+  border: var(--card-border, 0.0625rem solid var(--color-border-subtle));
   background-color: var(--card-bg);
   text-align: var(--card-align, left);
 }
@@ -898,7 +1313,7 @@ figure:has(img[alt]) > figcaption {
   box-shadow: var(--card-hover-shadow);
 }
 [data-card=interactive]:focus-visible {
-  outline: 0.125rem solid var(--color-focus, #0066cc);
+  outline: 0.125rem solid var(--color-focus);
   outline-offset: 0.125rem;
 }
 [data-card=interactive]:focus:not(:focus-visible) {
@@ -910,8 +1325,8 @@ progress {
   all: revert;
   --progress-width: 100%;
   --progress-height: 1rem;
-  --progress-bg: #cccccc;
-  --progress-color: rgb(71, 71, 245);
+  --progress-bg: var(--color-neutral-300);
+  --progress-color: var(--color-primary);
   --progress-accent-color: var(--progress-color);
   /* This code changes the color of the progress bar. */
   /* The variable names indicate the colors that are used. */
@@ -959,7 +1374,7 @@ progress[aria-busy]::-webkit-progress-bar {
 }
 
 details {
-  --details-border: 0.0625rem solid #dfdfdf;
+  --details-border: 0.0625rem solid var(--color-border-subtle);
   --details-direction: column;
   --details-display: flex;
   --details-gap: 0rem;
@@ -993,7 +1408,6 @@ details {
 @starting-style {
   details {
     transition: var(--summary-transitions);
-    color: red;
   }
 }
 details + details {
@@ -1031,7 +1445,7 @@ details summary::-webkit-details-marker {
 details summary:focus-within {
   outline: none;
   border-bottom: solid 2px currentColor;
-  background-color: whitesmoke;
+  background-color: var(--color-surface-secondary);
 }
 details summary:hover {
   cursor: var(--summary-cursor);
@@ -1085,7 +1499,7 @@ details[open] > section {
  * - Uses :focus-visible for better UX (keyboard vs mouse)
  */
 a[href] {
-  --link-color: #085ab7;
+  --link-color: var(--color-link);
   --link-fw: 400;
   --link-fs: 1rem;
   --link-decoration: none;
@@ -1941,20 +2355,20 @@ footer > div {
 :root {
   --dialog-min-width: max(20rem, 80%);
   --dialog-gap: 0.625rem;
-  --dialog-border-color: lightgray;
+  --dialog-border-color: var(--color-border);
   --dialog-border-width: thin;
   --dialog-border-style: solid;
   --dialog-border-radius: var(--border-radius);
   --dialog-padding: 1.5rem;
   --dialog-padding-inline: 1rem;
-  --dialog-close-color: gray;
+  --dialog-close-color: var(--color-text-secondary);
   --dialog-button-bg: transparent;
   --dialog-button-border: transparent thin solid;
-  --dialog-button-hover-bg: whitesmoke;
+  --dialog-button-hover-bg: var(--color-surface-secondary);
   --dialog-display: flex;
   --dialog-flex-direction: column;
   /* Focus and accessibility */
-  --dialog-focus-color: #0066cc;
+  --dialog-focus-color: var(--color-focus);
   --dialog-focus-width: 0.125rem;
   --dialog-focus-offset: 0.125rem;
   --dialog-focus-outline: var(--dialog-focus-width) solid var(--dialog-focus-color);
@@ -2997,7 +3411,7 @@ dialog section {
 }
 
 sup:has(> span) {
-  --badge-bg: lightgray;
+  --badge-bg: var(--color-neutral-300);
   --badge-color: currentColor;
   --badge-radius: 0.5rem;
   --badge-padding: 0.3rem;
@@ -3067,7 +3481,7 @@ body > nav ul > li,
 body > nav ul > li:hover,
 [aria-label~=navbar] ul > li:hover,
 .navbar ul > li:hover {
-  background-color: var(--nav-hover-bg, #e8e8e8);
+  background-color: var(--nav-hover-bg, var(--color-surface-secondary));
 }
 body > nav ul > li:hover:has(img, button),
 [aria-label~=navbar] ul > li:hover:has(img, button),
@@ -3156,15 +3570,15 @@ nav button:focus-visible {
  * CSS Custom Properties:
  * - --checkbox-gap: Space between checkbox and label (default: 0.5rem)
  * - --checkbox-disabled-opacity: Opacity for disabled state (default: 0.6)
- * - --checkbox-disabled-color: Label color when disabled (default: #6b7280)
+ * - --checkbox-disabled-color: Label color when disabled (default: var(--color-disabled-text))
  * - --checkbox-label-fs: Label font size (default: 1rem)
  * - --checkbox-label-lh: Label line height (default: 1.5)
- * - --color-required: Required indicator color (default: #dc2626)
- * - --checkbox-focus-ring-color: Focus ring color (default: #2563eb)
+ * - --color-required: Required indicator color (default: var(--color-required))
+ * - --checkbox-focus-ring-color: Focus ring color (default: var(--color-focus-ring))
  * - --checkbox-focus-ring-width: Focus ring width (default: 0.125rem)
  * - --checkbox-focus-ring-offset: Focus ring offset (default: 0.125rem)
  * - --checkbox-hover-label-color: Label color on hover (default: inherit)
- * - --checkbox-error-label-color: Label color when invalid (default: #dc2626)
+ * - --checkbox-error-label-color: Label color when invalid (default: var(--color-error-text))
  * - --checkbox-valid-label-color: Label color when valid (default: #16a34a)
  * - --checkbox-focus-radius: Focus outline border radius (default: 0.125rem)
  *
@@ -3186,10 +3600,10 @@ div:has(> input[type=checkbox]) > input[type=checkbox] {
   order: -1;
 }
 div:has(> input[type=checkbox]):not(:has(> input[aria-disabled=true])):hover .checkbox-label {
-  color: var(--checkbox-hover-label-color, inherit);
+  color: var(--checkbox-hover-label-color, currentColor);
 }
 div:has(> input[type=checkbox]):has(> input:focus-visible) .checkbox-label {
-  outline: var(--checkbox-focus-ring-width, 0.125rem) solid var(--checkbox-focus-ring-color, #2563eb);
+  outline: var(--checkbox-focus-ring-width, 0.125rem) solid var(--checkbox-focus-ring-color, var(--color-focus-ring));
   outline-offset: var(--checkbox-focus-ring-offset, 0.125rem);
   border-radius: var(--checkbox-focus-radius, 0.125rem);
 }
@@ -3198,14 +3612,14 @@ div:has(> input[type=checkbox]):has(> input[aria-disabled=true]) {
   cursor: not-allowed;
 }
 div:has(> input[type=checkbox]):has(> input[aria-disabled=true]) .checkbox-label {
-  color: var(--checkbox-disabled-color, #6b7280);
+  color: var(--checkbox-disabled-color, var(--color-disabled-text));
   cursor: not-allowed;
 }
 div:has(> input[type=checkbox]):has(> input[aria-invalid=true]) .checkbox-label {
-  color: var(--checkbox-error-label-color, #dc2626);
+  color: var(--checkbox-error-label-color, var(--color-error-text));
 }
-div:has(> input[type=checkbox]):has(> input[aria-invalid=false]:checked) .checkbox-label {
-  color: var(--checkbox-valid-label-color, #16a34a);
+div:has(> input[type=checkbox]):has(> input[aria-invalid=false]:checked) label[for] {
+  color: var(--checkbox-valid-label-color, currentColor);
 }
 
 .checkbox-label {
@@ -3224,7 +3638,7 @@ div:has(> input[type=checkbox]):has(> input[aria-invalid=false]:checked) .checkb
   }
 }
 .checkbox-label .checkbox-required {
-  color: var(--color-required, #dc2626);
+  color: var(--color-required);
   font-weight: 600;
   margin-inline-start: 0.125rem;
 }
@@ -3242,7 +3656,7 @@ div:has(> input[type=checkbox]):has(> input[aria-invalid=false]:checked) .checkb
   }
 }
 :root {
-  --input-border-color: gray;
+  --input-border-color: var(--color-border);
   --input-appearance: none;
   --input-bg: inherit;
   --input-border: none;
@@ -3254,10 +3668,10 @@ div:has(> input[type=checkbox]):has(> input[aria-invalid=false]:checked) .checkb
   --input-width: clamp(200px, 100%, 500px);
   --input-focus-outline: medium solid var(--input-border-color);
   --input-focus-outline-offset: 0;
-  --input-disabled-bg: #f5f5f5;
+  --input-disabled-bg: var(--color-disabled-bg);
   --input-disabled-opacity: 0.6;
   --input-disabled-cursor: not-allowed;
-  --placeholder-color: gray;
+  --placeholder-color: var(--color-text-tertiary);
   --placeholder-style: italic;
   --placeholder-fs: smaller;
   --form-direction: column;
@@ -3272,12 +3686,17 @@ div:has(> input[type=checkbox]):has(> input[aria-invalid=false]:checked) .checkb
      Base Properties
      ========================================================================== */
   --checkbox-size: var(--checkbox-size-md);
-  --checkbox-bg: #ffffff;
-  --checkbox-border: 0.125rem solid #6b7280; /* 2px border */
-  --checkbox-border-color: #6b7280; /* Gray 500 */
+  --checkbox-bg: var(--color-surface);
+  --checkbox-border: 0.125rem solid var(--color-neutral-600); /* 2px border */
+  --checkbox-border-color: var(--color-neutral-600); /* Gray 500 */
   --checkbox-radius: 0.25rem; /* 4px */
   --checkbox-cursor: pointer;
   --checkbox-transition: all 0.2s cubic-bezier(0.4, 0, 0.2, 1);
+  /* ==========================================================================
+     Checked State Properties
+     ========================================================================== */
+  --checkbox-checked-outline-color: var(--color-success);
+  --checkbox-checked-bg: var(--color-success);
 }
 
 form {
@@ -3304,14 +3723,14 @@ input {
   padding-inline: var(--input-padding-inline);
   padding-block: var(--input-padding-block);
   border-radius: var(--input-radius);
-  background-color: var(--input-bg, #fff);
+  background-color: var(--input-bg, var(--color-surface));
 }
 input:focus-visible, input:focus {
   outline: var(--input-focus-outline);
   outline-offset: var(--input-focus-outline-offset);
 }
 input[aria-disabled=true], input:disabled {
-  --input-border-color: lightgray;
+  --input-border-color: var(--color-border-subtle);
   background-color: var(--input-disabled-bg);
   opacity: var(--input-disabled-opacity);
   cursor: var(--input-disabled-cursor);
@@ -3349,8 +3768,8 @@ input[type=checkbox] {
 }
 input[type=checkbox]:checked {
   background-color: var(--checkbox-bg, red);
-  outline: rebeccapurple solid 2px;
-  background: #dbeafe;
+  outline: var(--checkbox-checked-outline-color) solid 2px;
+  background: var(--checkbox-checked-bg) url("data:image/svg+xml;utf8,<svg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 16 16' fill='white'><path d='M6.173 11.414l-3.89-3.89 1.414-1.414 2.476 2.475 5.657-5.657 1.414 1.414z'/></svg>") no-repeat center center;
 }
 
 select {
@@ -3630,28 +4049,28 @@ li:has(> button) {
 }
 
 [role=alert] {
-  /* Success colors */
-  --alert-success-bg: #e6f4ea;
-  --alert-success-border: #34a853;
-  --alert-success-text: #1e4620;
-  /* Error colors */
-  --alert-error-bg: #fdeded;
-  --alert-error-border: #d32f2f;
-  --alert-error-text: #5f2120;
-  /* Warning colors */
-  --alert-warning-bg: #fff4e5;
-  --alert-warning-border: #ff9800;
-  --alert-warning-text: #663c00;
-  /* Info colors */
-  --alert-info-bg: #e5f6fd;
-  --alert-info-border: #0288d1;
-  --alert-info-text: #084154;
+  /* Success colors - WCAG AA compliant (mapped to semantic tokens) */
+  --alert-success-bg: var(--color-success-bg);
+  --alert-success-border: var(--color-success-border);
+  --alert-success-text: var(--color-success-text);
+  /* Error colors - WCAG AA compliant (mapped to semantic tokens) */
+  --alert-error-bg: var(--color-error-bg);
+  --alert-error-border: var(--color-error-border);
+  --alert-error-text: var(--color-error-text);
+  /* Warning colors - WCAG AA compliant (mapped to semantic tokens) */
+  --alert-warning-bg: var(--color-warning-bg);
+  --alert-warning-border: var(--color-warning-border);
+  --alert-warning-text: var(--color-warning-text);
+  /* Info colors - WCAG AA compliant (mapped to semantic tokens) */
+  --alert-info-bg: var(--color-info-bg);
+  --alert-info-border: var(--color-info-border);
+  --alert-info-text: var(--color-info-text);
   /* Animation */
   --alert-transition-duration: 0.3s;
   --alert-border: thin solid currentColor;
-  background-color: var(--alert-bg, whitesmoke);
-  border: var(--alert-border, currentColor);
-  color: var(--alert-color, currentColor);
+  background-color: var(--alert-bg, var(--color-surface));
+  border: var(--alert-border, var(--color-border));
+  color: var(--alert-color, var(--color-text));
   padding: var(--alert-padding, var(--spc-4));
   margin-block-end: var(--alert-margin-block-end);
   font-size: var(--fs-0);
@@ -3772,7 +4191,7 @@ li:has(> button) {
 
 [data-tts] {
   --tts-gap: 0.5rem;
-  --tts-bg: #fff;
+  --tts-bg: var(--color-surface);
   --tts-border-width: 0.125rem;
   --tts-border-style: solid;
   --tts-border-color: currentColor;
@@ -3854,16 +4273,16 @@ li:has(> button) {
   --title-fs: var(--title-size-2xl);
 }
 [data-title][data-title~=primary] {
-  --title-color: #1e3a8a;
+  --title-color: var(--color-primary);
 }
 [data-title][data-title~=secondary] {
-  --title-color: #4b5563;
+  --title-color: var(--color-text-secondary);
 }
 [data-title][data-title~=accent] {
-  --title-color: #7c3aed;
+  --title-color: var(--color-primary);
 }
 [data-title][data-title~=muted] {
-  --title-color: #6b7280;
+  --title-color: var(--color-text-tertiary);
 }
 [data-title][data-title~=inherit] {
   --title-color: inherit;
@@ -4650,6 +5069,21 @@ li:has(> button) {
   box-shadow: var(--shadow-xl);
 }
 
+/**
+ * DEPRECATED: This file is deprecated in favor of the new token system.
+ *
+ * Use tokens from src/sass/tokens/ instead:
+ * - Primitives: src/sass/tokens/_color-primitives.scss
+ * - Semantic: src/sass/tokens/_color-semantic.scss
+ *
+ * Use utility classes from src/sass/utilities/ for quick styling:
+ * - .text-primary, .text-success, .text-error, etc.
+ * - .bg-primary, .bg-success, .bg-error, etc.
+ * - .border-primary, .border-success, .border-error, etc.
+ *
+ * This file will be removed in v6.0.0
+ * Keeping for backward compatibility only.
+ */
 :root {
   --transparent: transparent;
 }