@getvitops/generator 0.9.0 → 2.0.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@getvitops/generator",
-  "version": "0.9.0",
+  "version": "2.0.0",
   "description": "Generate design-system outputs (Bricks, standalone CSS, Tailwind v4) from a design-system.json.",
   "license": "MIT",
   "files": [
@@ -25,12 +25,14 @@
     "access": "public"
   },
   "dependencies": {
+    "@iconify/utils": "^2.3.0",
     "lightningcss": "^1.32.0",
     "zod": "^4.1.13",
-    "@getvitops/utils": "0.9.0"
+    "@getvitops/utils": "2.0.0"
   },
   "devDependencies": {
+    "@iconify/types": "^2.0.0",
     "vitest": "^4.1.9",
-    "@getvitops/core": "0.9.0"
+    "@getvitops/core": "2.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": [
@@ -74,7 +89,7 @@
             ],
             "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": "Palette hues by name. Each becomes an 11-step numeric OKLCH scale (`--color-<hue>-50…950`)."
+          "description": "Palette hues by name. Each becomes an 11-step numeric OKLCH scale (`--color-<hue>-50…950`). Every ramp shares one fixed lightness ladder, so a step means the same lightness in every hue; only chroma and hue vary. Beyond the outermost authored colour the chroma decays towards a small endpoint value (0.008 light / 0.015 dark) so the near-white and near-black ends keep a whisper of the hue — but that is a **ceiling**, not a target, so a low-chroma seed stays low and **a chroma-0 seed gives a true neutral** rather than a tinted one. The ladder is also enforced: if pinned colours leave a ramp non-monotonic (some step darker than the one below it), the build fails rather than shipping a scale whose hover states run backwards."
         },
         "roles": {
           "type": "object",
@@ -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 semantic role names onto palette hues. Role names are ARBITRARY — add a key and the generator emits that role's full FUNCTIONAL token set (`--<role>-{bg,bg-muted,border,border-bold,solid,solid-bold,on-solid,text,text-muted,text-x-muted}`), its emphasis stops, its dark-mode flip and its utility classes. Dark mode flips automatically; there is no per-appearance scheme grammar. 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."
+          "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"
@@ -120,7 +162,7 @@
       }
     },
     "fonts": {
-      "description": "Raw font stacks by name, emitted as `--font-<name>` tokens (referenced by `typography.families`).",
+      "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"
@@ -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"
@@ -416,11 +458,11 @@
                 }
               ]
             },
-            "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."
+            "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."
           }
         },
         "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",