From 666129191aba22c3084b86f29297e05319851b1c Mon Sep 17 00:00:00 2001
From: barsa <tumurbarsnarantuya@gmail.com>
Date: Tue, 16 Dec 2025 17:43:02 +0900
Subject: [PATCH] Refactor global styles and component tokens for improved
 consistency and clarity

- Updated globals.css to streamline design tokens and enhance semantic color usage across the application.
- Refined error and loading components to utilize new color tokens for better visual coherence.
- Adjusted various components, including AppShell, Header, and Sidebar, to align with updated design tokens and improve styling consistency.
- Enhanced utility classes in utilities.css to reflect the consolidated color system and improve component styling.
- Improved documentation in tokens.css to clarify the purpose and structure of design tokens.
---
 apps/portal/src/app/globals.css               | 415 ++++--------------
 .../src/components/atoms/error-state.tsx      |   8 +-
 .../src/components/atoms/loading-skeleton.tsx |  16 +-
 .../organisms/AppShell/AppShell.tsx           |   4 +-
 .../components/organisms/AppShell/Header.tsx  |   2 +-
 .../components/organisms/AppShell/Sidebar.tsx |   4 +-
 .../billing/components/InvoiceStatusBadge.tsx |  36 +-
 .../catalog/components/base/CardBadge.tsx     |   2 +-
 .../components/DataUsageChart.tsx             |   8 +-
 .../components/SubscriptionDetails.tsx        |  14 +-
 .../components/SubscriptionStatusBadge.tsx    |  28 +-
 apps/portal/src/styles/tokens.css             | 279 ++----------
 apps/portal/src/styles/utilities.css          |  65 ++-
 13 files changed, 232 insertions(+), 649 deletions(-)

diff --git a/apps/portal/src/app/globals.css b/apps/portal/src/app/globals.css
index 35b0e4f9..470c6979 100644
--- a/apps/portal/src/app/globals.css
+++ b/apps/portal/src/app/globals.css
@@ -1,4 +1,4 @@
-/* Tailwind CSS v4: import the full framework */
+/* Tailwind CSS v4 */
 @import "tailwindcss";
 @import "../styles/tokens.css";
 @import "../styles/utilities.css";
@@ -6,456 +6,212 @@
 
 @custom-variant dark (&:is(.dark *));
 
