wangjia
5a1e185b1a
phosphor console v1.1 设计系统（从现网 web/style.css 演化）：tokens(colors/effects/ typography/fonts) + components(core/forms/surfaces .jsx) + ui_kits(console + console_mobile) + assets/icons(15 双色 SVG) + guidelines + CLAUDE/SKILL/readme。供 B1–B6 重构任务对照实现。 Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
77 lines
5.7 KiB
Markdown
77 lines
5.7 KiB
Markdown
# 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.
|