@getvitops/generator 0.6.0 → 0.7.0

package/CHANGELOG.md

@@ -0,0 +1,86 @@
+# @getvitops/generator
+
+## 0.7.0
+
+### Patch Changes
+
+- @getvitops/utils@0.7.0
+
+## 0.6.0
+
+### Minor Changes
+
+- 2cc847d: Package-resident agent skill + `vitops docs`:
+  - `@getvitops/cli` now ships the `vitops-design-system` agent skill inside the package
+    (`skill/SKILL.md`). `vitops agents` no longer emits a generated skill into the repo — it
+    symlinks `.agents/skills/` and `.claude/skills/` entries to the installed package (logical
+    `node_modules/@getvitops/cli/skill` target, surviving version bumps) and writes the
+    AGENTS.md pointer block. Old generated-skill directories are migrated automatically;
+    `--docs-dir` keeps the emit-files layout.
+  - New `vitops docs [topic]` command prints reference docs to stdout, rendered live from the
+    project's `design-system.json` (topics: classes, authoring, formats, color, scales,
+    patterns, elements; `--all` concatenates).
+  - `renderSkill()` removed from `@getvitops/generator` (superseded by the packaged skill).
+
+### Patch Changes
+
+- @getvitops/utils@0.6.0
+
+## 0.5.0
+
+### Minor Changes
+
+- Ship design-system context to downstream agents:
+  - JSON Schema descriptions: every `design-system.json` and site-config field now carries a
+    `description` (authored in the zod schemas via `desc()`), emitted into `schema.json` /
+    `site.schema.json` for editor hovers and agent consumption.
+  - New generated OKF docs: `authoring.md` (field reference walked from the JSON Schema),
+    `formats.md` (tailwind vs css vs bricks, including the TW_CLASH utilities Tailwind
+    provides natively), and `concepts/{color,scales,patterns}.md` (seeded OKLCH colour
+    system, fluid modular scales, pattern token cascade + override hooks).
+  - `vitops agents` now emits a generated `vitops-design-system` agent skill into
+    `.agents/skills/vitops-design-system/` (SKILL.md + the docs bundle as `references/`,
+    with an idempotent `.claude/skills/` symlink) and writes a compact pointer block into
+    `AGENTS.md`. Pass `--docs-dir` for the legacy docs-only layout.
+  - `TW_CLASH` and `BASE_HOOK` are exported from `@getvitops/generator`.
+
+### Patch Changes
+
+- @getvitops/utils@0.5.0
+
+## 0.4.0
+
+### Patch Changes
+
+- Updated dependencies [d7e6491]
+  - @getvitops/utils@0.4.0
+
+## 0.3.0
+
+### Patch Changes
+
+- Updated dependencies
+  - @getvitops/utils@0.3.0
+
+## 0.2.1
+
+### Patch Changes
+
+- d28aae7: Fix Tailwind output: the `.centered > *` default (`grid-column: measure`) was emitted unlayered,
+  which in Tailwind v4 outranks every layer — so track utilities (`.spotlight`/`.breakout`/
+  `.fullbleed`) never overrode it and all `.centered` children fell back to `measure`. Emit the
+  structural rules (and the animation engine + patterns) in `@layer components` so the track/spacing
+  `@utility` classes (utilities layer) win.
+  - @getvitops/utils@0.2.1
+
+## 0.2.0
+
+### Minor Changes
+
+- Redesign the colour system: seeded OKLCH tonal scales plus functional semantic tokens
+  (`bg`/`text`/`solid`/`on-solid`, `muted`/`bold`), with named-alias back-compat. Updates the
+  framework CSS, the schema, and the generated docs to the new token model.
+
+### Patch Changes
+
+- @getvitops/utils@0.2.0

package/README.md

