@neuravision/construct 2.3.1 → 2.4.0

package/CHANGELOG.md

@@ -5,6 +5,75 @@ All notable changes to `@neuravision/construct` will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [Unreleased]
+
+## [2.4.0] - 2026-11-05
+
+### Added
+
+- **Aperture app grammar:** `data-grammar="aperture"` re-maps the semantic tokens for whole
+  applications (paper and ink, cobalt as the only accent, 4px radii, grotesk). The source is
+  `tokens/grammar.aperture.json`; `build-tokens.mjs` emits one reference-only block after all theme
+  and system blocks and validates the default contrast pairs for every theme with the grammar
+  applied. New `schemas/grammar.schema.json`, signature layer `components/aperture-app.css` (seam
+  mark instead of the Datum edge, Datum marks hidden), story **Patterns → Aperture App** and
+  `docs/aperture-app.md`.
+- New Aperture roles `elevated`, `accentHover`, `accentActive`, `borderSubtle` in every theme and
+  primitives cobalt 100/300/600/800/900 and graphite 200/300/700/900.
+- **Stepper (`ct-stepper`):** progress indicator for multi-step flows. Ordered list in a labelled
+  `<nav>`, state from `aria-current="step"` and `data-state="completed" | "error"`, native buttons
+  (disabled = not reachable), `--vertical` modifier, 44px targets, labels collapse to the current step
+  below 600px, forced-colors support. In Aperture the finished path reads as a cobalt seam. Story
+  **Components → Navigation → Stepper**.
+- **Bottom navigation (`ct-bottom-nav`):** primary destinations on small screens, icon + label,
+  current destination via `aria-current="page"` (Datum leading edge on top, Aperture split seam),
+  `--fixed` modifier with safe-area inset, 44px targets. Story
+  **Components → Navigation → Bottom Navigation**.
+
+### Fixed
+
+- Control aliases (`--ct-control-*`) now re-resolve inside nested `[data-theme]` and `[data-grammar]`
+  scopes. Before, they were substituted once at `:root`, so inputs inside a dark section of a light
+  page kept the light background.
+- `.ct-table-wrap` is now a containing block (`position: relative`). Absolutely positioned content in
+  a wide table (e.g. visually hidden header text) was not clipped by the scroll container and made
+  the whole page scroll sideways on phones.
+
+### Security
+
+- Development toolchain updated for new advisories that failed the release audit gate: Storybook
+  10.6.6 (preview origin validation and dev-server code injection, GHSA-f2ph-cmg5-wxc8,
+  GHSA-px85-f4q5-jh77) and Vitest 4.1.12 (`@vitest/mocker` manual-mock injection,
+  GHSA-qxg6-89mg-rqv8, GHSA-xp26-3454-mjgp). Development dependencies only; the published CSS,
+  tokens and behaviors are unchanged.
+
+- Development toolchain updated for two new advisories that failed the CI audit gate: Vitest
+  4.1.11 (`@vitest/mocker` path traversal, GHSA-82fw-gwwq-j7x9) and `source-map-js` 1.2.2
+  (event-loop denial of service, GHSA-68fv-2mgg-jv7q). Development dependencies only; the
+  published CSS, tokens and behaviors are unchanged.
+
+## [2.3.2] - 2026-10-12
+
+### Fixed
+
+- `ct-tabs` clamps its content track like every other grid content slot since 2.3.1. Its `auto`
+  column grew to the widest panel's max-content size, so a table or other wide content in a tab
+  panel stretched the whole tab set — list and panel — past the width it was given; on a phone the
+  surrounding card clipped it. Content now wraps or scrolls inside the panel. `ct-tabs--vertical`
+  clamps its panel column the same way. The Content Slot Containment story covers tabs: on the
+  previous CSS the panel track measured 426.4px inside a 320px slot.
+- Table cell modifiers align their column again. `.ct-table th, .ct-table td` set
+  `text-align: start` with a higher specificity than `ct-table__cell--numeric`, `--actions` and
+  `--checkbox`, so numbers and row actions stayed left-aligned and checkboxes uncentred. The
+  modifiers are now scoped to `.ct-table`; the new Card & Table "Cell types" story checks the
+  computed alignment.
+- `publish.sh` asks for a one-time password whenever npm demands one. It assumed that an
+  `NPM_TOKEN` in the environment made 2FA unnecessary, which only holds for automation tokens —
+  with any other credential the publish stopped at `EOTP` and the script had no way to recover,
+  because its OTP prompt sat in the branch without a token. The token now only authenticates,
+  the prompt is shared by both paths, and a failure that is not `EOTP` aborts instead of asking
+  for a code.
+
 ## [2.3.1] - 2026-09-17
 
 ### Fixed

