Template
66 lines
4.5 KiB
Markdown
66 lines
4.5 KiB
Markdown
# 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.
|