@@ -33,3 +33,9 @@ await generate({
 | `bricks`   | `styles.min.css`, `bricks-colors-*.json`, `bricks-variables.json`, `tokens.json`, JS, `bricks/`, `docs/` |
 
 See the [`design-system.json` schema](./schema.json) for the config shape.
+
+## Changelog
+
+This package's history: [`CHANGELOG.md`](./CHANGELOG.md) (shipped in the npm tarball, so it
+also reads from `node_modules/@getvitops/generator/CHANGELOG.md`). `@getvitops/core`, `generator`,
+`utils`, `cli`, `vite` and `astro` share one version and are released together.

package/assets/css/patterns/code.css

@@ -3,10 +3,10 @@
  * Consumes the generated token cascade (src/css/generated/tokens.css).
  */
 
-/* ── Inline code chip — prose <code> that isn't inside a <pre>. Element-level at
-   zero specificity (like the schema-generated button/link patterns) so bare
+/* ── Inline code — prose <code> that isn't inside a <pre>. Element-level at
+   zero specificity (like the schema-generated btn/link patterns) so bare
    <code> needs no class and any explicit class overrides it. .font-code styles
-   type only; this adds the chip. ── */
+   type only; this adds the boxed treatment. ── */
 :where(:not(pre) > code) {
   font-family: var(--font-mono);
   font-size: 0.85em;

package/assets/css/patterns/list.css

@@ -3,7 +3,7 @@
  * Consumes the generated token cascade (src/css/generated/tokens.css).
  */
 
-/* ── List family — base list, facets, filtered search, virtual, chips ─────── */
+/* ── List family — base list, facets, filtered search, virtual, tag list ──── */
 .list {
   --_p: var(--p-list, var(--p-list-group, var(--p-default)));
   --_b: var(--b-list, var(--b-list-group, var(--b-default)));
@@ -216,11 +216,15 @@
   }
 }
 
-.chip-list {
-  --_p: var(--p-chip-list, var(--p-control, var(--p-default)));
-  --_b: var(--b-chip-list, var(--b-control, var(--b-default)));
-  --_br: var(--br-chip-list, var(--br-control, var(--br-default)));
-  --_fs: var(--fs-chip-list, var(--fs-control, var(--fs-default)));
+/* ── Tag list — a bordered field of dismissable tags plus a free-text input.
+   Items are the generated `.tag` pattern (+ `.tag__remove` from tag.css): a tag is
+   the editable/dismissable label, a badge is the static one — so this needs no
+   parallel item styling of its own. ── */
+.tag-list {
+  --_p: var(--p-tag-list, var(--p-control, var(--p-default)));
+  --_b: var(--b-tag-list, var(--b-control, var(--b-default)));
+  --_br: var(--br-tag-list, var(--br-control, var(--br-default)));
+  --_fs: var(--fs-tag-list, var(--fs-control, var(--fs-default)));
 
   display: flex;
   flex-wrap: wrap;
@@ -232,31 +236,7 @@
   align-items: center;
   font-size: var(--_fs);
 
-  .chip-list__chip {
-    display: inline-flex;
-    align-items: center;
-    gap: 0.25rem;
-    padding: 0.25rem 0.5rem;
-    border-radius: var(--br-chip, var(--br-tag, 0.25rem));
-    font-size: 0.875rem;
-    background: var(--color-surface-muted);
-  }
-
-  .chip-list__chip-remove {
-    padding: 0;
-    background: transparent;
-    border: none;
-    cursor: pointer;
-    opacity: 0.6;
-    line-height: 1;
-    transition: opacity 0.15s ease;
-
-    &:hover {
-      opacity: 1;
-    }
-  }
-
-  .chip-list__input {
+  .tag-list__input {
     flex: 1;
     min-inline-size: 6rem;
     border: none;
@@ -266,7 +246,7 @@
   }
 
   &:focus-within {
-    outline: 2px solid var(--chip-list-focus-color, var(--color-brand-primary-muted));
+    outline: 2px solid var(--tag-list-focus-color, var(--color-brand-primary-muted));
     outline-offset: 2px;
   }
 }

package/dist/index.d.mts

@@ -58,6 +58,7 @@ declare const DesignSystemSchema: z.ZodMiniObject<{
       overrides: z.ZodMiniOptional<z.ZodMiniRecord<z.ZodMiniString<string>, z.ZodMiniString<string>>>;
       element: z.ZodMiniOptional<z.ZodMiniString<string>>;
       class: z.ZodMiniOptional<z.ZodMiniString<string>>;
+      fill: z.ZodMiniOptional<z.ZodMiniBoolean<boolean>>;
       default_role: z.ZodMiniOptional<z.ZodMiniString<string>>;
       base: z.ZodMiniOptional<z.ZodMiniRecord<z.ZodMiniString<string>, z.ZodMiniString<string>>>;
       states: z.ZodMiniOptional<z.ZodMiniRecord<z.ZodMiniString<string>, z.ZodMiniRecord<z.ZodMiniString<string>, z.ZodMiniUnknown>>>;
@@ -147,6 +148,7 @@ declare const jsonSchema: {
         overrides: z.ZodMiniOptional<z.ZodMiniRecord<z.ZodMiniString<string>, z.ZodMiniString<string>>>;
         element: z.ZodMiniOptional<z.ZodMiniString<string>>;
         class: z.ZodMiniOptional<z.ZodMiniString<string>>;
+        fill: z.ZodMiniOptional<z.ZodMiniBoolean<boolean>>;
         default_role: z.ZodMiniOptional<z.ZodMiniString<string>>;
         base: z.ZodMiniOptional<z.ZodMiniRecord<z.ZodMiniString<string>, z.ZodMiniString<string>>>;
         states: z.ZodMiniOptional<z.ZodMiniRecord<z.ZodMiniString<string>, z.ZodMiniRecord<z.ZodMiniString<string>, z.ZodMiniUnknown>>>;
@@ -278,8 +280,9 @@ declare function generateDocs(ds: DesignSystem, assetsDir: string): Record<strin
  */
 /**
  * Pattern base geometry props → per-pattern override-hook shorthand. Each hook
- * wraps the authored value (`padding: var(--p-button, 0.6em 1.2em)`) so a
- * consumer restyles one pattern by setting one variable.
+ * wraps the authored value (`padding: var(--p-btn, 0.4em 0.8em)`) so a
+ * consumer restyles one pattern by setting one variable. The hook is named after
+ * the pattern's key, not its class.
  */
 declare const BASE_HOOK: Record<string, string>;
 /**
@@ -497,6 +500,7 @@ declare const SiteConfigSchema: z.ZodMiniObject<{
         overrides: z.ZodMiniOptional<z.ZodMiniRecord<z.ZodMiniString<string>, z.ZodMiniString<string>>>;
         element: z.ZodMiniOptional<z.ZodMiniString<string>>;
         class: z.ZodMiniOptional<z.ZodMiniString<string>>;
+        fill: z.ZodMiniOptional<z.ZodMiniBoolean<boolean>>;
         default_role: z.ZodMiniOptional<z.ZodMiniString<string>>;
         base: z.ZodMiniOptional<z.ZodMiniRecord<z.ZodMiniString<string>, z.ZodMiniString<string>>>;
         states: z.ZodMiniOptional<z.ZodMiniRecord<z.ZodMiniString<string>, z.ZodMiniRecord<z.ZodMiniString<string>, z.ZodMiniUnknown>>>;
@@ -992,6 +996,7 @@ declare const siteJsonSchema: {
           overrides: z.ZodMiniOptional<z.ZodMiniRecord<z.ZodMiniString<string>, z.ZodMiniString<string>>>;
           element: z.ZodMiniOptional<z.ZodMiniString<string>>;
           class: z.ZodMiniOptional<z.ZodMiniString<string>>;
+          fill: z.ZodMiniOptional<z.ZodMiniBoolean<boolean>>;
           default_role: z.ZodMiniOptional<z.ZodMiniString<string>>;
           base: z.ZodMiniOptional<z.ZodMiniRecord<z.ZodMiniString<string>, z.ZodMiniString<string>>>;
           states: z.ZodMiniOptional<z.ZodMiniRecord<z.ZodMiniString<string>, z.ZodMiniRecord<z.ZodMiniString<string>, z.ZodMiniUnknown>>>;

package/dist/index.d.mts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.mts","names":[],"sources":["../src/schema.ts","../src/generate.ts","../src/docs.ts","../src/shared.ts","../src/site.ts","../src/index.ts"],"mappings":"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"}
+{"version":3,"file":"index.d.mts","names":[],"sources":["../src/schema.ts","../src/generate.ts","../src/docs.ts","../src/shared.ts","../src/site.ts","../src/index.ts"],"mappings":"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"}

package/dist/index.mjs

@@ -62,7 +62,8 @@ const Pattern = desc(z.object({
 	group: desc(z.optional(z.string()), "Token-cascade group this pattern belongs to (e.g. tag / control / panel); base declarations resolve through `--<prop>-<group>` before `--<prop>-default`."),
 	overrides: z.optional(desc(CssDecls, "Per-pattern token overrides, emitted as `--<prop>-<name>-group` values.")),
 	element: desc(z.optional(z.string()), "Style at element level via zero-specificity `:where(<element>)` (instead of, or alongside, a class)."),
-	class: desc(z.optional(z.string()), "Class name to emit (defaults to the pattern's key)."),
+	class: desc(z.optional(z.string()), "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."),
+	fill: desc(z.optional(z.boolean()), "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."),
 	default_role: desc(z.optional(z.string()), "Semantic colour role applied to the bare/default variant."),
 	base: z.optional(desc(CssDecls, "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: desc(z.optional(z.record(z.string(), z.record(z.string(), z.unknown()))), "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)`."),
@@ -159,8 +160,9 @@ function validate(input) {
 */
 /**
 * Pattern base geometry props → per-pattern override-hook shorthand. Each hook
-* wraps the authored value (`padding: var(--p-button, 0.6em 1.2em)`) so a
-* consumer restyles one pattern by setting one variable.
+* wraps the authored value (`padding: var(--p-btn, 0.4em 0.8em)`) so a
+* consumer restyles one pattern by setting one variable. The hook is named after
+* the pattern's key, not its class.
 */
 const BASE_HOOK = {
 	padding: "p",
@@ -1012,9 +1014,10 @@ pattern CSS is assembled — token cascade, \`--p-<pattern>\`-style override hoo
 shortcuts — is explained in [/concepts/patterns.md](../concepts/patterns.md).)
 
 - Patterns: ${code(patterns)}.
-- Roles (for coloured patterns like \`badge\`, \`tag\`, \`status\`, \`button\`):
-  ${code(patternRoles)} — e.g. \`badge-success\`, \`button-danger\`. The default (unsuffixed)
-  variant uses the brand-primary role.
+- Roles (for coloured patterns — \`badge\`, \`tag\`, \`status\`, \`cta\`, \`btn\`, …):
+  ${code(patternRoles)} — e.g. \`badge-success\`, \`cta-danger\`. A pattern that also styles an
+  element accepts the bare role class too (\`<button class="danger">\`). The default
+  (unsuffixed) variant uses the pattern's \`default_role\`.
 - Shape primitives: \`--br-<name>\` radii — ${code(radii)}.
 `;
 }
@@ -1343,16 +1346,25 @@ Shared geometry resolves through a variable chain, most-specific first:
 
 ## 2 — Base declarations & override hooks
 
-Each pattern's \`base\` block is emitted on its selector — a class (\`.<class ?? name>\`) or,
-with \`element\`, a **zero-specificity** \`:where(<element>)\` rule so author CSS can always
-override it. Geometry properties are wrapped in a **per-pattern override hook**:
+Each pattern's \`base\` block is emitted on its selector:
+
+- \`class\` only → \`.<class ?? name>\`, at normal class specificity.
+- \`element\` only → a **zero-specificity** \`:where(<element>)\` rule, so author CSS can always
+  override it.
+- **both** → one \`:where(<element>, .<class>)\` rule (e.g. \`:where(button, .btn)\`). The element
+  gets the styling with no class needed, the class carries it to any other tag, and — because the
+  whole thing sits at zero specificity — any explicit class wins, including a louder pattern
+  (\`.cta\`) or a component's own rule (\`.dialog__close\`).
+
+Geometry properties are wrapped in a **per-pattern override hook**:
 
 | base property | hook variable |
 | --- | --- |
 ${hookTable}
 
-e.g. \`padding: var(--p-button, 0.6em 1.2em)\` — a consumer restyles every button by setting
-\`--p-button\` on \`:root\`, without touching the pattern.
+e.g. \`padding: var(--p-btn, 0.4em 0.8em)\` — a consumer restyles every button by setting
+\`--p-btn\` on \`:root\`, without touching the pattern. The hook is named after the pattern's
+**key**, not its class.
 
 ## 3 — States
 
@@ -1374,7 +1386,10 @@ rules are wrapped in \`@media (hover: hover)\` so touch devices never stick.
 ## 4 — Role variants
 
 \`roles\` lists semantic colour variants: class patterns emit \`.<pattern>-<role>\`
-(\`.badge-success\`), element patterns emit \`<element>.<role>\` (\`button.danger\`). Fill
+(\`.badge-success\`). A pattern with an \`element\` emits both the bare role class on the
+element and the \`-<role>\` form (\`:where(button, .btn).danger, .btn-danger\`), so the same
+variant works on a non-element host — both at class specificity, so neither outranks a
+plain class. Fill
 patterns set \`background-color: var(--<role>-solid)\` + \`color: var(--<role>-on-solid)\`;
 text patterns use the role's \`bold\` emphasis stop. \`default_role\` colours the bare,
 unsuffixed pattern. States re-apply per variant with the variant's role.
@@ -1704,6 +1719,7 @@ function build(ds, format, assetsDir) {
 		generated["typography.css"] = typo;
 	}
 	const stateRules = (sel, role, states, colorProp = "background-color") => {
+		const sels = Array.isArray(sel) ? sel : [sel];
 		let out = "";
 		for (const [state, spec] of Object.entries(states)) {
 			const body = [];
@@ -1721,7 +1737,8 @@ function build(ds, format, assetsDir) {
 			}
 			if (spec.css && typeof spec.css === "object") for (const [k, v] of Object.entries(spec.css)) body.push(`${k}: ${v};`);
 			if (!body.length) continue;
-			const rule = `${sel}${state === "hover" ? ":hover" : state === "active" ? ":active" : state === "focus-visible" ? ":focus-visible" : `:${state}`} {\n  ${body.join("\n  ")}\n}\n`;
+			const pseudo = state === "hover" ? ":hover" : state === "active" ? ":active" : state === "focus-visible" ? ":focus-visible" : `:${state}`;
+			const rule = `${sels.map((s) => `${s}${pseudo}`).join(",\n")} {\n  ${body.join("\n  ")}\n}\n`;
 			out += state === "hover" ? `@media (hover: hover) {\n${rule}}\n` : rule;
 		}
 		return out;
@@ -1731,11 +1748,12 @@ function build(ds, format, assetsDir) {
 	for (const [pname, p] of Object.entries(patterns?.items ?? {})) {
 		if (!p.base) continue;
 		const states = p.states ?? {};
-		const isElement = !!p.element;
-		const defaultSel = isElement ? `:where(${p.element})` : `.${p.class ?? pname}`;
+		const cls = p.class ?? (p.element ? void 0 : pname);
+		const elementSel = (extra = "") => `:where(${[p.element, cls && `.${cls}`].filter(Boolean).join(", ")})${extra}`;
+		const defaultSel = p.element ? elementSel() : `.${cls}`;
 		const defaultRole = p.default_role ?? null;
 		const base = { ...p.base };
-		const fills = pname === "button" || pname === "badge" || base["background-color"] != null || base["background"] != null;
+		const fills = p.fill ?? (pname === "button" || pname === "badge" || base["background-color"] != null || base["background"] != null);
 		const colorProp = fills ? "background-color" : "color";
 		pat += `${defaultSel} {\n`;
 		if (Object.keys(states).length > 0) {
@@ -1753,10 +1771,10 @@ function build(ds, format, assetsDir) {
 		pat += decls(wrappedBase) + "\n}\n";
 		pat += stateRules(defaultSel, defaultRole, states, colorProp);
 		for (const role of p.roles ?? []) {
-			const variantSel = isElement ? `${p.element}.${role}` : `.${p.class ?? pname}-${role}`;
+			const variantSels = p.element ? [elementSel(`.${role}`), ...cls ? [`.${cls}-${role}`] : []] : [`.${cls}-${role}`];
 			const variantColorDecl = fills ? `background-color: var(--${role}-solid); color: var(--${role}-on-solid)` : `color: var(--color-${role}-bold)`;
-			pat += `${variantSel} { ${variantColorDecl}; }\n`;
-			pat += stateRules(variantSel, role, states, colorProp);
+			pat += `${variantSels.join(",\n")} { ${variantColorDecl}; }\n`;
+			pat += stateRules(variantSels, role, states, colorProp);
 		}
 		pat += "\n";
 	}
@@ -1992,7 +2010,7 @@ function build(ds, format, assetsDir) {
 				reverseIndex
 			}, null, 2);
 		})(),
-		tailwind: emitTailwind({
+		tailwind: format !== "tailwind" ? "" : emitTailwind({
 			ds,
 			expandedPalette,
 			scaleRoles,
@@ -3087,21 +3105,73 @@ function defaultConfig() {
 				top: 1e3
 			},
 			items: {
-				button: {
+				btn: {
 					group: "control",
 					element: "button",
+					class: "btn",
+					fill: false,
+					overrides: {
+						b: "1px solid transparent",
+						fs: "inherit"
+					},
+					base: {
+						display: "inline-flex",
+						"align-items": "center",
+						"justify-content": "center",
+						gap: "0.4em",
+						padding: "var(--p-btn-group)",
+						"border-radius": "var(--br-btn-group)",
+						border: "var(--b-btn-group)",
+						"box-shadow": "var(--ds-btn-group)",
+						background: "transparent",
+						color: "inherit",
+						"font-family": "inherit",
+						"font-size": "var(--fs-btn-group)",
+						"font-weight": "inherit",
+						"text-decoration": "none",
+						cursor: "pointer"
+					},
+					states: {
+						hover: {
+							step: 1,
+							css: { "background-color": "var(--color-surface-muted)" }
+						},
+						"focus-visible": { ring: true }
+					},
+					roles: []
+				},
+				cta: {
+					group: "control",
+					class: "cta",
+					fill: true,
 					default_role: "brand-primary",
+					overrides: {
+						p: "0.75em 1.5em",
+						b: "none",
+						ds: "var(--shadow-sm)",
+						fs: "inherit"
+					},
 					base: {
-						padding: "0.6em 1.2em",
-						"border-radius": "var(--br-control, 0.25rem)",
-						border: "none",
+						display: "inline-flex",
+						"align-items": "center",
+						"justify-content": "center",
+						gap: "0.5em",
+						padding: "var(--p-cta-group)",
+						"border-radius": "var(--br-cta-group)",
+						border: "var(--b-cta-group)",
+						"font-family": "inherit",
+						"font-size": "var(--fs-cta-group)",
 						"font-weight": "600",
-						color: "#fff",
+						"text-decoration": "none",
 						cursor: "pointer",
-						"box-shadow": "var(--shadow-sm)"
+						color: "var(--brand-primary-on-solid)",
+						"box-shadow": "var(--ds-cta-group)"
 					},
 					states: {
-						hover: { step: 1 },
+						hover: {
+							step: 1,
+							lift: "1px"
+						},
 						active: { scale: .97 },
 						"focus-visible": { ring: true }
 					},