maestro/design/CLAUDE.md

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.