design-system/AGENTS.md

Northstar Design System — agent handbook

React 19 + Vite 8 + TypeScript design-system showcase. Dark-first, token-driven UI with a light theme.

Commands

Task	Command
Dev server	npm run dev (vite.config.ts pins 0.0.0.0:5173)
Full gate: lint + token contract + typecheck + build	npm run check — run before declaring any change done
Lint only	npm run lint (oxlint)

Sandboxed worker dev flow

• vite.config.ts allows *.preview.k6n.net; expose port 5173 via repo_instance_expose for a preview URL.
• Removing allowedHosts breaks preview ingress with a 403 ("host not allowed"). Don't.

Design tokens — the contract

1. Single source of truth: src/tokens.css. Every font size, color, spacing, radius, and shadow color comes from a token. The palette is defined in modern CSS Color 4 lab(...) color space:
   • Dark theme (.dark, [data-theme='dark']): Pitch black base (lab(0% 0 0)), deep cards (lab(.903296% 0 0)), radiant electric mint/cyan primary (lab(89.9321% -47.9163 -15.7303)), vivid destructive (lab(54.5811% 71.684 50.9279)), chart colors 1–5, and subtle dot grid (--dot-color).
   • Light theme (:root, [data-theme='light']): Pure white daylight base (lab(100% 0 0)), crisp charcoal primary (lab(7.78201% -.0000149012 0)), and high-contrast surfaces.
2. The guard scripts/check-tokens.mjs (in npm run check) bans hardcoded hex colors, px font sizes, and raw rgba() in application CSS — new colors go in as tokens, accent washes use color-mix(in srgb, var(--primary) N%, transparent).
3. Typography scale (--text-3xs … --text-2xl, --text-hero) is rem-based on a 9→28px grid. Longform body --text-md, buttons/nav --text-xs, meta/eyebrows --text-2xs/--text-3xs.
4. Global density knob: --root-font-size (default 112% readability preset, baseline 16px = 100%). One line scales every token-driven size app-wide; spacing tokens follow.
5. Theming: components read only var(--*) and never know the theme. Toggle synchronizes both document.documentElement.dataset.theme and .dark/.light classes.

Smart Utils & AI Workflow

• Class helper: src/utils/cn.ts — zero-dependency classnames merging utility for conditional component styles.
• Smart CSS: src/utils.css — ready-to-use helpers (.dot-canvas, .surface-card, .surface-sidebar, .badge-*, .hover-lift, .kbd-tag, .skeleton-pulse, .progress-*, .ui-table-*, .dialog-*, .sheet-*, .alert-*, .ui-tabs-*, .switch-*).
• Composable Primitives: src/components/ui/ (Dialog, Sheet, Tabs, Alert, EmptyState, Table, Progress, Switch, Badge, Card, StatCard, Skeleton, Tooltip, Kbd, Icon).
• Reusable Application Patterns: src/components/examples/ (MetricsDashboard, SettingsPanel, ServiceTable, DeploymentModal).
• Icon Library: lucide-react — 1,400+ tree-shaken SVGs with uniform stroke and color inheritance (<Icon name="..." /> or direct import).

Structure

src/
  tokens.css        ← lab() design tokens + dark & light themes (edit this first)
  utils.css         ← token-compliant smart CSS utility classes
  index.css         ← fonts, tokens & utils import, base resets
  App.css           ← application component styles (token-driven, plain CSS)
  App.tsx           ← page composition & showcase layout
  utils/
    cn.ts           ← conditional classnames utility
  components/
    ui/             ← composable UI primitives (Dialog, Sheet, Tabs, Alert, EmptyState, Table, Progress, Switch, Badge, Card, StatCard, Skeleton, Tooltip, Kbd, Icon)
    examples/       ← reusable pattern components (MetricsDashboard, SettingsPanel, ServiceTable, DeploymentModal)
    AIWorkflowSection.tsx ← interactive pattern switcher & showcase
    IconMatrix.tsx  ← interactive Lucide icon explorer & search
    Topbar.tsx      ← owns the theme toggle (.dark & data-theme)
    Hero.tsx, CodeSample.tsx, RightRail.tsx, ButtonMatrix.tsx,
    Sidebar.tsx, Section.tsx, FormField.tsx, TokenGrid.tsx,
    MarkdownRenderer.tsx, CodeEditor.tsx, Button.tsx, Icon.tsx
  data/
    library.ts      ← demo content and color token data for the showcase
scripts/check-tokens.mjs ← token contract guard (part of npm run check)

Iteration workflow for visual changes

1. Change the token (or component markup) — never a literal.
2. npm run check until green.
3. Verify live: dev server + preview URL; screenshot at desktop width; toggle light/dark via the topbar button.