@getvitops/cli 4.0.0 → 5.0.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@getvitops/cli",
-  "version": "4.0.0",
+  "version": "5.0.0",
   "description": "CLI for the Vitops design-system generator: generate, init, and validate a design-system.json.",
   "license": "MIT",
   "bin": {
@@ -22,8 +22,8 @@
     "access": "public"
   },
   "dependencies": {
-    "@getvitops/utils": "4.0.0",
-    "@getvitops/generator": "4.0.0"
+    "@getvitops/generator": "5.0.0",
+    "@getvitops/utils": "5.0.0"
   },
   "devDependencies": {
     "vitest": "^4.1.9"

package/skill/SKILL.md

@@ -22,6 +22,83 @@ colour roles, fluid type/space scales, component patterns, animation effects).
 **Core rule:** prefer the framework's utility + component classes over hand-written CSS or
 ad-hoc values — they encode the tokens, respond to dark mode, and update with the system.
 
+## Layout foundations — apply these before fetching anything
+
+Six classes carry the structure of nearly every page. They are stated here rather than
+left to `vitops docs classes` because the failure mode is not disagreement, it is **not
+knowing there was a decision to make** — writing a container by hand looks like ordinary
+CSS competence, so nothing prompts you to go look. Every row below has been found in real
+downstream sites.
+
+| About to write…                                         | Write this instead                              |
+| ------------------------------------------------------- | ----------------------------------------------- |
+| a `wrap` / `wrapper` / `container` / `inner` class      | **`centered`** — never invent a container class |
+| `max-width` + `margin-inline: auto`                     | **`centered`**                                  |
+| `padding-block` on a section to separate it             | **`region`**                                    |
+| margins between headings, paragraphs, lists             | **`rhythm`** on the container                   |
+| `display: grid` + `grid-template-columns: repeat(n, …)` | **`subgrid`**                                   |
+| `repeat(auto-fit, minmax(…))`                           | **`grid-auto`** (or `subgrid`, below)           |
+| `display: flex` + `gap` for a row of buttons/badges     | **`cluster`**                                   |
+
+**`centered` is not a max-width box, which is why hand-rolling it never quite works.** It is
+a grid of _named tracks_, so a child widens itself (`breakout`, `spotlight`, `fullbleed`)
+without the parent knowing. A bespoke `.wrap` renders identically until the first full-bleed
+image, and then the only way out is more hand-written CSS. There is no case where inventing a
+container class is correct.
+
+**More than one card means `subgrid`.** This is the most under-used class in the framework,
+and the reason it gets skipped is that a plain `grid` _looks_ right — it aligns the outer
+boxes. It cannot align the tranches **inside** them, so across three cards the headings sit
+at three heights, the bodies start at three points, and the CTAs float wherever the copy
+ended. `subgrid` re-declares the parent's row tracks on each item so head / body / footer
+share row lines regardless of content length. Write
+`<ul class="subgrid subgrid-cols-3" role="list">` with `<li class="card subgrid-card">` items —
+a set of cards is a list — and set `--subgrid-row-span` (or `subgrid-rows-<n>`) to the number of
+row bands each card holds. In Astro use `<Subgrid />`, which renders the slot verbatim: **author
+the `<li>` items yourself.**
+
+**`role="list"` is not optional on a hand-written one.** `subgrid` is markerless on `ul`/`ol`,
+and Safari + VoiceOver stop announcing a marker-less `<ul>` as a list — so the marker reset
+silently costs the semantics the `<ul>` was chosen for. `<Subgrid />` adds it for you.
+
+**When the whole card is a link, the card is still the grid item** — and there are two ways to
+do it, both keeping the accessible name on real text rather than on a whole card of it:
+
+| Want                                 | Use                                        |
+| ------------------------------------ | ------------------------------------------ |
+| no JS at all                         | `stretched-link` — **text not selectable** |
+| selectable text and a clickable card | `<Cards>` / `<wc-cards>` — needs JS        |
+
+- `stretched-link` goes on a link **inside** the card (usually the heading); its `::after`
+  covers it. `subgrid-card` already carries the required `position: relative`; on a bare `card`
+  add `relative`. Anything else interactive in the card needs **`raised`** — `relative` alone
+  does not work, because a positioned element at `z-index: auto` cannot rise above an explicit
+  one. The cost is inherent to the technique: the overlay takes the pointer-drag, so the card's
+  text can no longer be selected.
+- `<Cards>` wraps the list in `<wc-cards>`, which adds no overlay and instead distinguishes a
+  click from the end of a drag. Text stays selectable; with no JS the card's own link still
+  works, and the pointer cursor appears only once the element upgrades. It emits its own
+  `<wc-cards>` — do not add your own wrapper.
+- **Never layer the two.** The overlay wins, so you lose selection _and_ the JS never runs.
+  `vitops lint` reports the combination.
+
+`<li><a class="card">` is the wrong shape and **it renders fine**, which is why it keeps being
+written: the `<li>` is the grid item, so the anchor is an ordinary block inside it and the
+tranches within the anchor never reach the parent's shared row lines — the alignment is
+silently absent, and the anchor does not fill the cell either. Putting the anchor in the
+grid's place (`<ul><a></ul>`) is invalid HTML. `vitops lint` reports this shape.
+
+The one honest alternative is **`grid-auto`** — an auto-fit track (`--grid-min`, `--grid-gap`)
+for items with **no internal tranches to align**: a gallery, a logo wall, a row of icons. Never
+hand-write `repeat(auto-fit, minmax(…))`; that is `grid-auto`. The moment an item has an
+eyebrow and a heading and a footer, `subgrid` is the one that lines them up.
+
+**`vitops lint` reports all six of these**, in CSS, in `<style>` blocks and in markup — a
+hand-rolled container, a repeated-item grid, and a loop that renders cards outside a
+`subgrid`. They report as `suggestion`, so they do not fail the build unless `--strict`.
+Run it before considering a page done; if it names one of these, the fix is the class, not a
+justification for the CSS.
+
 ## Getting the current reference docs
 
 Run **`vitops docs <topic>`** — it prints the reference as markdown to stdout, generated
