@getvitops/generator 0.4.0 → 0.6.0

package/package.json

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

package/schema.json

@@ -4,6 +4,7 @@
   "type": "object",
   "properties": {
     "$schema": {
+      "description": "URL of the published JSON Schema (stamped by `vitops init`) so editors provide autocomplete + validation.",
       "type": "string"
     },
     "colors": {
@@ -20,7 +21,8 @@
                 "type": "object",
                 "properties": {
                   "seed": {
-                    "type": "string"
+                    "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",
@@ -29,13 +31,15 @@
                     },
                     "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
+                "additionalProperties": false,
+                "description": "Seeded hue: the 11-step scale is GENERATED in OKLCH from `seed` (anchors pin specific steps)."
               },
               {
                 "type": "object",
@@ -57,16 +61,20 @@
                           "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
+                "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": "Palette hues by name. Each becomes an 11-step numeric OKLCH scale (`--color-<hue>-50…950`)."
         },
         "roles": {
           "type": "object",
@@ -75,7 +83,8 @@
           },
           "additionalProperties": {
             "type": "string"
-          }
+          },
+          "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."
         },
         "utilities": {
           "type": "array",
@@ -89,16 +98,19 @@
               "fill",
               "stroke"
             ]
-          }
+          },
+          "description": "Which colour utility-class families to emit (`bg-*`, `text-*`, `border-*`, `outline-*`, `fill-*`, `stroke-*`). Defaults to bg, text, border."
         }
       },
       "required": [
         "palette",
         "roles"
       ],
-      "additionalProperties": false
+      "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."
     },
     "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"
@@ -108,6 +120,7 @@
       }
     },
     "fonts": {
+      "description": "Raw font stacks by name, emitted as `--font-<name>` tokens (referenced by `typography.families`).",
       "type": "object",
       "propertyNames": {
         "type": "string"
@@ -117,40 +130,51 @@
       }
     },
     "typeScale": {
+      "description": "Fluid modular TYPE scale → `--text-<name>` tokens, consumed by typography roles and text-size utilities.",
       "type": "object",
       "properties": {
         "base": {
-          "type": "string"
+          "type": "string",
+          "description": "Anchor size (a CSS length, e.g. \"1rem\") — the value at `baseStep`."
         },
         "ratio": {
-          "type": "number"
+          "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`.",
           "type": "object",
           "properties": {
             "minVw": {
-              "type": "string"
+              "type": "string",
+              "description": "Viewport width (CSS length) where fluid scaling bottoms out."
             },
             "maxVw": {
-              "type": "string"
+              "type": "string",
+              "description": "Viewport width (CSS length) where fluid scaling tops out."
             },
             "minRatio": {
-              "type": "number"
+              "type": "number",
+              "description": "Modular ratio at/below `minVw` (usually < `ratio`)."
             }
           },
           "required": [
@@ -168,40 +192,51 @@
       "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"
+          "type": "string",
+          "description": "Anchor size (a CSS length, e.g. \"1rem\") — the value at `baseStep`."
         },
         "ratio": {
-          "type": "number"
+          "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`.",
           "type": "object",
           "properties": {
             "minVw": {
-              "type": "string"
+              "type": "string",
+              "description": "Viewport width (CSS length) where fluid scaling bottoms out."
             },
             "maxVw": {
-              "type": "string"
+              "type": "string",
+              "description": "Viewport width (CSS length) where fluid scaling tops out."
             },
             "minRatio": {
-              "type": "number"
+              "type": "number",
+              "description": "Modular ratio at/below `minVw` (usually < `ratio`)."
             }
           },
           "required": [
@@ -228,7 +263,8 @@
           },
           "additionalProperties": {
             "type": "string"
-          }
+          },
+          "description": "Cascade-wide fallback tokens, emitted as `--<prop>-default`."
         },
         "radii": {
           "type": "object",
@@ -237,9 +273,11 @@
           },
           "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.",
           "type": "object",
           "propertyNames": {
             "type": "string"
@@ -251,10 +289,12 @@
             },
             "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"
@@ -264,6 +304,7 @@
           }
         },
         "items": {
+          "description": "The component patterns to emit, keyed by name.",
           "type": "object",
           "propertyNames": {
             "type": "string"
@@ -272,6 +313,7 @@
             "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`.",
                 "type": "string"
               },
               "overrides": {
@@ -281,15 +323,19 @@
                 },
                 "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).",
                 "type": "string"
               },
               "default_role": {
+                "description": "Semantic colour role applied to the bare/default variant.",
                 "type": "string"
               },
               "base": {
@@ -299,9 +345,11 @@
                 },
                 "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"
@@ -315,22 +363,26 @@
                 }
               },
               "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"
                 }
               }
             },
-            "additionalProperties": false
+            "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
+      "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"
@@ -340,6 +392,7 @@
           }
         },
         "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"
@@ -358,10 +411,12 @@
                   "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"
@@ -371,12 +426,14 @@
           }
         }
       },
-      "additionalProperties": false
+      "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"
@@ -385,7 +442,8 @@
             "type": "object",
             "properties": {
               "kf": {
-                "type": "string"
+                "type": "string",
+                "description": "Keyframe family driving the effect: composite (transform/opacity), paint, or layout."
               },
               "css": {
                 "type": "object",
@@ -401,7 +459,8 @@
                       "type": "number"
                     }
                   ]
-                }
+                },
+                "description": "Extra literal declarations merged into the effect class as-is."
               },
               "vars": {
                 "type": "object",
@@ -417,19 +476,23 @@
                       "type": "number"
                     }
                   ]
-                }
+                },
+                "description": "Effect endpoint variables (`--<key>: <value>`, e.g. opacity-from, translate-y-to) that override the keyframe defaults."
               }
             },
             "required": [
               "kf"
             ],
-            "additionalProperties": false
+            "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"
@@ -452,6 +515,7 @@
               }
             },
             "compose": {
+              "description": "Combinations of base parts, each emitted as a `.<parts>-journey` class.",
               "type": "array",
               "items": {
                 "type": "array",
@@ -464,7 +528,8 @@
           "additionalProperties": false
         }
       },
-      "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."
     }
   },
   "required": [