feat(design-system): token re-import + round-trip guarantee and documented consumers#110
Merged
PAMulligan merged 1 commit intoJul 1, 2026
Conversation
…nsumers Complete the v2.0.0 "design system export" scope. The /export-design-system command, output format, and skill already shipped on main; this fills the two remaining gaps: a defined consumer (#3) and a round-trip guarantee (#4). - Add scripts/import-design-tokens.js (+ .sh wrapper): the inverse of the exporter. Reconstructs design-tokens.lock.json from an exported package's lossless tokens.json (--from export root | package dir | tokens.json file), with --out/--verify/--force/--json. tokens.css and tailwind-preset are derived, one-way views and are never used for reconstruction. - Add scripts/__tests__/design-system-roundtrip.test.js: proves tokens -> export -> reimport produces a deep-equal lockfile, plus --verify, direct tokens.json import, and input-validation exit codes. - Add docs/design-system-export/consumers.md: the interchange contract and how the named consumers ingest the export — Aurelius (self re-import), Flavian (WordPress/FSE theme.json mapping + adapter snippet), Nerva (typed tokens in a Hono/Workers backend), and a Style Dictionary note. - Wire re-import/round-trip into the export-design-system skill and the /export-design-system command; document the new script in CLAUDE.md and add a README Documentation Index entry. - Record the validated design in docs/plans/2026-07-01-...-design.md. Closes #82 Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Completes the v2.0.0 design system export scope (#82). The
/export-design-systemcommand, its output format (CSS vars + JSON + typed TS +Tailwind preset), and the
export-design-systemskill already shipped onmain(criteria #1, #2). This PR fills the two remaining gaps:
Key insight
The exported
@scope/design-tokenspackage ships four token artifacts, but onlytokens.json/tokens.tsare lossless snapshots of the lockfile.tokens.cssandtailwind-preset.tsare derived, one-way views (they dropnested color scales, typography families,
textContent, metadata). So theround-trip goes through
tokens.json, the canonical interchange.What changed
scripts/import-design-tokens.js(+.shwrapper): theinverse of the exporter. Reconstructs
design-tokens.lock.jsonfrom an exportroot, a package dir, or a raw
tokens.json(--from), with--out/--verify/--force/--json.--verifyis the executable form of theround-trip guarantee (exit 0 identical, 1 drifted). Exit codes mirror the
exporter (0/1/2/3).
scripts/__tests__/design-system-roundtrip.test.js:tokens → export → reimport → deep-equal lockfile, plus
--verify, directtokens.jsonimport, and input-validation exit codes (8 tests).docs/design-system-export/consumers.md: the interchangetable (lossless vs derived), the round-trip guarantee, and how the named
consumers ingest the export — Aurelius (self re-import), Flavian
(WordPress/FSE
theme.jsonmapping table + adapter snippet), Nerva (typedtokens in a Hono/Workers backend), plus a Style Dictionary note.
export-design-systemskill and the
/export-design-systemcommand; the new script documented inCLAUDE.md; a README Documentation Index entry for the consumer doc.docs/plans/2026-07-01-design-system-export-consumer-roundtrip-design.md.Acceptance criteria (#82)
/export-design-systemunder.claude/commands/(already on main; re-import wiring added)tokens.jsonis the lossless interchange (Style Dictionary optional)theme.json) and Nerva (typed tokens), with mapping tables + examplesVerification
pnpm vitest run scripts/__tests__/design-system-roundtrip.test.js→ 8 passedeslinton the new JS → cleanprettier --checkon all new/changed files → clean./scripts/check-doc-counts.sh→ 0 driftBuilt TDD: the round-trip test was written first (RED), then the reimporter made it pass (GREEN).
Closes #82