# CLAUDE.md — Maestro Design System

Engineering conventions for working in this design-system repo. Read alongside `README.md` (design foundations) and `SKILL.md` (the design language quick-start). The phosphor-console aesthetic and the rules in SKILL.md are binding — this file covers **how the code is organized and how to extend it correctly**.

## What this repo is

A compiler-backed design system. On every change an automated compiler reads the sources and regenerates three files — **never hand-edit these**:

- `_ds_bundle.js` — the compiled component library, exposed as `window.MaestroDesignSystem_a6a290`
- `_ds_manifest.json` — card / token / component index
- `_adherence.oxlintrc.json` — lint rules

The only fixed entry point is `styles.css` (root). It must stay a list of `@import` lines — never inline rules there.

## Layout

```
styles.css                 # entry — @import only
tokens/                    # CSS custom properties, one file per concern
  colors.css               # base + signal + -dim + semantic aliases + [data-theme=light] scope
  typography.css           # --mono family, size/leading/tracking scale
  effects.css              # spacing, radii, borders, shadows, @keyframes
  fonts.css                # Google Fonts @import (IBM Plex Mono + Noto Sans SC)
guidelines/*.card.html     # specimen cards for the Design System tab
components/<group>/        # core | forms | surfaces
  Name.jsx                 # the component (named export)
  Name.d.ts                # props contract (+ @startingPoint JSDoc if applicable)
  Name.prompt.md           # one-line what/when + JSX example
  <group>.card.html        # @dsCard showcase for the whole group
ui_kits/console/           # desktop console recreation (composes components)
ui_kits/console_mobile/    # 390px mobile recreation
assets/icons/*.svg         # double-tone icon set
```

## Authoring a component (the contract the compiler enforces)

A component is discovered when a directory holds **all three**: `Name.jsx` (PascalCase, with `export function Name(props)`), `Name.d.ts`, and ideally `Name.prompt.md`. To add or change one:

1. Write `Name.jsx` — React only, no npm deps, no CSS-in-JS libs. Style via the CSS custom properties (`var(--…)`). Self-contained; siblings may import each other by relative path.
2. Inject component CSS once via an `ensure<X>Css()` guard that appends a `<style id="…">` (see any existing component) — keeps class rules out of global scope and idempotent.
3. Write `Name.d.ts` with the full props interface and JSDoc. Write `Name.prompt.md`: line 1 = what & when, then a small JSX example, then notable variants.
4. Add the variant/state to the directory's `<group>.card.html` so it shows in the Design System tab. Load the bundle via `<script src="…/_ds_bundle.js">` and read `const { Name } = window.MaestroDesignSystem_a6a290`. **Never `<script src>` a `.jsx` directly** — the export is unreachable that way.
5. Run `check_design_system` and fix anything it reports until clean.

Do **not** write `_ds_bundle.js`, `_ds_manifest.json`, `_adherence.oxlintrc.json`, or a barrel `index.js` — all generated.

## Styling rules

- All color/spacing/radius/motion values come from tokens. If a value isn't a token yet and is reused, add it to the right `tokens/*.css` file rather than hardcoding.
- New tokens: base value + a semantic alias when it has meaning (`--violet` + `--status-gate`). Theme overrides go under the `[data-theme="light"]` scope in `colors.css`.
- Respect the five-signal-color discipline (SKILL.md). Approval = violet, MED = amber — do not collapse them.
- Radii use `--radius-xs/sm/md/lg`; never `border-radius: 0` for new surfaces (zero-radius was retired in v1.1) and never a raw px circle except status dots.

## UI-kit conventions (`ui_kits/console`)

- `index.html` is the React entry (Babel-in-browser, pinned versions + integrity hashes — keep them). Each surface is its own `*.jsx` file attached to `window.MaestroKit*`; `data.js` holds the mock, `i18n.js` holds all strings.
- **Every user-facing string goes through `t.<key>` in i18n.js across all 5 languages (zh/en/es/ja/fr).** Never hardcode display text in a component. Status/gate/event/autonomy labels are passed as props from `t`.
- Persisted UI state (sidebar/event collapse, column widths, language, theme) uses `localStorage` keys prefixed `maestro-kit-`. Never clear keys you didn't write.
- Flyout panels that live inside the `overflow:hidden` rails must use `position: fixed` with a measured anchor rect (see `GlobalConfigRow` / `AgentsRow` / `UserRow`) so they aren't clipped.
- Three-column grid widths are drag-resizable with min/max clamps that guarantee a ≥480px center; collapsed rails are 52px. Keep that invariant if you touch the layout.

## Icons

Add new icons to `assets/icons/` on the same grid: 24×24, `fill="none"`, `stroke="currentColor"`, `stroke-width="2"`, round caps/joins. Two-tone semantic strokes use `var(--icon-accent, <signal fallback>)`. Don't add a third-party icon library. Brand glyphs (`▍ ▮ → ↳ · « »`) stay as mono characters, not SVG.

## Before finishing any change

1. `check_design_system` → resolve all reported issues.
2. Verify the affected `ui_kits/*/index.html` renders with no console errors, in both themes and at least zh + en.
3. Keep `README.md` INDEX and component lists in sync if you add/remove files.

## Known caveats

- Fonts are CDN-loaded; no woff2 binaries in-repo. For offline/production, drop woff2 into the project and convert `tokens/fonts.css` to local `@font-face`.
- The logo is a 15×12 pixel-octopus drawn in canvas/CSS (see `guidelines/brand-logo.card.html`) — there is no logo image file.
- `_ds_bundle.js` recompiles at end of turn; a freshly edited component may look stale in the preview until then.