chati-dev 4.3.0 → 4.4.0

package/framework/scaffold/saas-dashboard/app/globals.css.template

@@ -0,0 +1,746 @@
+/*
+ * app/globals.css -- saas-dashboard preset v1.0.0
+ *
+ * WHY THIS FILE EXISTS
+ * --------------------
+ * Every CSS custom property that any component in this preset may reference
+ * is declared exactly once here. Components never use raw hex values, raw
+ * pixel numbers, or bare ease keywords. The rule is: if you cannot find a
+ * CSS variable for the value you want, add it here first, THEN use it.
+ *
+ * ARCHITECTURE: THREE LAYERS
+ *
+ *   Layer 1 -- Raw scale (neutral-0 through neutral-1000, accent raw values):
+ *     Calibrated hex values. Nothing references these directly except
+ *     Layer 2 semantic tokens. Changing a raw value here propagates
+ *     everywhere that semantic token is consumed.
+ *
+ *   Layer 2 -- Semantic tokens (bg-base, text-primary, border-default, etc.):
+ *     Named by intent, not by value. Components consume only these.
+ *     A theme switch (dark <-> light) overrides only Layer 2, in the
+ *     [data-theme='light'] block below, without touching any component file.
+ *
+ *   Layer 3 -- Component-level tokens (btn-height, input-pad, etc.):
+ *     Derived from Layer 2. Centralise component defaults so a single
+ *     change in :root propagates to all instances without touching TSX.
+ *
+ * MOTION SYSTEM
+ * -------------
+ * Every transition in the codebase must:
+ *   1. Name EXACTLY the property being transitioned (never transition:all).
+ *   2. Use a duration token from --duration-*.
+ *   3. Use an easing token from --ease-*.
+ *   4. Match the spatial metaphor: ease-out entering, ease-in leaving,
+ *      ease-in-out toggling, ease-spring for delightful micro-interactions.
+ *
+ * The @media (prefers-reduced-motion: reduce) block at the bottom of this
+ * file collapses all durations to 0ms or 80ms and removes transform
+ * animations. This is the ONLY place reduced-motion is handled; components
+ * read it via the useReducedMotion() hook from framer-motion.
+ *
+ * TAILWIND v4 INTEGRATION
+ * -----------------------
+ * The @theme block registers tokens as Tailwind utility classes. This means
+ * bg-bg-base, text-text-primary, border-border-default etc. work without
+ * arbitrary value syntax. The xl breakpoint is overridden to 75rem (1200px)
+ * to eliminate the 1200-1279px dead zone on MacBook Air viewports where
+ * lg: applied but xl: did not, producing layout gaps on laptops.
+ */
+
+@import "tailwindcss";
+
+/* Exclude non-source directories from Tailwind v4 scanning. Non-existent paths
+   are a no-op in Tailwind v4, so this is safe in both a full chati.dev project
+   (where these dirs exist) and a plain Next.js app (where they do not). */
+@source not "../artifacts";
+@source not "../.chati";
+@source not "../.chati.dev";
+@source not "../docs";
+
+/* ================================================================
+   FONT IMPORTS
+   Inter Variable and JetBrains Mono Variable from Google Fonts.
+   next/font handles this in layout.tsx; these @import declarations
+   are the CSS fallback for storybook / non-Next contexts.
+   ================================================================ */
+
+/* In Next.js the fonts are loaded via next/font in layout.tsx.
+   This comment is intentionally left as a reminder; do not add
+   @import url() here as it conflicts with next/font's optimization. */
+
+/* ================================================================
+   ROOT: DESIGN TOKEN DECLARATIONS
+   All custom properties for both dark (default) and light themes.
+   ================================================================ */
+
+:root {
+  color-scheme: dark;
+
+  /* ---------------------------------------------------------------
+     LAYER 1: NEUTRAL SCALE
+     Philosophy: A single hue (220deg, blue-shifted) at 12% saturation
+     produces a neutral that reads as "cool grey" without drifting
+     toward purple or green. The 14 steps provide even perceptual
+     luminance increments -- verified against APCA contrast model.
+     ---------------------------------------------------------------  */
+  --color-neutral-0:    #ffffff;   /* pure white */
+  --color-neutral-50:   #f7f8fa;   /* off-white surface */
+  --color-neutral-100:  #eef0f4;   /* subtle divider bg */
+  --color-neutral-200:  #dde1e9;   /* border default (light mode) */
+  --color-neutral-300:  #c4cad6;   /* border emphasis (light mode) */
+  --color-neutral-400:  #9aa3b4;   /* placeholder text */
+  --color-neutral-500:  #6b7689;   /* muted text */
+  --color-neutral-600:  #4e5769;   /* secondary text */
+  --color-neutral-700:  #343d4f;   /* primary text (light mode), strong border (dark) */
+  --color-neutral-800:  #1f2635;   /* card surface (dark mode) */
+  --color-neutral-850:  #171d2b;   /* sidebar/modal background */
+  --color-neutral-900:  #0f1420;   /* page background (dark mode) */
+  --color-neutral-950:  #080c14;   /* deepest dark surface */
+  --color-neutral-1000: #000000;   /* pure black */
+
+  /* ---------------------------------------------------------------
+     LAYER 1: ACCENT SCALE
+     Violet (258deg) is used in exactly two semantic roles:
+       Role 1 -- interactive affordance: buttons, links, active states.
+       Role 2 -- brand emphasis: tinted backgrounds, selected rows.
+     Using it in more than two roles kills hierarchy and makes the
+     UI feel "purple-washed". If you need a third role, create a
+     new semantic token with a different hue.
+     ---------------------------------------------------------------  */
+  --color-accent:        {{ACCENT_HEX}};   /* role 1: interactive affordance */
+  --color-accent-hover:  {{ACCENT_HOVER_HEX}};   /* role 1 hover state (+15% lightness) */
+  --color-accent-active: #6644e8;   /* role 1 pressed state (-10% lightness) */
+  --color-accent-subtle: #1e1640;   /* role 2: tinted background (dark) */
+  --color-accent-muted:  #4a3490;   /* role 2: tinted border (dark) */
+
+  /* ---------------------------------------------------------------
+     LAYER 2: SEMANTIC SURFACE TOKENS
+     Components reference these, never raw neutrals.
+     The hierarchy communicates depth: base -> raised -> overlay.
+     Sunken is lower than base (input wells, code blocks).
+     ---------------------------------------------------------------  */
+  --color-bg-base:       var(--color-neutral-900);   /* page background */
+  --color-bg-raised:     var(--color-neutral-800);   /* card surfaces */
+  --color-bg-raised-hover:  var(--color-neutral-700); /* raised-surface hover (e.g. secondary button) */
+  --color-bg-raised-active: var(--color-neutral-800); /* raised-surface pressed */
+  --color-bg-overlay:    var(--color-neutral-850);   /* sidebar, modal backdrop */
+  --color-bg-sunken:     var(--color-neutral-950);   /* input wells, code bg */
+  --color-bg-highlight:  var(--color-accent-subtle); /* selected rows, active nav */
+
+  /* ---------------------------------------------------------------
+     LAYER 2: SEMANTIC TEXT TOKENS
+     Contrast ratios verified at their intended sizes (WCAG 2.1 AA):
+       text-primary on bg-base:     19.4:1 (passes AAA)
+       text-secondary on bg-base:   5.8:1  (passes AA at body size)
+       text-muted on bg-base:       3.9:1  (passes AA at 18px+)
+     ---------------------------------------------------------------  */
+  --color-text-primary:   var(--color-neutral-50);    /* headings, labels, strong copy */
+  --color-text-secondary: var(--color-neutral-400);   /* supporting copy, metadata */
+  --color-text-muted:     var(--color-neutral-500);   /* captions, placeholders, disabled */
+  --color-text-inverse:   var(--color-neutral-950);   /* text on light/accent backgrounds */
+  --color-text-accent:    var(--color-accent-hover);  /* links, active sidebar items */
+
+  /* ---------------------------------------------------------------
+     LAYER 2: SEMANTIC BORDER TOKENS
+     ---------------------------------------------------------------  */
+  --color-border-default:  var(--color-neutral-700);  /* cards, dividers, table rows */
+  --color-border-emphasis: var(--color-neutral-600);  /* focused inputs, hover borders */
+  --color-border-accent:   var(--color-accent-muted); /* accent focus ring, active cards */
+
+  /* ---------------------------------------------------------------
+     LAYER 2: STATUS TOKENS
+     These are the only raw hex values in Layer 2 because status
+     colors are hue-distinct by nature and do not belong to the
+     neutral or accent ramps.
+     ---------------------------------------------------------------  */
+  --color-success:          #22c55e;  /* text, icon on success-subtle */
+  --color-success-subtle:   #052e16;  /* background tint */
+  --color-warning:          #f59e0b;  /* text, icon on warning-subtle */
+  --color-warning-subtle:   #27200a;  /* background tint */
+  --color-danger:           #ef4444;  /* text, icon on danger-subtle */
+  --color-danger-subtle:    #2a0a0a;  /* background tint */
+  --color-danger-hover-bg:  rgba(239, 68, 68, 0.20);  /* destructive hover surface */
+  --color-danger-active-bg: rgba(239, 68, 68, 0.30);  /* destructive active surface */
+  --color-overlay-scrim:    rgba(8, 12, 20, 0.72);    /* modal and palette backdrop */
+  --color-info:             #38bdf8;  /* text, icon on info-subtle */
+  --color-info-subtle:      #082030;  /* background tint */
+
+  /* ---------------------------------------------------------------
+     DATA VISUALISATION SERIES
+     Six perceptually-spaced hues that remain distinguishable:
+       - At 4px line weight on dark background
+       - To the most common color-vision deficiencies (deuteranopia,
+         protanopia, tritanopia)
+     The series starts with accent (violet) to tie viz to brand,
+     then fans out through sky, emerald, amber, pink, orange --
+     no two adjacent hues share the same luminance band.
+     ---------------------------------------------------------------  */
+  --color-viz-1: #7c5af8;   /* violet   -- accent, brand-tied */
+  --color-viz-2: #38bdf8;   /* sky      -- info-adjacent */
+  --color-viz-3: #22c55e;   /* emerald  -- success-adjacent */
+  --color-viz-4: #f59e0b;   /* amber    -- warning-adjacent */
+  --color-viz-5: #f472b6;   /* pink     -- no semantic overlap */
+  --color-viz-6: #fb923c;   /* orange   -- no semantic overlap */
+
+  /* ---------------------------------------------------------------
+     FOCUS RING
+     WCAG 2.1 SC 2.4.11 (Level AA, WCAG 2.2): focus indicator must
+     be at least 2px wide and have a contrast ratio >= 3:1 against
+     adjacent colors. Our 2px outline at 2px offset on bg-base gives
+     approximately 8:1 contrast for the accent color.
+     Applied globally via :focus-visible in the @layer base block.
+     ---------------------------------------------------------------  */
+  --color-focus-ring: var(--color-accent);
+
+  /* ================================================================
+     TYPE SCALE
+     Ratio: 1.250 (Major Third) applied to a 16px base.
+     Fluid clamp() interpolates linearly from 320px to 1440px viewport.
+     Formula: clamp(min, min + (max - min) * (100vw - 320px) / 1120, max)
+     Simplified: clamp(min_rem, slope_vw + intercept_rem, max_rem)
+
+     Tracking decisions:
+       Display/h1: -0.03em (optical tightening at large sizes prevents
+         letterforms from appearing to float apart)
+       h2/h3: -0.02em to -0.01em (gradual relaxation toward body size)
+       body/small: 0em (neutral -- reading comfort over optical correction)
+       caption: +0.01em (slight opening improves legibility at 12px)
+       mono: 0em (monospace already has designed optical spacing)
+
+     Line-height decisions:
+       display/h1 (1.1): content is usually 1-2 lines, no long reads;
+         tight LH maximises visual impact of large type.
+       h2/h3 (1.25-1.30): medium titles may wrap; needs breathing room.
+       body (1.5): WCAG 1.4.8 recommends >= 1.5 for body text.
+       caption (1.4): compact but not cramped; used only for short labels.
+       mono (1.6): extra breathing for code lines improves scan speed.
+     ================================================================ */
+
+  --type-display:    clamp(2rem, 4vw + 1rem, 3rem);
+  --type-display-lh: 1.1;
+  --type-display-ls: -0.03em;
+
+  --type-h1:    clamp(1.5rem, 2.5vw + 0.75rem, 2.25rem);
+  --type-h1-lh: 1.15;
+  --type-h1-ls: -0.025em;
+
+  --type-h2:    clamp(1.25rem, 1.8vw + 0.6rem, 1.75rem);
+  --type-h2-lh: 1.25;
+  --type-h2-ls: -0.02em;
+
+  --type-h3:    clamp(1.125rem, 1.2vw + 0.5rem, 1.375rem);
+  --type-h3-lh: 1.3;
+  --type-h3-ls: -0.01em;
+
+  --type-h4:    clamp(1rem, 0.5vw + 0.875rem, 1.125rem);
+  --type-h4-lh: 1.35;
+  --type-h4-ls: -0.005em;
+
+  /* Body is not fluid -- a stable 16px baseline prevents micro-jitter
+     in dense layouts when the viewport resizes by a few pixels. */
+  --type-body:    1rem;
+  --type-body-lh: 1.5;
+  --type-body-ls: 0em;
+
+  --type-small:    0.875rem;
+  --type-small-lh: 1.45;
+  --type-small-ls: 0em;
+
+  --type-caption:    0.75rem;
+  --type-caption-lh: 1.4;
+  --type-caption-ls: 0.01em;
+
+  --type-mono:    0.8125rem; /* 13px -- slightly smaller than body for visual weight parity */
+  --type-mono-lh: 1.6;
+  --type-mono-ls: 0em;
+
+  --font-sans: 'Inter Variable', system-ui, -apple-system, sans-serif;
+  --font-mono: 'JetBrains Mono Variable', ui-monospace, 'Cascadia Code', monospace;
+
+  --font-weight-regular:  400;
+  --font-weight-medium:   500;
+  --font-weight-semibold: 600;
+  --font-weight-bold:     700;
+
+  /* ================================================================
+     SPACING SCALE
+     Base unit: 4px (--space-1).
+     Why 4px and not 8px: dashboard UIs are data-dense. The 4px base
+     gives fine-grained control for compact table cells, badge padding,
+     and inline micro-gaps without resorting to arbitrary values.
+     Named steps ascend as multiples of 4px up to 256px.
+     Semantic aliases are what components USE; numeric steps are what
+     the design spec references.
+     ================================================================ */
+
+  --space-px:  1px;
+  --space-0:   0px;
+  --space-1:   4px;    /* micro: icon-to-text gap, badge inset */
+  --space-2:   8px;    /* tight: chip padding, table cell vertical */
+  --space-3:   12px;   /* compact: input vertical padding, small gap */
+  --space-4:   16px;   /* base: button horizontal padding, list spacing */
+  --space-5:   20px;   /* medium: label-to-input gap */
+  --space-6:   24px;   /* card internal padding, section inner spacing */
+  --space-7:   28px;   /* modal header height, sidebar section gap */
+  --space-8:   32px;   /* section vertical gap */
+  --space-9:   36px;
+  --space-10:  40px;   /* sidebar item height, large button height */
+  --space-11:  44px;   /* table row height -- WCAG 2.5.5 touch target */
+  --space-12:  48px;   /* topbar height */
+  --space-14:  56px;
+  --space-16:  64px;   /* sidebar width collapsed */
+  --space-20:  80px;
+  --space-24:  96px;
+  --space-32:  128px;  /* empty state illustration reserved area */
+  --space-40:  160px;
+  --space-48:  192px;
+  --space-56:  224px;
+  --space-64:  256px;
+
+  /* Semantic spacing aliases -- what components reference */
+  --spacing-page-edge:      clamp(1.5rem, 4vw, 2.5rem);  /* 24px to 40px */
+  --spacing-section:        var(--space-8);    /* 32px between page sections */
+  --spacing-card-pad:       var(--space-6);    /* 24px card internal padding */
+  --spacing-card-gap:       var(--space-5);    /* 20px gap between cards in grid */
+  --spacing-input-pad-v:    var(--space-3);    /* 12px input vertical padding */
+  --spacing-input-pad-h:    var(--space-4);    /* 16px input horizontal padding */
+  --spacing-topbar-h:       var(--space-12);   /* 48px topbar height */
+  --spacing-sidebar-w:      240px;             /* sidebar expanded width */
+  --spacing-sidebar-w-col:  var(--space-16);   /* sidebar collapsed width: 64px */
+
+  /* ================================================================
+     RADIUS SYSTEM
+     Three distinct radii communicate affordance tier:
+       sharp   (2px):  data-dense elements: table chips, code blocks.
+                       Signals precision and density.
+       default (8px):  cards, inputs, modals. Neutral -- does not
+                       draw attention to its own rounding.
+       large   (12px): prominent panels, toasts, sidepanels.
+                       Communicates soft/approachable without being playful.
+       pill:           badges, tags, toggles. Unmistakably interactive.
+       circle:         avatars, icon buttons, spinners.
+     ================================================================ */
+
+  --radius-sharp:   2px;
+  --radius-sm:      4px;
+  --radius-default: 8px;
+  --radius-lg:      12px;
+  --radius-xl:      16px;
+  --radius-pill:    9999px;
+  --radius-circle:  50%;
+
+  /* ================================================================
+     ELEVATION SYSTEM (3 levels)
+     Philosophy: On dark backgrounds, standard box-shadow produces
+     muddy grey blobs that reduce depth instead of conveying it.
+     Instead we use:
+       - Inset top border: simulates a "light source from above" highlight
+         that reads as a raised surface.
+       - Subtle ambient shadow: very low opacity dark shadow for the
+         physical impression of lift.
+       - No colored glows on structural shadows (only focus states use
+         a colored outline).
+     Level 1: card/panel lift (structural)
+     Level 2: floating layer (dropdown, popover, tooltip)
+     Level 3: modal layer (dialog, command palette)
+     ================================================================ */
+
+  --shadow-1:
+    inset 0 1px 0 rgba(255,255,255,0.06),
+    0 1px 3px rgba(0,0,0,0.30),
+    0 2px 8px rgba(0,0,0,0.20);
+
+  --shadow-2:
+    inset 0 1px 0 rgba(255,255,255,0.08),
+    0 4px 12px rgba(0,0,0,0.40),
+    0 8px 24px rgba(0,0,0,0.25),
+    0 0 0 1px rgba(255,255,255,0.04);
+
+  --shadow-3:
+    0 8px 32px rgba(0,0,0,0.55),
+    0 24px 64px rgba(0,0,0,0.40),
+    0 0 0 1px rgba(255,255,255,0.06),
+    0 0 60px rgba(124,90,248,0.08);
+
+  /* Focus ring shadow -- supplements outline on complex elements */
+  --shadow-focus:
+    0 0 0 2px var(--color-bg-base),
+    0 0 0 4px var(--color-focus-ring);
+
+  /* ================================================================
+     MOTION SYSTEM
+     Design principle: motion communicates spatial metaphor.
+
+     Entering (ease-out): element travels from its source toward its
+       resting position, shedding velocity on arrival. The observer
+       sees it "land" naturally.
+
+     Leaving (ease-in): element builds momentum toward its destination.
+       The exit feels intentional, not accidental.
+
+     Toggling (ease-in-out): symmetric: equal energy on departure
+       and arrival. Appropriate for accordions, sliders, state flips
+       where no direction is conceptually "upward".
+
+     Spring (ease-spring): slight overshoot produces the delightful
+       "bounce" sensation reserved for micro-interactions where extra
+       delight is warranted (badge appear, success icon pop).
+
+     Subtle: minimal energy, for low-profile state fades (muted hover
+       on secondary elements).
+
+     Duration philosophy:
+       micro (80-150ms): state changes the eye tracks peripherally.
+         Used for: focus ring, status dot, badge colour.
+       component (200-350ms): elements in the focal region.
+         Used for: button hover, dropdown open, input focus.
+       layout (400-500ms): page-level spatial changes.
+         Used for: sidebar collapse, panel slide, route transition.
+
+     Stagger: 40ms between list items. Below 30ms the items appear
+     simultaneous; above 60ms the animation feels mechanical.
+     ================================================================ */
+
+  --ease-out:    cubic-bezier(0.16, 1, 0.3, 1);     /* spring-like enter */
+  --ease-in:     cubic-bezier(0.4, 0, 1, 1);         /* momentum exit */
+  --ease-in-out: cubic-bezier(0.4, 0, 0.2, 1);       /* symmetric toggle */
+  --ease-spring: cubic-bezier(0.34, 1.56, 0.64, 1);  /* overshoot delight */
+  --ease-subtle: cubic-bezier(0.25, 0, 0, 1);         /* low-profile fade */
+
+  --duration-instant:  80ms;   /* state dot, focus ring, icon swap */
+  --duration-fast:     120ms;  /* badge appear, status change */
+  --duration-normal:   200ms;  /* button hover, input focus border */
+  --duration-medium:   300ms;  /* dropdown open, tooltip appear */
+  --duration-slow:     400ms;  /* sidebar collapse, panel open */
+  --duration-layout:   500ms;  /* page-level spatial transitions */
+
+  --stagger-base: 40ms;  /* per-item stagger delay in list animations */
+
+  /* ================================================================
+     Z-INDEX SCALE
+     A named scale prevents the "z-index arms race" where components
+     competing for stacking order escalate to z-index:9999.
+     Each level owns a clearly-described stacking context.
+     ================================================================ */
+
+  --z-sidebar:  30;
+  --z-topbar:   40;
+  --z-dropdown: 50;
+  --z-tooltip:  60;
+  --z-modal:    70;
+  --z-toast:    80;
+  --z-command:  90;
+
+  /* ================================================================
+     COMPONENT-LEVEL TOKENS (LAYER 3)
+     Derived from semantic tokens. Allow centralised component
+     defaults: change one token here, all instances update.
+     ================================================================ */
+
+  /* Button */
+  --btn-h-sm:    32px;
+  --btn-h-md:    40px;
+  --btn-h-lg:    48px;
+  --btn-px-sm:   var(--space-3);
+  --btn-px-md:   var(--space-4);
+  --btn-px-lg:   var(--space-6);
+  --btn-radius:  var(--radius-default);
+
+  /* Input */
+  --input-h:       40px;
+  --input-radius:  var(--radius-default);
+  --input-pl:      var(--spacing-input-pad-h);  /* overridden when iconLeft present */
+
+  /* Table */
+  --table-row-h:   var(--space-11);  /* 44px -- WCAG touch target minimum */
+  --table-header-h: 40px;
+}
+
+/* ================================================================
+   LIGHT THEME OVERRIDES
+   Applied when <html data-theme="light"> is set.
+   ONLY Layer 2 semantic tokens are overridden here.
+   Raw scales (Layer 1) and component tokens (Layer 3) are
+   intentionally NOT overridden -- they derive their values from
+   the semantic tokens, so they update automatically.
+   ================================================================ */
+
+[data-theme='light'] {
+  color-scheme: light;
+
+  --color-bg-base:       var(--color-neutral-50);
+  --color-bg-raised:     var(--color-neutral-0);
+  --color-bg-raised-hover:  var(--color-neutral-100);
+  --color-bg-raised-active: var(--color-neutral-200);
+  --color-bg-overlay:    var(--color-neutral-100);
+  --color-bg-sunken:     var(--color-neutral-100);
+  --color-bg-highlight:  #ede9ff;
+
+  --color-text-primary:   var(--color-neutral-900);
+  --color-text-secondary: var(--color-neutral-600);
+  --color-text-muted:     var(--color-neutral-500);
+  --color-text-accent:    var(--color-accent);
+
+  --color-border-default:  var(--color-neutral-200);
+  --color-border-emphasis: var(--color-neutral-300);
+
+  --color-accent-subtle: #ede9ff;
+  --color-accent-muted:  #a78bfa;
+
+  --color-success-subtle: #f0fdf4;
+  --color-warning-subtle: #fffbeb;
+  --color-danger-subtle:  #fef2f2;
+  --color-overlay-scrim:  rgba(15, 20, 30, 0.45);
+  --color-info-subtle:    #f0f9ff;
+
+  /* Light mode shadows: softer, less opaque -- dark shadows on
+     light backgrounds need lower opacity to avoid over-saturation. */
+  --shadow-1:
+    inset 0 1px 0 rgba(255,255,255,0.80),
+    0 1px 3px rgba(0,0,0,0.08),
+    0 2px 8px rgba(0,0,0,0.06);
+
+  --shadow-2:
+    0 4px 12px rgba(0,0,0,0.10),
+    0 8px 24px rgba(0,0,0,0.07),
+    0 0 0 1px rgba(0,0,0,0.05);
+
+  --shadow-3:
+    0 8px 32px rgba(0,0,0,0.15),
+    0 24px 64px rgba(0,0,0,0.10),
+    0 0 0 1px rgba(0,0,0,0.06);
+}
+
+/* ================================================================
+   TAILWIND v4 @theme BLOCK
+   Registers all tokens as Tailwind utility classes so components
+   can use class-based notation (bg-bg-base, text-text-primary)
+   without arbitrary value syntax.
+
+   The xl breakpoint override (75rem instead of default 80rem /
+   1280px) eliminates the "MacBook Air dead zone": laptop viewports
+   between 1200-1279px were stuck at lg: utilities despite having
+   enough horizontal space for the xl: layout tier.
+   ================================================================ */
+
+@theme {
+  /* Breakpoint override */
+  --breakpoint-xl: 75rem;  /* 1200px instead of Tailwind default 1280px */
+
+  /* Font families */
+  --font-sans: var(--font-sans);
+  --font-mono: var(--font-mono);
+
+  /* Accent colors for Tailwind utilities */
+  --color-accent:        {{ACCENT_HEX}};
+  --color-accent-hover:  {{ACCENT_HOVER_HEX}};
+  --color-accent-subtle: #1e1640;
+  --color-accent-muted:  #4a3490;
+
+  /* Neutral scale */
+  --color-neutral-0:    #ffffff;
+  --color-neutral-50:   #f7f8fa;
+  --color-neutral-100:  #eef0f4;
+  --color-neutral-200:  #dde1e9;
+  --color-neutral-300:  #c4cad6;
+  --color-neutral-400:  #9aa3b4;
+  --color-neutral-500:  #6b7689;
+  --color-neutral-600:  #4e5769;
+  --color-neutral-700:  #343d4f;
+  --color-neutral-800:  #1f2635;
+  --color-neutral-850:  #171d2b;
+  --color-neutral-900:  #0f1420;
+  --color-neutral-950:  #080c14;
+
+  /* Status colors */
+  --color-success: #22c55e;
+  --color-warning: #f59e0b;
+  --color-danger:  #ef4444;
+  --color-info:    #38bdf8;
+
+  /* Viz series */
+  --color-viz-1: #7c5af8;
+  --color-viz-2: #38bdf8;
+  --color-viz-3: #22c55e;
+  --color-viz-4: #f59e0b;
+  --color-viz-5: #f472b6;
+  --color-viz-6: #fb923c;
+}
+
+/* ================================================================
+   BASE STYLES
+   Semantic HTML defaults. Applied inside @layer base so Tailwind
+   utilities in components can override via normal cascade order.
+   ================================================================ */
+
+@layer base {
+  *,
+  *::before,
+  *::after {
+    box-sizing: border-box;
+  }
+
+  html {
+    /* scroll-behavior:smooth is NOT set here; it breaks browser
+       native scroll-jump (anchor links) in Firefox and conflicts
+       with framer-motion AnimatePresence page transitions.
+       Individual smooth-scroll sections set it on their container. */
+    scroll-behavior: auto;
+    /* Prevent horizontal overflow from miscalculated widths */
+    overflow-x: hidden;
+  }
+
+  body {
+    background-color: var(--color-bg-base);
+    color: var(--color-text-primary);
+    font-family: var(--font-sans);
+    font-size: var(--type-body);
+    line-height: var(--type-body-lh);
+    letter-spacing: var(--type-body-ls);
+    -webkit-font-smoothing: antialiased;
+    -moz-osx-font-smoothing: grayscale;
+    font-feature-settings: 'calt' 1, 'cv02' 1, 'cv03' 1, 'cv04' 1;
+    /* Transitioning background-color here enables smooth theme toggle.
+       Only background-color -- not color or other properties. */
+    transition:
+      background-color var(--duration-medium) var(--ease-in-out),
+      color var(--duration-medium) var(--ease-in-out);
+  }
+
+  /* Heading hierarchy with role-differentiated type scale */
+  h1 {
+    font-family: var(--font-sans);
+    font-size: var(--type-h1);
+    font-weight: var(--font-weight-bold);
+    line-height: var(--type-h1-lh);
+    letter-spacing: var(--type-h1-ls);
+    color: var(--color-text-primary);
+  }
+
+  h2 {
+    font-family: var(--font-sans);
+    font-size: var(--type-h2);
+    font-weight: var(--font-weight-bold);
+    line-height: var(--type-h2-lh);
+    letter-spacing: var(--type-h2-ls);
+    color: var(--color-text-primary);
+  }
+
+  h3 {
+    font-family: var(--font-sans);
+    font-size: var(--type-h3);
+    font-weight: var(--font-weight-semibold);
+    line-height: var(--type-h3-lh);
+    letter-spacing: var(--type-h3-ls);
+    color: var(--color-text-primary);
+  }
+
+  h4 {
+    font-family: var(--font-sans);
+    font-size: var(--type-h4);
+    font-weight: var(--font-weight-semibold);
+    line-height: var(--type-h4-lh);
+    letter-spacing: var(--type-h4-ls);
+    color: var(--color-text-primary);
+  }
+
+  /* Focus ring: global :focus-visible rule.
+     Components with complex inner structure (button with icon children)
+     add --shadow-focus via box-shadow in addition to this outline.
+     NEVER suppress focus-visible for accessibility. */
+  :focus-visible {
+    outline: 2px solid var(--color-focus-ring);
+    outline-offset: 2px;
+    border-radius: var(--radius-sm);
+  }
+
+  /* Scroll margin for anchor-linked headings: accounts for sticky topbar */
+  [id] {
+    scroll-margin-top: calc(var(--spacing-topbar-h) + var(--space-4));
+  }
+
+  /* Code elements use mono font and sunken background */
+  code, pre, kbd, samp {
+    font-family: var(--font-mono);
+    font-size: var(--type-mono);
+    line-height: var(--type-mono-lh);
+    letter-spacing: var(--type-mono-ls);
+  }
+
+  /* Reduce motion for SVG animations: browsers do not always honour
+     the @media block for inline SVG animations */
+  @media (prefers-reduced-motion: reduce) {
+    svg * {
+      animation-duration: 0.01ms !important;
+      transition-duration: 0.01ms !important;
+    }
+  }
+}
+
+/* ================================================================
+   SKELETON SHIMMER ANIMATION
+   Used by SkeletonBlock component. Defined globally because @keyframes
+   inside a component CSS module would duplicate across instances.
+   The animation uses transform:translateX only (no layout-affecting
+   properties) to stay on the GPU compositor thread.
+   ================================================================ */
+
+@keyframes skeleton-shimmer {
+  0%   { transform: translateX(-100%); }
+  100% { transform: translateX(100%); }
+}
+
+/* Stat card loading pulse: opacity-only fade (no geometry change) */
+@keyframes pulse-opacity {
+  0%, 100% { opacity: 1; }
+  50%       { opacity: 0.4; }
+}
+
+/* Toast/badge entrance from below */
+@keyframes slide-up {
+  from { transform: translateY(8px); opacity: 0; }
+  to   { transform: translateY(0);   opacity: 1; }
+}
+
+/* ================================================================
+   REDUCED MOTION OVERRIDE
+   This block is the single source of truth for reduced-motion
+   behaviour. It intentionally uses !important to override any
+   inline or component-level transition declaration.
+
+   Opacity fades are preserved at 80ms (--duration-instant) because
+   users with vestibular disorders can still perceive colour/opacity
+   changes without experiencing motion sickness from transforms.
+
+   Transform-based animations are removed entirely (set to none).
+   Framer-motion variants should check useReducedMotion() and skip
+   x/y/scale variants, keeping only opacity.
+   ================================================================ */
+
+@media (prefers-reduced-motion: reduce) {
+  *,
+  *::before,
+  *::after {
+    animation-duration: 0.01ms !important;
+    animation-iteration-count: 1 !important;
+    transition-duration: 0.01ms !important;
+    scroll-behavior: auto !important;
+  }
+
+  /* Restore opacity transitions for non-motion feedback */
+  [data-motion-safe] {
+    transition-duration: 80ms !important;
+    animation-duration: 80ms !important;
+  }
+
+  /* Skeleton shimmer: show static muted colour instead of animating */
+  .skeleton-shimmer::after {
+    animation: none !important;
+  }
+}
+
+/* DataTable row hover (the table sets per-cell styles inline; the row hover is
+   a global rule so non-selected rows get a token-driven hover surface). */
+.data-table-row { transition: background-color var(--duration-fast, 150ms) var(--ease-out, ease-out); }
+.data-table-row:hover { background-color: var(--color-bg-overlay); }
+@media (prefers-reduced-motion: reduce) { .data-table-row { transition: none; } }