feat: Penpot interop on top of DTCG support

[nujovich]

Context

Penpot (github.com/penpot/penpot) is an
open-source design tool with native support for design tokens following
the W3C Design Tokens Community Group (DTCG) Format Module v1 — the same spec
that mint-ds validate --spec dtcg checks today (PR #69).

That overlap opens a low-cost interop path: once Mint can emit DTCG, the same
artifact is consumable by Penpot's Tokens panel and by Tokens Studio for
Figma, with zero vendor-specific code.

This issue tracks the work to close that loop.

Goals

• Round-trip tokens between Mint and Penpot using the DTCG standard format.
• No vendor lock-in: every layer below works just as well with Figma's Tokens
  Studio plugin, Style Dictionary, etc.

Non-goals

• Building a Mint clone inside Penpot.
• Supporting Penpot-only features that aren't expressible in DTCG.

Milestones

Milestone 1 — --target dtcg export (prerequisite)

Add a new export target that transforms mint-ds.tokens.json (Mint's internal
shape) into a DTCG-v1-compliant JSON. Validated by feeding the output back
through mint-ds validate --spec dtcg (must exit 0).

• Map colors[].name/value/scale → grouped DTCG color tokens with
  inherited $type: color
• Map spacing, borderRadius, shadows, typography.fontFamilies,
  typography.fontWeights to the corresponding DTCG types
• Reuse examples/frankenstein/ as a golden fixture: committed
  mint-ds.tokens.dtcg.json is the expected output
• Add a vitest case that exports the fixture and asserts
  validateDTCG(output).hasErrors === false

Depends on: PR #69 merged.

Milestone 2 — Penpot import path documentation

Once --target dtcg lands, document the end-to-end happy path:

• README section "Use with Penpot": run mint-ds export --target dtcg,
  open Penpot → Tokens panel → Import JSON
• Add the same section for Tokens Studio in Figma (same JSON, different
  consumer — reinforces the no-lock-in story)

No code change beyond docs.

Milestone 3 — Penpot API push (optional, exploratory)

If there's traction after M1+M2, add a --push penpot flag that uploads
tokens to a Penpot file via its REST API instead of writing locally.

• Spike: confirm Penpot's REST API exposes a writable tokens endpoint on
  the latest self-hostable release
• mint-ds export --target dtcg --push penpot --file-id <id> reads
  PENPOT_API_TOKEN, posts the JSON
• Inverse direction: mint-ds pull --penpot --file-id <id> writes the
  Penpot tokens to a local tokens.json that the audit can consume

Milestone 4 — Penpot plugin (optional, ambitious)

Wrap the existing app/api/audit/route.ts pipeline as a Penpot plugin:

• Plugin scans styles of the open Penpot file
• Calls Mint's audit endpoint, shows the cluster/font/spacing review UI
  inside Penpot
• Writes the curated tokens back to the same file

This is essentially the 3-step web wizard hosted inside Penpot.

Why not just add $extensions validation (PR #69 Milestone 4)?

That milestone validates the metadata block Tokens Studio writes into a
DTCG file ($extensions["studio.tokens"], etc.). It's spec polish — it does
not make Mint talk to Figma or Penpot. The actual interop is the
emit-DTCG → import-DTCG round-trip described above.

Related

• PR feat: DTCG v1 validation for tokens.json #69 — DTCG v1 validation (foundation for M1's golden test)
• W3C DTCG Format Module v1: https://www.designtokens.org/TR/2025.10/format/
• Penpot design tokens: https://help.penpot.app/user-guide/design-tokens/

[nujovich]

BUILD 2026-07-12: M1 done. PR draft #85 ready for review — --target dtcg deterministic export. 52 tests passing (11 exporter + 41 validator). All token categories mapped, golden fixture validated with mint-ds validate --spec dtcg.