tegwick
722c83b57d
CLAUDE.md modular rules, AGENTS/INTENT/SCOPE/.custodian-brief, and the state-hub bootstrap workplan (WHYNOT-WP-0001). Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
35 lines
4.1 KiB
Markdown
35 lines
4.1 KiB
Markdown
## Stack
|
|
|
|
- **Language:** ES modules (no build step, no transpile — source ships as-is).
|
|
- **Key deps:** `lit` ^3 (web components, the one runtime dep); `@playwright/test` (the one dev dep, visual regression).
|
|
- **Components:** shadow-DOM Lit elements that adopt a shared stylesheet so the Layer 1 `.wn-*` utility classes work inside the shadow root. `src/elements/_styles.js` is **auto-generated** from `src/styles/components.css` by `scripts/sync-shared-styles.mjs` — never hand-edit it.
|
|
|
|
## Dev Commands
|
|
|
|
```bash
|
|
pnpm install
|
|
pnpm showcase # serve :4321 → /examples/showcase/ (every component)
|
|
pnpm example # serve :4322 → examples/whynot-control
|
|
pnpm test:visual # Playwright visual-regression run (auto-starts a static server)
|
|
pnpm test:visual:update # regenerate screenshot baselines after an intentional change
|
|
pnpm check # check-changelog: fails if CHANGELOG.md gained no entry vs main
|
|
npx playwright test -g "inbox" # run a single visual test by name
|
|
|
|
make # list make targets (help is the default goal)
|
|
make designbook-sync # after a /design-sync pull, record changes + last-sync time → RecentChanges.md
|
|
make designbook-check # ask Claude Design (via llm-connect) if the cloud is newer; warn if mirror is stale
|
|
make recent-changes # regenerate RecentChanges.md (alias; ARGS="--range main..HEAD" supported)
|
|
make sync-styles # = node scripts/sync-shared-styles.mjs
|
|
```
|
|
|
|
There is no unit-test suite — correctness is verified by full-page Playwright screenshot diffs of the two `examples/` pages (`tests/visual/ui-kit.spec.mjs`, `maxDiffPixelRatio: 0.005`). Any visual change needs `pnpm test:visual:update` + baseline review.
|
|
|
|
## Integrating the designbook
|
|
|
|
The **designbook** is the upstream atelier — the **Claude Design project** (cloud, `claude.ai/design`), source of truth for the *language*. Its local mirror lives in-repo at `designbook/` (see `designbook/README.md`). Sync is **agent-driven and incremental** (one component at a time, never a wholesale replace):
|
|
|
|
1. **Pull** — run `/design-sync` in Claude Code (the `DesignSync` tool over the claude.ai login); it writes into `designbook/`. Immediately stamp the time: `node scripts/designbook-sync.mjs --mark-synced`. A Makefile cannot invoke the MCP tool, so the pull is always an agent step.
|
|
2. **Record** — `make designbook-sync` runs `scripts/designbook-sync.mjs`, writing `RecentChanges.md`: a **snapshot** (not a log) of what changed across `designbook/` + the derived surfaces (`tokens/`, `src/styles/`, `src/elements/`, `examples/`), grouped by layer.
|
|
|
|
**Freshness** is tracked in `designbook/.design-sync.json` (`lastSyncAt`, `remoteUpdatedAt`, `projectId`, `projectName`). Every report states **"Last /design-sync: <datetime>"** so it's clear whether the snapshot reflects the latest design. The cloud-ahead check is backed by **llm-connect** (`make designbook-check` → `scripts/check_designbook_staleness.py`): it uses the `claude-code` adapter to ask the local `claude` binary for the project's current `updatedAt` via `DesignSync.list_projects`, then records it with `node scripts/designbook-sync.mjs --remote-updated <iso>`. Only the `claude-code` adapter can reach the user's Claude Design project (Gemini/OpenRouter/OpenAI cannot), and no secret goes in the prompt — DesignSync uses the claude.ai login (see `credential-routing.md`). The check needs `llm_connect` importable; the Makefile auto-selects `~/llm-connect/.venv/bin/python`. Use `--remote-updated <iso>` to run the comparison offline/manually, or `--fail-if-stale` (exit 3) in automation. When `remoteUpdatedAt` is newer than `lastSyncAt`, the report and stdout **warn that the local mirror is OUTDATED** until the next `/design-sync`. If no sync was ever recorded, it warns that `/design-sync` has not run. The reporter is deterministic (built from `git status`/`git diff`), only writes the working tree, never commits, and never edits `designbook/` content. Fold notable entries into `CHANGELOG.md` under `## [Unreleased]` before releasing — `RecentChanges.md` is overwritten every run and is **not** the CI-enforced artifact.
|