agentsys 5.1.0 → 5.2.1

package/scripts/validate-counts.js

@@ -125,6 +125,9 @@ function checkVersionAlignment() {
 
   // Check each plugin's plugin.json
   const pluginsDir = path.join(REPO_ROOT, 'plugins');
+  if (!fs.existsSync(pluginsDir)) {
+    return { mainVersion, issues };
+  }
   const plugins = fs.readdirSync(pluginsDir).filter(f => {
     const stat = fs.statSync(path.join(pluginsDir, f));
     return stat.isDirectory();
@@ -237,6 +240,20 @@ function formatCountMismatch(file, metric, expected, actual) {
  * @returns {Object} Validation result with status, issues, fixes
  */
 function runValidation() {
+  // When plugins/ doesn't exist, counts are not meaningful — return ok
+  if (!fs.existsSync(path.join(REPO_ROOT, 'plugins'))) {
+    return {
+      status: 'ok',
+      message: 'plugins/ not present (extracted to standalone repos)',
+      actualCounts: { plugins: 0, fileBasedAgents: 0, roleBasedAgents: 0, totalAgents: 0, skills: 0 },
+      docCounts: {},
+      versionCheck: { mainVersion: null, aligned: true },
+      memoryAlignment: { aligned: true, similarity: '100.0%' },
+      issues: [],
+      fixes: [],
+      summary: { issueCount: 0, fixableCount: 0, bySeverity: { high: 0, medium: 0, low: 0 } }
+    };
+  }
   const actualCounts = getActualCounts();
   const docCounts = extractCountsFromDocs();
   const versionCheck = checkVersionAlignment();
@@ -365,6 +382,16 @@ if (require.main === module) {
   const args = process.argv.slice(2);
   const jsonMode = args.includes('--json');
 
+  // When plugins/ doesn't exist, counts are not meaningful — skip validation
+  if (!require('fs').existsSync(require('path').join(REPO_ROOT, 'plugins'))) {
+    if (jsonMode) {
+      console.log(JSON.stringify({ status: 'ok', message: 'plugins/ not present (extracted to standalone repos)', issues: [] }, null, 2));
+    } else {
+      console.log('[OK] plugins/ not present (extracted to standalone repos) — skipping count validation');
+    }
+    process.exit(0);
+  }
+
   const result = runValidation();
 
   if (jsonMode) {

package/site/assets/css/design-system/base.css

@@ -0,0 +1,151 @@
+/*
+ * ==========================================================================
+ * AGENT-SH DESIGN SYSTEM - BASE STYLES
+ * ==========================================================================
+ *
+ * Reset rules, element defaults, and utility classes built on the token
+ * system. Import AFTER tokens.css.
+ *
+ * NOTE: Do NOT import this file in Docusaurus sites - Infima provides its
+ * own reset and base styles. Use tokens.css + tokens-docusaurus.css instead.
+ *
+ * ==========================================================================
+ */
+
+/* --------------------------------------------------------------------------
+ * BASE RESET & DEFAULTS
+ *
+ * Minimal reset that sets up the token system on actual elements.
+ * This ensures tokens flow into the cascade properly.
+ * -------------------------------------------------------------------------- */
+*,
+*::before,
+*::after {
+  box-sizing: border-box;
+  margin: 0;
+  padding: 0;
+}
+
+html {
+  font-size: 16px;
+  -webkit-font-smoothing: antialiased;
+  -moz-osx-font-smoothing: grayscale;
+  text-rendering: optimizeLegibility;
+  scroll-behavior: smooth; /* Overridden by reduced-motion below */
+}
+
+body {
+  font-family: var(--font-sans);
+  font-size: var(--text-base);
+  font-weight: var(--font-normal);
+  line-height: var(--leading-normal);
+  color: var(--color-text-primary);
+  background-color: var(--color-bg-base);
+}
+
+/* Code elements use the mono stack */
+code,
+kbd,
+samp,
+pre {
+  font-family: var(--font-mono);
+  font-size: 0.9em; /* Slightly smaller than surrounding text to match x-height */
+}
+
+/* Links use the accent color */
+a {
+  color: var(--color-accent-purple);
+  text-decoration: none;
+  transition: color var(--duration-fast) var(--ease-out);
+}
+
+a:hover {
+  color: var(--color-accent-hover);
+}
+
+/* Selection uses accent tint */
+::selection {
+  background-color: rgba(var(--color-accent-purple-rgb), 0.3);
+  color: var(--color-text-primary);
+}
+
+/* Respect user motion preferences */
+@media (prefers-reduced-motion: reduce) {
+  html {
+    scroll-behavior: auto;
+  }
+}
+
+/* --------------------------------------------------------------------------
+ * UTILITY CLASSES
+ *
+ * Commonly needed utilities built on the token system.
+ * These provide quick access to the most-used patterns.
+ * -------------------------------------------------------------------------- */
+
+/* Accent gradient text - for headings and emphasis */
+.text-gradient {
+  background: var(--gradient-accent-text);
+  -webkit-background-clip: text;
+  background-clip: text;
+  -webkit-text-fill-color: transparent;
+}
+
+/* Glass panel - the signature component style */
+.glass {
+  background: var(--glass-bg);
+  backdrop-filter: blur(var(--glass-blur));
+  -webkit-backdrop-filter: blur(var(--glass-blur));
+  border: var(--glass-border);
+  border-radius: var(--radius-lg);
+}
+
+.glass-accent {
+  background: var(--glass-bg-accent);
+  backdrop-filter: blur(var(--glass-blur));
+  -webkit-backdrop-filter: blur(var(--glass-blur));
+  border: var(--glass-border-accent);
+  border-radius: var(--radius-lg);
+}
+
+/* Glow effect - for accent-highlighted elements */
+.glow {
+  box-shadow: var(--glow-accent);
+}
+
+.glow-strong {
+  box-shadow: var(--glow-accent-strong);
+}
+
+/* Accent border gradient (applied via pseudo-element) */
+.border-gradient {
+  position: relative;
+  border-radius: var(--radius-lg);
+}
+
+.border-gradient::before {
+  content: '';
+  position: absolute;
+  inset: 0;
+  padding: 1px;
+  border-radius: inherit;
+  background: var(--gradient-accent);
+  -webkit-mask: linear-gradient(#fff 0 0) content-box, linear-gradient(#fff 0 0);
+  mask: linear-gradient(#fff 0 0) content-box, linear-gradient(#fff 0 0);
+  -webkit-mask-composite: xor;
+  mask-composite: exclude;
+  pointer-events: none;
+}
+
+/* Visually hidden but accessible to screen readers */
+.sr-only {
+  position: absolute;
+  width: 1px;
+  height: 1px;
+  padding: 0;
+  margin: -1px;
+  overflow: hidden;
+  clip: rect(0, 0, 0, 0);
+  white-space: nowrap;
+  border-width: 0;
+}

package/site/assets/css/design-system/tokens.css

@@ -0,0 +1,354 @@
+/*
+ * ==========================================================================
+ * AGENT-SH DESIGN SYSTEM - TOKENS
+ * ==========================================================================
+ *
+ * Shared design tokens for all agent-sh ecosystem sites.
+ * This is the single source of truth for visual properties.
+ *
+ * Consumers:
+ *   - agentsys/site/assets/css/tokens.css (via @import)
+ *   - agent-sh.dev/src/styles/tokens.css (via @import)
+ *   - agnix/website/src/css/custom.css (via @import)
+ *
+ * ==========================================================================
+ */
+
+/* --------------------------------------------------------------------------
+ * FONTS
+ *
+ * Required: Inter + JetBrains Mono (Google Fonts or self-hosted).
+ * Each consumer site must load fonts via HTML <link> tags, NOT @import here.
+ * This avoids render-blocking CSS @import chains.
+ *
+ * Recommended <link> tags (add to each site's <head>):
+ *   <link rel="preconnect" href="https://fonts.googleapis.com">
+ *   <link rel="preconnect" href="https://fonts.gstatic.com" crossorigin>
+ *   <link rel="stylesheet" href="https://fonts.googleapis.com/css2?family=Inter:wght@400;500;600;700;800&family=JetBrains+Mono:wght@400;500;600;700&display=swap">
+ * -------------------------------------------------------------------------- */
+
+/* --------------------------------------------------------------------------
+ * ROOT TOKENS
+ *
+ * Every visual property in the system derives from these tokens.
+ * Components should ONLY reference custom properties, never raw values.
+ * This enables theming, responsive adjustments, and systematic changes.
+ * -------------------------------------------------------------------------- */
+:root {
+
+  /* ========================================================================
+   * COLORS - BACKGROUND SCALE
+   *
+   * Built on zinc-900 tones with a slight blue undertone (#09090b).
+   * NOT pure black - pure black feels dead on screens and creates harsh
+   * contrast with text. The slight warmth adds depth and professionalism.
+   *
+   * Scale: base -> surface-1 -> surface-2 -> surface-3 (increasing elevation)
+   * Each step is ~6-8% lighter, maintaining perceptible but subtle difference.
+   * ======================================================================== */
+  --color-bg-base:       #09090b;    /* Page background - the deepest layer                */
+  --color-bg-surface-1:  #111113;    /* Cards, panels - first elevation above base          */
+  --color-bg-surface-2:  #18181b;    /* Hover states, active panels - second elevation       */
+  --color-bg-surface-3:  #1f1f23;    /* Modals, dropdowns - highest elevation                */
+  --color-bg-code:       #0c0c0e;    /* Code blocks - slightly darker than base for inset    */
+  --color-bg-inset:      #06060a;    /* Deeply recessed areas (code editors, terminals)      */
+
+  /* ========================================================================
+   * COLORS - BORDER SCALE
+   *
+   * Borders are intentionally subtle. The design relies on elevation
+   * (background color steps) and glassmorphism (backdrop-filter) for
+   * separation rather than hard lines. Borders are a last resort.
+   * ======================================================================== */
+  --color-border-subtle:   #1e1e22;  /* Default border - barely visible, structural only    */
+  --color-border-default:  #27272a;  /* Standard border - used when separation is needed     */
+  --color-border-strong:   #3f3f46;  /* Emphasized border - focus rings, active states       */
+  --color-border-accent:   rgba(168, 85, 247, 0.25); /* Accent-tinted border for highlights */
+
+  /* ========================================================================
+   * COLORS - TEXT SCALE
+   *
+   * Four-level hierarchy provides clear visual ranking without bold abuse.
+   * Primary (#fafafa) has 15.4:1 contrast ratio against base - exceeds
+   * WCAG AAA. Even muted (#71717a) hits 4.6:1, meeting WCAG AA.
+   * ======================================================================== */
+  --color-text-primary:    #fafafa;  /* Headings, primary content - near-white, not pure     */
+  --color-text-secondary:  #a1a1aa;  /* Body text, descriptions - comfortable reading         */
+  --color-text-muted:      #71717a;  /* Labels, captions, metadata - deliberately quiet       */
+  --color-text-faint:      #52525b;  /* Disabled states, decorative text                      */
+  --color-text-inverse:    #09090b;  /* Text on light/accent backgrounds                      */
+
+  /* ========================================================================
+   * COLORS - ACCENT GRADIENT (SIGNATURE)
+   *
+   * The purple-to-cyan gradient is the ONE brand color. Everything else is
+   * monochrome. This constraint makes the accent unmistakable.
+   *
+   * Purple (#a855f7): creativity, intelligence, premium feel.
+   * Cyan (#06b6d4): technology, speed, freshness.
+   * Together: AI-powered precision meets developer tooling.
+   *
+   * Used for: CTAs, active states, links, progress indicators, hero elements.
+   * NEVER used for: backgrounds, large surfaces, body text.
+   * ======================================================================== */
+  --color-accent-purple:   #a855f7;  /* Gradient start - violet-500                          */
+  --color-accent-cyan:     #06b6d4;  /* Gradient end - cyan-500                              */
+  --color-accent-mid:      #7c3aed;  /* Midpoint for single-color needs - violet-600         */
+
+  /* RGB components for use in rgba() - enables opacity control with tokens */
+  --color-accent-purple-rgb: 168, 85, 247;
+  --color-accent-cyan-rgb:   6, 182, 212;
+  --color-zinc-rgb:          113, 113, 122;
+  --color-info-rgb:          59, 130, 246;
+
+  /* Pre-composed gradients for consistent use across components */
+  --gradient-accent:       linear-gradient(135deg, #a855f7, #06b6d4);
+  --gradient-accent-hover: linear-gradient(135deg, #c084fc, #22d3ee);
+  --gradient-accent-text:  linear-gradient(135deg, #c084fc, #22d3ee);
+  --gradient-accent-subtle: linear-gradient(135deg, rgba(168, 85, 247, 0.15), rgba(6, 182, 212, 0.15));
+
+  /* Accent as solid colors for simpler contexts */
+  --color-accent-primary:  #a855f7;  /* Primary accent when gradient not possible            */
+  --color-accent-hover:    #c084fc;  /* Lighter on hover - violet-400                        */
+  --color-accent-active:   #9333ea;  /* Darker on press - violet-600                         */
+  --color-accent-muted:    rgba(168, 85, 247, 0.12); /* Accent tint for backgrounds         */
+
+  /* ========================================================================
+   * COLORS - GLOW EFFECTS
+   *
+   * Glows replace traditional shadows in dark UIs. Instead of darkening
+   * beneath elements (invisible on dark bg), we emit colored light.
+   * Creates the "objects emitting light" metaphor that premium dark UIs use.
+   * ======================================================================== */
+  --glow-accent:           0 0 20px rgba(168, 85, 247, 0.15),
+                           0 0 60px rgba(168, 85, 247, 0.05);
+  --glow-accent-strong:    0 0 30px rgba(168, 85, 247, 0.25),
+                           0 0 80px rgba(168, 85, 247, 0.10),
+                           0 0 120px rgba(6, 182, 212, 0.05);
+  --glow-accent-hero:      0 0 40px rgba(168, 85, 247, 0.3),
+                           0 0 100px rgba(168, 85, 247, 0.15),
+                           0 0 200px rgba(6, 182, 212, 0.08);
+  --glow-card-hover:       0 0 0 1px rgba(168, 85, 247, 0.1),
+                           0 4px 20px rgba(168, 85, 247, 0.08),
+                           0 0 60px rgba(168, 85, 247, 0.04);
+  --glow-btn-hover:        0 0 0 1px rgba(168, 85, 247, 0.2),
+                           0 4px 16px rgba(168, 85, 247, 0.2),
+                           0 0 40px rgba(168, 85, 247, 0.08);
+  --glow-cyan:             0 0 20px rgba(6, 182, 212, 0.15),
+                           0 0 60px rgba(6, 182, 212, 0.05);
+
+  /* ========================================================================
+   * COLORS - SEMANTIC (STATUS)
+   *
+   * Standard traffic-light semantic colors, tuned for dark backgrounds.
+   * Slightly desaturated compared to pure hues to feel less alarming and
+   * more "at home" in the dark theme.
+   * ======================================================================== */
+  --color-success:         #22c55e;  /* Green-500 - completed, active, healthy               */
+  --color-success-muted:   rgba(34, 197, 94, 0.12);
+  --color-warning:         #eab308;  /* Yellow-500 - attention needed, in progress            */
+  --color-warning-muted:   rgba(234, 179, 8, 0.12);
+  --color-error:           #ef4444;  /* Red-500 - failed, broken, destructive                 */
+  --color-error-muted:     rgba(239, 68, 68, 0.12);
+  --color-info:            #3b82f6;  /* Blue-500 - informational, neutral highlight           */
+  --color-info-muted:      rgba(59, 130, 246, 0.12);
+
+  /* ========================================================================
+   * TYPOGRAPHY
+   *
+   * Type scale uses a 1.25 ratio (Major Third) - professional and readable
+   * without the dramatic jumps of larger ratios. Each step is clearly
+   * distinct but not jarring.
+   *
+   * Base: 16px (1rem) - browser default, accessible, comfortable.
+   * ======================================================================== */
+  --font-sans:             'Inter', -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif;
+  --font-mono:             'JetBrains Mono', 'Fira Code', 'Cascadia Code', 'Consolas', monospace;
+
+  /* Size scale - Major Third (1.25) */
+  --text-xs:               0.75rem;   /* 12px - fine print, badges                           */
+  --text-sm:               0.875rem;  /* 14px - secondary text, labels                       */
+  --text-base:             1rem;      /* 16px - body text, default                           */
+  --text-lg:               1.125rem;  /* 18px - lead paragraphs                              */
+  --text-xl:               1.25rem;   /* 20px - section headings                             */
+  --text-2xl:              1.563rem;  /* 25px - page subheadings                             */
+  --text-3xl:              1.953rem;  /* ~31px - page headings                               */
+  --text-4xl:              2.441rem;  /* ~39px - hero subheadings                            */
+  --text-5xl:              3.052rem;  /* ~49px - hero headlines                               */
+  --text-6xl:              3.815rem;  /* ~61px - display text, oversized hero                 */
+
+  /* Font weights - named for intent, not number */
+  --font-normal:           400;       /* Body text                                            */
+  --font-medium:           500;       /* Emphasis within body, nav items                      */
+  --font-semibold:         600;       /* Subheadings, buttons, labels                         */
+  --font-bold:             700;       /* Headings                                             */
+  --font-extrabold:        800;       /* Hero headlines, display text                         */
+
+  /* Line heights - tighter for headings, looser for body */
+  --leading-none:          1;         /* Display text, single-line headings                   */
+  --leading-tight:         1.25;      /* Headings, short text blocks                          */
+  --leading-snug:          1.375;     /* Subheadings, medium text                             */
+  --leading-normal:        1.5;       /* Body text - optimal for readability                  */
+  --leading-relaxed:       1.625;     /* Long-form content, documentation                     */
+  --leading-loose:         2;         /* Spacious text, pull quotes                           */
+
+  /* Letter spacing - tighter for large text, normal/wider for small */
+  --tracking-tighter:     -0.05em;    /* Display/hero text                                   */
+  --tracking-tight:       -0.025em;   /* Headings                                            */
+  --tracking-normal:       0;         /* Body text                                            */
+  --tracking-wide:         0.025em;   /* Labels, overlines, uppercase text                   */
+  --tracking-wider:        0.05em;    /* Small caps, badges                                  */
+  --tracking-widest:       0.1em;     /* All-caps headings                                   */
+
+  /* ========================================================================
+   * SPACING SCALE
+   *
+   * 4px base unit. Every spacing value is a multiple of 4px.
+   * This creates a consistent rhythm throughout the UI that feels
+   * intentional even when users cannot articulate why.
+   *
+   * Named 1-20 (multiply by 4 for px value).
+   * ======================================================================== */
+  --space-0:               0;
+  --space-px:              1px;       /* Hairline borders, 1px adjustments                    */
+  --space-0-5:             0.125rem;  /* 2px  - micro adjustments                             */
+  --space-1:               0.25rem;   /* 4px  - tight padding, icon gaps                      */
+  --space-1-5:             0.375rem;  /* 6px  - small component internal                      */
+  --space-2:               0.5rem;    /* 8px  - standard small gap                            */
+  --space-3:               0.75rem;   /* 12px - component padding                             */
+  --space-4:               1rem;      /* 16px - standard gap, base unit                       */
+  --space-5:               1.25rem;   /* 20px - medium gap                                    */
+  --space-6:               1.5rem;    /* 24px - section padding                               */
+  --space-8:               2rem;      /* 32px - large gap                                     */
+  --space-10:              2.5rem;    /* 40px - section margin                                */
+  --space-12:              3rem;      /* 48px - large section margin                          */
+  --space-16:              4rem;      /* 64px - page section spacing                          */
+  --space-20:              5rem;      /* 80px - hero spacing                                  */
+  --space-24:              6rem;      /* 96px - major section breaks                          */
+  --space-32:              8rem;      /* 128px - page-level vertical rhythm                   */
+
+  /* ========================================================================
+   * BORDER RADIUS
+   *
+   * Slightly rounded corners (not pill-shaped) signal modernity without
+   * feeling playful. Consistent radii across components create cohesion.
+   * ======================================================================== */
+  --radius-none:           0;
+  --radius-sm:             0.25rem;   /* 4px  - badges, small chips                          */
+  --radius-default:        0.375rem;  /* 6px  - buttons, inputs, cards (DEFAULT)              */
+  --radius-md:             0.5rem;    /* 8px  - larger cards, modals                          */
+  --radius-lg:             0.75rem;   /* 12px - panels, major containers                      */
+  --radius-xl:             1rem;      /* 16px - hero cards, feature blocks                    */
+  --radius-2xl:            1.5rem;    /* 24px - large decorative elements                     */
+  --radius-full:           9999px;    /* Pill shape - tags, avatars, toggles                  */
+
+  /* ========================================================================
+   * SHADOWS
+   *
+   * Layered shadows for realistic depth. Each level adds another layer.
+   * On dark backgrounds, traditional shadows are near-invisible, so these
+   * combine subtle downward shadows with slight ambient glow.
+   * ======================================================================== */
+  --shadow-sm:             0 1px 2px rgba(0, 0, 0, 0.3);
+  --shadow-default:        0 1px 3px rgba(0, 0, 0, 0.3),
+                           0 1px 2px rgba(0, 0, 0, 0.2);
+  --shadow-md:             0 4px 6px -1px rgba(0, 0, 0, 0.3),
+                           0 2px 4px -2px rgba(0, 0, 0, 0.2);
+  --shadow-lg:             0 10px 15px -3px rgba(0, 0, 0, 0.3),
+                           0 4px 6px -4px rgba(0, 0, 0, 0.2);
+  --shadow-xl:             0 20px 25px -5px rgba(0, 0, 0, 0.4),
+                           0 8px 10px -6px rgba(0, 0, 0, 0.2);
+  --shadow-2xl:            0 25px 50px -12px rgba(0, 0, 0, 0.5);
+
+  /* ========================================================================
+   * GLASSMORPHISM
+   *
+   * The defining visual technique of the brand. Frosted glass panels
+   * over the dark background create depth and layering without hard edges.
+   *
+   * Key ingredients:
+   * - backdrop-filter: blur() for the frosted effect
+   * - Semi-transparent background for the tint
+   * - Subtle border for edge definition
+   * - Works because our backgrounds have subtle gradients/noise
+   * ======================================================================== */
+  --glass-bg:              rgba(17, 17, 19, 0.7);       /* Standard panel  */
+  --glass-bg-heavy:        rgba(17, 17, 19, 0.85);      /* More opaque     */
+  --glass-bg-light:        rgba(17, 17, 19, 0.4);       /* More see-through */
+  --glass-bg-accent:       rgba(168, 85, 247, 0.05);    /* Accent-tinted   */
+  --glass-blur:            12px;                          /* Standard blur   */
+  --glass-blur-heavy:      24px;                          /* Strong blur     */
+  --glass-blur-light:      6px;                           /* Subtle blur     */
+  --glass-bg-elevated:     rgba(24, 24, 27, 0.6);                 /* Elevated */
+  --glass-border:          1px solid rgba(255, 255, 255, 0.06);  /* Edge    */
+  --glass-border-accent:   1px solid rgba(168, 85, 247, 0.12);  /* Accent  */
+  --glass-border-top-highlight: 1px solid rgba(255, 255, 255, 0.1); /* Top edge highlight */
+
+  /* ========================================================================
+   * ANIMATION
+   *
+   * Motion design principles:
+   * - Enter: ease-out (fast start, gentle landing)
+   * - Exit: ease-in (gentle start, fast departure)
+   * - Move: ease-in-out (smooth both ways)
+   * - Micro-interactions: 150ms (instant feel)
+   * - State transitions: 200-300ms (noticeable but quick)
+   * - Layout changes: 300-500ms (smooth reflow)
+   * - Page transitions: 500ms+ (dramatic but not slow)
+   * ======================================================================== */
+  --duration-instant:      75ms;
+  --duration-fast:         150ms;     /* Hover effects, color changes                        */
+  --duration-normal:       200ms;     /* State transitions, toggles                          */
+  --duration-moderate:     300ms;     /* Panel reveals, expansions                           */
+  --duration-slow:         500ms;     /* Page transitions, hero animations                   */
+  --duration-slower:       700ms;     /* Staggered entrance sequences                        */
+
+  /* Easing curves - custom cubic-beziers for premium feel */
+  --ease-out:              cubic-bezier(0.16, 1, 0.3, 1);     /* Enter: quick start, soft land      */
+  --ease-in:               cubic-bezier(0.7, 0, 0.84, 0);     /* Exit: gentle start, quick leave    */
+  --ease-in-out:           cubic-bezier(0.65, 0, 0.35, 1);    /* Move: symmetrical smooth           */
+  --ease-bounce:           cubic-bezier(0.34, 1.56, 0.64, 1); /* Playful overshoot (use sparingly)  */
+  --ease-spring:           cubic-bezier(0.22, 1.5, 0.36, 1);  /* Subtle spring for micro-interaction*/
+
+  /* Stagger delay for sequential animations */
+  --stagger-delay:         80ms;
+
+  /* ========================================================================
+   * Z-INDEX SCALE
+   *
+   * Named layers prevent z-index wars. Every z-index in the codebase
+   * should reference one of these tokens, never a raw number.
+   * ======================================================================== */
+  --z-behind:             -1;
+  --z-base:                0;
+  --z-raised:              10;       /* Cards, elevated surfaces                              */
+  --z-dropdown:            20;       /* Dropdown menus, popovers                              */
+  --z-sticky:              30;       /* Sticky headers, sidebars                              */
+  --z-overlay:             40;       /* Overlays, backdrops                                   */
+  --z-modal:               50;       /* Modal dialogs                                         */
+  --z-toast:               60;       /* Toast notifications                                   */
+  --z-tooltip:             70;       /* Tooltips (always on top)                              */
+
+  /* ========================================================================
+   * LAYOUT
+   *
+   * Content width constraints and breakpoint-aware sizing.
+   * Max-width prevents ultra-wide unreadable lines.
+   * ======================================================================== */
+  --width-prose:           65ch;      /* Optimal reading width for body text                  */
+  --width-content:         72rem;     /* 1152px - main content area                           */
+  --width-wide:            80rem;     /* 1280px - wide content (tables, grids)                */
+  --width-full:            90rem;     /* 1440px - max page width                              */
+  --width-sidebar:         16rem;     /* 256px - sidebar navigation                           */
+
+  /* ========================================================================
+   * BREAKPOINTS (for reference - use in @media queries)
+   *
+   * Mobile-first: styles apply at the breakpoint and above.
+   * sm:  640px  - Large phones, small tablets
+   * md:  768px  - Tablets, small laptops
+   * lg:  1024px - Standard laptops, desktops
+   * xl:  1280px - Large desktops
+   * 2xl: 1536px - Ultra-wide displays
+   * ======================================================================== */
+}