@viglet/viglet-design-system 2026.3.4 → 2026.3.8

package/dist/vite/boot-loader.d.ts

@@ -65,10 +65,12 @@ export interface VigletBootLoaderOptions {
  * build/dev time, so the loader visuals stay identical across the ecosystem and
  * there is a single place to evolve the design.
  *
- * Four of the six consumers take it: Turing, Shio, Dumont and the Cloud Home.
+ * Four of the seven consumers take it: Turing, Shio, Dumont and the Cloud Home.
  * The Cloud Console and Schools are Next applications and have no Vite build to
  * plug into — they render their own first paint, which is what a server-rendered
- * page does instead of a boot loader.
+ * page does instead of a boot loader. The Roadkeep GUI has a Vite build and
+ * still does not take it: it ships as a desktop application, so its bundle is on
+ * disk and nothing is waiting on a fetch to paint.
  *
  * What the plugin injects:
  *

package/dist/vite/boot-loader.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"boot-loader.d.ts","sourceRoot":"","sources":["../../src/vite/boot-loader.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAA4B,MAAM,EAAE,MAAM,MAAM,CAAC;AAE7D;;;;;;;;;;;;;;;GAeG;AACH,MAAM,WAAW,uBAAuB;IACtC,oEAAoE;IACpE,KAAK,EAAE,MAAM,CAAC;IACd,mFAAmF;IACnF,QAAQ,EAAE,MAAM,CAAC;IACjB;;;;;;;OAOG;IACH,KAAK,EAAE,MAAM,CAAC;IACd,0FAA0F;IAC1F,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB;;;;;;;OAOG;IACH,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,sFAAsF;IACtF,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB;;;;;;OAMG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB;;;;;;;OAOG;IACH,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,uBAAuB,GAAG,MAAM,CAsEzE"}
+{"version":3,"file":"boot-loader.d.ts","sourceRoot":"","sources":["../../src/vite/boot-loader.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAA4B,MAAM,EAAE,MAAM,MAAM,CAAC;AAE7D;;;;;;;;;;;;;;;GAeG;AACH,MAAM,WAAW,uBAAuB;IACtC,oEAAoE;IACpE,KAAK,EAAE,MAAM,CAAC;IACd,mFAAmF;IACnF,QAAQ,EAAE,MAAM,CAAC;IACjB;;;;;;;OAOG;IACH,KAAK,EAAE,MAAM,CAAC;IACd,0FAA0F;IAC1F,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB;;;;;;;OAOG;IACH,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,sFAAsF;IACtF,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB;;;;;;OAMG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB;;;;;;;OAOG;IACH,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,uBAAuB,GAAG,MAAM,CAsEzE"}

package/docs/BENTO-AUTHORING.md

@@ -0,0 +1,225 @@
+# Authoring a bento page
+
+The rules that keep every bento screen looking like the same product. They held
+across a hundred-odd pages in one console because one team read one file; this
+is that file, addressed to anyone importing
+`@viglet/viglet-design-system/bento`.
+
+The first mistake is a page that looks bento inside a console that does not.
+Adopt the shell before the pages.
+
+## 1. The shell, and the page's regions
+
+The shell is these regions, and every one of them is owned once — by the shell, by a page,
+or by the product passing a prop. Almost all of the divergence between two products built
+from this layer is an argument about that ownership rather than about a component.
+[docs/reference/page-anatomy.dc.html](reference/page-anatomy.dc.html) draws it.
+
+**The nav is the rail** — fixed, one width, desktop only, with its gutter reserved by
+`bento-rail-gutter` on whatever wraps the routed page (§7).
+
+**The header carries a set, in this order:** the mark and wordmark; a back control where
+the route has a parent; the palette trigger, with the platform's own keyboard hint. On the
+trailing edge: the locale where a second one ships, the ground, and the signed-in user.
+`BentoBackToTop` sits at the corner.
+
+Two things the header is not. It is not a second always-visible nav — the rail is the nav
+and the palette is the mobile one, and a second eats the width the content needs. And it is
+not a home for one surface's controls: a switcher or a pending count belongs to the surface
+that owns it, not to every page that renders beneath it.
+
+**The shell owns the reading column.** `main` sets the max width, the gutters and the
+vertical rhythm once, so every page begins and ends on the same line; a page sets none of
+the three. A narrower column for a single-question form is a variant the shell offers by
+name, not a class each page repeats. The moment pages set their own they disagree, and the
+defect exists only *between* screens — which is why nobody reviewing one of them sees it.
+
+**A page may own an aside**, inside that column and scrolling with it: filters, a contents
+list, a conversation. That is not the console era's sidebar, which collapses, remembers its
+width and pushes content — the reason that era needs a provider and this one does not.
+
+**The footer is the one region this chrome has not settled.** `AppFooter` is exported — a
+hairline, then the product name, its version and a few links — and it is written `mt-auto`,
+so it expects a shell that is a flex column with the main growing. No bento shell mounts
+one. Either the shell carries a footer for every page or the chrome has none; what must not
+happen is one page growing its own.
+
+**The signed-in user is two routes**, and `BentoUserMenu` has a default for neither (§3).
+Anything past them — a tenant, a review count — belongs to the surface that owns it.
+
+## 2. Structure — thin config, not bespoke pages
+
+There are three page shapes. Almost every screen is one of them plus data.
+
+**A detail screen** is `BentoEntityShell` wrapping a form. The shell owns the
+identity hero, the save-bar morph and the delete flow; the form is a render prop
+receiving `{ staged, onStateChange }` and groups its fields in
+`BentoFormSection`s. Wire the query hooks in the page and put no shell mechanics
+there.
+
+**A list screen** is one `BentoListPage` call with a `renderTile`. Use
+`BentoEntityTile` for the common icon-chip + status-pill + title + meta shape;
+hand-roll a tile only when the entity genuinely needs a different layout.
+
+**A form screen with its own hero** is `BentoFormHero` as the first child inside
+the `<form>` it submits. It renders both halves of the morph itself.
+
+**A frosted box with arbitrary content** — a stats strip, a toolbar, a listing,
+a message — is `BentoPanel`. It is the one container in this layer with **no
+heading**, which is the point rather than an omission: those surfaces sit under a
+hero that already names the page, and a heading on them is noise that also puts a
+section in the document outline the page does not have. Two class slots,
+`className` on the frosted container and `contentClassName` on the inner wrapper,
+and no padding of its own — a table wants `p-0` and a toolbar wants `py-2`.
+Never hand-roll `bento-glass rounded-2xl border`: the moment two call sites pick
+different radii the product is inconsistent for a reason no diff shows.
+
+Two rules that outrank convenience:
+
+- **Identity lives in the hero, never in the form.** Title, description, icon
+  and enabled state are the shell's; a form field for any of them is a second
+  place to edit the same thing.
+- **The save bar is always the morph.** Controls start in the hero and a fixed
+  bar fades in as the hero scrolls away, so nothing is duplicated on screen and
+  the bar appears exactly when the title leaves. Never a hand-rolled
+  `<div className="sticky …">`, and never a permanently visible bar.
+  - `BentoEntityShell` gives you this for free.
+  - Every own-hero form uses `BentoFormHero`. Do not compose a fade-out control
+    group and a `BentoScrollSaveBar` yourself: they are two halves that drift.
+  - A page that saves **imperatively** passes its own buttons through
+    `BentoFormHero`'s `actions`, which replaces the default pair in *both*
+    copies and keeps the morph.
+  - Keep the **destructive** action in the hero's `trailing` only. A controlled
+    dialog rendered twice opens two modals at once, and an action inside the
+    fade-out group vanishes as the reader scrolls.
+
+## 3. What the package will not hold
+
+The layer is chrome; the map of your product is yours. Four things arrive as
+props, and the package has no default for any of them:
+
+| You supply | To |
+|---|---|
+| The nav array, already filtered by privilege or licence | `BentoNavRail`, `BentoCommandPalette` |
+| Routes for account, sign-out and any tenancy surfaces | `BentoUserMenu` |
+| A resolved layout and callbacks to persist it | `BentoListPage` |
+| A keyword suggester, if you want one | `IconPickerDialog` |
+
+`BentoNavItem` is the render contract, deliberately narrower than what you will
+keep: carry `privilege`, licence flags and anything else on your own type, and
+pass the filtered result.
+
+An entry appears when its route does. That is how you say a reader may see
+something — the package cannot read your feature model, and should not try.
+
+## 4. Colour — a tone is a token
+
+No component in the layer names a colour. A tone is
+`--vg-bento-tone-<name>-from` / `-to` in the preset, and the chip reads them, so
+you re-key the palette by redefining variables rather than forking a component.
+The status intents (`on`, `warn`, `error`, `danger`) work the same way.
+
+Accents — a focus border, the rail's active marker, a hover ring — take your
+`--primary`. A shared component marking "you are here" in a colour of its own is
+the clearest way to make one product look wrong.
+
+**Claim `--primary`, or four surfaces stay neutral.** The rail's active marker is
+not the only thing reading it: `.bento-tile:hover` takes its glow from
+`--primary`, `.bento-editing` and `.bento-new-tile` take their borders, and the
+default `Button` variant is `bg-primary text-primary-foreground`. The preset's
+value is a neutral rather than a brand, so keying only the accent leaves all four
+near-black on light and near-white on dark — which is what "you are here" looks
+like in a product that thinks it has re-keyed.
+
+Claim it at `:root`, through the inputs, the way the accent is claimed:
+
+```css
+:root {
+  --vg-primary-base: …;                 /* the mark, on light */
+  --vg-primary-base-dark: …;            /* and on dark */
+  --vg-primary-foreground-base: …;      /* what the solid fill carries */
+  --vg-primary-foreground-base-dark: …;
+}
+```
+
+**Setting `--vg-primary` itself is the mistake the inputs exist to prevent.** Your
+stylesheet imports this package and then declares its own `:root`, so it lands
+after the preset's dark block at the same specificity and in no layer. One value
+set there wins on *both* grounds, and the dark ground silently gets the light
+value. The inputs are read per ground, so you never write a dark block.
+
+The solid fill carries text, so that pair holds 4.5:1 on both grounds (§6). An
+accent stop at full chroma usually does not, so this value is often a deeper step
+than the one the chip is drawn with.
+
+If you need a one-off tint, set `--bento-tone-from` / `--bento-tone-to` on a
+subtree instead of touching the tokens.
+
+## 5. i18n
+
+- Reuse the keys you already have. Do not mint a parallel namespace for a
+  surface that already has one: the same entity rendered in two chromes is the
+  same entity.
+- Always pass a default in the **object** form: `t("key", { defaultValue: "…" })`.
+  The string form is ambiguous and test mocks generally do not honour it.
+- Add every new key to every locale you ship.
+
+## 6. Accessibility
+
+This is a gate, not advice — the catalogue's stories run under axe on every
+push, and a violation fails the build.
+
+- **Icon-only controls** get an `aria-label`. Decorative glyphs get
+  `aria-hidden` and convey their meaning through an adjacent `sr-only` span:
+  screen readers do not reliably announce `aria-label` on a bare `<svg>`, and
+  Testing Library's `getByLabelText` will not match it either.
+- **Keyboard**: inline edit is reachable and committable by keyboard, the
+  palette is arrow-key and Enter navigable, and active rows carry
+  `aria-current="page"` (rail) or `aria-selected` (palette).
+- **ARIA values are string literals** — `aria-expanded="true"`,
+  `aria-selected={active ? "true" : "false"}`. A bare attribute or a
+  `{boolean}` expression is a lint failure.
+- **Headings increase by one.** The hero is `h1`, so a section under it is `h2`
+  — which is what `BentoFormSection` renders by default. A repeated label, like
+  the sticky bar's title, is not a heading at all.
+- **Contrast holds at 4.5:1**, including text on a tinted surface. Tinted pills
+  need the darker text token in light mode.
+- **Reduced motion**: every animation in `bento.css` is turned off under
+  `@media (prefers-reduced-motion: reduce)`, and a test asserts that every
+  animating selector is named in that guard. A new keyframe that is not is a
+  failing build, not a review comment.
+
+## 7. Responsive
+
+- The grid is `grid-cols-2 md:grid-cols-4 lg:grid-cols-6` with `col-span-2`
+  tiles and `row-span-2` for a featured one. **Keep spans in multiples of two**
+  so tiles reflow cleanly at every breakpoint — this is what keeps two consoles'
+  grids aligned.
+- The nav rail is desktop-only. Reserve its gutter with `bento-rail-gutter` on
+  whatever wraps the routed page. On mobile, navigation is the header's command
+  trigger and the global shortcut; do not add a second always-visible nav that
+  eats mobile width.
+- There is **no sidebar provider**, and no context between the shell's pieces.
+  The console era needs one because its sidebar collapses, remembers and pushes
+  content; the rail is fixed, one width, and hidden below `md`. That is about the
+  shell — a page's own aside is §1, and it needs no provider either.
+
+## 8. Tests
+
+- Every shared component here carries vitest and Testing Library coverage, so a
+  regression surfaces once rather than in each console.
+- Router-dependent components render inside a `MemoryRouter`.
+- Assert on the readable `defaultValue` strings rather than on i18n keys, so a
+  test reads like the screen does.
+- jsdom implements neither `matchMedia`, `ResizeObserver` nor `scrollIntoView`.
+  This package's own setup polyfills all three; a consumer testing these
+  components will need the same.
+
+## What this does not cover
+
+Which components are the shared layer and which stay in a product is
+[docs/BENTO-BOUNDARY.md](BENTO-BOUNDARY.md).
+
+Every rule above, drawn rather than stated, is [docs/reference/](reference/) — eight
+artboards, one per decision. Look there when a sentence here is clear and you still cannot
+picture the page it describes.

package/docs/BENTO-BOUNDARY.md

@@ -0,0 +1,114 @@
+# The bento boundary
+
+Which of Turing's `components/bento` exports become a layer of this package, and
+which stay in the product. Decided once, before any file moves, because the
+alternative is deciding it twenty-seven times under time pressure and shipping a
+package the second product has to import around.
+
+## The rule
+
+A component is **shared** when a second console would render the same thing.
+A component is **product** when what makes it useful is one product's data, one
+product's offer, or one product's brand.
+
+Two consequences worth stating, because they are where the rule gets bent:
+
+- **Generic mechanism plus product data is shared, and the data is a prop.** The
+  nav rail is not Turing's because it renders Turing's routes; it is shared, and
+  the routes are an argument. This is the package's existing non-goal — no
+  product data here — applied to chrome.
+- **Generic mechanism plus product content is product**, when the mechanism on
+  its own is thin enough that this package already offers it. A stepped dialog is
+  `Dialog` and `Stepper`, both already exported.
+
+## Inventory
+
+Counted from the barrel rather than from the file listing, because several files
+export more than one component: **28 components, 4 hooks and 15 other bindings**
+(tone maps, layout maths, the nav arrays and their helpers).
+
+The roadmap line that opened this work said twenty-three components. That number
+was taken per file, and misses `BentoTileGrid`, `BentoEntityTile` and
+`BentoBackLink`, each of which lives inside a file named after a sibling. The
+split below is 23 shared and 5 product — the twenty-three is a coincidence of
+arithmetic, not the same twenty-three.
+
+### Shared — the layer (23 components, 1 hook)
+
+| Export | Coupling to lift before it moves |
+|---|---|
+| `BentoTile` | — |
+| `BentoCountTile` | — |
+| `BentoSection` | — |
+| `BentoHero`, `BentoBackLink` | — |
+| `BentoEmptyState` | — |
+| `BentoFormSection` | — |
+| `BentoSaveBar` | — |
+| `BentoScrollSaveBar` | — |
+| `BentoFormHero` | — |
+| `useBentoScrollFade` | — |
+| `BentoStatusMarker` | — |
+| `BentoHeroIconPicker` | — |
+| `BentoInlineEdit` | — |
+| `BentoActionsMenu` | — |
+| `BentoBackToTop` | — |
+| `BentoEntityShell` | — |
+| `BentoTileGrid` | — |
+| `BentoEntityTile` | — |
+| `BentoListPage` | Persists per-surface layout through `@/api/queries/bento-layout.queries`. The mosaic is generic; where the layout is stored is the product's. Lift to props: a resolved layout in, a save callback out. |
+| `BentoNavRail` | Imports `ROUTES`. Takes the nav array as a prop. |
+| `BentoUserMenu` | Imports `ROUTES` and `useFeatures`. Routes and feature flags become props. |
+| `BentoCommandPalette` | Reads the nav config. Takes the same array the rail does — this is what VDS17 separates. |
+| `BentoShortcutsDialog` | — |
+
+### Product — stays in Turing (5 components, 1 hook, the nav data)
+
+| Export | Why |
+|---|---|
+| `BentoActivationCard` | Turing's commercial offer rendered as a card. |
+| `BentoQuotaBanner`, `useQuotaRefusal` | Quota is the shape of the licence, not of the chrome. |
+| `BentoNoLlmState` | An empty state whose whole content is one product's capability. |
+| `BentoVigletActivationDialog` | Activation flow — the offer again, as a modal. |
+| `BentoFirstRunTour`, `BENTO_TOUR_SEEN_KEY`, `hasSeenBentoTour` | Decided below. |
+| `BENTO_NAV_ITEMS`, `BENTO_NAV_SECTIONS`, `bentoNavTarget`, `bentoSectionByAreaRoute`, `bentoSectionAreaRoute`, `useVisibleBentoNav`, `useVisibleBentoSections` (`bento-nav.config.ts`) | Routes, privileges and entity ids, and the two hooks that filter them by privilege. This is the product data the package must never hold. The *schema* of an entry moves with the rail and the palette; the array does not. The span constants in the same file do not belong to it — see below. |
+
+The first four are the ones the roadmap names as commercial, and they are the
+reason this document exists: moving them as chrome would put one product's
+business model into every product's console.
+
+### Non-component modules
+
+| Module | Verdict |
+|---|---|
+| `bento-tones.ts` (`BENTO_TONE_GRADIENTS`, `BentoTone`) | Shared, but re-keyed as CSS custom properties rather than moved as Tailwind class strings — a shared component that names its own colours makes one of two products look wrong. |
+| `bento-layout.ts` — `BENTO_EMPHASIS_SPAN`, `BENTO_EMPHASIS_NEXT`, `resolveBentoLayout`, `toBentoLayoutEntries` | Shared. Pure functions and maps over a layout response; no product data in them. |
+| `BENTO_SPAN_FEATURED`, `BENTO_SPAN_WIDE`, `BENTO_SPAN_SQUARE` | Shared, and currently in the wrong file — they are grid spans, defined in `bento-nav.config.ts` because the nav array is what sizes tiles with them. Moving the layer means splitting them out to sit beside `bento-layout.ts`; the array that uses them stays behind. |
+| `bento-scroll-fade.ts` | Shared — already listed above as `useBentoScrollFade`. |
+| `bento-nav.config.ts` | Product, as above. |
+| `bento.styles.css` | Shared. The frosted surface and the hover-lift are what make a page read as bento. |
+
+## The first-run tour
+
+**Product.** It was the one genuinely open question, and the argument runs both
+ways: the overlay, the step index and the seen-flag are generic, while the four
+steps are Turing's.
+
+It lands on product because of what is left after the content is removed. The
+mechanism is a `Dialog` holding a step index and a `localStorage` flag — perhaps
+sixty lines, over primitives this package already exports. Against that, every
+distinctive thing in the file is Turing's: the `TurLogo` it renders, the four
+steps, and a first step whose entire subject is turning the product's AI on.
+Extracting a tour engine to serve one product's onboarding is generality bought
+before there is a second buyer. If a second console wants a tour, that is the
+moment the shape of a shared one is actually known.
+
+The mechanism is cheap to rebuild and the content is not portable, which is the
+test this rule uses everywhere else.
+
+## What this does not decide
+
+- **How** a component moves. That is VDS11 and the lines after it.
+- Whether a moved component keeps its props. It does — a move whose diff also
+  changes behaviour cannot be reviewed against the pages that depend on it.
+- Where the authoring contract lives. Turing's `CONVENTIONS.md` is addressed to
+  Turing; VDS20 rewrites it product-neutral and brings it here.

package/docs/reference/README.md

@@ -0,0 +1,46 @@
+# The page reference
+
+Nine artboards, one per decision that makes two products built from this package stop
+looking like one. They are the composition half of the catalogue: a story proves a component
+in isolation, and these prove the arrangement.
+
+Read them beside [BENTO-AUTHORING.md](../BENTO-AUTHORING.md), which states the same rules in
+prose. Where the two disagree, the contract is right and an artboard is stale.
+
+## What is here
+
+| Page       | Artboard                | The decision                                                              |
+| ---------- | ----------------------- | ------------------------------------------------------------------------- |
+| The shell  | `page-anatomy.dc.html`  | every region of a page and who owns it, the signed-in user included       |
+| The shell  | `shell.dc.html`         | what the header carries, in what order, and what it is not                |
+| The shell  | `reading-column.dc.html`| the shell sets the measure once, or every page repeats one and they differ |
+| The shell  | `primary.dc.html`       | the four surfaces `--primary` reaches, unclaimed beside claimed           |
+| The shapes | `list.dc.html`          | a list screen, and the discriminator between tiles and rows               |
+| The shapes | `detail.dc.html`        | a detail screen, and the save-bar morph at both ends of the scroll        |
+| The shapes | `form-hero.dc.html`     | a form with no entity behind it yet                                       |
+| The shapes | `panel.dc.html`         | the frosted box with no heading, and why it has none                      |
+| The shapes | `grounds.dc.html`       | the same components on both grounds, with the ratios                      |
+
+`canvas.json` places them and names the two pages.
+
+## Two rules about the content
+
+**No product data.** Subjects are role labels — "Entity name", "Eyebrow", "Meta". A
+reference carrying somebody's routes and entity names is a screenshot of their console, and
+the package's non-goals forbid it for the same reason they forbid a nav array.
+
+**The values are the resolved tokens**, not an impression of them. Colour, type, radius,
+the rail's width and the header's height come from `src/styles/preset.css`, so an artboard
+is checkable against the preset. The accent shown is the one this package ships, because a
+product's own is a re-key and `primary.dc.html` is where that is drawn.
+
+## Editing them
+
+Each `.dc.html` is one artboard: a standalone file whose root is a fixed-size element
+matching the `w`/`h` this directory's `canvas.json` declares for it. Keep the two in step —
+a root larger than its frame is clipped, not scaled.
+
+These files are also vendored into consuming repositories, where they are refreshed from
+here on every install. So an artboard is corrected in this directory and nowhere else: a
+consumer that edits its copy loses the edit on the next run, the same way a forked component
+loses it on the next upgrade.

package/docs/reference/canvas.json

@@ -0,0 +1,108 @@
+{
+  "pages": [
+    { "id": "vds-shell", "name": "The shell" },
+    { "id": "vds-shapes", "name": "The shapes" }
+  ],
+  "artboards": [
+    {
+      "file": "page-anatomy.dc.html",
+      "x": 0,
+      "y": 0,
+      "w": 1400,
+      "h": 980,
+      "title": "The page's regions",
+      "page": "vds-shell"
+    },
+    {
+      "file": "shell.dc.html",
+      "x": 1520,
+      "y": 0,
+      "w": 1280,
+      "h": 760,
+      "title": "The shell",
+      "page": "vds-shell"
+    },
+    {
+      "file": "reading-column.dc.html",
+      "x": 2920,
+      "y": 0,
+      "w": 1280,
+      "h": 720,
+      "title": "Who owns the reading column",
+      "page": "vds-shell"
+    },
+    {
+      "file": "primary.dc.html",
+      "x": 4320,
+      "y": 0,
+      "w": 1080,
+      "h": 640,
+      "title": "What --primary reaches",
+      "page": "vds-shell"
+    },
+    {
+      "file": "list.dc.html",
+      "x": 0,
+      "y": 0,
+      "w": 1280,
+      "h": 720,
+      "title": "A list screen",
+      "page": "vds-shapes"
+    },
+    {
+      "file": "detail.dc.html",
+      "x": 1400,
+      "y": 0,
+      "w": 1280,
+      "h": 760,
+      "title": "A detail screen",
+      "page": "vds-shapes"
+    },
+    {
+      "file": "form-hero.dc.html",
+      "x": 2800,
+      "y": 0,
+      "w": 1080,
+      "h": 680,
+      "title": "A form with its own hero",
+      "page": "vds-shapes"
+    },
+    {
+      "file": "panel.dc.html",
+      "x": 0,
+      "y": 900,
+      "w": 1080,
+      "h": 680,
+      "title": "The panel",
+      "page": "vds-shapes"
+    },
+    {
+      "file": "grounds.dc.html",
+      "x": 1200,
+      "y": 900,
+      "w": 1180,
+      "h": 700,
+      "title": "Both grounds",
+      "page": "vds-shapes"
+    }
+  ],
+  "annotations": [
+    {
+      "id": "vds-why-shell",
+      "page": "vds-shell",
+      "x": 0,
+      "y": -190,
+      "w": 700,
+      "text": "Three decisions live on this page, and none of them is a component defect -- which is why no component change closes them.\nThe contract says adopt the shell before the pages. These artboards say what the shell is: what the header carries and in what order, who owns the reading column, and which surfaces --primary reaches.\nThe content is role-labelled on purpose. Routes and entity names belong to a product, never to this package."
+    },
+    {
+      "id": "vds-why-shapes",
+      "page": "vds-shapes",
+      "x": 0,
+      "y": -190,
+      "w": 700,
+      "text": "Almost every screen is one of three shapes plus data: a detail is BentoEntityShell wrapping a form, a list is one BentoListPage call with a renderTile, a form with no entity behind it yet is BentoFormHero as the first child of its form.\nThe panel is the fourth thing and not a shape: a frosted box with no heading, for whatever a hero already named.\nThe last artboard is the same components on both grounds, because one look means one look twice."
+    }
+  ],
+  "launch": { "view": "canvas", "page": "vds-shell" }
+}