+/* =============================================================================
+   DESIGN TOKENS
+   
+   Only define CSS variables here. Tailwind @theme maps them to utility classes.
+   ============================================================================= */
+
 :root {
   --radius: 0.625rem;
 
-  /* ============= CORE NEUTRALS ============= */
-  --background: oklch(1 0 0); /* pure white for main content */
+  /* Core */
+  --background: oklch(1 0 0);
   --foreground: oklch(0.16 0 0);
-
-  --card: oklch(1 0 0); /* pure white for cards */
+  --card: oklch(1 0 0);
   --card-foreground: var(--foreground);
-  --card-muted: oklch(0.98 0.008 234.4); /* subtle brand-tinted gray */
   --popover: oklch(1 0 0);
   --popover-foreground: var(--foreground);
-
-  /* ============= BRAND COLORS (from logo) ============= */
-  /* Primary Light Blue - Brand Accent */
-  --primary: oklch(0.6884 0.1342 234.4);
-  --primary-foreground: oklch(0.99 0 0);
-  --primary-hover: oklch(0.62 0.1342 234.4);
-  --primary-active: oklch(0.56 0.1342 234.4);
-
-  /* Subtle surfaces & text - tinted with primary brand hue */
-  --secondary: oklch(0.95 0.015 234.4);
-  --secondary-foreground: oklch(0.29 0 0);
-
   --muted: oklch(0.96 0.008 234.4);
   --muted-foreground: oklch(0.5 0 0);
 
-  /* Light accent (tinted with brand) */
+  /* Brand */
+  --primary: oklch(0.6884 0.1342 234.4);
+  --primary-foreground: oklch(0.99 0 0);
+  --secondary: oklch(0.95 0.015 234.4);
+  --secondary-foreground: oklch(0.29 0 0);
   --accent: oklch(0.95 0.04 234.4);
   --accent-foreground: var(--foreground);
 
-  /* ============= SEMANTIC STATUS COLORS ============= */
-  /* Three-tier system: text (dark readable), bg (almost white), border (subtle accent) */
-  /* Reserve brand cyan for primary interaction; status colors are secondary */
-
-  /* Success - #166534 text, #F0FDF4 bg, #BBF7D0 border */
-  --success: oklch(0.42 0.1 145); /* dark green for text/icons */
+  /* 5 Semantic Colors (each: base, foreground, bg, border) */
+  --success: oklch(0.42 0.1 145);
   --success-foreground: oklch(0.99 0 0);
-  --success-bg: oklch(0.98 0.02 145); /* very light green bg */
-  --success-border: oklch(0.93 0.08 150); /* subtle green border */
+  --success-bg: oklch(0.98 0.02 145);
+  --success-border: oklch(0.93 0.08 150);
 
-  /* Info - uses primary brand hue */
   --info: oklch(0.48 0.1 234.4);
   --info-foreground: oklch(0.99 0 0);
   --info-bg: oklch(0.97 0.02 234.4);
   --info-border: oklch(0.91 0.05 234.4);
 
-  /* Warning - #92400E text, #FFFBEB bg, #FDE68A border */
-  --warning: oklch(0.45 0.12 55); /* dark amber for text/icons */
+  --warning: oklch(0.45 0.12 55);
   --warning-foreground: oklch(0.99 0 0);
-  --warning-bg: oklch(0.99 0.02 90); /* very light amber bg */
-  --warning-border: oklch(0.92 0.12 90); /* subtle amber border */
+  --warning-bg: oklch(0.99 0.02 90);
+  --warning-border: oklch(0.92 0.12 90);
 
-  /* Error - #9F1239 text, #FFF1F2 bg, #FECDD3 border (Overdue) */
-  --error: oklch(0.42 0.16 0); /* dark rose for text/icons */
-  --error-foreground: oklch(0.99 0 0);
-  --error-bg: oklch(0.98 0.01 0); /* very light rose bg */
-  --error-border: oklch(0.89 0.06 0); /* subtle rose border */
+  --danger: oklch(0.42 0.15 12);
+  --danger-foreground: oklch(0.99 0 0);
+  --danger-bg: oklch(0.98 0.01 10);
+  --danger-border: oklch(0.89 0.06 10);
 
-  /* Destructive - #991B1B text, #FEF2F2 bg, #FECACA border (Terminated) */
-  --destructive: oklch(0.43 0.15 25); /* dark red for text/icons */
-  --destructive-foreground: oklch(0.99 0 0);
-  --destructive-bg: oklch(0.98 0.01 20); /* very light red bg */
-  --destructive-border: oklch(0.89 0.06 20); /* subtle red border */
-
-  /* Neutral - uses sidebar brand hue */
   --neutral: oklch(0.36 0.03 272.34);
   --neutral-foreground: oklch(0.99 0 0);
   --neutral-bg: oklch(0.97 0.008 272.34);
   --neutral-border: oklch(0.87 0.02 272.34);
 
-  /* ============= GRANULAR STATUS COLORS ============= */
-  /* Three-tier: text (dark readable), bg (almost white), border (subtle accent) */
-
-  /* Active - uses primary brand hue */
-  --status-active: oklch(0.48 0.1 234.4);
-  --status-active-bg: oklch(0.97 0.02 234.4);
-  --status-active-border: oklch(0.91 0.05 234.4);
-
-  /* Completed - uses sidebar brand hue */
-  --status-completed: oklch(0.2754 0.1199 272.34);
-  --status-completed-bg: oklch(0.96 0.02 272.34);
-  --status-completed-border: oklch(0.87 0.07 272.34);
-
-  /* Paid - #0F766E text, #ECFDF5 bg, #A7F3D0 border (teal, closer to brand) */
-  --status-paid: oklch(0.48 0.08 175);
-  --status-paid-bg: oklch(0.98 0.02 165);
-  --status-paid-border: oklch(0.92 0.08 160);
-
-  /* Success - #166534 text, #F0FDF4 bg, #BBF7D0 border */
-  --status-success: oklch(0.42 0.1 145);
-  --status-success-bg: oklch(0.98 0.02 145);
-  --status-success-border: oklch(0.93 0.08 150);
-
-  /* Pending - #92400E text, #FFFBEB bg, #FDE68A border */
-  --status-pending: oklch(0.45 0.12 55);
-  --status-pending-bg: oklch(0.99 0.02 90);
-  --status-pending-border: oklch(0.92 0.12 90);
-
-  /* Suspended - uses sidebar brand hue */
-  --status-suspended: oklch(0.36 0.03 272.34);
-  --status-suspended-bg: oklch(0.97 0.008 272.34);
-  --status-suspended-border: oklch(0.87 0.02 272.34);
-
-  /* Unpaid - #9A3412 text, #FFF7ED bg, #FED7AA border */
-  --status-unpaid: oklch(0.46 0.13 45);
-  --status-unpaid-bg: oklch(0.98 0.02 70);
-  --status-unpaid-border: oklch(0.9 0.08 65);
-
-  /* Terminated - #991B1B text, #FEF2F2 bg, #FECACA border */
-  --status-terminated: oklch(0.43 0.15 25);
-  --status-terminated-bg: oklch(0.98 0.01 20);
-  --status-terminated-border: oklch(0.89 0.06 20);
-
-  /* Overdue - #9F1239 text, #FFF1F2 bg, #FECDD3 border */
-  --status-overdue: oklch(0.42 0.16 0);
-  --status-overdue-bg: oklch(0.98 0.01 0);
-  --status-overdue-border: oklch(0.89 0.06 0);
-
-  /* ============= SOFT COLOR VARIANTS (for badges/pills) ============= */
-  /* These use the -bg colors for backgrounds with text colors for contrast */
-  --success-soft: var(--success-bg);
-  --info-soft: var(--info-bg);
-  --warning-soft: var(--warning-bg);
-  --destructive-soft: var(--destructive-bg);
-  --neutral-soft: var(--neutral-bg);
-
-  /* ============= UI CHROME ============= */
+  /* Chrome */
   --border: oklch(0.9 0.005 234.4);
-  --border-muted: oklch(0.92 0.003 234.4);
   --input: oklch(0.88 0.005 234.4);
   --ring: oklch(0.72 0.12 234.4);
-  --ring-subtle: color-mix(in oklch, var(--ring) 45%, transparent);
 
-  /* ============= CHARTS ============= */
-  /* Harmonious palette based on brand and status colors */
-  --chart-1: oklch(0.6884 0.1342 234.4); /* Primary brand blue */
-  --chart-2: oklch(0.65 0.12 145); /* Success - green */
-  --chart-3: oklch(0.75 0.14 85); /* Pending - amber */
-  --chart-4: oklch(0.55 0.16 38); /* Overdue - orange-red */
-  --chart-5: oklch(0.2754 0.1199 272.34); /* Sidebar brand navy */
-
-  /* ============= SIDEBAR ============= */
-  /* Primary Dark Blue - Brand Anchor (Logo Color) */
+  /* Sidebar */
   --sidebar: oklch(0.2754 0.1199 272.34);
   --sidebar-foreground: oklch(1 0 0);
-  --sidebar-primary: oklch(0.6884 0.1342 234.4); /* primary brand blue for accent */
-  --sidebar-primary-foreground: oklch(1 0 0);
-  --sidebar-accent: oklch(0.36 0.1199 272.34);
-  --sidebar-accent-foreground: oklch(1 0 0);
   --sidebar-border: oklch(0.36 0.1 272.34);
-  --sidebar-ring: oklch(0.72 0.12 234.4);
+
+  /* Header */
+  --header: oklch(1 0 0 / 0.95);
+  --header-foreground: oklch(0.2 0 0);
+  --header-border: var(--border);
+
+  /* Charts */
+  --chart-1: var(--primary);
+  --chart-2: var(--success);
+  --chart-3: oklch(0.75 0.14 85);
+  --chart-4: var(--danger);
+  --chart-5: var(--neutral);
 }
 
 .dark {
-  /* ============= CORE NEUTRALS (DARK) ============= */
   --background: oklch(0.15 0.01 272.34);
   --foreground: oklch(0.98 0 0);
-
   --card: oklch(0.18 0.01 272.34);
-  --card-foreground: var(--foreground);
-  --card-muted: oklch(0.22 0.01 272.34);
   --popover: oklch(0.18 0.01 272.34);
-  --popover-foreground: var(--foreground);
-
-  /* ============= BRAND COLORS (DARK MODE) ============= */
-  /* Lighter brand blue for dark mode visibility */
-  --primary: oklch(0.76 0.12 234.4);
-  --primary-foreground: oklch(0.15 0 0);
-  --primary-hover: oklch(0.7 0.12 234.4);
-  --primary-active: oklch(0.65 0.12 234.4);
-
-  /* Subtle surfaces & text - tinted with sidebar hue */
-  --secondary: oklch(0.22 0.01 272.34);
-  --secondary-foreground: oklch(0.9 0 0);
-
   --muted: oklch(0.25 0.01 272.34);
   --muted-foreground: oklch(0.74 0 0);
 
-  /* Accent (tinted with brand) */
+  --primary: oklch(0.76 0.12 234.4);
+  --primary-foreground: oklch(0.15 0 0);
+  --secondary: oklch(0.22 0.01 272.34);
+  --secondary-foreground: oklch(0.9 0 0);
   --accent: oklch(0.24 0.03 234.4);
   --accent-foreground: oklch(0.92 0 0);
 
-  /* ============= SEMANTIC STATUS COLORS (DARK) ============= */
-  /* Three-tier: text (lighter for dark bg), bg (dark subtle), border (mid accent) */
-
-  /* Success - lighter green for dark mode */
   --success: oklch(0.72 0.1 145);
   --success-foreground: oklch(0.15 0 0);
   --success-bg: oklch(0.24 0.04 145);
   --success-border: oklch(0.38 0.08 150);
 
-  /* Info - uses primary brand hue */
   --info: oklch(0.72 0.1 234.4);
   --info-foreground: oklch(0.15 0 0);
   --info-bg: oklch(0.24 0.04 234.4);
   --info-border: oklch(0.38 0.07 234.4);
 
-  /* Warning - lighter amber for dark mode */
   --warning: oklch(0.78 0.12 55);
   --warning-foreground: oklch(0.15 0 0);
   --warning-bg: oklch(0.26 0.04 90);
   --warning-border: oklch(0.42 0.1 90);
 
-  /* Error - lighter rose for dark mode */
-  --error: oklch(0.72 0.14 0);
-  --error-foreground: oklch(0.15 0 0);
-  --error-bg: oklch(0.24 0.03 0);
-  --error-border: oklch(0.38 0.08 0);
+  --danger: oklch(0.72 0.14 12);
+  --danger-foreground: oklch(0.15 0 0);
+  --danger-bg: oklch(0.24 0.03 10);
+  --danger-border: oklch(0.38 0.08 10);
 
-  /* Destructive - lighter red for dark mode */
-  --destructive: oklch(0.7 0.14 25);
-  --destructive-foreground: oklch(0.15 0 0);
-  --destructive-bg: oklch(0.24 0.03 20);
-  --destructive-border: oklch(0.38 0.08 20);
-
-  /* Neutral - uses sidebar brand hue */
   --neutral: oklch(0.7 0.03 272.34);
   --neutral-foreground: oklch(0.15 0 0);
   --neutral-bg: oklch(0.24 0.02 272.34);
   --neutral-border: oklch(0.38 0.03 272.34);
 
-  /* ============= GRANULAR STATUS COLORS (DARK) ============= */
-  /* Active - uses primary brand hue */
-  --status-active: oklch(0.72 0.1 234.4);
-  --status-active-bg: oklch(0.24 0.04 234.4);
-  --status-active-border: oklch(0.38 0.07 234.4);
-
-  /* Completed - uses sidebar brand hue */
-  --status-completed: oklch(0.55 0.1 272.34);
-  --status-completed-bg: oklch(0.24 0.04 272.34);
-  --status-completed-border: oklch(0.38 0.07 272.34);
-
-  /* Paid */
-  --status-paid: oklch(0.7 0.08 175);
-  --status-paid-bg: oklch(0.24 0.04 165);
-  --status-paid-border: oklch(0.4 0.08 160);
-
-  /* Success */
-  --status-success: oklch(0.72 0.1 145);
-  --status-success-bg: oklch(0.24 0.04 145);
-  --status-success-border: oklch(0.38 0.08 150);
-
-  /* Pending */
-  --status-pending: oklch(0.78 0.12 55);
-  --status-pending-bg: oklch(0.26 0.04 90);
-  --status-pending-border: oklch(0.42 0.1 90);
-
-  /* Suspended - uses sidebar brand hue */
-  --status-suspended: oklch(0.7 0.03 272.34);
-  --status-suspended-bg: oklch(0.24 0.02 272.34);
-  --status-suspended-border: oklch(0.38 0.03 272.34);
-
-  /* Unpaid */
-  --status-unpaid: oklch(0.76 0.12 45);
-  --status-unpaid-bg: oklch(0.26 0.04 70);
-  --status-unpaid-border: oklch(0.42 0.08 65);
-
-  /* Terminated */
-  --status-terminated: oklch(0.7 0.14 25);
-  --status-terminated-bg: oklch(0.24 0.03 20);
-  --status-terminated-border: oklch(0.38 0.08 20);
-
-  /* Overdue */
-  --status-overdue: oklch(0.72 0.14 0);
-  --status-overdue-bg: oklch(0.24 0.03 0);
-  --status-overdue-border: oklch(0.38 0.08 0);
-
-  /* ============= SOFT COLOR VARIANTS (for badges/pills) ============= */
-  --success-soft: var(--success-bg);
-  --info-soft: var(--info-bg);
-  --warning-soft: var(--warning-bg);
-  --destructive-soft: var(--destructive-bg);
-  --neutral-soft: var(--neutral-bg);
-
-  /* ============= UI CHROME (DARK) ============= */
   --border: oklch(0.32 0.02 272.34);
-  --border-muted: oklch(0.28 0.01 272.34);
   --input: oklch(0.35 0.02 272.34);
   --ring: oklch(0.78 0.11 234.4);
-  --ring-subtle: color-mix(in oklch, var(--ring) 40%, transparent);
 
-  /* ============= CHARTS (DARK) ============= */
-  --chart-1: oklch(0.76 0.12 234.4); /* Primary brand blue */
-  --chart-2: oklch(0.72 0.12 145); /* Success - green */
-  --chart-3: oklch(0.82 0.14 85); /* Pending - amber */
-  --chart-4: oklch(0.65 0.15 38); /* Overdue - orange-red */
-  --chart-5: oklch(0.5 0.1 272.34); /* Sidebar brand navy */
-
-  /* ============= SIDEBAR (DARK) ============= */
   --sidebar: oklch(0.22 0.1199 272.34);
-  --sidebar-foreground: oklch(1 0 0);
-  --sidebar-primary: oklch(0.76 0.12 234.4); /* lighter primary brand blue */
-  --sidebar-primary-foreground: oklch(0.15 0 0);
-  --sidebar-accent: oklch(0.32 0.1 272.34);
-  --sidebar-accent-foreground: oklch(1 0 0);
   --sidebar-border: oklch(0.3 0.08 272.34);
-  --sidebar-ring: var(--ring);
+
+  --header: oklch(0.18 0 0 / 0.95);
+  --header-foreground: var(--foreground);
+
+  --chart-3: oklch(0.82 0.14 85);
 }
 
