Token-contract JSON Schema for preset authoring

SPEC-111 §6 — publish a JSON Schema derived from the universal token contract (SPEC-048) so JSON presets get editor validation/autocomplete and a future visual editor has a foundation.

changeset-release/main View source

Criteria completion

Tracking started Jun 24 — check back for trends.

Relationships

ID:SPEC-111Status:accepted

Decoupled preset packs with scope and compatibility metadata

ID:SPEC-048Status:accepted

Design tokens contract & config

ID:WORK-448Status:done

Bake ADR-023 peerDeps, compat range, devDeps and build wiring into scaffolds

Priority:highComplexity:moderateMilestone:v0.25.0

ID:WORK-456Status:done

Preset-pack format and presets.json manifest (capability not kind)

Priority:highComplexity:moderateMilestone:v0.25.0

ID:WORK-459Status:done

Preset scope and tunedFor metadata with pack-manifest validation

Priority:mediumComplexity:moderateMilestone:v0.25.0

changeset-release/main current done

main done claude/v0.25.0-impl-2 done claude/v0.25.0-workitems ready

Jun 24, 07:10 PM2264093
Created (done)by github-actions[bot]

Acceptance Criteria

A JSON Schema is generated from the universal token contract and published at a stable path/URL
A JSON preset declaring "$schema": "…" validates against it, with editor autocomplete
The preset-pack scaffold seeds $schema in its example preset (WORK-448/WORK-456)
The schema is regenerated/checked in CI so it tracks the token contract (no drift)

Approach

Derive the schema from the typed token contract in packages/types (codegen from the TS types, or a hand-maintained schema with a CI drift check). Keep it the single source editors and the validator (WORK-459) reference.

Dependencies

WORK-456 — the pack format

References

SPEC-111 §6; SPEC-048 (universal token contract)

Resolution

Completed: 2026-06-24

Branch: claude/v0.25.0-impl-2

What was done

packages/transform/theme-tokens.schema.json — a JSON Schema for ThemeTokensConfig authored faithfully from the universal token contract (SPEC-048): top-level namespaces font/text/weight/leading/tracking/color/radius/spacing/shadow/syntax/reveal + modes (per-mode overlays) + extra, with structured color (scalar chrome + nested surface/code/sentiment groups). Strict at the root (additionalProperties:false) for typo-catching editor validation.
Exported as ./theme-tokens.schema.json + added to files; referenced by the preset scaffold's $schema (https://refrakt.md/schemas/vX.Y/theme-tokens.json, same publishing convention as refrakt.config.schema.json).
theme-tokens-schema.test.ts (ajv) — validates the scaffold's syntax preset + a full palette preset (chrome/surface/sentiment/dark mode), rejects an unknown top-level key and a non-string scalar, and a drift guard asserts the schema's namespaces match the contract list. Added ajv devDep to transform.

Notes

The repo hand-maintains refrakt.config.schema.json (no codegen dep); this schema follows suit, with the drift-guard test as the "tracks the contract" mechanism.