@getvitops/generator 0.9.0 → 2.0.0

package/site.schema.json

@@ -796,85 +796,157 @@
     },
     "designSystem": {
       "type": "object",
-      "propertyNames": {
-        "type": "string"
-      },
-      "additionalProperties": {
-        "type": "object",
-        "properties": {
-          "$schema": {
-            "description": "URL of the published JSON Schema (stamped by `vitops init`) so editors provide autocomplete + validation.",
+      "properties": {
+        "themes": {
+          "type": "object",
+          "propertyNames": {
             "type": "string"
           },
-          "colors": {
+          "additionalProperties": {
             "type": "object",
             "properties": {
-              "palette": {
+              "$schema": {
+                "description": "URL of the published JSON Schema (stamped by `vitops init`) so editors provide autocomplete + validation.",
+                "type": "string"
+              },
+              "meta": {
+                "description": "Brand identity for agent-facing output. Consumed only by the `design` format (`DESIGN.md`); it emits no CSS and no tokens.",
                 "type": "object",
-                "propertyNames": {
-                  "type": "string"
+                "properties": {
+                  "name": {
+                    "description": "Brand/system name. Used as the `name` field and `<h1>` of the `design` format's `DESIGN.md`. Defaults to \"Design System\".",
+                    "type": "string"
+                  },
+                  "description": {
+                    "description": "One or two sentences on the brand personality and the feeling the UI should evoke — what an agent needs when no token answers the question. Becomes the DESIGN.md `description` field and opens its Overview section; if omitted, a generic description of the system's mechanics is used instead.",
+                    "type": "string"
+                  }
                 },
-                "additionalProperties": {
-                  "anyOf": [
-                    {
-                      "type": "object",
-                      "properties": {
-                        "seed": {
-                          "type": "string",
-                          "description": "Seed colour (hex or oklch()). An 11-step numeric scale (50…950, tinted near-white → tinted near-black) is generated in OKLCH from it; the seed is preserved at its natural step."
-                        },
-                        "anchors": {
-                          "type": "object",
-                          "propertyNames": {
-                            "type": "string"
-                          },
-                          "additionalProperties": {
-                            "type": "string"
-                          },
-                          "description": "Step → colour overrides (hex or oklch()) that pin specific steps of the generated scale; the remaining steps interpolate around them."
-                        }
-                      },
-                      "required": [
-                        "seed"
-                      ],
-                      "additionalProperties": false,
-                      "description": "Seeded hue: the 11-step scale is GENERATED in OKLCH from `seed` (anchors pin specific steps)."
+                "additionalProperties": false
+              },
+              "colors": {
+                "type": "object",
+                "properties": {
+                  "palette": {
+                    "type": "object",
+                    "propertyNames": {
+                      "type": "string"
                     },
-                    {
-                      "type": "object",
-                      "properties": {
-                        "tones": {
-                          "anyOf": [
-                            {
-                              "type": "array",
-                              "items": {
-                                "type": "string"
-                              }
+                    "additionalProperties": {
+                      "anyOf": [
+                        {
+                          "type": "object",
+                          "properties": {
+                            "seed": {
+                              "type": "string",
+                              "description": "Seed colour (hex or oklch()). An 11-step numeric scale (50…950, tinted near-white → tinted near-black) is generated in OKLCH from it; the seed is preserved at its natural step."
                             },
-                            {
+                            "anchors": {
                               "type": "object",
                               "propertyNames": {
                                 "type": "string"
                               },
                               "additionalProperties": {
                                 "type": "string"
-                              }
+                              },
+                              "description": "Step → colour overrides (hex or oklch()) pinned VERBATIM at those steps. Every other step takes its lightness from the shared ladder, with chroma and hue interpolated between the anchors — so an anchor is reproduced exactly and is the only step allowed off the ladder. An explicit anchor overrides the seed at that step; two anchors that resolve to the same step are an error."
                             }
+                          },
+                          "required": [
+                            "seed"
                           ],
-                          "description": "Fixed brand kit: authored tones placed verbatim at their nearest steps plus tinted off-white/off-black endpoints; no interpolation. Either an ordered light → dark array or a step → colour map."
+                          "additionalProperties": false,
+                          "description": "Seeded hue: the 11-step scale is GENERATED in OKLCH from `seed` (anchors pin specific steps)."
+                        },
+                        {
+                          "type": "object",
+                          "properties": {
+                            "tones": {
+                              "anyOf": [
+                                {
+                                  "type": "array",
+                                  "items": {
+                                    "type": "string"
+                                  }
+                                },
+                                {
+                                  "type": "object",
+                                  "propertyNames": {
+                                    "type": "string"
+                                  },
+                                  "additionalProperties": {
+                                    "type": "string"
+                                  }
+                                }
+                              ],
+                              "description": "Fixed brand kit: authored tones placed verbatim at their nearest steps plus tinted off-white/off-black endpoints; no interpolation. Either an ordered light → dark array or a step → colour map."
+                            }
+                          },
+                          "required": [
+                            "tones"
+                          ],
+                          "additionalProperties": false,
+                          "description": "Fixed hue: authored brand tones used verbatim; no generation."
                         }
-                      },
-                      "required": [
-                        "tones"
                       ],
-                      "additionalProperties": false,
-                      "description": "Fixed hue: authored brand tones used verbatim; no generation."
+                      "description": "A palette hue, authored one of two ways: `{ seed, anchors? }` generates an 11-step numeric OKLCH scale (50…950) from the seed, or `{ tones }` supplies a fixed brand kit used verbatim."
                     }
-                  ],
-                  "description": "A palette hue, authored one of two ways: `{ seed, anchors? }` generates an 11-step numeric OKLCH scale (50…950) from the seed, or `{ tones }` supplies a fixed brand kit used verbatim."
-                }
+                  },
+                  "roles": {
+                    "type": "object",
+                    "propertyNames": {
+                      "type": "string"
+                    },
+                    "additionalProperties": {
+                      "anyOf": [
+                        {
+                          "type": "string",
+                          "description": "A palette hue name. Shorthand for `{ hue, kind: \"chromatic\" }`."
+                        },
+                        {
+                          "type": "object",
+                          "properties": {
+                            "hue": {
+                              "type": "string",
+                              "description": "The palette hue this role resolves to."
+                            },
+                            "kind": {
+                              "type": "string",
+                              "enum": [
+                                "surface",
+                                "chromatic"
+                              ],
+                              "description": "`surface` — a page/panel colour: gets a bare `bg-<role>` plus the full emphasis range and text scale. `chromatic` (default) — a signal colour: tints and solids only, no bare `bg-<role>`."
+                            }
+                          },
+                          "required": [
+                            "hue"
+                          ],
+                          "additionalProperties": false
+                        }
+                      ]
+                    }
+                  },
+                  "utilities": {
+                    "type": "array",
+                    "items": {
+                      "type": "string",
+                      "enum": [
+                        "bg",
+                        "text",
+                        "icon",
+                        "border",
+                        "outline",
+                        "fill",
+                        "stroke"
+                      ]
+                    }
+                  }
+                },
+                "additionalProperties": false
               },
-              "roles": {
+              "shadows": {
+                "description": "Named shadows → `--shadow-<name>` tokens and `.drop-shadow-<name>` utilities. Values are shadow parameter lists (offset/blur/colour). Each token feeds two consumers with different grammars — `box-shadow` (pattern geometry, via the `--ds-*` group aliases) and `filter: drop-shadow(…)` (the utilities and the `shadow:` state shortcut) — so values must stay in the intersection: **one layer, no spread radius, no `inset`**. `drop-shadow()` rejects all three, and rejecting them invalidates the whole filter, so the shadow vanishes rather than degrading.",
                 "type": "object",
                 "propertyNames": {
                   "type": "string"
@@ -883,257 +955,170 @@
                   "type": "string"
                 }
               },
-              "utilities": {
-                "type": "array",
-                "items": {
-                  "type": "string",
-                  "enum": [
-                    "bg",
-                    "text",
-                    "border",
-                    "outline",
-                    "fill",
-                    "stroke"
-                  ]
-                }
-              }
-            },
-            "additionalProperties": false
-          },
-          "shadows": {
-            "description": "Named shadows → `--shadow-<name>` tokens and `.drop-shadow-<name>` utilities. Values are shadow parameter lists (offset/blur/colour), applied via `filter: drop-shadow(…)`.",
-            "type": "object",
-            "propertyNames": {
-              "type": "string"
-            },
-            "additionalProperties": {
-              "type": "string"
-            }
-          },
-          "fonts": {
-            "description": "Raw font stacks by name, emitted as `--font-<name>` tokens (referenced by `typography.families`).",
-            "type": "object",
-            "propertyNames": {
-              "type": "string"
-            },
-            "additionalProperties": {
-              "type": "string"
-            }
-          },
-          "typeScale": {
-            "description": "Fluid modular TYPE scale → `--text-<name>` tokens, consumed by typography roles and text-size utilities.",
-            "type": "object",
-            "properties": {
-              "base": {
-                "type": "string",
-                "description": "Anchor size (a CSS length, e.g. \"1rem\") — the value at `baseStep`."
-              },
-              "ratio": {
-                "type": "number",
-                "description": "Modular ratio between adjacent steps at large viewports."
-              },
-              "steps": {
-                "description": "Token count when `names` is absent (steps are then named 1..steps).",
-                "type": "number"
-              },
-              "names": {
-                "description": "Step names, smallest → largest (e.g. [\"xs\",\"sm\",\"md\",…]); each becomes a token suffix.",
-                "type": "array",
-                "items": {
+              "fonts": {
+                "description": "Raw font stacks by name, emitted as `--font-<name>` tokens (referenced by `typography.families`). **Stacks only — vitops does not load webfonts.** A value here is a `font-family` list and nothing more: it emits no `@font-face`, no preload, and no metrics-matched fallback. If a family needs loading, declare it in Astro's `fonts:` config (`astro.config`, or the site config's `fonts` array) and point the token at the family's `cssVariable` — `\"display\": \"var(--font-league-spartan), sans-serif\"`. Installing a `@fontsource*` package and importing its CSS also works but gives up subsetting, preload and `size-adjust`/`ascent-override` fallbacks, so it regresses CLS.",
+                "type": "object",
+                "propertyNames": {
+                  "type": "string"
+                },
+                "additionalProperties": {
                   "type": "string"
                 }
               },
-              "baseStep": {
-                "description": "1-based index of the step whose value is `base`.",
-                "type": "number"
-              },
-              "baseline": {
-                "description": "Named step used as the fluid pivot / GUI scale centre (defaults to `baseStep`).",
-                "type": "string"
-              },
-              "fluid": {
-                "description": "Makes the scale fluid: each step compiles to a clamp() that interpolates from `minRatio` at `minVw` to `ratio` at `maxVw`.",
+              "typeScale": {
+                "description": "Fluid modular TYPE scale → `--text-<name>` tokens, consumed by typography roles and text-size utilities.",
                 "type": "object",
                 "properties": {
-                  "minVw": {
-                    "type": "string",
-                    "description": "Viewport width (CSS length) where fluid scaling bottoms out."
-                  },
-                  "maxVw": {
+                  "base": {
                     "type": "string",
-                    "description": "Viewport width (CSS length) where fluid scaling tops out."
+                    "description": "Anchor size (a CSS length, e.g. \"1rem\") — the value at `baseStep`."
                   },
-                  "minRatio": {
+                  "ratio": {
                     "type": "number",
-                    "description": "Modular ratio at/below `minVw` (usually < `ratio`)."
+                    "description": "Modular ratio between adjacent steps at large viewports."
+                  },
+                  "steps": {
+                    "description": "Token count when `names` is absent (steps are then named 1..steps).",
+                    "type": "number"
+                  },
+                  "names": {
+                    "description": "Step names, smallest → largest (e.g. [\"xs\",\"sm\",\"md\",…]); each becomes a token suffix.",
+                    "type": "array",
+                    "items": {
+                      "type": "string"
+                    }
+                  },
+                  "baseStep": {
+                    "description": "1-based index of the step whose value is `base`.",
+                    "type": "number"
+                  },
+                  "baseline": {
+                    "description": "Named step used as the fluid pivot / GUI scale centre (defaults to `baseStep`).",
+                    "type": "string"
+                  },
+                  "fluid": {
+                    "description": "Makes the scale fluid: each step compiles to a clamp() that interpolates from `minRatio` at `minVw` to `ratio` at `maxVw`.",
+                    "type": "object",
+                    "properties": {
+                      "minVw": {
+                        "type": "string",
+                        "description": "Viewport width (CSS length) where fluid scaling bottoms out."
+                      },
+                      "maxVw": {
+                        "type": "string",
+                        "description": "Viewport width (CSS length) where fluid scaling tops out."
+                      },
+                      "minRatio": {
+                        "type": "number",
+                        "description": "Modular ratio at/below `minVw` (usually < `ratio`)."
+                      }
+                    },
+                    "required": [
+                      "minVw",
+                      "maxVw",
+                      "minRatio"
+                    ],
+                    "additionalProperties": false
                   }
                 },
                 "required": [
-                  "minVw",
-                  "maxVw",
-                  "minRatio"
+                  "base",
+                  "ratio"
                 ],
                 "additionalProperties": false
-              }
-            },
-            "required": [
-              "base",
-              "ratio"
-            ],
-            "additionalProperties": false
-          },
-          "spaceScale": {
-            "description": "Fluid modular SPACE scale → `--space-<name>` tokens, consumed by spacing/gap utilities and vertical rhythm.",
-            "type": "object",
-            "properties": {
-              "base": {
-                "type": "string",
-                "description": "Anchor size (a CSS length, e.g. \"1rem\") — the value at `baseStep`."
-              },
-              "ratio": {
-                "type": "number",
-                "description": "Modular ratio between adjacent steps at large viewports."
               },
-              "steps": {
-                "description": "Token count when `names` is absent (steps are then named 1..steps).",
-                "type": "number"
-              },
-              "names": {
-                "description": "Step names, smallest → largest (e.g. [\"xs\",\"sm\",\"md\",…]); each becomes a token suffix.",
-                "type": "array",
-                "items": {
-                  "type": "string"
-                }
-              },
-              "baseStep": {
-                "description": "1-based index of the step whose value is `base`.",
-                "type": "number"
-              },
-              "baseline": {
-                "description": "Named step used as the fluid pivot / GUI scale centre (defaults to `baseStep`).",
-                "type": "string"
-              },
-              "fluid": {
-                "description": "Makes the scale fluid: each step compiles to a clamp() that interpolates from `minRatio` at `minVw` to `ratio` at `maxVw`.",
+              "spaceScale": {
+                "description": "Fluid modular SPACE scale → `--space-<name>` tokens, consumed by spacing/gap utilities and vertical rhythm.",
                 "type": "object",
                 "properties": {
-                  "minVw": {
-                    "type": "string",
-                    "description": "Viewport width (CSS length) where fluid scaling bottoms out."
-                  },
-                  "maxVw": {
+                  "base": {
                     "type": "string",
-                    "description": "Viewport width (CSS length) where fluid scaling tops out."
+                    "description": "Anchor size (a CSS length, e.g. \"1rem\") — the value at `baseStep`."
                   },
-                  "minRatio": {
+                  "ratio": {
                     "type": "number",
-                    "description": "Modular ratio at/below `minVw` (usually < `ratio`)."
+                    "description": "Modular ratio between adjacent steps at large viewports."
+                  },
+                  "steps": {
+                    "description": "Token count when `names` is absent (steps are then named 1..steps).",
+                    "type": "number"
+                  },
+                  "names": {
+                    "description": "Step names, smallest → largest (e.g. [\"xs\",\"sm\",\"md\",…]); each becomes a token suffix.",
+                    "type": "array",
+                    "items": {
+                      "type": "string"
+                    }
+                  },
+                  "baseStep": {
+                    "description": "1-based index of the step whose value is `base`.",
+                    "type": "number"
+                  },
+                  "baseline": {
+                    "description": "Named step used as the fluid pivot / GUI scale centre (defaults to `baseStep`).",
+                    "type": "string"
+                  },
+                  "fluid": {
+                    "description": "Makes the scale fluid: each step compiles to a clamp() that interpolates from `minRatio` at `minVw` to `ratio` at `maxVw`.",
+                    "type": "object",
+                    "properties": {
+                      "minVw": {
+                        "type": "string",
+                        "description": "Viewport width (CSS length) where fluid scaling bottoms out."
+                      },
+                      "maxVw": {
+                        "type": "string",
+                        "description": "Viewport width (CSS length) where fluid scaling tops out."
+                      },
+                      "minRatio": {
+                        "type": "number",
+                        "description": "Modular ratio at/below `minVw` (usually < `ratio`)."
+                      }
+                    },
+                    "required": [
+                      "minVw",
+                      "maxVw",
+                      "minRatio"
+                    ],
+                    "additionalProperties": false
                   }
                 },
                 "required": [
-                  "minVw",
-                  "maxVw",
-                  "minRatio"
+                  "base",
+                  "ratio"
                 ],
                 "additionalProperties": false
-              }
-            },
-            "required": [
-              "base",
-              "ratio"
-            ],
-            "additionalProperties": false
-          },
-          "patterns": {
-            "type": "object",
-            "properties": {
-              "defaults": {
-                "type": "object",
-                "propertyNames": {
-                  "type": "string"
-                },
-                "additionalProperties": {
-                  "type": "string"
-                },
-                "description": "Cascade-wide fallback tokens, emitted as `--<prop>-default`."
-              },
-              "radii": {
-                "type": "object",
-                "propertyNames": {
-                  "type": "string"
-                },
-                "additionalProperties": {
-                  "type": "string"
-                },
-                "description": "Shape primitives, emitted as `--br-<name>` (referenced by pattern bases)."
               },
-              "groups": {
-                "description": "Group-level tokens, emitted as `--<prop>-<group>`; patterns opt in via their `group` key.",
+              "patterns": {
                 "type": "object",
-                "propertyNames": {
-                  "type": "string"
-                },
-                "additionalProperties": {
-                  "type": "object",
-                  "propertyNames": {
-                    "type": "string"
-                  },
-                  "additionalProperties": {
-                    "type": "string"
-                  },
-                  "description": "A CSS declaration block: property → value. Values stay strings (they can be hex, var(), clamp(), keywords, …); the generator, not the schema, interprets them."
-                }
-              },
-              "z": {
-                "description": "Z-index tiers → `--z-tier-<name>`.",
-                "type": "object",
-                "propertyNames": {
-                  "type": "string"
-                },
-                "additionalProperties": {
-                  "type": "number"
-                }
-              },
-              "items": {
-                "description": "The component patterns to emit, keyed by name.",
-                "type": "object",
-                "propertyNames": {
-                  "type": "string"
-                },
-                "additionalProperties": {
-                  "type": "object",
-                  "properties": {
-                    "group": {
-                      "description": "Token-cascade group this pattern belongs to (e.g. tag / control / panel); base declarations resolve through `--<prop>-<group>` before `--<prop>-default`.",
+                "properties": {
+                  "defaults": {
+                    "type": "object",
+                    "propertyNames": {
                       "type": "string"
                     },
-                    "overrides": {
-                      "type": "object",
-                      "propertyNames": {
-                        "type": "string"
-                      },
-                      "additionalProperties": {
-                        "type": "string"
-                      },
-                      "description": "Per-pattern token overrides, emitted as `--<prop>-<name>-group` values."
-                    },
-                    "element": {
-                      "description": "Style at element level via zero-specificity `:where(<element>)` (instead of, or alongside, a class).",
+                    "additionalProperties": {
                       "type": "string"
                     },
-                    "class": {
-                      "description": "Class name to emit (defaults to the pattern's key when no `element` is set). Combined with `element`, the pattern emits one zero-specificity `:where(<element>, .<class>)` rule so the class works on any tag and any explicit class overrides it.",
+                    "description": "Cascade-wide fallback tokens, emitted as `--<prop>-default`."
+                  },
+                  "radii": {
+                    "type": "object",
+                    "propertyNames": {
                       "type": "string"
                     },
-                    "fill": {
-                      "description": "Whether this pattern is colour-filled (states/roles drive `background-color` + `on-solid` text) or text-coloured (they drive `color`). Defaults to true when `base` declares a background.",
-                      "type": "boolean"
+                    "additionalProperties": {
+                      "type": "string"
                     },
-                    "default_role": {
-                      "description": "Semantic colour role applied to the bare/default variant.",
+                    "description": "Shape primitives, emitted as `--br-<name>` (referenced by pattern bases)."
+                  },
+                  "groups": {
+                    "description": "Group-level tokens, emitted as `--<prop>-<group>`; patterns opt in via their `group` key.",
+                    "type": "object",
+                    "propertyNames": {
                       "type": "string"
                     },
-                    "base": {
+                    "additionalProperties": {
                       "type": "object",
                       "propertyNames": {
                         "type": "string"
@@ -1141,123 +1126,118 @@
                       "additionalProperties": {
                         "type": "string"
                       },
-                      "description": "Base CSS declarations. Geometry properties (padding, border-radius, border, box-shadow, font-size) are wrapped in per-pattern override hooks (`--p-<name>`, `--br-<name>`, `--b-<name>`, `--ds-<name>`, `--fs-<name>`) so consumers can restyle one pattern by setting one variable."
-                    },
-                    "states": {
-                      "description": "Interaction states (hover / active / focus-visible), each a map of shortcuts: `step` (intensify fills/text by n emphasis stops), `scale` (transform scale), `lift` (translateY + shadow), `shadow` (a shadow name → drop-shadow(var(--shadow-<name>)), or true → lift shadow), `ring` (focus ring), or raw `css` declarations. Hover rules are wrapped in `@media (hover: hover)`.",
-                      "type": "object",
-                      "propertyNames": {
-                        "type": "string"
-                      },
-                      "additionalProperties": {
-                        "type": "object",
-                        "propertyNames": {
-                          "type": "string"
-                        },
-                        "additionalProperties": {}
-                      }
-                    },
-                    "roles": {
-                      "description": "Semantic colour role variants to emit as `<pattern>-<role>` classes (fills use the role solid / on-solid tokens).",
-                      "type": "array",
-                      "items": {
-                        "type": "string"
-                      }
+                      "description": "A CSS declaration block: property → value. Values stay strings (they can be hex, var(), clamp(), keywords, …); the generator, not the schema, interprets them."
                     }
                   },
-                  "additionalProperties": false,
-                  "description": "One component pattern (button, link, badge, card, …): base declarations + interaction states + semantic role variants, resolved through the pattern token cascade."
-                }
-              }
-            },
-            "additionalProperties": false,
-            "description": "Component patterns and their token cascade: `defaults` → `groups` → per-pattern `overrides`, plus shape (`radii`) and z-index primitives."
-          },
-          "typography": {
-            "type": "object",
-            "properties": {
-              "families": {
-                "description": "Role-facing family aliases → CSS font values, usually referencing the top-level `fonts` tokens (e.g. \"var(--font-display)\").",
-                "type": "object",
-                "propertyNames": {
-                  "type": "string"
-                },
-                "additionalProperties": {
-                  "type": "string"
-                }
-              },
-              "roles": {
-                "description": "Semantic type roles (display, title, heading, body, quote, caption, eyebrow, code, lead, footnote, tag, …), each emitted as a `font-<role>` class.",
-                "type": "object",
-                "propertyNames": {
-                  "type": "string"
-                },
-                "additionalProperties": {
-                  "type": "object",
-                  "propertyNames": {
-                    "type": "string"
-                  },
-                  "additionalProperties": {
-                    "anyOf": [
-                      {
-                        "type": "string"
-                      },
-                      {
-                        "type": "number"
-                      }
-                    ]
+                  "z": {
+                    "description": "Z-index tiers → `--z-tier-<name>`.",
+                    "type": "object",
+                    "propertyNames": {
+                      "type": "string"
+                    },
+                    "additionalProperties": {
+                      "type": "number"
+                    }
                   },
-                  "description": "An open bag of CSS-ish keys (family / size / weight / line-height / tracking / transform / decoration / text-wrap / …); the generator maps known keys and passes the rest through."
-                }
-              },
-              "headings": {
-                "description": "Maps heading elements (h1…h6) to type roles so bare headings pick up role styling.",
-                "type": "object",
-                "propertyNames": {
-                  "type": "string"
-                },
-                "additionalProperties": {
-                  "type": "string"
-                }
-              }
-            },
-            "additionalProperties": false,
-            "description": "Typography: family aliases, semantic type roles (→ `font-<role>` classes), and the heading-element → role mapping."
-          },
-          "animations": {
-            "type": "object",
-            "properties": {
-              "effects": {
-                "description": "Effect classes to emit (`.fade-in`, `.reveal-left`, …), keyed by class name.",
-                "type": "object",
-                "propertyNames": {
-                  "type": "string"
-                },
-                "additionalProperties": {
-                  "type": "object",
-                  "properties": {
-                    "kf": {
-                      "type": "string",
-                      "description": "Keyframe family driving the effect: composite (transform/opacity), paint, or layout."
+                  "items": {
+                    "description": "The component patterns to emit, keyed by name.",
+                    "type": "object",
+                    "propertyNames": {
+                      "type": "string"
                     },
-                    "css": {
+                    "additionalProperties": {
                       "type": "object",
-                      "propertyNames": {
-                        "type": "string"
-                      },
-                      "additionalProperties": {
-                        "anyOf": [
-                          {
+                      "properties": {
+                        "group": {
+                          "description": "Token-cascade group this pattern belongs to (e.g. tag / control / panel); base declarations resolve through `--<prop>-<group>` before `--<prop>-default`.",
+                          "type": "string"
+                        },
+                        "overrides": {
+                          "type": "object",
+                          "propertyNames": {
+                            "type": "string"
+                          },
+                          "additionalProperties": {
+                            "type": "string"
+                          },
+                          "description": "Per-pattern token overrides, emitted as `--<prop>-<name>-group` values."
+                        },
+                        "element": {
+                          "description": "Style at element level via zero-specificity `:where(<element>)` (instead of, or alongside, a class).",
+                          "type": "string"
+                        },
+                        "class": {
+                          "description": "Class name to emit (defaults to the pattern's key when no `element` is set). Combined with `element`, the pattern emits one zero-specificity `:where(<element>, .<class>)` rule so the class works on any tag and any explicit class overrides it.",
+                          "type": "string"
+                        },
+                        "fill": {
+                          "description": "Whether this pattern is colour-filled (states/roles drive `background-color` + `on-solid` text) or text-coloured (they drive `color`). Defaults to true when `base` declares a background.",
+                          "type": "boolean"
+                        },
+                        "default_role": {
+                          "description": "Semantic colour role applied to the bare/default variant.",
+                          "type": "string"
+                        },
+                        "base": {
+                          "type": "object",
+                          "propertyNames": {
                             "type": "string"
                           },
-                          {
-                            "type": "number"
+                          "additionalProperties": {
+                            "type": "string"
+                          },
+                          "description": "Base CSS declarations. Geometry properties (padding, border-radius, border, box-shadow, font-size) are wrapped in per-pattern override hooks (`--p-<name>`, `--br-<name>`, `--b-<name>`, `--ds-<name>`, `--fs-<name>`) so consumers can restyle one pattern by setting one variable."
+                        },
+                        "states": {
+                          "description": "Interaction states (hover / active / focus-visible), each a map of shortcuts: `step` (intensify the fill or text by n rungs — `bg-<role>-solid` → `-solid-bold`, `text-<role>` → `-bold`), `scale` (transform scale), `lift` (translateY + shadow), `shadow` (a shadow name → drop-shadow(var(--shadow-<name>)), or true → lift shadow), `ring` (focus ring), or raw `css` declarations. Hover rules are wrapped in `@media (hover: hover)`.",
+                          "type": "object",
+                          "propertyNames": {
+                            "type": "string"
+                          },
+                          "additionalProperties": {
+                            "type": "object",
+                            "propertyNames": {
+                              "type": "string"
+                            },
+                            "additionalProperties": {}
                           }
-                        ]
+                        },
+                        "roles": {
+                          "description": "Semantic colour role variants to emit as `<pattern>-<role>` classes (fills use the role solid / on-solid tokens).",
+                          "type": "array",
+                          "items": {
+                            "type": "string"
+                          }
+                        }
                       },
-                      "description": "Extra literal declarations merged into the effect class as-is."
+                      "additionalProperties": false,
+                      "description": "One component pattern (button, link, badge, card, …): base declarations + interaction states + semantic role variants, resolved through the pattern token cascade."
+                    }
+                  }
+                },
+                "additionalProperties": false,
+                "description": "Component patterns and their token cascade: `defaults` → `groups` → per-pattern `overrides`, plus shape (`radii`) and z-index primitives."
+              },
+              "typography": {
+                "type": "object",
+                "properties": {
+                  "families": {
+                    "description": "Role-facing family aliases → CSS font values, usually referencing the top-level `fonts` tokens (e.g. \"var(--font-display)\").",
+                    "type": "object",
+                    "propertyNames": {
+                      "type": "string"
+                    },
+                    "additionalProperties": {
+                      "type": "string"
+                    }
+                  },
+                  "roles": {
+                    "description": "Semantic type roles (display, title, heading, body, quote, caption, eyebrow, code, lead, footnote, tag, …), each emitted as a `font-<role>` class.",
+                    "type": "object",
+                    "propertyNames": {
+                      "type": "string"
                     },
-                    "vars": {
+                    "additionalProperties": {
                       "type": "object",
                       "propertyNames": {
                         "type": "string"
@@ -1272,104 +1252,173 @@
                           }
                         ]
                       },
-                      "description": "Effect endpoint variables (`--<key>: <value>`, e.g. opacity-from, translate-y-to) that override the keyframe defaults."
+                      "description": "A bag of CSS-ish keys, each mapped to a declaration plus a `--<role>-<sfx>` override hook. The recognised set is **closed**: `family`, `size`, `weight`, `style`, `line-height`, `tracking` (→ `letter-spacing`), `text-transform`, `text-decoration`, `text-wrap`, `color`. Note the last four are spelled with their full CSS property names — `transform` and `decoration` are NOT accepted. Anything unrecognised is **ignored**, not passed through, so the generator warns rather than emitting it: a silently-dropped `transform: uppercase` is how title-case navigation reaches production. Note also that `style`, `text-transform`, `text-decoration` and `text-wrap` are emitted on **every** role at their identity value (`normal`/`none`/`none`/`wrap`) whether declared or not, so applying one role class over another fully resets it — which means **omitting `text-wrap` is not \"inherit\"**: it emits `text-wrap: wrap` and cancels the `pretty` the role would otherwise inherit from a `pretty` ancestor such as a `body`-mapped role. Declare it on every role — `balance` for heading-like roles, `pretty` for copy, `wrap` for short single-line labels."
                     }
                   },
-                  "required": [
-                    "kf"
-                  ],
-                  "additionalProperties": false,
-                  "description": "A named animation effect class — a pure value layer (`--_anim` + `--<prop>-from/-to`) over the static keyframe engine."
-                }
+                  "headings": {
+                    "description": "Maps bare elements to type roles so unclassed markup picks up role styling — `{ \"h1\": \"display\", \"h2\": \"heading\" }`. The key is used verbatim as a selector, so it is not limited to h1…h6: **map `\"body\"` to your prose role** to bind base page typography to the role rather than hand-writing it. That binding is what makes the role editable — a stylesheet that re-states `font-family`/`line-height` as literals on `body` shadows `--<role>-ff`/`--<role>-lh`, and the live theme editor then appears to do nothing.",
+                    "type": "object",
+                    "propertyNames": {
+                      "type": "string"
+                    },
+                    "additionalProperties": {
+                      "type": "string"
+                    }
+                  }
+                },
+                "additionalProperties": false,
+                "description": "Typography: family aliases, semantic type roles (→ `font-<role>` classes), and the bare-element → role mapping."
               },
-              "journeys": {
-                "description": "Multi-part journey classes composed from `base` building blocks.",
+              "animations": {
                 "type": "object",
                 "properties": {
-                  "base": {
-                    "description": "Named journey building blocks: part name → var map.",
+                  "effects": {
+                    "description": "Effect classes to emit (`.fade-in`, `.reveal-left`, …), keyed by class name.",
                     "type": "object",
                     "propertyNames": {
                       "type": "string"
                     },
                     "additionalProperties": {
                       "type": "object",
-                      "propertyNames": {
-                        "type": "string"
+                      "properties": {
+                        "kf": {
+                          "type": "string",
+                          "description": "Keyframe family driving the effect: composite (transform/opacity), paint, or layout."
+                        },
+                        "css": {
+                          "type": "object",
+                          "propertyNames": {
+                            "type": "string"
+                          },
+                          "additionalProperties": {
+                            "anyOf": [
+                              {
+                                "type": "string"
+                              },
+                              {
+                                "type": "number"
+                              }
+                            ]
+                          },
+                          "description": "Extra literal declarations merged into the effect class as-is."
+                        },
+                        "vars": {
+                          "type": "object",
+                          "propertyNames": {
+                            "type": "string"
+                          },
+                          "additionalProperties": {
+                            "anyOf": [
+                              {
+                                "type": "string"
+                              },
+                              {
+                                "type": "number"
+                              }
+                            ]
+                          },
+                          "description": "Effect endpoint variables (`--<key>: <value>`, e.g. opacity-from, translate-y-to) that override the keyframe defaults."
+                        }
                       },
-                      "additionalProperties": {
-                        "anyOf": [
-                          {
+                      "required": [
+                        "kf"
+                      ],
+                      "additionalProperties": false,
+                      "description": "A named animation effect class — a pure value layer (`--_anim` + `--<prop>-from/-to`) over the static keyframe engine."
+                    }
+                  },
+                  "journeys": {
+                    "description": "Multi-part journey classes composed from `base` building blocks.",
+                    "type": "object",
+                    "properties": {
+                      "base": {
+                        "description": "Named journey building blocks: part name → var map.",
+                        "type": "object",
+                        "propertyNames": {
+                          "type": "string"
+                        },
+                        "additionalProperties": {
+                          "type": "object",
+                          "propertyNames": {
                             "type": "string"
                           },
-                          {
-                            "type": "number"
+                          "additionalProperties": {
+                            "anyOf": [
+                              {
+                                "type": "string"
+                              },
+                              {
+                                "type": "number"
+                              }
+                            ]
                           }
-                        ]
+                        }
+                      },
+                      "compose": {
+                        "description": "Combinations of base parts, each emitted as a `.<parts>-journey` class.",
+                        "type": "array",
+                        "items": {
+                          "type": "array",
+                          "items": {
+                            "type": "string"
+                          }
+                        }
                       }
-                    }
+                    },
+                    "additionalProperties": false
+                  }
+                },
+                "additionalProperties": false,
+                "description": "Animation effect + journey classes (pure value layers). The animation engine itself — keyframes, drivers, floats, utilities — is static framework CSS, not configured here."
+              },
+              "displayName": {
+                "description": "Human-readable theme name (localisable). The label a theme picker would show — nothing reads it yet, because nothing builds more than one theme (see `themes`).",
+                "anyOf": [
+                  {
+                    "type": "string"
                   },
-                  "compose": {
-                    "description": "Combinations of base parts, each emitted as a `.<parts>-journey` class.",
-                    "type": "array",
-                    "items": {
-                      "type": "array",
-                      "items": {
-                        "type": "string"
-                      }
+                  {
+                    "type": "object",
+                    "propertyNames": {
+                      "type": "string"
+                    },
+                    "additionalProperties": {
+                      "type": "string"
                     }
                   }
-                },
-                "additionalProperties": false
-              }
-            },
-            "additionalProperties": false,
-            "description": "Animation effect + journey classes (pure value layers). The animation engine itself — keyframes, drivers, floats, utilities — is static framework CSS, not configured here."
-          },
-          "displayName": {
-            "description": "Human-readable theme name (localisable).",
-            "anyOf": [
-              {
-                "type": "string"
+                ]
               },
-              {
-                "type": "object",
-                "propertyNames": {
-                  "type": "string"
-                },
-                "additionalProperties": {
-                  "type": "string"
-                }
+              "extends": {
+                "description": "Another `themes` key to inherit from; this entry then only supplies what it overrides.",
+                "type": "string"
               }
-            ]
+            },
+            "additionalProperties": false
           },
-          "extends": {
-            "description": "Another `designSystem` key to inherit from; this entry then only supplies what it overrides.",
-            "type": "string"
-          }
+          "description": "Named themes. `default` is the base; others may `extends` another and supply a partial patch. Light/dark is NOT a theme — the functional tokens flip per appearance within each one, so `default` already has both. Only the default theme is built today; multi-theme output and a picker are not wired yet."
         },
-        "additionalProperties": false
+        "defaultTheme": {
+          "description": "Which `themes` entry to use (convention: \"default\"). Validated against the map; selecting a non-default theme is not wired yet.",
+          "type": "string"
+        },
+        "defaultColorScheme": {
+          "description": "Initial appearance. `\"system\"` follows the OS via `prefers-color-scheme` and is what makes `<color-scheme-toggle>`'s \"System\" position resolve to anything — it removes the theme attribute, so without this the page falls through to light. It also gives a no-JS page the OS appearance. Defaults to `\"light\"`, because switching an existing site to `\"system\"` visibly flips it dark for dark-OS visitors.",
+          "type": "string",
+          "enum": [
+            "light",
+            "dark",
+            "system"
+          ]
+        }
       },
-      "description": "Named-theme map of design systems. `default` is the base; other entries may `extends` another and supply a partial patch. Light/dark is automatic (functional tokens flip per appearance), not a separate theme entry. A bare design system (with `colors`) is shorthand for `{ default: … }`."
-    },
-    "defaultTheme": {
-      "description": "Which `designSystem` entry to use by default (convention: \"default\").",
-      "type": "string"
-    },
-    "defaultColorScheme": {
-      "description": "Initial appearance to render before any user/system preference applies.",
-      "type": "string",
-      "enum": [
-        "light",
-        "dark"
-      ]
-    },
-    "respectSystemPreference": {
-      "description": "Follow the user's OS light/dark preference.",
-      "type": "boolean"
+      "required": [
+        "themes"
+      ],
+      "additionalProperties": false,
+      "description": "The design system: named themes plus the system-wide facts (which theme, which appearance). A bare design system, or a bare theme map, is accepted as shorthand for `{ themes: … }`."
     },
     "fonts": {
-      "description": "Font LOADING (a serialisable projection of the Astro Fonts API: provider, weights, subsets, preload). Font TOKENS live in `designSystem.<theme>.fonts` and reference the same `cssVariable`.",
+      "description": "Font LOADING (a serialisable projection of the Astro Fonts API: provider, weights, subsets, preload). Font TOKENS live in `designSystem.themes.<theme>.fonts` and reference the same `cssVariable`.",
       "type": "array",
       "items": {
         "type": "object",
@@ -2177,7 +2226,7 @@
       "additionalProperties": false
     },
     "analytics": {
-      "description": "Analytics provider IDs (gated per environment via `environments.<env>.analytics`).",
+      "description": "Analytics provider IDs (gated per environment via `environments.<env>.analytics`). Which provider is set is also what the generated privacy policy and cookie notice disclose — see `legal`.",
       "type": "object",
       "properties": {
         "googleAnalyticsId": {
@@ -2188,6 +2237,33 @@
         },
         "googleTagManagerId": {
           "type": "string"
+        },
+        "clarityId": {
+          "description": "Microsoft Clarity project ID.",
+          "type": "string"
+        },
+        "matomo": {
+          "description": "Matomo instance.",
+          "type": "object",
+          "properties": {
+            "url": {
+              "type": "string",
+              "description": "Instance base URL (self-hosted, or `*.matomo.cloud`)."
+            },
+            "siteId": {
+              "type": "string",
+              "description": "Site ID within that instance."
+            },
+            "cookies": {
+              "description": "Default false — Matomo runs cookieless (`disableCookies`), which is what lets the cookie notice state positively that it sets none.",
+              "type": "boolean"
+            }
+          },
+          "required": [
+            "url",
+            "siteId"
+          ],
+          "additionalProperties": false
         }
       },
       "additionalProperties": false
@@ -2238,9 +2314,16 @@
       "additionalProperties": false
     },
     "legal": {
-      "description": "Legal pages + cookie-consent configuration.",
+      "description": "Legal pages: which documents exist, where they live, and the facts the generated prose asserts.",
       "type": "object",
       "properties": {
+        "jurisdiction": {
+          "description": "Which legal template set the generated documents use. Default `ca`.",
+          "type": "string",
+          "enum": [
+            "ca"
+          ]
+        },
         "privacyPolicy": {
           "type": "object",
           "properties": {
@@ -2254,6 +2337,95 @@
             "lastUpdated": {
               "type": "string",
               "pattern": "^\\d{4}-\\d{2}-\\d{2}$"
+            },
+            "privacyOfficer": {
+              "description": "Who privacy requests go to. Falls back to `contact`, then `primaryLocation`.",
+              "anyOf": [
+                {
+                  "type": "string"
+                },
+                {
+                  "type": "object",
+                  "properties": {
+                    "name": {
+                      "type": "string"
+                    },
+                    "email": {
+                      "type": "string",
+                      "format": "email",
+                      "pattern": "^(?!\\.)(?!.*\\.\\.)([A-Za-z0-9_'+\\-\\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$"
+                    },
+                    "phone": {
+                      "type": "string"
+                    },
+                    "address": {
+                      "type": "object",
+                      "properties": {
+                        "streetAddress": {
+                          "type": "string"
+                        },
+                        "addressLocality": {
+                          "type": "string",
+                          "description": "City."
+                        },
+                        "addressRegion": {
+                          "description": "State / province.",
+                          "type": "string"
+                        },
+                        "postalCode": {
+                          "type": "string"
+                        },
+                        "addressCountry": {
+                          "type": "string",
+                          "description": "Country (ISO 3166-1 alpha-2 preferred)."
+                        }
+                      },
+                      "required": [
+                        "streetAddress",
+                        "addressLocality",
+                        "addressCountry"
+                      ],
+                      "additionalProperties": false,
+                      "description": "schema.org `PostalAddress` field names, so JSON-LD generation is lossless."
+                    }
+                  },
+                  "additionalProperties": false
+                }
+              ]
+            },
+            "retention": {
+              "description": "How long personal information is kept, in prose (e.g. \"24 months after last contact\").",
+              "type": "string"
+            },
+            "processors": {
+              "description": "Third parties that receive personal information and cannot be inferred from the rest of the config (payment processors, CRMs, mail senders). Known providers implied by `analytics`, `security` and `deployment` are added automatically — list only the rest.",
+              "type": "array",
+              "items": {
+                "type": "object",
+                "properties": {
+                  "name": {
+                    "type": "string",
+                    "description": "The provider, as a reader would recognise it (e.g. \"Stripe\")."
+                  },
+                  "purpose": {
+                    "type": "string",
+                    "description": "Why they receive it, as a noun phrase that reads after \"for\" (e.g. \"payment processing\")."
+                  },
+                  "country": {
+                    "description": "Where they process it, as it should read in a sentence (e.g. \"the United States\"). Feeds the cross-border-transfer disclosure.",
+                    "type": "string"
+                  },
+                  "privacyUrl": {
+                    "type": "string",
+                    "format": "uri"
+                  }
+                },
+                "required": [
+                  "name",
+                  "purpose"
+                ],
+                "additionalProperties": false
+              }
             }
           },
           "required": [
@@ -2281,6 +2453,10 @@
                   "type": "null"
                 }
               ]
+            },
+            "governingLaw": {
+              "description": "Governing-law clause, in prose (e.g. \"the Province of Ontario\"). Defaults from the contact address.",
+              "type": "string"
             }
           },
           "required": [
@@ -2330,13 +2506,21 @@
       "type": "object",
       "properties": {
         "ui": {
-          "description": "Icon set used for UI chrome (e.g. \"lucide\").",
+          "description": "Icon set used for UI chrome (e.g. \"lucide\", \"ph\").",
           "type": "string"
         },
         "brand": {
           "description": "Icon set used for brand marks.",
           "type": "string"
         },
+        "weight": {
+          "description": "Weight for suffix-weighted sets like Phosphor (\"regular\" | \"bold\" | \"duotone\" | \"fill\" | \"light\" | \"thin\"). Ignored by sets that split weights across collections, e.g. Font Awesome.",
+          "type": "string"
+        },
+        "sprite": {
+          "description": "Emit an SVG sprite (icons.svg) alongside the stylesheet, for consumers that cannot run an icon integration (Bricks/WordPress, EmDash renderers).",
+          "type": "boolean"
+        },
         "semantic": {
           "description": "Named semantic icons to include.",
           "type": "array",
@@ -2391,9 +2575,15 @@
           "items": {
             "type": "string"
           }
+        },
+        "ph": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          }
         }
       },
-      "additionalProperties": false
+      "additionalProperties": {}
     },
     "favicon": {
       "description": "Favicon/PWA asset generation (consumed by `@getvitops/utils` favicon tooling).",