tegwick
0d688ca94a
Author the design language once in the canonical React designbook and project it
one-way onto each stack: React -> designbook/ -> ir/ -> adapters/<stack>/.
Phase 0 — contracts & governance (T01-T03):
- ir/SCHEMA.md + ir/schema/{component,tokens}.schema.json — neutral IR contract
(W3C DTCG tokens; React prop -> HTML attribute mapping; non-portable props flagged).
- adapters/ADAPTER_CONTRACT.md — inputs, drift-report + parity-result shapes,
idempotency rules, CI exit codes (0 ok / 2 usage / 3 drift / 4 parity / 5 internal).
- .claude/rules/designbook-propagation.md + DesignSystemIntroduction.md §5.1 —
one-way directionality + drift-resolution workflow.
T04 — canonical React designbook + the missing pull tool:
- The bundled /design-sync skill only PUSHES repo->cloud; it cannot populate
designbook/. Added scripts/designbook_pull.py + `make designbook-pull`, which drives
the local claude binary headless (acceptEdits) so DesignSync fetch+write runs in a
subprocess (contents never hit the orchestrator's context). Pulled 44 files;
excludes the _whynot-design-seed/ self-copy. Corrected the docs that wrongly called
/design-sync the pull.
T05 — IR extractor (scripts/ir-extract.mjs + `make ir`):
- ir/tokens.json (80 tokens, DTCG, var() -> {ref} alias resolution); ir/components/*.json
(10 contracts parsed from .jsx signatures: enum/boolean/number inference, prop->attr
map, style/callback marked non-portable); ir/exemplars/*.
T06 — Lit token adapter (adapters/lit/ + `make adapt-lit`):
- Full-gen tokens into src/styles/colors_and_type.css :root (marker-bounded, idempotent
no-op on re-run; hand-authored type CSS preserved).
NOTE: token regen synced Lit to canonical React — fonts IBM Plex -> system stacks and 8
status tokens added. This is a VISUAL change: review and run `pnpm test:visual:update`
before merge. Remaining: T07 scaffold+drift, T08 parity, T09 runbook, T10 2nd-adapter.
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
101 lines
6.5 KiB
Markdown
101 lines
6.5 KiB
Markdown
# Changelog
|
||
|
||
All notable changes to `@whynot/design` are recorded here. Hand-edited until release cadence makes it painful.
|
||
|
||
Format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/). Versioning rules: see [`DesignSystemIntroduction.md` §6](./DesignSystemIntroduction.md#6-versioning-discipline).
|
||
|
||
## [Unreleased]
|
||
|
||
### Added
|
||
|
||
- **Technology-neutral IR + stack-adapter pipeline** (WHYNOT-WP-0002, Phase 0–3). The
|
||
design language is now authored once in the canonical React designbook and projected
|
||
one-way onto each stack: `React → designbook/ → ir/ → adapters/<stack>/`.
|
||
- `ir/` — committed, diffable blueprint: `ir/SCHEMA.md`, JSON Schemas
|
||
(`ir/schema/{component,tokens}.schema.json`), and the extractor's output
|
||
(`ir/tokens.json` in W3C DTCG format, `ir/components/*.json`, `ir/exemplars/*`).
|
||
- `adapters/ADAPTER_CONTRACT.md` — the contract every stack adapter implements
|
||
(inputs, drift report + parity result shapes, idempotency, CI exit codes).
|
||
- `scripts/designbook_pull.py` + `make designbook-pull` — pulls the React designbook
|
||
from Claude Design into `designbook/` (the bundled `/design-sync` skill only
|
||
*pushes*, so it cannot populate `designbook/`).
|
||
- `scripts/ir-extract.mjs` + `make ir` — extracts the IR from the `.jsx` ui-kit,
|
||
manifest, and previews.
|
||
- `adapters/lit/` + `make adapt-lit` — Lit reference adapter; tokens fully generated
|
||
into `src/styles/colors_and_type.css` (marker-bounded, idempotent).
|
||
- `.claude/rules/designbook-propagation.md` + `DesignSystemIntroduction.md` §5.1 —
|
||
one-way governance and drift-resolution workflow.
|
||
|
||
### Changed
|
||
|
||
- `src/styles/colors_and_type.css` — token `:root` block is now **generated** by
|
||
`make adapt-lit` from `ir/tokens.json` (between `@generated tokens` markers). This
|
||
synced the Lit token layer to the canonical React designbook: font stacks switched
|
||
from IBM Plex to system-font stacks, and the functional-status tokens
|
||
(`--status-error/warn/success/info` + `-bg`) were added. **Visual change — Playwright
|
||
baselines need review + `pnpm test:visual:update`.**
|
||
|
||
## [0.2.0] — 2026-05-25
|
||
|
||
**Architectural reframe.** The system is now delivered as three stacked layers — tokens + CSS, Lit web components, optional framework adapters. The previous React-only component layer has been removed.
|
||
|
||
### Added
|
||
|
||
- `MultiFrameworkSupport.md` — full integration guide for React, Django, HTMX, Vue, Svelte, plain HTML.
|
||
- `src/elements/` — Lit-based web components, light-DOM rendered:
|
||
- **Atoms** (`atoms.js`): `<wn-button>`, `<wn-tag>`, `<wn-eyebrow>`, `<wn-stamp>`, `<wn-stage-dot>`, `<wn-phase-dot>`, `<wn-icon>`.
|
||
- **Form** (`form.js`): `<wn-input>`, `<wn-textarea>`, `<wn-select>`, `<wn-search-input>`, `<wn-field-row>`.
|
||
- **Layout** (`layout.js`): `<wn-card>`, `<wn-modal>`, `<wn-table>` + `<wn-table-row>` + `<wn-table-cell>`, `<wn-banner>`, `<wn-toast>` + `<wn-toast-region>`, `<wn-empty-state>`, `<wn-breadcrumb>`.
|
||
- **Chrome** (`chrome.js`): `<wn-top-nav>`, `<wn-sidebar>` + `<wn-sidebar-group>` + `<wn-sidebar-item>`, `<wn-page-header>`, `<wn-pipeline>`, `<wn-prototype-card>`.
|
||
- `src/elements/icons.js` — Lucide-derived inline icon paths (no runtime CDN dependency).
|
||
- `src/styles/components.css` — utility-class layer (`wn-btn`, `wn-card`, `wn-tag`, etc.). Consumable directly from any HTML for the "Layer 1 only" use case.
|
||
- `adapters/django/templates/whynot/*.html` — `{% include %}`-ready partials for Django consumers (button, eyebrow, tag, stage-dot, page-header, pipeline, field-row, prototype-card, banner, empty-state).
|
||
- `adapters/django/README.md` — how to wire the partials into a Django app.
|
||
- `examples/showcase/index.html` — single-page reference rendering every component. Doubles as the Playwright visual-regression baseline.
|
||
- `lit` ^3.2.1 as a runtime dependency.
|
||
|
||
### Changed
|
||
|
||
- `DesignSystemIntroduction.md` — updated to describe the three-layer architecture, multi-framework consumption, and the revised propagation pipeline.
|
||
- `README.md` — top-level rewrite around the new architecture, with quick-start blocks per framework.
|
||
- `package.json` — adds per-group `exports` (`@whynot/design/atoms`, `/form`, `/layout`, `/chrome`, `/icons`).
|
||
- CI now runs visual regression against `examples/showcase/index.html` *and* `examples/whynot-control/index.html`.
|
||
|
||
### Removed
|
||
|
||
- `src/components/Atoms.jsx`, `src/components/Chrome.jsx` — the React-only component layer. Consumers using these from v0.1.0 should swap to the corresponding custom elements (drop-in replacements; see `MultiFrameworkSupport.md` § React).
|
||
- `peerDependencies` on React. React is no longer required to consume `@whynot/design`.
|
||
|
||
### Migration
|
||
|
||
If you were on v0.1.0 with React imports like `import { Button } from "@whynot/design"`:
|
||
|
||
| Before (v0.1.0) | After (v0.2.0) |
|
||
|---|---|
|
||
| `import { Button } from "@whynot/design"; <Button variant="primary">…</Button>` | `import "@whynot/design"; <wn-button variant="primary">…</wn-button>` |
|
||
| `import { Tag } from "@whynot/design"; <Tag active>…</Tag>` | `<wn-tag active>…</wn-tag>` |
|
||
| `<StageDot level="S2" />` | `<wn-stage-dot level="S2"></wn-stage-dot>` |
|
||
|
||
CSS imports are unchanged; add the new `components.css` import alongside `colors_and_type.css`.
|
||
|
||
### Known caveats
|
||
|
||
- IBM Plex is loaded from Google Fonts. Drop `.woff2` files into `fonts/` and swap to a local `@font-face` for offline use.
|
||
- The showcase uses `importmap` + esm.sh to load Lit (no bundler). Real consumers using `pnpm add` will pick up Lit from `node_modules` via the package's `dependencies` entry.
|
||
- No TypeScript declarations for JSX yet — deferred until a TS consumer asks.
|
||
- `<wn-select>` uses a native `<select>` internally; richer custom selects (ElementInternals-based) will appear when a real need shows up.
|
||
|
||
## [0.1.0] — 2026-05-23
|
||
|
||
**Initial seed.** Established `whynot-design` as the implementation surface for the `whynot` visual language. (Pre-architectural reframe — see v0.2.0.)
|
||
|
||
### Added
|
||
|
||
- `src/styles/colors_and_type.css` — full token set + semantic element styles.
|
||
- `tokens/` — source-of-truth JSON tokens for colours, type, spacing, radii, shadows.
|
||
- `src/components/Atoms.jsx` — React: `Eyebrow`, `Tag`, `Button`, `StageDot`, `Stamp`, `Icon`.
|
||
- `src/components/Chrome.jsx` — React: `TopNav`, `Sidebar`, `PageHeader`, `PipelineStrip`.
|
||
- `examples/whynot-control/` — click-through UI kit recreating the `whynot-control` surface.
|
||
- `assets/whynot-logo.png` — LEGO-brick + `?!` mark.
|
||
- `SKILL.md`, `README.md`, `DesignSystemIntroduction.md`, `CONTRIBUTING.md`, `BOOTSTRAP.md`.
|