@getvitops/create 0.4.0 → 0.5.0

package/CHANGELOG.md

@@ -1,5 +1,121 @@
 # @getvitops/create
 
+## 0.5.0
+
+### Minor Changes
+
+- **The framework now says out loud which patterns are foundational, and reports it when you
+  reach past them.** From repeated downstream reports: sites were inventing a `.wrap` class and
+  using it everywhere instead of `.centered`, and `.subgrid` — the class for any set of cards —
+  was going essentially unused. Neither failure is visible in a build: every class involved is
+  real, nothing errors, and the page renders.
+
+  **`.subgrid` was missing from the generated class reference entirely.** So was `.cluster`, and
+  so was `.region`. `vitops docs classes` is the doc an agent is told to fetch for "which class
+  do I apply", and the framework's answer for a set of cards was not in it — which is most of why
+  it never got used. All three are now documented, along with `grid-auto`, and the reference opens
+  with a **Foundations** section that states the six substitutions as
+  _temptation → what to write instead_ rather than as a vocabulary list. The same table is now in
+  the shipped agent skill and in the `@getvitops/create` template's `AGENTS.md`, because a pointer
+  to a doc only helps someone who already suspects there is something to look up. (`css`/`bricks`
+  and `tailwind` alike — this is documentation and the `TIERS` manifest, not emitted CSS.)
+
+  **`vitops lint` gained three reuse rules and a markup pass.** The existing `.centered` rule only
+  fired when the hand-written CSS already referenced `--width-measure`, which is precisely the
+  author who was never going to hand-roll a container. It now also catches a page-scale
+  `max-width` (≥ 48rem, or a `ch` reading measure) with auto margins, and a
+  container-shaped class name — `wrap`, `wrapper`, `container`, `inner`, `shell`, … — carrying any
+  width cap at all. Reading the cap out of `min()` / `clamp()` too. New rules report a
+  hand-written `repeat()` grid as `.subgrid` (or `.grid-auto`), and a new **markup** pass reports a
+  repeated card set laid out without either — a loop that renders a card, or three or more cards
+  written out. That last one is the only check that can see this drift at all, since a card list
+  built from utility classes contains no bad class and no hand-written CSS.
+
+  All of these are `suggestion` severity, so they do not fail your build unless you pass
+  `--strict`. They found five real instances in this repo's own docs site.
+
+  **`vitops lint [files...]`** now takes explicit paths instead of scanning `--src`, so it can be
+  wired into a pre-commit hook — `vp`'s `staged` key appends the staged files to whatever it runs,
+  and a command that refused positionals could not be put in the one place the feedback lands at
+  the moment the code is written. Unreadable and non-source paths are skipped rather than fatal. The
+  `@getvitops/create` emdash template wires it up with `--strict` and adds a `lint:design` script.
+
+  **Two answers for "the whole card is a link", because one cannot exist.** Reported downstream:
+  agents dislike the `<li>` wrapper when a card is a link and write `<li><a class="card">` instead.
+  That shape is **wrong in a way that renders fine**, which is why it survives review — 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 `.subgrid` exists for silently does not
+  happen, and the anchor does not fill the cell either. Putting the anchor in the grid's place
+  (`<ul><a></ul>`) is invalid HTML, so there was genuinely no correct shape to reach for.
+
+  There are now two, and they trade against each other because **no CSS-only technique can make a
+  whole card clickable and leave its text selectable** — a transparent overlay necessarily receives
+  the pointer-drag:
+
+  | Want                                     | Use                                         |
+  | ---------------------------------------- | ------------------------------------------- |
+  | zero JS, whole card clickable            | `.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; its `::after` covers the card.
+  **`<wc-cards>` is a new tier-2 element** that adds no overlay and instead tells a click apart from
+  the end of a drag, so text selection survives. Its fallback is the card's own link, fully usable
+  with no JS, and the pointer cursor is applied by the element — so the affordance never appears
+  without the behaviour. `<Cards>` emits it for you. They are alternatives, never layered: with an
+  overlay present the JS has nothing to do, and `vitops lint` reports the combination. (All formats
+  — pattern partials, deliberately not `utilities.css`, which the tailwind format skips on the
+  invariant that everything left in it is a name Tailwind ships itself.)
+
+  ### Breaking
+  - **`<Subgrid />` renders its slot verbatim — author the `<li>` items yourself.**
+
+    ```diff
+      <Subgrid>
+    -   <article class="card">…</article>
+    +   <li class="card subgrid-card">…</li>
+      </Subgrid>
+    ```
+
+    It used to parse the slotted HTML and rebuild each child as an `<li>`, carrying over only
+    `class` and `style`. That existed solely because a `<ul>` may contain nothing else, and it cost
+    more than it bought: the child's tag was discarded, `id`/`data-*`/`aria-*` were silently
+    dropped, and `href` could not survive at all. Nothing is copied now, so nothing is lost. `as`
+    picks the container (`ul` by default, `ol`, `div`), and all other props are forwarded — they
+    were previously discarded, including `role`.
+
+  - **`<Subgrid />` and `<Tree />` now emit `role="list"`,** as does the Bricks `sitenav` element.
+    `list-style: none` stops Safari + VoiceOver announcing a `<ul>` as a list, so every marker-less
+    framework list was silently losing the semantics its `<ul>` was chosen for. If you hand-write
+    `.subgrid`, `.list`, `.facet-list`, `.nav-items`, `.collapse-menu` or `.tree` markup, add
+    `role="list"` yourself — the framework cannot add it to markup it does not render, and each
+    partial now says so at the `list-style` reset.
+  - **`<Cards />` no longer adds `class="card"` to slotted children,** because it no longer parses
+    them. Write the class on the item. It now emits `<wc-cards>` around a `<Subgrid>`, which is what
+    makes the whole card clickable — and like `<Tree />`, **it emits its own element, so do not wrap
+    it in `<wc-cards>` yourself.** It also previously passed a `role="list"` that `<Subgrid>` silently
+    discarded, so that never took effect.
+  - **`.subgrid-card` now sets `position: relative`**, so `stretched-link` inside it needs no extra
+    class. If you were absolutely positioning a descendant of a `.subgrid-card` against an ancestor
+    _outside_ that card, it will now resolve against the card. Move the positioning context
+    explicitly. (`css`/`bricks`/`tailwind` — the pattern partial is inlined into all three.) Not
+    reachable by `vitops lint --fix`: the fix depends on which ancestor you meant, which the
+    linter cannot know.
+
+  ### Fixed
+  - **`packages/generator/src/docs.ts` contained a literal NUL byte** (`CODE_SLOT`, written as the
+    raw character rather than an escape). libmagic classified the file as `data` rather than text, so
+    grep and ripgrep treated the largest doc emitter in the repo as **binary and silently skipped
+    it** — every search for a string in it returned nothing, with no error. It is now written as the `\u0000` escape.
+    Behaviour is identical; the file is searchable.
+  - **`.grid-auto` is documented.** It was a real framework class for auto-fit card grids with no
+    entry in the class reference, so the honest alternative to `subgrid` was as invisible as
+    `subgrid` itself.
+  - **`.raised` replaces the advice to use `.relative` above a `stretched-link` overlay**, which
+    could not work: a positioned element at `z-index: auto` does not rise above an explicit
+    `z-index` regardless of DOM order, so a second link or button in the card stayed underneath and
+    unclickable. `.raised` sets both, against the same `--z-tier-raised` token the overlay now uses
+    instead of a hard-coded `1`.
+
 ## 0.4.0
 
 ### Minor Changes

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@getvitops/create",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "description": "Project templates for the Vitops design system — scaffold wired-up sites with `vp create @getvitops`.",
   "license": "MIT",
   "files": [

package/templates/emdash/AGENTS.md

@@ -20,6 +20,49 @@ styled by the Vitops design system.
 - Prefer framework CSS classes (utilities, patterns, type roles like
   `font-heading`) over bespoke CSS. Run `npx vitops agents` to append the
   full generated class-vocabulary reference to this file.
+- **Layout foundations — these are the answer, not a starting point.** Six
+  substitutions carry the structure of nearly every page:
+  | About to write… | Write instead |
+  | --- | --- |
+  | a `wrap`/`wrapper`/`container`/`inner` class | **`centered`** |
+  | `max-width` + `margin-inline: auto` | **`centered`** |
+  | `padding-block` on a section | **`region`** |
+  | margins between headings/paragraphs/lists | **`rhythm`** |
+  | `display: grid` + `grid-template-columns: repeat(n, …)` | **`subgrid`** |
+  | `repeat(auto-fit, minmax(…))` | **`grid-auto`** |
+  | `display: flex` + `gap` for a row of controls | **`cluster`** |
+
+  `centered` is a grid of _named tracks_, not a max-width box — a child widens
+  itself with `breakout`/`spotlight`/`fullbleed` without the parent knowing, which
+  is the thing a bespoke `.wrap` can never do. **More than one card means
+  `subgrid`**: a plain grid aligns the outer boxes but not the tranches inside
+  them, so headings and CTAs land at different heights across the set. Write
+  `<ul class="subgrid subgrid-cols-3" role="list">` with
+  `<li class="card subgrid-card">` items, or `<Subgrid />` (which renders the slot
+  verbatim — author the `<li>`s yourself; it adds `role="list"` for you, and a
+  hand-written one needs it because a marker-less `<ul>` stops being announced as a
+  list in Safari).
+
+  **When the whole card is a link the card is still the item**, and pick by whether
+  the card's text must stay selectable: `stretched-link` on a link inside it is
+  zero-JS but kills text selection, while `<Cards>` (which wraps the list in
+  `<wc-cards>`) keeps selection and falls back to that same link with no JS. Never
+  both — the overlay wins and the JS never runs. Never `<li><a class="card">`: the
+  `li` is the grid item, so the anchor's tranches never align and it does not fill
+  the cell; it renders fine, which is why it keeps getting written.
+
+  `npm run lint:design` reports all of these, and the pre-commit hook fails on them
+  — the fix is the class, not a justification for the CSS.
+
+- **Prerender by default.** `output: 'server'` is required (the admin, media/API
+  routes, preview and scheduled publishing 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 a `getStaticPaths()`
+  that queries the collection at build time. A route with no `prerender` export
+  is re-rendered for every visitor on every request. The cost is that a
+  prerendered page reflects the database as of the last build, so an admin
+  publish needs a redeploy — leave a route server-rendered only where that is
+  unacceptable (preview, personalised content, must-be-live-in-seconds).
 - The Worker cron trigger in `wrangler.jsonc` drives scheduled publishing —
   don't remove it.
 - Hosting (adapter + EmDash database/storage) comes from `vitopsHosting()`

package/templates/emdash/design-system.json

@@ -1,5 +1,5 @@
 {
-  "$schema": "https://unpkg.com/@getvitops/generator/schema.json",
+  "$schema": "./node_modules/@getvitops/generator/schema.json",
   "colors": {
     "palette": {
       "brand": { "seed": "#2e9b73" },

package/templates/emdash/package.json

@@ -13,6 +13,7 @@
     "init:hosting": "node scripts/init-hosting.mjs",
     "typecheck": "astro check",
     "build:css": "vitops generate -i design-system.json -f tailwind -o src/styles",
+    "lint:design": "vitops lint -i design-system.json -f tailwind --strict",
     "prepare": "vp config"
   },
   "dependencies": {

package/templates/emdash/vite.config.ts

@@ -3,6 +3,12 @@ import { defineConfig } from 'vite-plus';
 export default defineConfig({
   staged: {
     '*': 'vp check --fix',
+    // Design-system drift, checked on the files being committed. `--strict` makes
+    // the reuse hints fail here: a hand-rolled container or a card set without
+    // `subgrid` is the drift this catches, and it is only ever cheap to fix at the
+    // moment it is written. `vitops lint` takes the staged paths as positionals.
+    'src/**/*.{astro,html,ts,tsx,jsx,vue,svelte,css}':
+      'vitops lint -i design-system.json -f tailwind --strict',
   },
   fmt: {
     ignorePatterns: ['dist/**', 'node_modules/**', 'src/styles/**', 'public/vitops/**'],