@ggui-ai/project-config 0.15.0 → 0.17.0

package/dist/theme.js

@@ -1,82 +1,45 @@
 /**
- * `ggui.json#theme` → plain DTCG JSON document.
+ * `ggui.json#theme` → plain DTCG JSON document, v2 (ggui#987).
  *
  * The theme file is a plain JSON document matching the Design Tokens
- * Community Group (DTCG) spec. It is one of the open file-format
- * surfaces in the ggui manifest model, alongside
- * `ggui.primitives.json` and `ggui.ui.json`.
+ * Community Group (DTCG) spec, in the same vocabulary as
+ * `@ggui-ai/design`'s canonical {@link DtcgTheme}: the curated registry
+ * themes and an authored `theme.json` are the same shape.
  *
- * **Shape parity with the internal `DtcgTheme`.** This v1 schema is
- * deliberately the same shape as `@ggui-ai/design`'s canonical
- * {@link DtcgTheme} — `color`/`font`/`spacing`/`shape`/`motion`/
- * `accessibility`/`zIndex` — so an authored `theme.json`
- * uses the same vocabulary the curated registry themes (light/dark/
- * premium-*) use. Previously this schema was Tailwind-style flat
- * (`typography`/`radius`/`shadow` at root); the v1 schema now mirrors
- * the internal shape to remove the divergence.
+ * **What is authored, what is derived.** An author states the six
+ * layering roles (`ground`/`onGround`, `container`/`onContainer`,
+ * `sunken`/`onSunken`), one `500` anchor per family (`primary`,
+ * `success`, `warning`, `error`, `info`), the font families and
+ * weights, spacing, radii, shadows. Everything else — the ten-stop
+ * ramps, every `on*` ink and container, the neutral ladder, outlines,
+ * `elevated`, the type scale from the one `font.ramp` — is DERIVED by
+ * the one producer (`deriveThemeVariables`), so the retired ladders
+ * (`font.size`, `font.lineHeight`, `motion.duration`, `motion.easing`)
+ * and `$metadata.fontUrl` are refused, not ignored. Fonts are declared
+ * as `typography.faces` (https `src` only); the card installs them.
  *
- * **External-tool compatibility.** External tooling (Figma Tokens,
- * Style Dictionary, Tokens Studio) commonly emits only a subset of
- * the canonical shape. Only the original required groups (`color`,
- * `font`, `spacing`, `shape`) stay required; `motion`,
- * `accessibility`, `zIndex`, and the new DTCG metadata fields
- * (`$name`, `$description`, `$metadata`) are all OPTIONAL so tools
- * that only emit colors + dimensions still parse cleanly.
- *
- * **BREAKING for old `theme.json` files.** Authors who hand-wrote a
- * `theme.json` against the pre-rc schema must rename:
- *
- *   - `typography.fontFamily` → `font.family`
- *   - `typography.fontSize` → `font.size`
- *   - `typography.fontWeight` → `font.weight`
- *   - `typography.lineHeight` → `font.lineHeight`
- *   - top-level `radius` → `shape.radius`
- *   - top-level `shadow` → `shape.shadow`
- *   - top-level `duration` → `motion.duration`
- *   - top-level `transition` → `motion.transition`
- *
- * Plus: under `font.family`, `sans` is the only required sub-token
- * (was previously freeform); other family slots (`mono`, …) are
- * optional. The font-family record itself stays open so additional
- * named families parse without a schema change.
+ * **External-tool leniency.** `motion`, `accessibility`, `zIndex` and
+ * the DTCG metadata fields stay OPTIONAL; {@link normalizeThemeDocument}
+ * fills them from the shipped default and flattens the DTCG object
+ * forms (structured shadows, transitions, array font stacks) to the CSS
+ * strings the producer reads.
  *
  * **Ownership boundary:**
  *
  *   - *Where* the theme lives → `ggui.json#theme` (pointer string).
  *   - *What* the theme file looks like → this module's schema.
- *   - *How* DTCG tokens become CSS variables → `@ggui-ai/design`'s
- *     `generateCssVariables` (stays over there; this schema does not
- *     emit). The duck-typed walker accepts any DTCG-shaped tree, so
- *     the new nested groups (`font.size`, `shape.radius`, …) walk
- *     into `--ggui-font-size-md`/`--ggui-shape-radius-md` CSS vars
- *     without code changes.
+ *   - *How* the document becomes CSS variables → `@ggui-ai/design`'s
+ *     `deriveThemeVariables` (the loader calls it for both modes).
  *   - *Built-in default* when `theme` is absent → `@ggui-ai/design`'s
- *     shipped `lightTheme`.
- *
- * **Extending rules:**
+ *     shipped `lightTheme` / `darkTheme`.
  *
- *   1. Additive only within `schema: '1'`. New optional fields must
- *      default to no-op behaviour so older tooling ignores them.
- *   2. Framework-neutral + host-neutral. No vendor names in enum
- *      values, no build-pipeline fields.
- *   3. Root and per-group objects are strict — unknown keys fail
- *      parse. Same discipline as `ggui.json`, `ggui.ui.json`, and
- *      `ggui.primitives.json`.
- *
- * **Strictness tradeoff:**
- *
- * Individual DTCG token leaves are validated with a discriminated
- * union over `$type` (color / dimension / fontFamily / fontWeight /
- * shadow / duration / cubicBezier / transition / number). Each
- * variant validates its `$value` shape. `$description` is accepted
- * everywhere as a free-form docstring. Token leaves under newer
- * groups (`accessibility`, `zIndex`) accept a slightly
- * wider token vocabulary because external tools sometimes encode
- * scalar/array values with permissive `$type` strings (`string`,
- * `array`, …); the schema accepts those without enumerating every
- * possible spelling.
+ * **Extending rules:** additive only within `schema: '1'`; framework-
+ * and host-neutral; root and per-group objects are strict — unknown
+ * keys fail parse, the same discipline as `ggui.json`.
  */
 import { z } from 'zod';
