feat(pipeline): InDesign IR to WordPress design token mapper (#64)

[PAMulligan]

Summary

Stage 3 of the InDesign-to-WordPress pipeline (sub-issue of #61): map the
InDesign IR — produced by either the IDML parser (#62) or the PDF fallback
parser (#63) — to WordPress design tokens, so generated patterns inherit a
coherent design system instead of inline magic numbers.

mapTokens(ir, options) produces three artifacts:

• theme.json partial — additive, namespaced, deep-merges into a base theme.
• design-tokens.json — DTCG / Style Dictionary v4 compatible.
• report — warnings, validation result, provenance, font fallbacks, Google fonts.

A bin/map-tokens.mjs CLI composes with the parser CLIs (or parses .idml/.pdf directly).

Design decisions

Captured in docs/plans/2026-05-29-indesign-token-mapper-design.md:

1. Color: extend the IR Color with optional raw components and convert
   CMYK/LAB → sRGB in a shared module with out-of-gamut warnings. Side benefit:
   LAB/Spot swatches no longer collapse to #000000 in the IR.
2. Merge: additive, namespaced partial + a deep-merge helper (token arrays
   merge by slug), so derived tokens never clobber the curated base.
3. Validation: ajv against the vendored official WordPress theme.json schema
   and a zod schema for the emitted subset.
4. Typography: dynamic clustered scale that reuses base slugs when close,
   else namespaced derived slugs.

How it maps

• Swatches → color.palette (re-derive sRGB from components, dedupe by hex within tolerance, reuse close base slugs).
• Paragraph styles → typography.fontSizes (clustered) + styles.elements (h1–h6, caption) and styles.blocks['core/paragraph'] for body.
• Fonts → typography.fontFamilies via config/font-map.json (heuristic generic fallback + warning when unmapped).
• Page margins / gutters / paragraph spacing → quantized spacing.spacingSizes.

Acceptance criteria

• Generated theme.json validates against the WordPress block theme schema (ajv + vendored schema).
• Palette includes all distinct swatches, deduped by hex within a configurable tolerance.
• Every typography scale entry is referenced by ≥1 paragraph style (provenance recorded in the report).
• Font fallback warnings are emitted and listed in the generator report.
• Tests cover CMYK→sRGB (and LAB→sRGB) against fixtures, paragraph-style clustering, and the merge-with-base path.
• Works on either IR — end-to-end test runs on both an IDML-built and a PDF-built IR.

Test plan

• pnpm --filter @flavian/pipeline test → 88/88 pass (was 67 before this PR; existing parser/round-trip tests still green).
• New suites: color, ir-color, parser-color-components, map-colors, map-typography, map-spacing, map-fonts, map-theme-json, map-design-tokens, map-tokens (e2e).
• CLI verified manually: partial → stdout, report summary → stderr, four artifacts → --out-dir.

Notes

• The IR change is additive (Color.components optional); irVersion stays 1, and existing IRs still validate. The two merged parsers were routed through the new shared color.js.
• One pre-existing malformed.test.mjs case used LAB as its "unknown space" example expecting black; it was repointed to a genuinely unsupported space, with a new test documenting that LAB now converts.

Closes #64.

🤖 Generated with Claude Code