-/* Tailwind v4 token map */
+/* =============================================================================
+   TAILWIND THEME - Maps CSS vars to utility classes (bg-*, text-*, border-*)
+   ============================================================================= */
+
 @theme {
-  /* Core */
   --color-background: var(--background);
   --color-foreground: var(--foreground);
   --color-card: var(--card);
   --color-card-foreground: var(--card-foreground);
-  --color-card-muted: var(--card-muted);
   --color-popover: var(--popover);
   --color-popover-foreground: var(--popover-foreground);
-
-  /* Brand */
-  --color-primary: var(--primary);
-  --color-primary-foreground: var(--primary-foreground);
-  --color-primary-hover: var(--primary-hover);
-  --color-primary-active: var(--primary-active);
-
-  --color-secondary: var(--secondary);
-  --color-secondary-foreground: var(--secondary-foreground);
-
   --color-muted: var(--muted);
   --color-muted-foreground: var(--muted-foreground);
 
+  --color-primary: var(--primary);
+  --color-primary-foreground: var(--primary-foreground);
+  --color-secondary: var(--secondary);
+  --color-secondary-foreground: var(--secondary-foreground);
   --color-accent: var(--accent);
   --color-accent-foreground: var(--accent-foreground);
 
-  /* Semantic status colors (three-tier: text, bg, border + soft for badges) */
   --color-success: var(--success);
   --color-success-foreground: var(--success-foreground);
   --color-success-bg: var(--success-bg);
   --color-success-border: var(--success-border);
-  --color-success-soft: var(--success-soft);
 
   --color-info: var(--info);
   --color-info-foreground: var(--info-foreground);
   --color-info-bg: var(--info-bg);
   --color-info-border: var(--info-border);
-  --color-info-soft: var(--info-soft);
 
   --color-warning: var(--warning);
   --color-warning-foreground: var(--warning-foreground);
   --color-warning-bg: var(--warning-bg);
   --color-warning-border: var(--warning-border);
-  --color-warning-soft: var(--warning-soft);
 
-  --color-error: var(--error);
-  --color-error-foreground: var(--error-foreground);
-  --color-error-bg: var(--error-bg);
-  --color-error-border: var(--error-border);
-
-  --color-destructive: var(--destructive);
-  --color-destructive-foreground: var(--destructive-foreground);
-  --color-destructive-bg: var(--destructive-bg);
-  --color-destructive-border: var(--destructive-border);
-  --color-destructive-soft: var(--destructive-soft);
+  --color-danger: var(--danger);
+  --color-danger-foreground: var(--danger-foreground);
+  --color-danger-bg: var(--danger-bg);
+  --color-danger-border: var(--danger-border);
 
   --color-neutral: var(--neutral);
   --color-neutral-foreground: var(--neutral-foreground);
   --color-neutral-bg: var(--neutral-bg);
   --color-neutral-border: var(--neutral-border);
-  --color-neutral-soft: var(--neutral-soft);
 
-  /* Granular status colors (three-tier: text, bg, border) */
-  --color-status-active: var(--status-active);
-  --color-status-active-bg: var(--status-active-bg);
-  --color-status-active-border: var(--status-active-border);
+  /* Soft variants (alias to -bg, for badge backgrounds) */
+  --color-success-soft: var(--success-bg);
+  --color-info-soft: var(--info-bg);
+  --color-warning-soft: var(--warning-bg);
+  --color-danger-soft: var(--danger-bg);
+  --color-neutral-soft: var(--neutral-bg);
 
-  --color-status-completed: var(--status-completed);
-  --color-status-completed-bg: var(--status-completed-bg);
-  --color-status-completed-border: var(--status-completed-border);
+  /* Legacy aliases (existing components use these) */
+  --color-destructive: var(--danger);
+  --color-destructive-foreground: var(--danger-foreground);
+  --color-destructive-soft: var(--danger-bg);
+  --color-error: var(--danger);
+  --color-error-foreground: var(--danger-foreground);
 
-  --color-status-paid: var(--status-paid);
-  --color-status-paid-bg: var(--status-paid-bg);
-  --color-status-paid-border: var(--status-paid-border);
-
-  --color-status-success: var(--status-success);
-  --color-status-success-bg: var(--status-success-bg);
-  --color-status-success-border: var(--status-success-border);
-
-  --color-status-pending: var(--status-pending);
-  --color-status-pending-bg: var(--status-pending-bg);
-  --color-status-pending-border: var(--status-pending-border);
-
-  --color-status-suspended: var(--status-suspended);
-  --color-status-suspended-bg: var(--status-suspended-bg);
-  --color-status-suspended-border: var(--status-suspended-border);
-
-  --color-status-unpaid: var(--status-unpaid);
-  --color-status-unpaid-bg: var(--status-unpaid-bg);
-  --color-status-unpaid-border: var(--status-unpaid-border);
-
-  --color-status-terminated: var(--status-terminated);
-  --color-status-terminated-bg: var(--status-terminated-bg);
-  --color-status-terminated-border: var(--status-terminated-border);
-
-  --color-status-overdue: var(--status-overdue);
-  --color-status-overdue-bg: var(--status-overdue-bg);
-  --color-status-overdue-border: var(--status-overdue-border);
-
-  /* UI chrome */
   --color-border: var(--border);
-  --color-border-muted: var(--border-muted);
   --color-input: var(--input);
   --color-ring: var(--ring);
-  --color-ring-subtle: var(--ring-subtle);
 
-  /* Charts */
+  --color-sidebar: var(--sidebar);
+  --color-sidebar-foreground: var(--sidebar-foreground);
+  --color-sidebar-border: var(--sidebar-border);
+
+  --color-header: var(--header);
+  --color-header-foreground: var(--header-foreground);
+  --color-header-border: var(--header-border);
+
   --color-chart-1: var(--chart-1);
   --color-chart-2: var(--chart-2);
   --color-chart-3: var(--chart-3);
   --color-chart-4: var(--chart-4);
   --color-chart-5: var(--chart-5);
-
-  /* Sidebar */
-  --color-sidebar: var(--sidebar);
-  --color-sidebar-foreground: var(--sidebar-foreground);
-  --color-sidebar-primary: var(--sidebar-primary);
-  --color-sidebar-primary-foreground: var(--sidebar-primary-foreground);
-  --color-sidebar-accent: var(--sidebar-accent);
-  --color-sidebar-accent-foreground: var(--sidebar-accent-foreground);
-  --color-sidebar-border: var(--sidebar-border);
-  --color-sidebar-ring: var(--sidebar-ring);
-}
-
-@layer base {
-  * {
-    border-color: var(--border);
-    outline-color: var(--ring-subtle);
-  }
-  body {
-    background-color: var(--background);
-    color: var(--foreground);
-    font-family: var(--font-geist-sans), system-ui, sans-serif;
-  }
-}
-
-@theme inline {
-  --animate-aurora: aurora 60s linear infinite;
-  @keyframes aurora {
-    from {
-      backgroundposition:
-        50% 50%,
-        50% 50%;
-    }
-    to {
-      backgroundposition:
-        350% 50%,
-        350% 50%;
-    }
-  }
 }
 
 @layer base {
@@ -464,5 +220,6 @@
   }
   body {
     @apply bg-background text-foreground;
+    font-family: var(--font-geist-sans), system-ui, sans-serif;
   }
 }