@@ -56,7 +133,17 @@ never stale and always names the project's actual tokens. (If `vitops` isn't on
   emits no CSS, so it composes: `--format css,design`. The live reference above is
   richer; DESIGN.md is for handing the identity to a tool that doesn't have this skill.
 - `vitops init` / `vitops validate` — scaffold / check a config. `validate` routes on the
-  file's shape, so it checks a site config as a site config.
+  file's shape, so it checks a site config as a site config. It also resolves every
+  `var(--…)` the config authors against the tokens it emits, so a reference to a token
+  that does not exist is a build failure rather than a declaration that silently does
+  nothing.
+- `vitops lint [--src <dir>] [--fix]` — **run this after a major bump.** It finds
+  framework classes and design-system tokens in your source that resolve to nothing, and
+  it is the migration tool for anything the changelog says was renamed. `--fix` rewrites
+  pre-1.0 colour-grammar token references in one pass (several of those renames rotate, so
+  applying them one at a time compounds them); everything else it reports needs a decision
+  and is left alone.
+- Every subcommand takes `-h` / `--help`.
 
 **The config may be a `design-system.json` or the site config that embeds one.** Every
 `--input` (and the Vite plugin / Astro integration equivalent) accepts either; a site
@@ -66,10 +153,15 @@ there — do not create a second file for the tooling's sake.
 
 ## Which tier provides a pattern
 
-A pattern (tree, carousel, dialog, card, …) may be provided by up to four tiers, and they
-**compose** rather than compete: CSS framework classes, a `<wc-*>` web component, an Astro
-component, a Bricks element. **Run `vitops docs components`** for the full table — which
-tiers each pattern has, and the exact call to write.
+A pattern (tree, carousel, dialog, card, …) may be provided by up to **three tiers**, and they
+**compose** rather than compete: (1) CSS framework classes, (2) a `<wc-*>` web component,
+(3) a platform wrapper that generates the markup — an Astro component or a Bricks element.
+**Run `vitops docs components`** for the full table — which tiers each pattern has, and the
+exact call to write.
+
+**Astro and Bricks are the same tier, not tiers 3 and 4.** Both are HTML generators built on
+the classes and elements of tiers 1 and 2 — siblings chosen by which platform you are on. No
+project uses both, and neither outranks the other.
 
 Three things to know before you write markup:
 
@@ -83,6 +175,30 @@ Three things to know before you write markup:
   HTML is the no-JS fallback and must be semantic and usable on its own. If you find yourself
   wanting a component that renders from nothing, that pattern is in the wrong tier.
 
+## Astro rendering mode
+
+Nothing vitops emits needs a server — the CSS, favicons and web-component bundles are
+build-time artifacts, and the components progressively enhance markup that is already
+complete in the HTML. So the default is static, and the rule differs by project kind:
+
+- **A plain Astro site:** keep `output: 'static'` and add `export const prerender = false`
+  only on the individual routes that genuinely need per-request work (a form `POST` handler,
+  an auth-gated page, per-visitor content). Don't switch the whole site to `output: 'server'`
+  for a couple of dynamic routes.
+- **An EmDash site:** `output: 'server'` is required (the admin, media/API routes, preview
+  and scheduled publishing all need a server), so prerendering is opt-in per route. Put
+  `export const prerender = true` on every page that doesn't need per-request data, and give
+  dynamic routes (`[slug].astro`, `[...slug].astro`) a `getStaticPaths()` that queries the
+  collection at build time. A route with no `prerender` export is re-rendered on every
+  request.
+
+  A prerendered page reflects the database as of the last build, so publishing from the admin
+  needs a redeploy to appear. Leave a route server-rendered only where that is unacceptable —
+  the preview route, anything personalised, anything that must go live within seconds.
+
+Note `@astrojs/sitemap` lists prerendered routes only, so an unmarked route on a server site
+is also missing from the sitemap. (EmDash serves its own sitemap from the database.)
+
 ## Fonts: vitops names them, it does not load them
 
 `design-system.json`'s `fonts` block holds **stacks only** — each entry emits a
@@ -123,7 +239,12 @@ where no provider covers the family.
   collect, the countries it names come from the providers in use. So the fix for a wrong
   policy is a corrected config, never hand-editing the output — the next build overwrites
   it. Declare processors the config cannot imply (payment, CRM, mail) under
-  `legal.privacyPolicy.processors`.
+  `legal.privacyPolicy.processors`. On each one, **where it stores data and whose law reaches
+  it are separate facts**: `storage: [{ country, scope? }]` is residency, `operatorCountry` is
+  the jurisdiction that can compel access, and `country` is shorthand for both — so a Canadian
+  region run by a US company is `storage: [{ country: "Canada" }]` with
+  `operatorCountry: "the United States"`, not one string. Combining `country` with either is
+  rejected.
   Generated from config, not legal advice — always tell the user to have it reviewed
   before publishing.
 - `vitops search notify` — tell search engines a deploy happened, from a **site config**'s