whynot-design/.claude/rules/stack-and-commands.md

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

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: " 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.