diff --git a/apps/portal/src/components/atoms/error-state.tsx b/apps/portal/src/components/atoms/error-state.tsx
index daac3155..00211c94 100644
--- a/apps/portal/src/components/atoms/error-state.tsx
+++ b/apps/portal/src/components/atoms/error-state.tsx
@@ -23,8 +23,8 @@ export function ErrorState({
 
   const variantClasses = {
     page: "min-h-[400px] py-12",
-    card: "bg-card text-card-foreground border border-destructive/25 rounded-[var(--cp-card-radius)] p-[var(--cp-card-padding)] shadow-[var(--cp-card-shadow)]",
-    inline: "bg-destructive-soft border border-destructive/25 rounded-md p-4",
+    card: "bg-card text-card-foreground border border-danger/25 rounded-2xl p-6 shadow-md",
+    inline: "bg-danger-soft border border-danger/25 rounded-md p-4",
   };
 
   const iconSizes = {
@@ -47,7 +47,7 @@ export function ErrorState({
 
   return (
     <div className={cn(baseClasses, variantClasses[variant], className)}>
-      <div className={cn("text-destructive mb-4", variant === "inline" && "flex-shrink-0")}>
+      <div className={cn("text-danger mb-4", variant === "inline" && "flex-shrink-0")}>
         <ExclamationTriangleIcon className={iconSizes[variant]} />
       </div>
 
@@ -63,7 +63,7 @@ export function ErrorState({
             onClick={onRetry}
             variant="outline"
             size={variant === "inline" ? "sm" : "default"}
-            className="text-destructive border-destructive/30 hover:bg-destructive-soft"
+            className="text-danger border-danger/30 hover:bg-danger-soft"
           >
             <ArrowPathIcon className="h-4 w-4 mr-2" />
             {retryLabel}
diff --git a/apps/portal/src/components/atoms/loading-skeleton.tsx b/apps/portal/src/components/atoms/loading-skeleton.tsx
index 24811d54..183499e1 100644
--- a/apps/portal/src/components/atoms/loading-skeleton.tsx
+++ b/apps/portal/src/components/atoms/loading-skeleton.tsx
@@ -6,22 +6,14 @@ interface SkeletonProps {
 }
 
 export function Skeleton({ className, animate = true }: SkeletonProps) {
-  return (
-    <div
-      className={cn(
-        "bg-[var(--cp-skeleton-base)] rounded-md",
-        animate && "animate-pulse",
-        className
-      )}
-    />
-  );
+  return <div className={cn("bg-muted rounded-md", animate && "animate-pulse", className)} />;
 }
 
 export function LoadingCard({ className }: { className?: string }) {
   return (
     <div
       className={cn(
-        "bg-card text-card-foreground border border-border rounded-[var(--cp-card-radius)] p-[var(--cp-card-padding)] shadow-[var(--cp-card-shadow)]",
+        "bg-card text-card-foreground border border-border rounded-2xl p-6 shadow-md",
         className
       )}
     >
@@ -45,7 +37,7 @@ export function LoadingCard({ className }: { className?: string }) {
 
 export function LoadingTable({ rows = 5, columns = 4 }: { rows?: number; columns?: number }) {
   return (
-    <div className="bg-card text-card-foreground border border-border rounded-[var(--cp-card-radius)] overflow-hidden">
+    <div className="bg-card text-card-foreground border border-border rounded-2xl overflow-hidden">
       {/* Header */}
       <div className="border-b border-border p-4">
         <div className="grid gap-4" style={{ gridTemplateColumns: `repeat(${columns}, 1fr)` }}>
@@ -77,7 +69,7 @@ export function LoadingStats({ count = 4 }: { count?: number }) {
       {Array.from({ length: count }).map((_, i) => (
         <div
           key={i}
-          className="bg-card text-card-foreground border border-border rounded-[var(--cp-card-radius)] p-[var(--cp-card-padding)] shadow-[var(--cp-card-shadow)]"
+          className="bg-card text-card-foreground border border-border rounded-2xl p-6 shadow-md"
         >
           <div className="flex items-center">
             <Skeleton className="h-8 w-8 rounded-full" />
diff --git a/apps/portal/src/components/organisms/AppShell/AppShell.tsx b/apps/portal/src/components/organisms/AppShell/AppShell.tsx
index 9d78ddab..eb3c2a03 100644
--- a/apps/portal/src/components/organisms/AppShell/AppShell.tsx
+++ b/apps/portal/src/components/organisms/AppShell/AppShell.tsx
@@ -154,7 +154,7 @@ export function AppShell({ children }: AppShellProps) {
               className="fixed inset-0 bg-black/50 animate-in fade-in duration-300"
               onClick={() => setSidebarOpen(false)}
             />
-            <div className="relative flex-1 flex flex-col max-w-xs w-full bg-[var(--cp-sidebar-bg)] border-r border-[var(--cp-sidebar-border)] animate-in slide-in-from-left duration-300 shadow-2xl">
+            <div className="relative flex-1 flex flex-col max-w-xs w-full bg-sidebar border-r border-sidebar-border animate-in slide-in-from-left duration-300 shadow-2xl">
               <div className="absolute top-0 right-0 -mr-12 pt-2" />
               <Sidebar
                 navigation={navigation}
@@ -169,7 +169,7 @@ export function AppShell({ children }: AppShellProps) {
 
         {/* Desktop sidebar */}
         <div className="hidden md:flex md:flex-shrink-0">
-          <div className="flex flex-col w-[240px] border-r border-[var(--cp-sidebar-border)] bg-[var(--cp-sidebar-bg)] shadow-sm">
+          <div className="flex flex-col w-[240px] border-r border-sidebar-border bg-sidebar shadow-sm">
             <Sidebar
               navigation={navigation}
               pathname={pathname}
diff --git a/apps/portal/src/components/organisms/AppShell/Header.tsx b/apps/portal/src/components/organisms/AppShell/Header.tsx
index 6596e71e..4f1f1d30 100644
--- a/apps/portal/src/components/organisms/AppShell/Header.tsx
+++ b/apps/portal/src/components/organisms/AppShell/Header.tsx
@@ -24,7 +24,7 @@ export const Header = memo(function Header({ onMenuClick, user, profileReady }:
       : displayName.slice(0, 2).toUpperCase();
 
   return (
-    <div className="bg-[var(--cp-header-bg)] border-b border-[var(--cp-header-border)]/50 backdrop-blur-xl">
+    <div className="bg-header border-b border-header-border/50 backdrop-blur-xl">
       <div className="flex items-center h-16 gap-3 px-4 sm:px-6">
         <button
           type="button"
diff --git a/apps/portal/src/components/organisms/AppShell/Sidebar.tsx b/apps/portal/src/components/organisms/AppShell/Sidebar.tsx
index 6a0637b7..2c3e87c4 100644
--- a/apps/portal/src/components/organisms/AppShell/Sidebar.tsx
+++ b/apps/portal/src/components/organisms/AppShell/Sidebar.tsx
@@ -22,8 +22,8 @@ export const Sidebar = memo(function Sidebar({
   toggleExpanded,
 }: SidebarProps) {
   return (
-    <div className="flex flex-col h-0 flex-1 bg-[var(--cp-sidebar-bg)]">
-      <div className="flex items-center flex-shrink-0 h-16 px-5 border-b border-[var(--cp-sidebar-border)]">
+    <div className="flex flex-col h-0 flex-1 bg-sidebar">
+      <div className="flex items-center flex-shrink-0 h-16 px-5 border-b border-sidebar-border">
         <div className="flex items-center space-x-3">
           <div className="h-10 w-10 bg-white rounded-xl shadow-lg shadow-black/10 flex items-center justify-center">
             <Logo size={26} />
diff --git a/apps/portal/src/features/billing/components/InvoiceStatusBadge.tsx b/apps/portal/src/features/billing/components/InvoiceStatusBadge.tsx
index b4b11682..e0413536 100644
--- a/apps/portal/src/features/billing/components/InvoiceStatusBadge.tsx
+++ b/apps/portal/src/features/billing/components/InvoiceStatusBadge.tsx
@@ -16,53 +16,61 @@ type StatusConfig = {
   label: string;
 };
 
+/**
+ * Status → Semantic color mapping:
+ * - Paid → success (green)
+ * - Pending, Unpaid → warning (amber)
+ * - Draft, Cancelled → neutral (navy)
+ * - Overdue, Collections → danger (red)
+ * - Refunded → info (blue)
+ */
 const STATUS_CONFIG: Record<InvoiceStatus, StatusConfig> = {
   Draft: {
     icon: <DocumentTextIcon className="h-4 w-4" />,
     iconColor: "text-neutral",
-    color: "bg-neutral-soft text-neutral border-neutral-border",
+    color: "bg-neutral-bg text-neutral border-neutral-border",
     label: "Draft",
   },
   Pending: {
     icon: <ClockIcon className="h-4 w-4" />,
-    iconColor: "text-status-pending",
-    color: "bg-status-pending-bg text-status-pending border-status-pending-border",
+    iconColor: "text-warning",
+    color: "bg-warning-bg text-warning border-warning-border",
     label: "Pending",
   },
   Paid: {
     icon: <CheckCircleIcon className="h-4 w-4" />,
-    iconColor: "text-status-paid",
-    color: "bg-status-paid-bg text-status-paid border-status-paid-border",
+    iconColor: "text-success",
+    color: "bg-success-bg text-success border-success-border",
     label: "Paid",
   },
   Unpaid: {
     icon: <ClockIcon className="h-4 w-4" />,
-    iconColor: "text-status-unpaid",
-    color: "bg-status-unpaid-bg text-status-unpaid border-status-unpaid-border",
+    iconColor: "text-warning",
+    color: "bg-warning-bg text-warning border-warning-border",
     label: "Unpaid",
   },
   Overdue: {
     icon: <ExclamationTriangleIcon className="h-4 w-4" />,
-    iconColor: "text-status-overdue",
-    color: "bg-status-overdue-bg text-status-overdue border-status-overdue-border",
+    iconColor: "text-danger",
+    color: "bg-danger-bg text-danger border-danger-border",
     label: "Overdue",
   },
   Cancelled: {
     icon: <DocumentTextIcon className="h-4 w-4" />,
     iconColor: "text-neutral",
-    color: "bg-neutral-soft text-neutral border-neutral-border",
+    color: "bg-neutral-bg text-neutral border-neutral-border",
     label: "Cancelled",
   },
   Refunded: {
     icon: <CheckCircleIcon className="h-4 w-4" />,
     iconColor: "text-info",
-    color: "bg-info-soft text-info border-info-border",
+    color: "bg-info-bg text-info border-info-border",
     label: "Refunded",
   },
   Collections: {
     icon: <ExclamationTriangleIcon className="h-4 w-4" />,
-    iconColor: "text-destructive",
-    color: "bg-destructive-soft text-destructive border-destructive-border",
+    iconColor: "text-danger",
+    color: "bg-danger-bg text-danger border-danger-border",
     label: "Collections",
   },
 };
@@ -70,7 +78,7 @@ const STATUS_CONFIG: Record<InvoiceStatus, StatusConfig> = {
 const DEFAULT_STATUS: StatusConfig = {
   icon: <DocumentTextIcon className="h-4 w-4" />,
   iconColor: "text-neutral",
-  color: "bg-neutral-soft text-neutral border-neutral-border",
+  color: "bg-neutral-bg text-neutral border-neutral-border",
   label: "Unknown",
 };
 
diff --git a/apps/portal/src/features/catalog/components/base/CardBadge.tsx b/apps/portal/src/features/catalog/components/base/CardBadge.tsx
index 4d4b757b..12fbca38 100644
--- a/apps/portal/src/features/catalog/components/base/CardBadge.tsx
+++ b/apps/portal/src/features/catalog/components/base/CardBadge.tsx
@@ -21,7 +21,7 @@ export function CardBadge({ text, variant = "default", size = "md" }: CardBadgeP
       case "gold":
         return "bg-warning-bg text-warning border-warning-border";
       case "platinum":
-        return "bg-status-completed-bg text-status-completed border-status-completed-border";
+        return "bg-neutral-bg text-neutral border-neutral-border";
       case "silver":
         return "bg-neutral-soft text-neutral border-neutral-border";
       case "recommended":
diff --git a/apps/portal/src/features/sim-management/components/DataUsageChart.tsx b/apps/portal/src/features/sim-management/components/DataUsageChart.tsx
index 69add8cc..a9f9c0ff 100644
--- a/apps/portal/src/features/sim-management/components/DataUsageChart.tsx
+++ b/apps/portal/src/features/sim-management/components/DataUsageChart.tsx
@@ -38,16 +38,16 @@ export function DataUsageChart({
   };
 
   const getUsageColor = (percentage: number) => {
-    if (percentage >= 90) return "bg-destructive";
+    if (percentage >= 90) return "bg-danger";
     if (percentage >= 75) return "bg-warning";
-    if (percentage >= 50) return "bg-status-unpaid";
+    if (percentage >= 50) return "bg-warning/70";
     return "bg-success";
   };
 
   const getUsageTextColor = (percentage: number) => {
-    if (percentage >= 90) return "text-destructive";
+    if (percentage >= 90) return "text-danger";
     if (percentage >= 75) return "text-warning";
-    if (percentage >= 50) return "text-status-unpaid";
+    if (percentage >= 50) return "text-warning";
     return "text-success";
   };
 
diff --git a/apps/portal/src/features/subscriptions/components/SubscriptionDetails.tsx b/apps/portal/src/features/subscriptions/components/SubscriptionDetails.tsx
index b2061188..a83a4d7c 100644
--- a/apps/portal/src/features/subscriptions/components/SubscriptionDetails.tsx
+++ b/apps/portal/src/features/subscriptions/components/SubscriptionDetails.tsx
@@ -255,19 +255,17 @@ export const SubscriptionDetails = forwardRef<HTMLDivElement, SubscriptionDetail
             {/* VPN Service Information */}
             {isVpnService(subscription.productName) && (
               <SubCard title="VPN Service Information" icon={<ServerIcon className="h-5 w-5" />}>
-                <div className="bg-status-completed-bg border border-status-completed-border rounded-lg p-4">
+                <div className="bg-info-bg border border-info-border rounded-lg p-4">
                   <div className="flex items-start space-x-3">
-                    <div className="bg-status-completed/20 rounded-lg p-2">
-                      <ServerIcon className="h-5 w-5 text-status-completed" />
+                    <div className="bg-info/20 rounded-lg p-2">
+                      <ServerIcon className="h-5 w-5 text-info" />
                     </div>
                     <div>
-                      <h4 className="text-sm font-semibold text-status-completed mb-2">
-                        VPN Service Features
-                      </h4>
-                      <p className="text-sm text-status-completed/80 mb-3">
+                      <h4 className="text-sm font-semibold text-info mb-2">VPN Service Features</h4>
+                      <p className="text-sm text-info/80 mb-3">
                         Your VPN service provides secure and private internet access.
                       </p>
-                      <ul className="text-sm text-status-completed/70 space-y-1">
+                      <ul className="text-sm text-info/70 space-y-1">
                         <li>• Encrypted internet connection</li>
                         <li>• Multiple server locations</li>
                         <li>• No-logs policy</li>
diff --git a/apps/portal/src/features/subscriptions/components/SubscriptionStatusBadge.tsx b/apps/portal/src/features/subscriptions/components/SubscriptionStatusBadge.tsx
index 753d971d..93927e76 100644
--- a/apps/portal/src/features/subscriptions/components/SubscriptionStatusBadge.tsx
+++ b/apps/portal/src/features/subscriptions/components/SubscriptionStatusBadge.tsx
@@ -5,23 +5,25 @@ import {
   type SubscriptionStatus,
 } from "@customer-portal/domain/subscriptions";
 
+/**
+ * Status → Semantic color mapping:
+ * - Active, Paid → success (green)
+ * - Pending, Unpaid → warning (amber)
+ * - Suspended, Completed, Cancelled, Inactive → neutral (navy)
+ * - Terminated, Overdue → danger (red)
+ */
 const STATUS_COLOR_MAP: Record<SubscriptionStatus, string> = {
-  [SUBSCRIPTION_STATUS.ACTIVE]:
-    "bg-status-active-bg text-status-active border-status-active-border",
-  [SUBSCRIPTION_STATUS.INACTIVE]: "bg-neutral-soft text-neutral border-neutral-border",
-  [SUBSCRIPTION_STATUS.PENDING]:
-    "bg-status-pending-bg text-status-pending border-status-pending-border",
-  [SUBSCRIPTION_STATUS.SUSPENDED]:
-    "bg-status-suspended-bg text-status-suspended border-status-suspended-border",
-  [SUBSCRIPTION_STATUS.CANCELLED]: "bg-neutral-soft text-neutral border-neutral-border",
-  [SUBSCRIPTION_STATUS.TERMINATED]:
-    "bg-status-terminated-bg text-status-terminated border-status-terminated-border",
-  [SUBSCRIPTION_STATUS.COMPLETED]:
-    "bg-status-completed-bg text-status-completed border-status-completed-border",
+  [SUBSCRIPTION_STATUS.ACTIVE]: "bg-success-bg text-success border-success-border",
+  [SUBSCRIPTION_STATUS.INACTIVE]: "bg-neutral-bg text-neutral border-neutral-border",
+  [SUBSCRIPTION_STATUS.PENDING]: "bg-warning-bg text-warning border-warning-border",
+  [SUBSCRIPTION_STATUS.SUSPENDED]: "bg-neutral-bg text-neutral border-neutral-border",
+  [SUBSCRIPTION_STATUS.CANCELLED]: "bg-neutral-bg text-neutral border-neutral-border",
+  [SUBSCRIPTION_STATUS.TERMINATED]: "bg-danger-bg text-danger border-danger-border",
+  [SUBSCRIPTION_STATUS.COMPLETED]: "bg-neutral-bg text-neutral border-neutral-border",
 };
 
 export function SubscriptionStatusBadge({ status }: { status: SubscriptionStatus }) {
-  const color = STATUS_COLOR_MAP[status] ?? "bg-neutral-soft text-neutral border-neutral-border";
+  const color = STATUS_COLOR_MAP[status] ?? "bg-neutral-bg text-neutral border-neutral-border";
 
   return (
     <span className={`inline-flex px-2.5 py-1 text-xs font-medium rounded-full border ${color}`}>
diff --git a/apps/portal/src/styles/tokens.css b/apps/portal/src/styles/tokens.css
index f8de21e9..7deeb494 100644
--- a/apps/portal/src/styles/tokens.css
+++ b/apps/portal/src/styles/tokens.css
@@ -1,6 +1,22 @@
+/**
+ * Design System Tokens
+ * 
+ * This file contains NON-COLOR tokens only.
+ * All colors are defined in globals.css for a single source of truth.
+ * 
+ * Contents:
+ * - Spacing scale
+ * - Container widths
+ * - Typography scale
+ * - Border radii
+ * - Shadows
+ * - Motion/transitions
+ * - Component-specific tokens (card, badge, etc.)
+ */
+
 :root {
-  /* ============= SPACE ============= */
-  /* Single, consistent scale (4px base) */
+  /* ============= SPACING ============= */
+  /* 4px base scale */
   --cp-space-1: 0.25rem; /* 4px  */
   --cp-space-2: 0.5rem; /* 8px  */
   --cp-space-3: 0.75rem; /* 12px */
@@ -10,7 +26,7 @@
   --cp-space-8: 2rem; /* 32px */
   --cp-space-12: 3rem; /* 48px */
 
-  /* Friendly aliases (optional) */
+  /* Friendly aliases */
   --cp-space-xs: var(--cp-space-1);
   --cp-space-sm: var(--cp-space-2);
   --cp-space-md: var(--cp-space-3);
@@ -20,7 +36,6 @@
   --cp-space-3xl: var(--cp-space-12);
 
   /* ============= CONTAINERS ============= */
-  /* Mirrors Tailwind defaults for familiarity */
   --cp-container-sm: 640px;
   --cp-container-md: 768px;
   --cp-container-lg: 1024px;
@@ -31,7 +46,6 @@
   --cp-page-max-width: var(--cp-container-xl);
   --cp-page-padding-x: var(--cp-space-6);
   --cp-page-padding-y: var(--cp-space-6);
-  /* Compat alias (some components reference this older name) */
   --cp-page-padding: var(--cp-page-padding-x);
 
   /* Sidebar */
@@ -39,24 +53,22 @@
   --cp-sidebar-width-collapsed: 4rem; /* 64px  */
 
   /* ============= TYPOGRAPHY ============= */
-  /* Base sizing */
   --cp-text-xs: 0.75rem; /* 12px */
   --cp-text-sm: 0.875rem; /* 14px */
   --cp-text-base: 1rem; /* 16px */
   --cp-text-lg: 1.125rem; /* 18px */
   --cp-text-xl: 1.25rem; /* 20px */
-
-  /* Fluid display sizes (modern, but safe) */
   --cp-text-2xl: clamp(1.25rem, 1.1rem + 0.6vw, 1.5rem); /* 20–24px */
   --cp-text-3xl: clamp(1.5rem, 1.2rem + 1.2vw, 1.875rem); /* 24–30px */
 
-  /* Weights & leading */
+  /* Weights */
   --cp-font-light: 300;
   --cp-font-normal: 400;
   --cp-font-medium: 500;
   --cp-font-semibold: 600;
   --cp-font-bold: 700;
 
+  /* Line heights */
   --cp-leading-tight: 1.25;
   --cp-leading-normal: 1.5;
   --cp-leading-relaxed: 1.625;
@@ -68,267 +80,60 @@
   --cp-radius-xl: 1.5rem; /* 24px */
   --cp-radius-pill: 9999px;
 
-  /* Components derive from base radii */
+  /* Component radii */
   --cp-card-radius: var(--cp-radius-lg);
   --cp-card-radius-lg: var(--cp-radius-xl);
 
-  /* Card chrome (semantic, used by cp-card utilities/components) */
-  --cp-card-border: var(--cp-border);
-  --cp-card-shadow: var(--cp-shadow-2);
-  --cp-card-shadow-lg: var(--cp-shadow-3);
-
   /* ============= SHADOWS ============= */
   --cp-shadow-1: 0 1px 3px 0 rgb(0 0 0 / 0.08), 0 1px 2px -1px rgb(0 0 0 / 0.06);
   --cp-shadow-2: 0 2px 4px -1px rgb(0 0 0 / 0.1), 0 1px 3px 0 rgb(0 0 0 / 0.08);
   --cp-shadow-3: 0 10px 15px -3px rgb(0 0 0 / 0.1), 0 4px 6px -2px rgb(0 0 0 / 0.05);
 
+  /* Component shadows */
+  --cp-card-shadow: var(--cp-shadow-2);
+  --cp-card-shadow-lg: var(--cp-shadow-3);
+
   /* ============= MOTION ============= */
   --cp-duration-fast: 150ms;
   --cp-duration-normal: 200ms;
   --cp-duration-slow: 300ms;
   --cp-ease-standard: cubic-bezier(0.4, 0, 0.2, 1);
-  /* Compat aliases (some components reference these names) */
+
+  /* Aliases */
   --cp-transition-fast: var(--cp-duration-fast);
   --cp-transition-normal: var(--cp-duration-normal);
   --cp-transition-slow: var(--cp-duration-slow);
 
-  /* ============= COLOR (LIGHT) ============= */
-  /* Core neutrals */
-  --cp-bg: oklch(1 0 0); /* pure white for main content area */
-  --cp-fg: oklch(0.16 0 0);
-  --cp-surface: oklch(1 0 0); /* pure white for cards */
-  --cp-muted: oklch(0.97 0.008 234.4); /* subtle brand-tinted gray */
-  --cp-border: oklch(0.9 0.005 234.4);
-  --cp-border-muted: oklch(0.92 0.003 234.4);
+  /* ============= COMPONENT TOKENS ============= */
 
-  /* ============= BRAND COLORS (from logo) ============= */
-  /* Primary Light Blue - Brand Accent */
-  --cp-primary: oklch(0.6884 0.1342 234.4);
-  --cp-on-primary: oklch(0.99 0 0);
-  --cp-primary-hover: oklch(0.62 0.1342 234.4);
-  --cp-primary-active: oklch(0.56 0.1342 234.4);
-  --cp-ring: oklch(0.72 0.12 234.4);
+  /* Card */
+  --cp-card-padding: var(--cp-space-6);
+  --cp-card-padding-sm: var(--cp-space-4);
+  --cp-card-border: var(--border);
 
-  /* ============= SEMANTIC STATUS COLORS ============= */
-  /* Three-tier system: text (dark readable), bg (almost white), border (subtle accent) */
-
-  /* Success - #166534 text, #F0FDF4 bg, #BBF7D0 border */
-  --cp-success: oklch(0.42 0.1 145);
-  --cp-on-success: oklch(0.99 0 0);
-  --cp-success-bg: oklch(0.98 0.02 145);
-  --cp-success-border: oklch(0.93 0.08 150);
-
-  /* Info - uses primary brand hue */
-  --cp-info: oklch(0.48 0.1 234.4);
-  --cp-on-info: oklch(0.99 0 0);
-  --cp-info-bg: oklch(0.97 0.02 234.4);
-  --cp-info-border: oklch(0.91 0.05 234.4);
-
-  /* Warning - #92400E text, #FFFBEB bg, #FDE68A border */
-  --cp-warning: oklch(0.45 0.12 55);
-  --cp-on-warning: oklch(0.99 0 0);
-  --cp-warning-bg: oklch(0.99 0.02 90);
-  --cp-warning-border: oklch(0.92 0.12 90);
-
-  /* Error - #9F1239 text, #FFF1F2 bg, #FECDD3 border */
-  --cp-error: oklch(0.42 0.16 0);
-  --cp-on-error: oklch(0.99 0 0);
-  --cp-error-bg: oklch(0.98 0.01 0);
-  --cp-error-border: oklch(0.89 0.06 0);
-
-  /* Destructive - #991B1B text, #FEF2F2 bg, #FECACA border */
-  --cp-destructive: oklch(0.43 0.15 25);
-  --cp-on-destructive: oklch(0.99 0 0);
-  --cp-destructive-bg: oklch(0.98 0.01 20);
-  --cp-destructive-border: oklch(0.89 0.06 20);
-
-  /* Neutral - uses sidebar brand hue */
-  --cp-neutral: oklch(0.36 0.03 272.34);
-  --cp-on-neutral: oklch(0.99 0 0);
-  --cp-neutral-bg: oklch(0.97 0.008 272.34);
-  --cp-neutral-border: oklch(0.87 0.02 272.34);
-
-  /* ============= GRANULAR STATUS COLORS ============= */
-  /* Three-tier: text (dark readable), bg (almost white), border (subtle accent) */
-
-  /* Active - uses primary brand hue */
-  --cp-status-active: oklch(0.48 0.1 234.4);
-  --cp-status-active-bg: oklch(0.97 0.02 234.4);
-  --cp-status-active-border: oklch(0.91 0.05 234.4);
-
-  /* Completed - uses sidebar brand hue */
-  --cp-status-completed: oklch(0.2754 0.1199 272.34);
-  --cp-status-completed-bg: oklch(0.96 0.02 272.34);
-  --cp-status-completed-border: oklch(0.87 0.07 272.34);
-
-  /* Paid - #0F766E text, #ECFDF5 bg, #A7F3D0 border (teal, closer to brand) */
-  --cp-status-paid: oklch(0.48 0.08 175);
-  --cp-status-paid-bg: oklch(0.98 0.02 165);
-  --cp-status-paid-border: oklch(0.92 0.08 160);
-
-  /* Success - #166534 text, #F0FDF4 bg, #BBF7D0 border */
-  --cp-status-success: oklch(0.42 0.1 145);
-  --cp-status-success-bg: oklch(0.98 0.02 145);
-  --cp-status-success-border: oklch(0.93 0.08 150);
-
-  /* Pending - #92400E text, #FFFBEB bg, #FDE68A border */
-  --cp-status-pending: oklch(0.45 0.12 55);
-  --cp-status-pending-bg: oklch(0.99 0.02 90);
-  --cp-status-pending-border: oklch(0.92 0.12 90);
-
-  /* Suspended - uses sidebar brand hue */
-  --cp-status-suspended: oklch(0.36 0.03 272.34);
-  --cp-status-suspended-bg: oklch(0.97 0.008 272.34);
-  --cp-status-suspended-border: oklch(0.87 0.02 272.34);
-
-  /* Unpaid - #9A3412 text, #FFF7ED bg, #FED7AA border */
-  --cp-status-unpaid: oklch(0.46 0.13 45);
-  --cp-status-unpaid-bg: oklch(0.98 0.02 70);
-  --cp-status-unpaid-border: oklch(0.9 0.08 65);
-
-  /* Terminated - #991B1B text, #FEF2F2 bg, #FECACA border */
-  --cp-status-terminated: oklch(0.43 0.15 25);
-  --cp-status-terminated-bg: oklch(0.98 0.01 20);
-  --cp-status-terminated-border: oklch(0.89 0.06 20);
-
-  /* Overdue - #9F1239 text, #FFF1F2 bg, #FECDD3 border */
-  --cp-status-overdue: oklch(0.42 0.16 0);
-  --cp-status-overdue-bg: oklch(0.98 0.01 0);
-  --cp-status-overdue-border: oklch(0.89 0.06 0);
-
-  /* ============= SIDEBAR ============= */
-  /* Primary Dark Blue - Brand Anchor (Logo Color) */
-  --cp-sidebar-bg: oklch(0.2754 0.1199 272.34);
-  --cp-sidebar-border: oklch(0.36 0.1 272.34);
-  --cp-sidebar-text: oklch(1 0 0);
-  --cp-sidebar-text-hover: oklch(1 0 0);
-  --cp-sidebar-hover-bg: oklch(0.36 0.1199 272.34);
-  --cp-sidebar-active-bg: oklch(0.6884 0.1342 234.4 / 0.25); /* primary brand blue tint */
-  --cp-sidebar-active-text: oklch(1 0 0);
-
-  /* Header */
-  --cp-header-bg: oklch(1 0 0 / 0.95); /* slightly more opaque white */
-  --cp-header-border: var(--cp-border);
-  --cp-header-text: oklch(0.2 0 0);
-
-  /* Badges & Pills */
+  /* Badge */
   --cp-badge-radius: var(--cp-radius-sm);
   --cp-badge-padding-x: var(--cp-space-2);
   --cp-badge-padding-y: 0.125rem;
   --cp-badge-font-size: var(--cp-text-xs);
   --cp-badge-font-weight: var(--cp-font-medium);
 
+  /* Pill */
   --cp-pill-radius: var(--cp-radius-pill);
   --cp-pill-px: var(--cp-space-3);
   --cp-pill-py: var(--cp-space-1);
 
-  /* Components (derive from spacing) */
-  --cp-card-padding: var(--cp-space-6);
-  --cp-card-padding-sm: var(--cp-space-4);
-
   /* Focus */
-  --cp-focus-ring: 2px solid var(--cp-ring);
+  --cp-focus-ring: 2px solid var(--ring);
   --cp-focus-ring-offset: 2px;
 
-  /* Skeletons */
-  --cp-skeleton-base: rgb(243 244 246); /* gray-100 */
-  --cp-skeleton-shimmer: rgb(249 250 251); /* gray-50  */
+  /* Skeleton loading */
+  --cp-skeleton-base: rgb(243 244 246);
+  --cp-skeleton-shimmer: rgb(249 250 251);
 }
 
-/* ============= DARK MODE OVERRIDES ============= */
+/* Dark mode overrides for non-color tokens */
 .dark {
-  --cp-bg: oklch(0.15 0.01 272.34);
-  --cp-fg: oklch(0.98 0 0);
-  --cp-surface: oklch(0.18 0.01 272.34);
-  --cp-muted: oklch(0.22 0.01 272.34);
-  --cp-border: oklch(0.32 0.02 272.34);
-  --cp-border-muted: oklch(0.28 0.01 272.34);
-
-  /* Brand - lighter for dark mode visibility */
-  --cp-primary: oklch(0.76 0.12 234.4);
-  --cp-on-primary: oklch(0.15 0 0);
-  --cp-primary-hover: oklch(0.7 0.12 234.4);
-  --cp-primary-active: oklch(0.65 0.12 234.4);
-  --cp-ring: oklch(0.78 0.11 234.4);
-
-  /* Semantic colors - dark mode (three-tier) */
-  --cp-success: oklch(0.72 0.1 145);
-  --cp-on-success: oklch(0.15 0 0);
-  --cp-success-bg: oklch(0.24 0.04 145);
-  --cp-success-border: oklch(0.38 0.08 150);
-
-  --cp-info: oklch(0.72 0.1 234.4);
-  --cp-on-info: oklch(0.15 0 0);
-  --cp-info-bg: oklch(0.24 0.04 234.4);
-  --cp-info-border: oklch(0.38 0.07 234.4);
-
-  --cp-warning: oklch(0.78 0.12 55);
-  --cp-on-warning: oklch(0.15 0 0);
-  --cp-warning-bg: oklch(0.26 0.04 90);
-  --cp-warning-border: oklch(0.42 0.1 90);
-
-  --cp-error: oklch(0.72 0.14 0);
-  --cp-on-error: oklch(0.15 0 0);
-  --cp-error-bg: oklch(0.24 0.03 0);
-  --cp-error-border: oklch(0.38 0.08 0);
-
-  --cp-destructive: oklch(0.7 0.14 25);
-  --cp-on-destructive: oklch(0.15 0 0);
-  --cp-destructive-bg: oklch(0.24 0.03 20);
-  --cp-destructive-border: oklch(0.38 0.08 20);
-
-  --cp-neutral: oklch(0.7 0.03 272.34);
-  --cp-on-neutral: oklch(0.15 0 0);
-  --cp-neutral-bg: oklch(0.24 0.02 272.34);
-  --cp-neutral-border: oklch(0.38 0.03 272.34);
-
-  /* Granular status colors - dark mode (three-tier) */
-  --cp-status-active: oklch(0.72 0.1 234.4);
-  --cp-status-active-bg: oklch(0.24 0.04 234.4);
-  --cp-status-active-border: oklch(0.38 0.07 234.4);
-
-  --cp-status-completed: oklch(0.55 0.1 272.34);
-  --cp-status-completed-bg: oklch(0.24 0.04 272.34);
-  --cp-status-completed-border: oklch(0.38 0.07 272.34);
-
-  --cp-status-paid: oklch(0.7 0.08 175);
-  --cp-status-paid-bg: oklch(0.24 0.04 165);
-  --cp-status-paid-border: oklch(0.4 0.08 160);
-
-  --cp-status-success: oklch(0.72 0.1 145);
-  --cp-status-success-bg: oklch(0.24 0.04 145);
-  --cp-status-success-border: oklch(0.38 0.08 150);
-
-  --cp-status-pending: oklch(0.78 0.12 55);
-  --cp-status-pending-bg: oklch(0.26 0.04 90);
-  --cp-status-pending-border: oklch(0.42 0.1 90);
-
-  --cp-status-suspended: oklch(0.7 0.03 272.34);
-  --cp-status-suspended-bg: oklch(0.24 0.02 272.34);
-  --cp-status-suspended-border: oklch(0.38 0.03 272.34);
-
-  --cp-status-unpaid: oklch(0.76 0.12 45);
-  --cp-status-unpaid-bg: oklch(0.26 0.04 70);
-  --cp-status-unpaid-border: oklch(0.42 0.08 65);
-
-  --cp-status-terminated: oklch(0.7 0.14 25);
-  --cp-status-terminated-bg: oklch(0.24 0.03 20);
-  --cp-status-terminated-border: oklch(0.38 0.08 20);
-
-  --cp-status-overdue: oklch(0.72 0.14 0);
-  --cp-status-overdue-bg: oklch(0.24 0.03 0);
-  --cp-status-overdue-border: oklch(0.38 0.08 0);
-
-  /* Sidebar - Dark navy from logo */
-  --cp-sidebar-bg: oklch(0.22 0.1199 272.34);
-  --cp-sidebar-border: oklch(0.3 0.08 272.34);
-  --cp-sidebar-hover-bg: oklch(0.32 0.1 272.34);
-  --cp-sidebar-text: oklch(1 0 0);
-  --cp-sidebar-text-hover: oklch(1 0 0);
-  --cp-sidebar-active-bg: oklch(0.6884 0.1342 234.4 / 0.25); /* primary brand blue tint */
-  --cp-sidebar-active-text: oklch(1 0 0);
-
-  --cp-header-bg: oklch(0.18 0 0 / 0.95);
-  --cp-header-border: var(--cp-border);
-  --cp-header-text: var(--cp-fg);
+  --cp-skeleton-base: rgb(55 65 81);
+  --cp-skeleton-shimmer: rgb(75 85 99);
 }
diff --git a/apps/portal/src/styles/utilities.css b/apps/portal/src/styles/utilities.css
index 5559e37e..0e23be77 100644
--- a/apps/portal/src/styles/utilities.css
+++ b/apps/portal/src/styles/utilities.css
@@ -1,9 +1,8 @@
 /**
- * Minimal Design System Utilities
+ * Design System Utilities
  * 
- * This file contains only semantic component primitives.
- * Layout, spacing, typography, and responsive utilities come from Tailwind.
- * Design tokens (colors, spacing, etc.) are defined in tokens.css and globals.css.
+ * Semantic component primitives using the consolidated color system.
+ * Layout, spacing, typography utilities come from Tailwind.
  */
 
 @layer utilities {
@@ -59,7 +58,7 @@
     white-space: nowrap;
   }
 
-  /* Badge variants */
+  /* Badge variants - using 5 semantic colors */
   .cp-badge-primary {
     background: var(--primary);
     color: var(--primary-foreground);
@@ -75,40 +74,62 @@
     color: var(--success-foreground);
   }
 
-  .cp-badge-warning {
-    background: var(--warning);
-    color: var(--warning-foreground);
-  }
-
-  .cp-badge-error {
-    background: var(--destructive);
-    color: var(--destructive-foreground);
-  }
-
   .cp-badge-info {
     background: var(--info);
     color: var(--info-foreground);
   }
 
-  /* Soft badge variants */
+  .cp-badge-warning {
+    background: var(--warning);
+    color: var(--warning-foreground);
+  }
+
+  .cp-badge-danger {
+    background: var(--danger);
+    color: var(--danger-foreground);
+  }
+
+  .cp-badge-neutral {
+    background: var(--neutral);
+    color: var(--neutral-foreground);
+  }
+
+  /* Legacy aliases */
+  .cp-badge-error {
+    background: var(--danger);
+    color: var(--danger-foreground);
+  }
+
+  /* Soft badge variants (light bg, dark text) */
   .cp-badge-soft-success {
     background: var(--success-soft);
     color: var(--success);
   }
 
+  .cp-badge-soft-info {
+    background: var(--info-soft);
+    color: var(--info);
+  }
+
   .cp-badge-soft-warning {
     background: var(--warning-soft);
     color: var(--warning);
   }
 
-  .cp-badge-soft-error {
-    background: var(--destructive-soft);
-    color: var(--destructive);
+  .cp-badge-soft-danger {
+    background: var(--danger-soft);
+    color: var(--danger);
   }
 
-  .cp-badge-soft-info {
-    background: var(--info-soft);
-    color: var(--info);
+  .cp-badge-soft-neutral {
+    background: var(--neutral-soft);
+    color: var(--neutral);
+  }
+
+  /* Legacy aliases */
+  .cp-badge-soft-error {
+    background: var(--danger-soft);
+    color: var(--danger);
   }
 
   .cp-badge-outline {