@getvitops/generator 0.8.0 → 1.0.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@getvitops/generator",
-  "version": "0.8.0",
+  "version": "1.0.0",
   "description": "Generate design-system outputs (Bricks, standalone CSS, Tailwind v4) from a design-system.json.",
   "license": "MIT",
   "files": [
@@ -27,10 +27,10 @@
   "dependencies": {
     "lightningcss": "^1.32.0",
     "zod": "^4.1.13",
-    "@getvitops/utils": "0.8.0"
+    "@getvitops/utils": "1.0.0"
   },
   "devDependencies": {
     "vitest": "^4.1.9",
-    "@getvitops/core": "0.8.0"
+    "@getvitops/core": "1.0.0"
   }
 }

package/schema.json

@@ -7,6 +7,21 @@
       "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",
+      "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": false
+    },
     "colors": {
       "type": "object",
       "properties": {
@@ -32,7 +47,7 @@
                     "additionalProperties": {
                       "type": "string"
                     },
-                    "description": "Step → colour overrides (hex or oklch()) that pin specific steps of the generated scale; the remaining steps interpolate around them."
+                    "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": [
@@ -82,9 +97,35 @@
             "type": "string"
           },
           "additionalProperties": {
-            "type": "string"
+            "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
+              }
+            ]
           },
-          "description": "Maps each semantic role (neutral, surface, ui-primary/secondary/accent, brand-primary/secondary, info, success, warning, danger) to the palette hue backing it. The generator derives every role's FUNCTIONAL tokens (`--<role>-{bg,bg-muted,border,border-bold,solid,solid-bold,on-solid,text,text-muted,text-x-muted}`) plus emphasis stops from the hue's scale, and dark mode flips automatically — there is no per-appearance scheme grammar."
+          "description": "Maps semantic role names onto palette hues. Role names are ARBITRARY — add a key and the generator emits that role's token set (`--color-<target>-<role>[-<variant>]` for target bg/text/icon/border), its dark-mode flip and its utility classes.\n\nA value is either a hue name (`\"danger\": \"rust\"`) or `{ \"hue\": …, \"kind\": \"surface\" | \"chromatic\" }`. **The kind decides the shape of the token set.** `chromatic` (the default, and what the bare-string form means) is a signal colour: its backgrounds split into tints (`bg-<role>-x-muted`/`-muted`) and solids (`bg-<role>-solid[-bold|-x-bold]`), with deliberately **no bare `bg-<role>`** — \"how loud?\" is a question the author answers. `surface` is a page/panel colour: it has a bare `bg-<role>` plus the full emphasis range and text scale.\n\nDark mode flips automatically; there is no per-appearance scheme grammar. The solid family and its computed `text-on-<role>` foreground stay mode-stable so a filled button keeps its identity. Six roles are a required core, because the shipped framework CSS references them with no fallback: brand-primary, danger, neutral, surface, ui-primary, warning. Conventional additions are ui-secondary/accent, brand-secondary, info and success."
         },
         "utilities": {
           "type": "array",
@@ -93,13 +134,14 @@
             "enum": [
               "bg",
               "text",
+              "icon",
               "border",
               "outline",
               "fill",
               "stroke"
             ]
           },
-          "description": "Which colour utility-class families to emit (`bg-*`, `text-*`, `border-*`, `outline-*`, `fill-*`, `stroke-*`). Defaults to bg, text, border."
+          "description": "Which colour utility-class families to emit (`bg-*`, `text-*`, `icon-*`, `border-*`, `outline-*`, `fill-*`, `stroke-*`). Defaults to bg, text, icon, border. `icon` is a separate non-text tier (a glyph may run more vivid than text); `outline`/`fill`/`stroke` have no tokens of their own and alias the border and icon tiers."
         }
       },
       "required": [
@@ -107,10 +149,10 @@
         "roles"
       ],
       "additionalProperties": false,
-      "description": "The colour system (the only required section): `palette` hues become generated OKLCH scales; `roles` map semantic roles onto those hues, from which all functional tokens and dark mode derive."
+      "description": "The colour system (the only required section): `palette` hues become generated OKLCH scales; `roles` map semantic roles onto those hues, from which all role tokens and dark mode derive."
     },
     "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(…)`.",
+      "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"
@@ -353,7 +395,7 @@
                 "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)`.",
+                "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"
@@ -420,7 +462,7 @@
           }
         },
         "headings": {
-          "description": "Maps heading elements (h1…h6) to type roles so bare headings pick up role styling.",
+          "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"
@@ -431,7 +473,7 @@
         }
       },
       "additionalProperties": false,
-      "description": "Typography: family aliases, semantic type roles (→ `font-<role>` classes), and the heading-element → role mapping."
+      "description": "Typography: family aliases, semantic type roles (→ `font-<role>` classes), and the bare-element → role mapping."
     },
     "animations": {
       "type": "object",

package/site.schema.json

@@ -806,6 +806,21 @@
             "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",
+            "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": false
+          },
           "colors": {
             "type": "object",
             "properties": {
@@ -831,7 +846,7 @@
                           "additionalProperties": {
                             "type": "string"
                           },
-                          "description": "Step → colour overrides (hex or oklch()) that pin specific steps of the generated scale; the remaining steps interpolate around them."
+                          "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": [
@@ -880,7 +895,33 @@
                   "type": "string"
                 },
                 "additionalProperties": {
-                  "type": "string"
+                  "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": {
@@ -890,6 +931,7 @@
                   "enum": [
                     "bg",
                     "text",
+                    "icon",
                     "border",
                     "outline",
                     "fill",
@@ -901,7 +943,7 @@
             "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(…)`.",
+            "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"
@@ -1144,7 +1186,7 @@
                       "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)`.",
+                      "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"
@@ -1211,7 +1253,7 @@
                 }
               },
               "headings": {
-                "description": "Maps heading elements (h1…h6) to type roles so bare headings pick up role styling.",
+                "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"
@@ -1222,7 +1264,7 @@
               }
             },
             "additionalProperties": false,
-            "description": "Typography: family aliases, semantic type roles (→ `font-<role>` classes), and the heading-element → role mapping."
+            "description": "Typography: family aliases, semantic type roles (→ `font-<role>` classes), and the bare-element → role mapping."
           },
           "animations": {
             "type": "object",
@@ -2238,9 +2280,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 +2303,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 +2419,10 @@
                   "type": "null"
                 }
               ]
+            },
+            "governingLaw": {
+              "description": "Governing-law clause, in prose (e.g. \"the Province of Ontario\"). Defaults from the contact address.",
+              "type": "string"
             }
           },
           "required": [