package/components/README.md

@@ -215,7 +215,7 @@ Content card with header, body, and footer:
 ```
 
 `ct-card__body` clamps its content track, as every grid content slot does (`ct-modal__body`,
-`ct-drawer__body`, `ct-field`, `ct-alert`, `ct-confirmation`). Content wider than the card wraps,
+`ct-drawer__body`, `ct-field`, `ct-alert`, `ct-confirmation`, `ct-tabs`). Content wider than the card wraps,
 truncates, or scrolls inside its own scroll container — `ct-table-wrap` for tables — instead of
 stretching the card past the width it was given.
 
@@ -816,6 +816,44 @@ Use `ct-navbar--compact` for dense product headers. Mark expendable actions with
 
 The CSS controls presentation only. Application code must keep `aria-expanded`, `data-state`, focus movement, Escape handling, and focus return in sync.
 
+### Stepper
+
+```html
+<nav class="ct-stepper" aria-label="Einrichtung">
+  <ol class="ct-stepper__list">
+    <li class="ct-stepper__item" data-state="completed">
+      <button class="ct-stepper__button" type="button">
+        <span class="ct-stepper__marker" aria-hidden="true">✓</span>
+        <span class="ct-stepper__text"><span class="ct-stepper__label">Unternehmen</span></span>
+        <span class="ct-stepper__sr">Schritt 1 von 3, erledigt</span>
+      </button>
+    </li>
+    <li class="ct-stepper__item" aria-current="step">…</li>
+    <li class="ct-stepper__item"><button class="ct-stepper__button" type="button" disabled>…</button></li>
+  </ol>
+</nav>
+```
+
+- State: `aria-current="step"` (current), `data-state="completed" | "error"`; unreachable steps are `disabled`.
+- `.ct-stepper--vertical` stacks the steps; below 600px only the current step keeps its label.
+- In `data-grammar="aperture"` the finished path is drawn as a seam.
+
+### Bottom Navigation
+
+```html
+<nav class="ct-bottom-nav ct-bottom-nav--fixed" aria-label="Hauptnavigation">
+  <ul class="ct-bottom-nav__list">
+    <li><a class="ct-bottom-nav__link" href="/rechnungen" aria-current="page">
+      <svg class="ct-bottom-nav__icon" aria-hidden="true">…</svg><span class="ct-bottom-nav__label">Rechnungen</span>
+    </a></li>
+  </ul>
+</nav>
+```
+
+- 3–5 destinations; the current one has `aria-current="page"`.
+- `--fixed` pins the bar to the bottom (safe-area aware). The product hides it above its breakpoint and
+  reserves space at the end of the content (`padding-block-end`).
+
 ### App Shell
 
 App Shell V2 is the recommended layout for new applications. The original `.ct-app-shell` remains a supported compatibility layout and is not being rewritten, so existing DOM and selectors keep working. Both variants now share these public override hooks:

package/components/_shared.css

@@ -1,4 +1,8 @@
-:root {
+/* Re-resolve the aliases at every theme and grammar scope: custom properties are substituted where
+   they are declared, so a root-only declaration would freeze light values inside nested scopes. */
+:root,
+[data-theme],
+[data-grammar] {
   --ct-control-bg: var(--component-control-background);
   --ct-control-bg-hover: var(--component-control-background-hover);
   --ct-control-bg-disabled: var(--component-control-background-disabled);

package/components/aperture-app.css

@@ -0,0 +1,120 @@
+/* Aperture as app grammar — signature layer.
+ *
+ * Activated by data-grammar="aperture" (on <html> or any subtree). The token re-map itself is
+ * generated from tokens/grammar.aperture.json into tokens.css; this file only swaps the Datum
+ * signature for Aperture motifs inside that scope:
+ *   - the orange leading edge becomes a split cobalt seam mark (46 / 8 / 46 rhythm),
+ *   - Datum registration marks and eyebrow ticks are hidden, eyebrows read like aperture labels,
+ *   - text and brand typography switch to the grotesk stack.
+ * Without the attribute nothing in this file matches, so Datum surfaces are unchanged. */
+
+[data-grammar='aperture'] {
+  --font-family-text: var(--font-family-aperture);
+  --font-family-brand: var(--font-family-aperture);
+}
+
+/* Seam mark: current navigation item, active list item. */
+[data-grammar='aperture']
+  :is(
+    .ct-nav-item--active,
+    .ct-nav-item[aria-current='page'],
+    .ct-list__item--active,
+    .ct-list__item[data-state='active'],
+    .ct-list__item[aria-selected='true']
+  ),
+[data-grammar='aperture']
+  .ct-table
+  tbody
+  tr:is([aria-selected='true'], [aria-current='true'], [data-state='selected'])
+  > :first-child {
+  box-shadow: none;
+  background-image: linear-gradient(
+    to bottom,
+    var(--color-brand-accent) 0 46%,
+    transparent 46% 54%,
+    var(--color-brand-accent) 54% 100%
+  );
+  background-repeat: no-repeat;
+  background-size: var(--component-datum-edge-width) calc(100% - var(--space-2));
+  background-position: left 0 top var(--space-2);
+}
+
+[data-grammar='aperture']
+  :is(
+    .ct-nav-item--active,
+    .ct-nav-item[aria-current='page'],
+    .ct-list__item--active,
+    .ct-list__item[data-state='active'],
+    .ct-list__item[aria-selected='true']
+  ):dir(rtl) {
+  background-position: right 0 top var(--space-2);
+}
+
+/* Sorted table column: horizontal seam instead of a continuous underline. */
+[data-grammar='aperture'] .ct-table thead th:is([aria-sort='ascending'], [aria-sort='descending']) {
+  box-shadow: none;
+  background-image: linear-gradient(
+    to right,
+    var(--color-brand-accent) 0 46%,
+    transparent 46% 54%,
+    var(--color-brand-accent) 54% 100%
+  );
+  background-repeat: no-repeat;
+  background-size: 100% var(--component-datum-edge-width);
+  background-position: left bottom;
+}
+
+/* Datum cards and frames become quiet paper cards with a hairline. */
+[data-grammar='aperture'] :is(.ct-datum-frame, .ct-card--datum, .ct-frame--datum)::before {
+  display: none;
+}
+
+[data-grammar='aperture'] .ct-card[data-state='active'] {
+  box-shadow: var(--component-card-shadow);
+  border-color: var(--color-brand-accent);
+}
+
+/* Eyebrows read as aperture labels; the orange tick disappears. */
+[data-grammar='aperture'] .ct-eyebrow::before,
+[data-grammar='aperture'] .ct-eyebrow--numbered::after {
+  display: none;
+}
+
+[data-grammar='aperture'] .ct-eyebrow {
+  color: var(--color-text-secondary);
+  padding-inline-start: 0;
+}
+
+/* Stepper: the finished part of the path reads as a seam (46 / 8 / 46), not a solid line. */
+[data-grammar='aperture'] .ct-stepper__item[data-state='completed']::after {
+  background: linear-gradient(
+    to right,
+    var(--color-brand-accent) 0 46%,
+    transparent 46% 54%,
+    var(--color-brand-accent) 54% 100%
+  );
+}
+
+/* Bottom navigation: split seam instead of the Datum leading edge. */
+[data-grammar='aperture'] .ct-bottom-nav__link[aria-current='page']::before {
+  background: linear-gradient(
+    to right,
+    var(--color-brand-accent) 0 46%,
+    transparent 46% 54%,
+    var(--color-brand-accent) 54% 100%
+  );
+}
+
+@media (forced-colors: active) {
+  [data-grammar='aperture']
+    :is(
+      .ct-nav-item--active,
+      .ct-nav-item[aria-current='page'],
+      .ct-list__item--active,
+      .ct-list__item[data-state='active'],
+      .ct-list__item[aria-selected='true']
+    ),
+  [data-grammar='aperture'] .ct-table thead th:is([aria-sort='ascending'], [aria-sort='descending']) {
+    background-image: none;
+  }
+}

package/components/bottom-nav.css

@@ -0,0 +1,112 @@
+/* Bottom navigation — primary destinations on small screens.
+ *
+ * Markup: <nav class="ct-bottom-nav" aria-label> > <ul class="ct-bottom-nav__list"> > <li> >
+ *   <a class="ct-bottom-nav__link" aria-current="page"?> <svg class="ct-bottom-nav__icon" aria-hidden> <span class="ct-bottom-nav__label">
+ * The current destination is marked with aria-current="page" (no modifier class).
+ * .ct-bottom-nav--fixed pins the bar to the viewport bottom and respects the safe-area inset;
+ * the product decides at which breakpoint it replaces the sidebar. 3–5 destinations work best. */
+
+.ct-bottom-nav {
+  display: block;
+  border-block-start: var(--border-thin) solid var(--color-border-subtle);
+  background: var(--color-bg-surface);
+  color: var(--color-text-secondary);
+}
+
+.ct-bottom-nav--fixed {
+  position: fixed;
+  inset-inline: 0;
+  inset-block-end: 0;
+  z-index: var(--z-sticky);
+  padding-block-end: env(safe-area-inset-bottom, 0px);
+}
+
+.ct-bottom-nav__list {
+  display: flex;
+  margin: 0;
+  padding: 0;
+  list-style: none;
+}
+
+.ct-bottom-nav__list > li {
+  flex: 1 1 0;
+  min-width: 0;
+}
+
+.ct-bottom-nav__link {
+  position: relative;
+  display: flex;
+  flex-direction: column;
+  align-items: center;
+  justify-content: center;
+  gap: var(--space-1);
+  min-height: 56px;
+  min-width: 44px;
+  padding: var(--space-2) var(--space-1);
+  border: 0;
+  background: none;
+  color: inherit;
+  font: inherit;
+  font-size: var(--font-size-xs);
+  line-height: 1.2;
+  text-align: center;
+  text-decoration: none;
+  cursor: pointer;
+}
+
+.ct-bottom-nav__link:hover {
+  color: var(--color-text-primary);
+}
+
+.ct-bottom-nav__link:focus-visible {
+  outline: 2px solid var(--color-focus-ring);
+  outline-offset: -4px;
+  border-radius: var(--radius-sm);
+}
+
+/* Datum: the current destination carries the leading edge on top. */
+.ct-bottom-nav__link[aria-current='page'] {
+  color: var(--color-text-primary);
+  font-weight: var(--font-weight-semibold);
+}
+
+.ct-bottom-nav__link[aria-current='page']::before {
+  content: '';
+  position: absolute;
+  inset-block-start: 0;
+  inset-inline: 25%;
+  height: var(--component-datum-edge-width);
+  background: var(--color-brand-accent);
+}
+
+.ct-bottom-nav__icon {
+  flex: none;
+  display: inline-grid;
+  place-items: center;
+  width: 1.5rem;
+  height: 1.5rem;
+}
+
+/* The icon class may sit on the <svg> itself or on a wrapper around it. */
+.ct-bottom-nav__icon > svg {
+  width: 100%;
+  height: 100%;
+}
+
+.ct-bottom-nav__label {
+  max-width: 100%;
+  overflow: hidden;
+  text-overflow: ellipsis;
+  white-space: nowrap;
+}
+
+@media (forced-colors: active) {
+  .ct-bottom-nav {
+    border-block-start-color: CanvasText;
+  }
+
+  .ct-bottom-nav__link[aria-current='page']::before {
+    background: Highlight;
+    forced-color-adjust: none;
+  }
+}

package/components/index.css

@@ -62,3 +62,8 @@
 @import './tree.css';
 @import './chart.css';
 @import './status.css';
+@import './stepper.css';
+@import './bottom-nav.css';
+
+/* Aperture as app grammar — signature layer for data-grammar="aperture" (token re-map lives in tokens.css) */
+@import './aperture-app.css';

package/components/stepper.css

@@ -0,0 +1,162 @@
+/* Stepper — progress indicator for multi-step flows.
+ *
+ * Markup: <nav class="ct-stepper" aria-label> > <ol class="ct-stepper__list"> > <li class="ct-stepper__item">
+ * State is driven by attributes, not modifier classes:
+ *   - aria-current="step" on the current item,
+ *   - data-state="completed" | "error" on finished or failing items.
+ * Each item holds a native <button class="ct-stepper__button"> (disabled = not reachable yet).
+ * Position/state texts for screen readers go into .ct-stepper__sr. */
+
+.ct-stepper {
+  --_marker-size: var(--space-8);
+  --_connector: var(--color-border-default);
+  --_connector-done: var(--color-brand-primary);
+  display: block;
+}
+
+.ct-stepper__list {
+  display: flex;
+  gap: var(--space-2);
+  margin: 0;
+  padding: 0;
+  list-style: none;
+}
+
+.ct-stepper--vertical .ct-stepper__list {
+  flex-direction: column;
+}
+
+.ct-stepper__item {
+  position: relative;
+  flex: 1 1 0;
+  min-width: 0;
+}
+
+/* Connector to the next step. */
+.ct-stepper__item::after {
+  content: '';
+  position: absolute;
+  inset-block-start: calc(var(--_marker-size) / 2 - 1px);
+  inset-inline: calc(var(--_marker-size) + var(--space-2)) var(--space-2);
+  height: 2px;
+  background: var(--_connector);
+}
+
+.ct-stepper__item:last-child::after,
+.ct-stepper--vertical .ct-stepper__item::after {
+  display: none;
+}
+
+.ct-stepper__item[data-state='completed']::after {
+  background: var(--_connector-done);
+}
+
+.ct-stepper__button {
+  display: flex;
+  align-items: flex-start;
+  gap: var(--space-2);
+  width: 100%;
+  min-height: 44px;
+  padding: 0;
+  border: 0;
+  background: none;
+  color: var(--color-text-secondary);
+  font: inherit;
+  text-align: start;
+  cursor: pointer;
+}
+
+.ct-stepper__button:disabled {
+  color: var(--color-text-muted);
+  cursor: default;
+}
+
+.ct-stepper__button:focus-visible {
+  outline: 2px solid var(--color-focus-ring);
+  outline-offset: 2px;
+  border-radius: var(--radius-sm);
+}
+
+.ct-stepper__marker {
+  position: relative;
+  z-index: 1;
+  flex: none;
+  display: inline-grid;
+  place-items: center;
+  width: var(--_marker-size);
+  height: var(--_marker-size);
+  border: 2px solid var(--color-border-strong);
+  border-radius: var(--radius-round);
+  background: var(--color-bg-surface);
+  font-variant-numeric: tabular-nums;
+  font-weight: var(--font-weight-semibold);
+}
+
+.ct-stepper__item[data-state='completed'] .ct-stepper__marker {
+  border-color: var(--color-brand-primary);
+  color: var(--color-brand-primary);
+}
+
+.ct-stepper__item[aria-current='step'] .ct-stepper__marker {
+  border-color: var(--color-brand-primary);
+  background: var(--color-brand-primary);
+  color: var(--color-text-on-primary);
+}
+
+.ct-stepper__item[data-state='error'] .ct-stepper__marker {
+  border-color: var(--color-state-danger);
+  color: var(--color-state-danger-text);
+}
+
+.ct-stepper__text {
+  display: flex;
+  flex-direction: column;
+  min-width: 0;
+  padding-block-start: var(--space-1);
+}
+
+.ct-stepper__label {
+  overflow-wrap: anywhere;
+}
+
+.ct-stepper__item[aria-current='step'] .ct-stepper__label {
+  color: var(--color-text-primary);
+  font-weight: var(--font-weight-semibold);
+}
+
+.ct-stepper__meta {
+  color: var(--color-text-muted);
+  font-size: var(--font-size-xs);
+}
+
+.ct-stepper__sr {
+  position: absolute;
+  width: 1px;
+  height: 1px;
+  overflow: hidden;
+  clip-path: inset(50%);
+  white-space: nowrap;
+}
+
+/* Small screens: only the current step keeps its label. */
+@media (max-width: 599px) {
+  .ct-stepper:not(.ct-stepper--vertical) .ct-stepper__item:not([aria-current='step']) .ct-stepper__text {
+    display: none;
+  }
+}
+
+@media (forced-colors: active) {
+  .ct-stepper__marker {
+    border-color: ButtonText;
+  }
+
+  .ct-stepper__item[aria-current='step'] .ct-stepper__marker {
+    background: Highlight;
+    color: HighlightText;
+    forced-color-adjust: none;
+  }
+
+  .ct-stepper__item::after {
+    background: ButtonText;
+  }
+}

package/components/table.css

@@ -1,4 +1,7 @@
 .ct-table-wrap {
+  /* Containing block for absolutely positioned content (e.g. visually hidden header text),
+     so the scroll container clips it instead of widening the page. */
+  position: relative;
   border: var(--border-thin) solid var(--color-border-subtle);
   border-radius: var(--radius-md);
   background: var(--color-bg-elevated);
@@ -115,17 +118,19 @@ th[aria-sort='descending'] .ct-table__sort-indicator::before {
   justify-content: flex-end;
 }
 
-.ct-table__cell--checkbox {
+/* Cell modifiers are scoped to the table so they outrank the base
+   `.ct-table th/td` alignment; unscoped, `text-align: start` always won. */
+.ct-table .ct-table__cell--checkbox {
   width: var(--space-8);
   text-align: center;
 }
 
-.ct-table__cell--numeric {
+.ct-table .ct-table__cell--numeric {
   text-align: end;
   font-variant-numeric: tabular-nums;
 }
 
-.ct-table__cell--actions {
+.ct-table .ct-table__cell--actions {
   text-align: end;
   white-space: nowrap;
 }

package/components/tabs.css

@@ -10,6 +10,9 @@
   --ct-tabs-indicator-color: var(--color-brand-accent);
 
   display: grid;
+  /* Clamped content track: a panel's projected content wraps or scrolls inside
+     the tabs instead of widening them. See `.ct-card__body`. */
+  grid-template-columns: minmax(0, 1fr);
   gap: var(--ct-tabs-gap);
 }
 
@@ -119,7 +122,8 @@ a.ct-tabs__trigger:active {
 /* Vertical orientation */
 
 .ct-tabs--vertical {
-  grid-template-columns: auto 1fr;
+  /* The panel column is clamped so wide content stays inside the tabs. */
+  grid-template-columns: auto minmax(0, 1fr);
 }
 
 .ct-tabs--vertical .ct-tabs__list {

package/docs/aperture-app.md

@@ -0,0 +1,55 @@
+# Aperture as app grammar
+
+`data-grammar="aperture"` turns Aperture from an editorial vocabulary into the look of a whole
+application: paper and ink, cobalt as the only accent, 4px radii and the grotesk stack. The orange
+Datum edge is replaced by a split cobalt seam mark.
+
+```html
+<html lang="de" data-grammar="aperture">              <!-- whole app -->
+<section data-grammar="aperture" data-theme="dark">   <!-- or a subtree -->
+```
+
+- Works with all four themes and with the system preference.
+- Nested `[data-theme]` scopes keep the grammar (the generated block re-applies the re-map).
+- Without the attribute nothing changes; Datum stays the default grammar.
+- Do not mix both signatures on one surface: inside an Aperture scope Datum marks are hidden.
+
+## How it is built
+
+The source is `tokens/grammar.aperture.json` (schema `schemas/grammar.schema.json`). Every value
+references an existing token, so `scripts/build-tokens.mjs` emits **one** block at the end of
+`tokens.css` that follows every theme. The pipeline resolves the grammar against each built-in theme
+and runs the default contrast pairs (text on surfaces ≥ 4.5:1, focus and control boundaries ≥ 3:1,
+text on the accent ≥ 4.5:1); a failing pair fails the build. Never edit the generated block.
+
+`components/aperture-app.css` is the signature layer: seam marks, hidden Datum marks and the font
+switch for `--font-family-text`/`--font-family-brand`.
+
+## Token re-map
+
+| Semantic token | Datum | Aperture app |
+|---|---|---|
+| `--color-bg-canvas`, `--color-bg-surface` | stone scale | `--color-aperture-paper` |
+| `--color-bg-elevated` | stone 0 / 700 | `--color-aperture-elevated` (new role) |
+| `--color-bg-muted`, `--color-bg-subtle` | stone scale | `--color-aperture-surface` |
+| `--color-text-primary` | stone ink | `--color-aperture-ink` |
+| `--color-text-secondary`, `--color-text-muted` | stone | `--color-aperture-muted` |
+| `--color-text-on-primary`, `--color-brand-on-accent` | stone | `--color-aperture-on-accent` |
+| `--color-brand-primary`, `--color-brand-accent` | ink / orange | `--color-aperture-accent` (cobalt) |
+| `…-hover` / `…-active`, `--color-brand-accent-strong` | orange scale | `--color-aperture-accent-hover` / `-active` (new roles) |
+| `--color-border-subtle`, `--color-border-muted` | stone | `--color-aperture-border-subtle` (new role) |
+| `--color-border-default` | stone 500 | `--color-aperture-muted` (≥ 3:1 for controls) |
+| `--color-border-strong` | stone 600 | `--color-aperture-ink` |
+| `--color-focus-ring` | orange | `--color-aperture-accent` |
+| `--font-family-heading`, `--font-family-body` (+ text/brand in the signature layer) | Lato | `--font-family-aperture` |
+| `--radius-control`, `--radius-card`, `--radius-modal` | md / lg / xl | `--radius-sm` |
+| `--color-state-*` | unchanged | unchanged |
+
+New primitives: cobalt 100/300/600/800/900 and graphite 200/300/700/900.
+
+## Verification
+
+- `npm run check:tokens` – contrast for every theme with the grammar applied.
+- `scripts/test-token-pipeline.mjs` – one reference-only block after all theme and system blocks.
+- Story **Patterns → Aperture App** – all four themes, a nested dark scope, and the regression gate
+  (a button outside the grammar keeps the Datum colour); runs with the a11y addon in error mode.

package/docs/aperture.md

@@ -112,3 +112,11 @@ an underlined selected radio label.
 Storybook includes interaction and automated accessibility checks. Touch and
 forced-colors suites cover the new controls. These are bounded automated checks,
 not a claim that any consuming page is completely WCAG conformant.
+
+## App grammar
+
+Aperture can also style complete applications: set `data-grammar="aperture"` on `<html>` (or a
+subtree). The editorial primitives above stay available; app components switch to paper, ink and
+cobalt. Rules: one dominant mark per composition, cobalt only for the main focus (one primary action
+per view), and never Datum and Aperture signatures on the same surface. Details, token table and
+verification: [aperture-app.md](aperture-app.md).