Skip to content

feat(design-system): token re-import + round-trip guarantee and documented consumers#110

Merged
PAMulligan merged 1 commit into
mainfrom
82-design-system-export-command-export-design-system
Jul 1, 2026
Merged

feat(design-system): token re-import + round-trip guarantee and documented consumers#110
PAMulligan merged 1 commit into
mainfrom
82-design-system-export-command-export-design-system

Conversation

@PAMulligan

Copy link
Copy Markdown
Collaborator

Summary

Completes the v2.0.0 design system export scope (#82). The
/export-design-system command, its output format (CSS vars + JSON + typed TS +
Tailwind preset), and the export-design-system skill already shipped on main
(criteria #1, #2). This PR fills the two remaining gaps:

Key insight

The exported @scope/design-tokens package ships four token artifacts, but only
tokens.json / tokens.ts are lossless snapshots of the lockfile.
tokens.css and tailwind-preset.ts are derived, one-way views (they drop
nested color scales, typography families, textContent, metadata). So the
round-trip goes through tokens.json, the canonical interchange.

What changed

  • Re-importerscripts/import-design-tokens.js (+ .sh wrapper): the
    inverse of the exporter. Reconstructs design-tokens.lock.json from an export
    root, a package dir, or a raw tokens.json (--from), with
    --out/--verify/--force/--json. --verify is the executable form of the
    round-trip guarantee (exit 0 identical, 1 drifted). Exit codes mirror the
    exporter (0/1/2/3).
  • Round-trip testscripts/__tests__/design-system-roundtrip.test.js:
    tokens → export → reimport → deep-equal lockfile, plus --verify, direct
    tokens.json import, and input-validation exit codes (8 tests).
  • Consumer contractdocs/design-system-export/consumers.md: the interchange
    table (lossless vs derived), the round-trip guarantee, and how the named
    consumers ingest the export — Aurelius (self re-import), Flavian
    (WordPress/FSE theme.json mapping table + adapter snippet), Nerva (typed
    tokens in a Hono/Workers backend), plus a Style Dictionary note.
  • Wiring — re-import/round-trip section added to the export-design-system
    skill and the /export-design-system command; the new script documented in
    CLAUDE.md; a README Documentation Index entry for the consumer doc.
  • Design docdocs/plans/2026-07-01-design-system-export-consumer-roundtrip-design.md.

Acceptance criteria (#82)

  • Slash command /export-design-system under .claude/commands/ (already on main; re-import wiring added)
  • Output format documented — CSS variables + JSON + typed TS + Tailwind preset; tokens.json is the lossless interchange (Style Dictionary optional)
  • Consumer documented — Flavian (theme.json) and Nerva (typed tokens), with mapping tables + examples
  • Round-trip test — tokens → export → reimport produces an identical lockfile

Verification

  • pnpm vitest run scripts/__tests__/design-system-roundtrip.test.js8 passed
  • eslint on the new JS → clean
  • prettier --check on all new/changed files → clean
  • ./scripts/check-doc-counts.sh0 drift
  • Pre-commit count guard passed on commit

Built TDD: the round-trip test was written first (RED), then the reimporter made it pass (GREEN).

Closes #82

…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>
@PAMulligan PAMulligan linked an issue Jul 1, 2026 that may be closed by this pull request
4 tasks
@PAMulligan PAMulligan self-assigned this Jul 1, 2026
@PAMulligan PAMulligan moved this from Todo to Done in PMDS Open Source Roadmap Jul 1, 2026
@PAMulligan PAMulligan added this to the v2.0.0 milestone Jul 1, 2026
@PAMulligan
PAMulligan merged commit 3b8f06f into main Jul 1, 2026
7 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

Development

Successfully merging this pull request may close these issues.

Design system export command (/export-design-system)

1 participant