+import { fontFaceDeclarationSchema } from '@ggui-ai/protocol';
+import { lightTheme } from '@ggui-ai/design/themes';
 // ─── Token leaves ────────────────────────────────────────────────────
 /** A CSS color string. `$value` is not structurally validated (hex,
  *  rgba, color-mix, named, etc. are all legal DTCG colors). */
@@ -112,14 +75,6 @@ const DurationToken = z.strictObject({
     $value: z.string().min(1),
     $description: z.string().optional(),
 });
-/** DTCG cubic-bezier easing token. `$value` is a CSS timing function
- *  string (`"cubic-bezier(0.4, 0, 0.2, 1)"`, keyword aliases like
- *  `"ease-out"`, etc.). */
-const CubicBezierToken = z.strictObject({
-    $type: z.literal('cubicBezier'),
-    $value: z.string().min(1),
-    $description: z.string().optional(),
-});
 /** Structured shadow value — DTCG spec composite shape. */
 const ShadowValue = z.strictObject({
     offsetX: z.string().min(1),
@@ -154,30 +109,11 @@ const NumberToken = z.strictObject({
     $description: z.string().optional(),
 });
 /** Line-height token — DTCG allows unit-less number or dimension. */
-const LineHeightToken = z.union([
-    z.strictObject({
-        $type: z.literal('number'),
-        $value: z.number(),
-        $description: z.string().optional(),
-    }),
-    z.strictObject({
-        $type: z.literal('dimension'),
-        $value: z.string().min(1),
-        $description: z.string().optional(),
-    }),
-]);
-/**
- * Permissive token leaf for the newer optional groups
- * (`motion.keyframes`, `zIndex`). DTCG hasn't standardised every
- * `$type` value the curated registry themes carry — for example
- * easing uses `$type: 'cubicBezier'`. Rather than
- * enumerate every spelling, this leaf accepts any `$type` string and
- * any JSON-serializable `$value`. Strict per-leaf shape stays in
- * force for the original token types via the leaves above.
- */
-const PermissiveToken = z.strictObject({
+/** A token whose `$value` is a CSS string under any `$type` spelling
+ *  (keyframes text, border style, …). */
+const StringToken = z.strictObject({
     $type: z.string().min(1),
-    $value: z.unknown(),
+    $value: z.string().min(1),
     $description: z.string().optional(),
 });
 // ─── Groups ──────────────────────────────────────────────────────────
@@ -188,42 +124,69 @@ const PermissiveToken = z.strictObject({
  */
 const ColorPalette = z.record(z.string(), ColorToken);
 /**
- * Color group — two-tier: `{palette}` records for scales (primary /
- * neutral / semantic scales) plus single-token semantic roles
- * (surface / onSurface / outline / …) at the top level.
- *
- * Kept open (`z.record` not `z.strictObject`) so authored themes
- * can add brand-specific palettes (`accent`, `brand-green`, …) and
- * semantic roles without a schema change. `color` itself is
- * required but its internal shape is author-extensible.
- *
- * Each entry can be EITHER a singleton `ColorToken` (e.g. a Material
- * role like `surface`) OR a `ColorPalette` (a scale like `primary`'s
- * 50-900 stops). Tools that emit only singleton colors (no scales)
- * stay parseable.
+ * The colour block: five family anchors (`500` stated; the other stops
+ * derived unless stated) + the six layering roles, all REQUIRED; the
+ * derived roles (`neutral`, outlines, `on*` inks, containers,
+ * `tertiary`, `link`) are optional and win over derivation when stated.
  */
-const ColorGroup = z.record(z.string(), z.union([ColorToken, ColorPalette]));
+const ColorGroup = z.strictObject({
+    primary: ColorPalette,
+    neutral: ColorPalette.optional(),
+    success: ColorPalette,
+    warning: ColorPalette,
+    error: ColorPalette,
+    info: ColorPalette,
+    ground: ColorToken,
+    onGround: ColorToken,
+    container: ColorToken,
+    onContainer: ColorToken,
+    sunken: ColorToken,
+    onSunken: ColorToken,
+    link: ColorToken.optional(),
+    outline: ColorToken.optional(),
+    outlineVariant: ColorToken.optional(),
+    onPrimary: ColorToken.optional(),
+    primaryContainer: ColorToken.optional(),
+    onPrimaryContainer: ColorToken.optional(),
+    onSuccess: ColorToken.optional(),
+    successContainer: ColorToken.optional(),
+    onSuccessContainer: ColorToken.optional(),
+    onWarning: ColorToken.optional(),
+    warningContainer: ColorToken.optional(),
+    onWarningContainer: ColorToken.optional(),
+    onError: ColorToken.optional(),
+    errorContainer: ColorToken.optional(),
+    onErrorContainer: ColorToken.optional(),
+    onInfo: ColorToken.optional(),
+    infoContainer: ColorToken.optional(),
+    onInfoContainer: ColorToken.optional(),
+    tertiary: ColorToken.optional(),
+    onTertiary: ColorToken.optional(),
+    tertiaryContainer: ColorToken.optional(),
+    onTertiaryContainer: ColorToken.optional(),
+});
 const SpacingGroup = z.record(z.string(), DimensionToken);
 /**
- * Font group — `family` / `size` / `weight` / `lineHeight` records.
- * Renamed from `typography` (previously: `typography.fontFamily`,
- * `typography.fontSize`, …) to mirror the internal `DtcgTheme`
- * shape's `font.family` / `font.size` / `font.weight` /
- * `font.lineHeight`.
- *
- * Inside `family`, `sans` is the only required slot — the canonical
- * theme always carries a sans-serif default. `mono` and any other
- * family slot (e.g. `serif`, `display`) are optional. The record
- * stays open so authors can declare additional named families.
+ * Font group — `family` (the `sans` slot required; `mono`, `heading`
+ * and any other named family optional) and `weight`; optional
+ * `letterSpacing` and the ONE `ramp` the type scale is derived from.
  */
+/** Font families: `sans` required; `mono`, `heading` and any other named family optional. */
 const FontFamilyGroup = z.record(z.string(), FontFamilyToken).and(z.object({
     sans: FontFamilyToken,
 }));
 const FontGroup = z.strictObject({
     family: FontFamilyGroup,
-    size: z.record(z.string(), DimensionToken),
     weight: z.record(z.string(), FontWeightToken),
-    lineHeight: z.record(z.string(), LineHeightToken),
+    letterSpacing: z
+        .strictObject({ body: DimensionToken.optional(), heading: DimensionToken.optional() })
+        .optional(),
+    ramp: z.strictObject({ base: DimensionToken, ratio: NumberToken }).optional(),
+});
+/** Declared font faces (ggui#987 §5). */
+const TypographyGroup = z.strictObject({
+    /** The ONE face grammar — `@ggui-ai/protocol`'s `fontFaceDeclarationSchema` (ggui#1093): the document door and the AppTheme wire's `fonts` validate identically. */
+    faces: z.array(fontFaceDeclarationSchema).optional(),
 });
 /**
  * Shape group — `radius` + `shadow`. Moved here from the previous
@@ -233,18 +196,162 @@ const FontGroup = z.strictObject({
 const ShapeGroup = z.strictObject({
     radius: z.record(z.string(), DimensionToken),
     shadow: z.record(z.string(), ShadowToken),
+    border: z.strictObject({ width: DimensionToken.optional(), style: StringToken.optional() }).optional(),
+});
+/**
+ * Motion group — `transition` (required sub-record) + `keyframes`
+ * (optional). Durations and easings are not ladders any more: they ride
+ * each transition's own value.
+ */
+/**
+ * The HOST DESIGN LANGUAGE's document members (ggui#1093 P1b, #1075 Track C (a);
+ * grammar co-signed with rnd 2026-09-15). These are DOCUMENT tokens, never wire
+ * members: they reach the card through `deriveThemeVariables` → the overlay,
+ * which stays the ONE projection (`docs/principles/mcp-apps-compliance.md`).
+ * Every group is OPTIONAL and absent ⇒ the document parses exactly as before
+ * (INVARIANT 1: no declaration, byte-identical output).
+ */
+/**
+ * One type role. `size` is required; `leading` is a RATIO (`NumberToken`) and
+ * never a length — the projection writes `line-height: <ratio>`, which survives
+ * a size change, while a length leading breaks the moment the role's size moves.
+ */
+const TypeScaleRole = z.strictObject({
+    size: DimensionToken,
+    weight: FontWeightToken.optional(),
+    tracking: DimensionToken.optional(),
+    leading: NumberToken.optional(),
+});
+/**
+ * PRECEDENCE, and the ONE sentence that governs every member in this group
+ * (ggui#1093 R1, ruled with rnd 2026-09-16): **a host-design-language member
+ * overrides the base document's corresponding ladder.** A stated `typeScale`
+ * role beats the `font.ramp` stop that would have generated it; a stated
+ * `rhythm.base` beats the `spacing` stops it re-derives. Those two read as
+ * opposite directions (role over scale, scale over rungs) and are not: in
+ * both, the member the HOST measured wins over the ladder ggui supplied.
+ *
+ * The asymmetry that makes the sentence necessary: a `typeScale` role IS a
+ * rung, so it wins its own stop and leaves the others to the ramp — a harvest
+ * that measured only `h1` and `body` must not blank the rest. A `rhythm.base`
+ * is a statement about the SCALE, and every real document already carries
+ * spacing stops (the base theme supplies them), so "stated stop wins" would
+ * make the member inert on every document a harvest can produce.
+ *
+ * Nothing is lost by it: a document needing one bespoke step states no
+ * rhythm, and an app needing one pinned value has `AppTheme.cssVariables`,
+ * which overrides the whole projection at the overlay layer.
+ *
+ * CONTRACTED AHEAD OF THEIR CONSUMERS — read this before assuming a stated
+ * member changes a pixel. A member may be contracted before its consumer
+ * exists; a VARIABLE may not enter the consumed-token manifest before its
+ * consumer exists (a name nothing reads is coverage debt, not a feature).
+ * Today that makes three of these members STATED, STORED and NOT YET
+ * VISIBLE: the role-named type families and `scrim` arrive with their
+ * consumers (ggui#1075 Track C (b), ggui#1083), and `motion` with
+ * **ggui#1106** — the card's motion is build-time constants in the
+ * primitives, so no `--ggui-motion-*` variable exists to project onto yet
+ * (the manifest carries 122 tokens and none of them is motion). A writer
+ * may declare all of them now, which is the point of contracting first;
+ * nobody should read the contract as shipping the behaviour.
+ */
+/** The five type roles; `display` is the poster-scale role a host page leads with. */
+const TypeScaleGroup = z.strictObject({
+    display: TypeScaleRole.optional(),
+    h1: TypeScaleRole.optional(),
+    h2: TypeScaleRole.optional(),
+    body: TypeScaleRole.optional(),
+    label: TypeScaleRole.optional(),
+});
+/**
+ * The spacing base a rhythm re-derives its scale from: a positive length in
+ * `px` (2–16) or `rem` / `em` (0.125–1, the same range at a 16px root). Other
+ * units and `calc()` are refused at the door — a base the reader cannot
+ * multiply is not a base.
+ */
+const RHYTHM_BASE_RE = /^(\d+(?:\.\d+)?)(px|rem|em)$/;
+function isRhythmBase(value) {
+    const m = RHYTHM_BASE_RE.exec(value);
+    if (m === null)
+        return false;
+    const n = Number(m[1]);
+    return m[2] === 'px' ? n >= 2 && n <= 16 : n >= 0.125 && n <= 1;
+}
+const RhythmBaseToken = DimensionToken.refine((t) => isRhythmBase(t.$value), 'rhythm.base must be a length in px (2–16) or rem/em (0.125–1)');
+/** `base` re-derives the spacing scale; `section` and `inset` are named steps. */
+const RhythmGroup = z.strictObject({
+    base: RhythmBaseToken,
+    section: DimensionToken.optional(),
+    inset: DimensionToken.optional(),
 });
+/** The CSS easing keywords a document may name. */
+const CSS_EASING_KEYWORDS = new Set(['linear', 'ease', 'ease-in', 'ease-out', 'ease-in-out', 'step-start', 'step-end']);
+const CUBIC_BEZIER_RE = /^cubic-bezier\(\s*-?\d*\.?\d+\s*(?:,\s*-?\d*\.?\d+\s*){3}\)$/;
+const STEPS_RE = /^steps\(\s*\d+\s*(?:,\s*(?:jump-start|jump-end|jump-none|jump-both|start|end)\s*)?\)$/;
 /**
- * Motion group — `duration` / `easing` / `transition` / `keyframes`.
- * Moved here from the previous top-level `duration` and `transition`
- * fields. `easing` and `keyframes` are optional because external
- * tools (Figma Tokens, Style Dictionary) don't always emit them.
+ * An easing a projection can emit verbatim: a CSS keyword, a well-formed
+ * `cubic-bezier(a,b,c,d)`, or `steps(n[, position])`. Validated HERE so no
+ * reader has to clamp a string it cannot trust.
  */
+function isCssEasing(value) {
+    return CSS_EASING_KEYWORDS.has(value) || CUBIC_BEZIER_RE.test(value) || STEPS_RE.test(value);
+}
+const EasingToken = z.strictObject({
+    $type: z.string().min(1),
+    $value: z.string().min(1).refine(isCssEasing, 'easing must be a CSS keyword, cubic-bezier(a,b,c,d) or steps(n[, position])'),
+    $description: z.string().optional(),
+});
+/**
+ * The per-app motion TEMPO OVERRIDE (ggui#1093 P1c; reverses the layer-1
+ * retirement of the theming spec §2.3, co-signed with rnd 2026-09-16).
+ *
+ * Layer-1 keeps the motion SCALE — the durations and easings the design
+ * system ships, which every card gets by default and no app may redefine
+ * wholesale. What a document may state is a BOUNDED tempo override, for a
+ * card that has to sit inside someone else's site: exactly the standing
+ * `palette` has (per-app forever, without that making colour "not
+ * layer-1"). The retired FREE-MAP ladders stay refused — three duration
+ * steps and three easing roles are admitted, and nothing else.
+ */
+const MotionDurationGroup = z.strictObject({
+    fast: DurationToken.optional(),
+    base: DurationToken.optional(),
+    slow: DurationToken.optional(),
+});
+const MotionEasingGroup = z.strictObject({
+    standard: EasingToken.optional(),
+    emphasized: EasingToken.optional(),
+    exit: EasingToken.optional(),
+});
+/**
+ * The scrim a host page's ground shows through (ggui#1083): `tone` is a word
+ * (`light` / `dark`) or a stated colour token, `opacity` a 0..1 ratio, `blur` a
+ * length. Absent ⇒ the completion derives it from the ground pair, so a
+ * builder who declares nothing still gets a scrim that matches their page.
+ */
+const ScrimGroup = z.strictObject({
+    tone: z.union([z.enum(['light', 'dark']), ColorToken]),
+    opacity: NumberToken.refine((t) => t.$value >= 0 && t.$value <= 1, 'scrim.opacity must be a ratio between 0 and 1'),
+    blur: DimensionToken,
+});
 const MotionGroup = z.strictObject({
-    duration: z.record(z.string(), DurationToken),
-    easing: z.record(z.string(), CubicBezierToken).optional(),
     transition: z.record(z.string(), TransitionToken),
-    keyframes: z.record(z.string(), PermissiveToken).optional(),
+    keyframes: z.record(z.string(), StringToken).optional(),
+    /** Per-app tempo override — three steps, bounded (ggui#1093 P1c). */
+    duration: MotionDurationGroup.optional(),
+    /** Per-app easing override — three roles, each value validated at the door (ggui#1093 P1c). */
+    easing: MotionEasingGroup.optional(),
+    /**
+     * What the composer does under `prefers-reduced-motion: reduce`.
+     *
+     * Two defaults that must never be read as disagreeing (rnd, ggui#1093
+     * P1c): the DOOR does not stamp a value — absent stays absent, so the
+     * document never carries something its author did not write — and the
+     * COMPOSER's default is `respect`: it emits the reduced-motion rule
+     * unless a document explicitly says `ignore`. Absence therefore means
+     * "respect" downstream, without the wire inventing it.
+     */
+    reduce: z.enum(['respect', 'ignore']).optional(),
 });
 const AccessibilityGroup = z.strictObject({
     focusRing: z
@@ -276,8 +383,9 @@ const ZIndexGroup = z.record(z.string(), NumberToken);
  */
 const MetadataGroup = z.strictObject({
     font: z.string().min(1).optional(),
-    fontUrl: z.string().min(1).optional(),
     philosophy: z.string().min(1).optional(),
+    /** The embedding host draws the card silhouette; the renderer suppresses root-children strokes. */
+    frameless: z.boolean().optional(),
 });
 // ─── Root document ───────────────────────────────────────────────────
 /**
@@ -299,7 +407,7 @@ const MetadataGroup = z.strictObject({
  * allow-listed (DTCG metadata); anything else is a typo. Additive
  * slices add new fields here under `schema: '1'`.
  */
-export const ThemeDocumentV1 = z.strictObject({
+export const ThemeDocumentV2 = z.strictObject({
     /** Optional DTCG spec URL. Not validated — the spec hasn't frozen
      *  a canonical URL and hand-authored themes often omit it. */
     $schema: z.string().min(1).optional(),
@@ -320,11 +428,27 @@ export const ThemeDocumentV1 = z.strictObject({
     spacing: SpacingGroup,
     /** Font tokens — `family` / `size` / `weight` / `lineHeight`. Required. */
     font: FontGroup,
+    /** Declared font faces (ggui#987 §5) — https `src` only; the card installs them. */
+    typography: TypographyGroup.optional(),
     /** Shape tokens — `radius` + `shadow`. Required. */
     shape: ShapeGroup,
-    /** Motion tokens — `duration` + `transition` (required sub-records),
-     *  `easing` + `keyframes` (optional sub-records). Optional. */
+    /** The five type ROLES of the host's design language (ggui#1093 P1b):
+     *  display / h1 / h2 / body / label, each `size` + optional weight,
+     *  tracking and a RATIO leading. Role-based, beside `font.ramp`'s
+     *  size-stop ladder — the projection reads a role when it is stated and
+     *  falls to the ramp when it is not. Optional. */
+    typeScale: TypeScaleGroup.optional(),
+    /** The host's spacing rhythm (ggui#1093 P1b): `base` re-derives the scale,
+     *  `section` / `inset` are named steps. Optional. */
+    rhythm: RhythmGroup.optional(),
+    /** Motion tokens — `transition` (required sub-record), `keyframes`, and
+     *  the bounded per-app TEMPO OVERRIDE (ggui#1093 P1c): `duration`
+     *  (fast/base/slow), `easing` (standard/emphasized/exit) and `reduce`.
+     *  The motion SCALE stays layer-1; the free-map ladders stay refused. */
     motion: MotionGroup.optional(),
+    /** The scrim between the host page's ground and the card (ggui#1093 P1b,
+     *  ggui#1083). Absent ⇒ derived from the ground pair. Optional. */
+    scrim: ScrimGroup.optional(),
     /** Accessibility tokens (focus ring, reduced motion, high contrast).
      *  Optional. */
     accessibility: AccessibilityGroup.optional(),
@@ -336,7 +460,7 @@ export const ThemeDocumentV1 = z.strictObject({
  * Throws a `ZodError` with human-readable issues on invalid input.
  */
 export function parseThemeDocument(raw) {
-    return ThemeDocumentV1.parse(raw);
+    return ThemeDocumentV2.parse(raw);
 }
 /**
  * Safe-parse variant — returns a discriminated `z.safeParse` result.
@@ -344,5 +468,69 @@ export function parseThemeDocument(raw) {
  * list without try/catch.
  */
 export function safeParseThemeDocument(raw) {
-    return ThemeDocumentV1.safeParse(raw);
+    return ThemeDocumentV2.safeParse(raw);
+}
+// ─── Normalisation → the producer's document ─────────────────────────
+function stringToken(token, value) {
+    return { $type: token.$type, $value: value, ...(token.$description !== undefined ? { $description: token.$description } : {}) };
+}
+function mapRecord(record, f) {
+    return Object.fromEntries(Object.entries(record).map(([k, v]) => [k, f(v)]));
+}
+/**
+ * Turn a parsed document into the EXACT {@link DtcgTheme} the one
+ * producer (`deriveThemeVariables`) consumes:
+ *
+ *   - names the document (`$name` ⇒ `'custom'`, `$description` ⇒ `''`);
+ *   - drops the DTCG envelope fields the producer does not read
+ *     (`$schema`, `$version`);
+ *   - flattens the DTCG object forms to the CSS strings the producer
+ *     reads: array font stacks → `'Inter, system-ui'`, numeric weights →
+ *     `'400'`, structured shadows → `'0 1px 2px 0 …'`, structured
+ *     transitions → `'<property ?? all> <duration> <timingFunction>'`;
+ *   - fills the optional groups (`motion`, `accessibility`, `zIndex` and
+ *     their sub-records) from the shipped default, so an external tool's
+ *     colours-and-dimensions export still derives every consumed token.
+ *
+ * The authored roles, anchors and faces pass through verbatim.
+ */
+export function normalizeThemeDocument(doc) {
+    const family = doc.font.family;
+    const fontFamily = (t) => stringToken(t, Array.isArray(t.$value) ? t.$value.join(', ') : t.$value);
+    const accessibility = doc.accessibility;
+    return {
+        $name: doc.$name ?? 'custom',
+        $description: doc.$description ?? '',
+        ...(doc.$metadata !== undefined ? { $metadata: doc.$metadata } : {}),
+        color: doc.color,
+        font: {
+            family: { ...mapRecord(family, fontFamily), sans: fontFamily(family.sans) },
+            weight: mapRecord(doc.font.weight, (t) => stringToken(t, String(t.$value))),
+            ...(doc.font.letterSpacing !== undefined ? { letterSpacing: doc.font.letterSpacing } : {}),
+            ...(doc.font.ramp !== undefined ? { ramp: doc.font.ramp } : {}),
+        },
+        ...(doc.typography !== undefined ? { typography: doc.typography } : {}),
+        spacing: doc.spacing,
+        shape: {
+            radius: doc.shape.radius,
+            shadow: mapRecord(doc.shape.shadow, (t) => stringToken(t, typeof t.$value === 'string'
+                ? t.$value
+                : `${t.$value.offsetX} ${t.$value.offsetY} ${t.$value.blur} ${t.$value.spread} ${t.$value.color}`)),
+            ...(doc.shape.border !== undefined ? { border: doc.shape.border } : {}),
+        },
+        motion: doc.motion === undefined
+            ? lightTheme.motion
+            : {
+                transition: mapRecord(doc.motion.transition, (t) => stringToken(t, typeof t.$value === 'string'
+                    ? t.$value
+                    : `${t.$value.property ?? 'all'} ${t.$value.duration} ${t.$value.timingFunction}`)),
+                keyframes: doc.motion.keyframes ?? lightTheme.motion.keyframes,
+            },
+        accessibility: {
+            focusRing: accessibility?.focusRing ?? lightTheme.accessibility.focusRing,
+            reducedMotion: accessibility?.reducedMotion ?? lightTheme.accessibility.reducedMotion,
+            highContrast: accessibility?.highContrast ?? lightTheme.accessibility.highContrast,
+        },
+        zIndex: doc.zIndex ?? lightTheme.zIndex,
+    };
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ggui-ai/project-config",
-  "version": "0.15.0",
+  "version": "0.17.0",
   "description": "Schema and loader for `ggui.json` — the portable app/agent manifest for the ggui protocol. Vendor-neutral. Consumed by the `ggui` CLI and any host that reconstitutes an agent from the manifest.",
   "keywords": [
     "ggui",
@@ -33,8 +33,8 @@
   "dependencies": {
     "tinyglobby": "^0.2.16",
     "zod": "^4.3.6",
-    "@ggui-ai/design": "0.15.0",
-    "@ggui-ai/protocol": "0.15.0"
+    "@ggui-ai/design": "0.17.0",
+    "@ggui-ai/protocol": "0.17.0"
   },
   "devDependencies": {
     "@types/node": "^24.0.0",