@aitrien/motifspec 1.13.0 → 1.13.2

package/docs/components/_template.md

@@ -1,37 +1,37 @@
----
-name: component-name
-status: draft          # draft | stable | deprecated
-tokens:                # semantic tokens this component uses
-  - color.accent
-  - space.md
----
-
-# Component name
-
-One sentence: what it is for.
-
-## When to use
-
-- …
-
-## When not to use
-
-- …
-
-## Markup
-
-```html preview
-<!-- Minimal markup. The dashboard renders this block as a live preview, and the MCP server returns it as the pattern to copy. -->
-```
-
-## Do
-
-- …
-
-## Don't
-
-- …
-
-## Accessibility
-
-- Keyboard behaviour, roles, contrast pairs.
+---
+name: component-name
+status: draft          # draft | stable | deprecated
+tokens:                # semantic tokens this component uses
+  - color.accent
+  - space.md
+---
+
+# Component name
+
+One sentence: what it is for.
+
+## When to use
+
+- …
+
+## When not to use
+
+- …
+
+## Markup
+
+```html preview
+<!-- Minimal markup. The dashboard renders this block as a live preview, and the MCP server returns it as the pattern to copy. -->
+```
+
+## Do
+
+- …
+
+## Don't
+
+- …
+
+## Accessibility
+
+- Keyboard behaviour, roles, contrast pairs.

package/docs/components/accession-label.md

@@ -1,106 +1,106 @@
----
-name: accession-label
-status: stable
-tokens:
-  - border.width.hairline
-  - color.border.default
-  - color.border.subtle
-  - color.link.rest
-  - color.ornament.muted
-  - color.status.success.text
-  - color.status.warning.text
-  - color.surface.raised
-  - color.text.accent
-  - color.text.muted
-  - color.text.primary
-  - font.family.mono
-  - font.line-height.ui
-  - font.size.label
-  - font.tracking.label
-  - font.tracking.ui
-  - font.weight.ui
-  - radius.round
-  - size.mark.tick
-  - space.inline.sm
-  - space.inline.xs
-  - space.inset.md
-  - space.inset.sm
-  - space.stack.xs
----
-
-# Accession label
-
-The system's signature: a herbarium-style label that gives an entry its catalogue number and key facts, framed by registration ticks.
-
-## When to use
-
-- At the top of a project case study (full label) and on a 404 ("No. — / Not in collection").
-- In compact form (`.cx-id`) on project cards, post rows and post meta lines.
-- Wherever an entry needs a stable, citable identifier.
-
-## When not to use
-
-- For decorative badges or skill lists; use `tag`.
-- For more than six fields. Move the rest into the prose.
-- On pages that are not catalogued entries (home, indexes).
-
-## Catalogue numbers
-
-`LM-{collection}-{sequence}`, with the sequence zero-padded to three digits and never reused.
-
-| Collection | Code | Example |
-|---|---|---|
-| Work (projects, case studies) | `W` | `LM-W-004` |
-| Writing (posts) | `P` | `LM-P-031` |
-
-Store the number in front matter (`accession: LM-W-004`) rather than deriving it from the date or slug, so it survives renames.
-
-## Markup
-
-```html preview
-<dl class="cx-label" aria-label="Accession label">
-  <div class="cx-label__id"><dt>No.</dt><dd>LM-W-001</dd></div>
-  <div><dt>Filed</dt><dd><time datetime="2026-03-14">2026-03-14</time></dd></div>
-  <div><dt>Role</dt><dd>Sole engineer</dd></div>
-  <div><dt>Stack</dt><dd>React <span class="cx-sep" aria-hidden="true">|</span> WebGL <span class="cx-sep" aria-hidden="true">|</span> Vite</dd></div>
-  <div><dt>Status</dt><dd><span class="cx-status cx-status--live">Live</span></dd></div>
-</dl>
-
-<!-- On a case study: the lead label above the title and the card after the article. Role and stack are
-     cx-label__detail fields; below size.breakpoint.md the lead label hides them and the card shows everything. -->
-<dl class="cx-label cx-label--lead" aria-label="Accession label">
-  <div class="cx-label__id"><dt>No.</dt><dd>LM-W-001</dd></div>
-  <div><dt>Filed</dt><dd><time datetime="2026-03-14">2026-03-14</time></dd></div>
-  <div class="cx-label__detail"><dt>Role</dt><dd>Sole engineer</dd></div>
-  <div class="cx-label__detail"><dt>Stack</dt><dd>React <span class="cx-sep" aria-hidden="true">|</span> WebGL <span class="cx-sep" aria-hidden="true">|</span> Vite</dd></div>
-  <div><dt>Status</dt><dd><span class="cx-status cx-status--live">Live</span></dd></div>
-</dl>
-<!-- … the article … -->
-<dl class="cx-label cx-label--card" aria-label="Accession label"><!-- the same five fields, no __detail classes --></dl>
-
-<!-- Compact form -->
-<p class="cx-id"><span class="cx-id__no">LM-P-031</span><time datetime="2026-10-02">2026-10-02</time><span>6 min read</span></p>
-```
-
-## Do
-
-- Put the number first, then the date, then everything else.
-- Use ISO dates (`2026-03-14`) in tabular figures.
-- Separate items inside a field with `cx-sep` (a hidden "|"). The compact form adds its own "|" between items.
-- Use `cx-status--live`, `--building` or `--archived`; each pairs a dot with a word.
-- On a case study, pair a lead label (`cx-label--lead`) above the title with a card (`cx-label--card`) after the article, holding the same fields. Below `size.breakpoint.md` the lead label shows only the number, date and status, because role and stack are marked `cx-label__detail`, and the card shows the full label at the end. From `size.breakpoint.md` up the lead label is complete and the card is hidden. Only one of the two is ever complete on screen.
-- Let the fields wrap. Each field grows to fill its row and carries a `color.border.subtle` rule on its right and below, so a label that wraps onto several rows reads as a ruled grid, with every row closed by a full-width rule; the frame stays `color.border.default`.
-
-## Don't
-
-- Don't use more than one full label per page. The lead label and its card count as one: at any width, only one of them shows role and stack.
-- Don't put links to unrelated pages in the label; it describes the entry.
-- Don't recolour the ticks or use them on other components except the specimen plate.
-
-## Accessibility
-
-- `<dl>` with `<dt>`/`<dd>` pairs is read as name–value pairs. Give the list `aria-label="Accession label"`.
-- Hidden fields and the hidden card use `display: none`, so assistive tech reads the same fields a sighted reader sees: on a phone, number, date and status at the top and the whole label after the article.
-- Status is a word plus a dot, never colour alone.
-- The ticks are a background on a pseudo-element and are invisible to assistive tech.
-- Pairs: `color.text.accent` on `color.surface.raised` (4.5:1); `color.text.muted` on `color.surface.raised` (4.5:1); `color.status.*.text` on `color.surface.raised` (4.5:1).
+---
+name: accession-label
+status: stable
+tokens:
+  - border.width.hairline
+  - color.border.default
+  - color.border.subtle
+  - color.link.rest
+  - color.ornament.muted
+  - color.status.success.text
+  - color.status.warning.text
+  - color.surface.raised
+  - color.text.accent
+  - color.text.muted
+  - color.text.primary
+  - font.family.mono
+  - font.line-height.ui
+  - font.size.label
+  - font.tracking.label
+  - font.tracking.ui
+  - font.weight.ui
+  - radius.round
+  - size.mark.tick
+  - space.inline.sm
+  - space.inline.xs
+  - space.inset.md
+  - space.inset.sm
+  - space.stack.xs
+---
+
+# Accession label
+
+The system's signature: a herbarium-style label that gives an entry its catalogue number and key facts, framed by registration ticks.
+
+## When to use
+
+- At the top of a project case study (full label) and on a 404 ("No. — / Not in collection").
+- In compact form (`.cx-id`) on project cards, post rows and post meta lines.
+- Wherever an entry needs a stable, citable identifier.
+
+## When not to use
+
+- For decorative badges or skill lists; use `tag`.
+- For more than six fields. Move the rest into the prose.
+- On pages that are not catalogued entries (home, indexes).
+
+## Catalogue numbers
+
+`LM-{collection}-{sequence}`, with the sequence zero-padded to three digits and never reused.
+
+| Collection | Code | Example |
+|---|---|---|
+| Work (projects, case studies) | `W` | `LM-W-004` |
+| Writing (posts) | `P` | `LM-P-031` |
+
+Store the number in front matter (`accession: LM-W-004`) rather than deriving it from the date or slug, so it survives renames.
+
+## Markup
+
+```html preview
+<dl class="cx-label" aria-label="Accession label">
+  <div class="cx-label__id"><dt>No.</dt><dd>LM-W-001</dd></div>
+  <div><dt>Filed</dt><dd><time datetime="2026-03-14">2026-03-14</time></dd></div>
+  <div><dt>Role</dt><dd>Sole engineer</dd></div>
+  <div><dt>Stack</dt><dd>React <span class="cx-sep" aria-hidden="true">|</span> WebGL <span class="cx-sep" aria-hidden="true">|</span> Vite</dd></div>
+  <div><dt>Status</dt><dd><span class="cx-status cx-status--live">Live</span></dd></div>
+</dl>
+
+<!-- On a case study: the lead label above the title and the card after the article. Role and stack are
+     cx-label__detail fields; below size.breakpoint.md the lead label hides them and the card shows everything. -->
+<dl class="cx-label cx-label--lead" aria-label="Accession label">
+  <div class="cx-label__id"><dt>No.</dt><dd>LM-W-001</dd></div>
+  <div><dt>Filed</dt><dd><time datetime="2026-03-14">2026-03-14</time></dd></div>
+  <div class="cx-label__detail"><dt>Role</dt><dd>Sole engineer</dd></div>
+  <div class="cx-label__detail"><dt>Stack</dt><dd>React <span class="cx-sep" aria-hidden="true">|</span> WebGL <span class="cx-sep" aria-hidden="true">|</span> Vite</dd></div>
+  <div><dt>Status</dt><dd><span class="cx-status cx-status--live">Live</span></dd></div>
+</dl>
+<!-- … the article … -->
+<dl class="cx-label cx-label--card" aria-label="Accession label"><!-- the same five fields, no __detail classes --></dl>
+
+<!-- Compact form -->
+<p class="cx-id"><span class="cx-id__no">LM-P-031</span><time datetime="2026-10-02">2026-10-02</time><span>6 min read</span></p>
+```
+
+## Do
+
+- Put the number first, then the date, then everything else.
+- Use ISO dates (`2026-03-14`) in tabular figures.
+- Separate items inside a field with `cx-sep` (a hidden "|"). The compact form adds its own "|" between items.
+- Use `cx-status--live`, `--building` or `--archived`; each pairs a dot with a word.
+- On a case study, pair a lead label (`cx-label--lead`) above the title with a card (`cx-label--card`) after the article, holding the same fields. Below `size.breakpoint.md` the lead label shows only the number, date and status, because role and stack are marked `cx-label__detail`, and the card shows the full label at the end. From `size.breakpoint.md` up the lead label is complete and the card is hidden. Only one of the two is ever complete on screen.
+- Let the fields wrap. Each field grows to fill its row and carries a `color.border.subtle` rule on its right and below, so a label that wraps onto several rows reads as a ruled grid, with every row closed by a full-width rule; the frame stays `color.border.default`.
+
+## Don't
+
+- Don't use more than one full label per page. The lead label and its card count as one: at any width, only one of them shows role and stack.
+- Don't put links to unrelated pages in the label; it describes the entry.
+- Don't recolour the ticks or use them on other components except the specimen plate.
+
+## Accessibility
+
+- `<dl>` with `<dt>`/`<dd>` pairs is read as name–value pairs. Give the list `aria-label="Accession label"`.
+- Hidden fields and the hidden card use `display: none`, so assistive tech reads the same fields a sighted reader sees: on a phone, number, date and status at the top and the whole label after the article.
+- Status is a word plus a dot, never colour alone.
+- The ticks are a background on a pseudo-element and are invisible to assistive tech.
+- Pairs: `color.text.accent` on `color.surface.raised` (4.5:1); `color.text.muted` on `color.surface.raised` (4.5:1); `color.status.*.text` on `color.surface.raised` (4.5:1).

package/docs/components/backdrop.md

@@ -1,83 +1,83 @@
----
-name: backdrop
-status: stable
-tokens:
-  - border.focus.offset
-  - border.focus.width
-  - border.width.contour
-  - color.backdrop.grain
-  - color.backdrop.saturation
-  - color.backdrop.tint
-  - color.focus.ring
-  - color.surface.base
-  - color.text.primary
-  - color.text.secondary
-  - motion.duration.drift
-  - motion.duration.fast
-  - motion.duration.plate
-  - motion.duration.slow
-  - motion.easing.standard
-  - radius.pill
-  - size.backdrop.blur
-  - size.backdrop.fade
-  - size.backdrop.height
-  - size.target.touch
----
-
-# Backdrop
-
-The contour survey drawn full-bleed behind every page, under a grainy frost. The page's own surface fades out over its first and last `size.backdrop.fade`, so the frost shows behind the header and footer and reading happens on the plain surface.
-
-## When to use
-
-- On every page of a site built from the system, in all six templates (`templates.md`), 404 included.
-- Once per page: one `cx-backdrop`, the first child of `<body class="cx-backdrop-page">`.
-- With the backdrop pause control in the header (`site-header.md`), because the terrain drifts.
-
-## When not to use
-
-- On the same page as the specimen plate: one contour field per page. The showcase, which documents both, is the only exception.
-- Inside a component or as a section background. The frost is one layer for the whole page.
-- Behind layouts that need the plain surface from the very top, such as a full-screen app or a print stylesheet.
-
-## Markup
-
-The build writes the backdrop to `dist/backdrop.html` (the contours at time zero, sliced to cover the viewport). In Hugo, inline it first in `<body>` and load `dist/plate.js`, which drifts it:
-
-```html preview
-<body class="cx-backdrop-page">
-  {{ (resources.Get "motifspec/backdrop.html").Content | safeHTML }}
-  <!-- <div class="cx-backdrop" aria-hidden="true" data-plate-seed="3"><svg class="cx-plate__map" preserveAspectRatio="xMidYMid slice" …>…</svg></div> -->
-  <a class="cx-skip-link" href="#main">Skip to content</a>
-  <header class="cx-header"><!-- site-header.md, with the backdrop pause control --></header>
-  <main id="main"><!-- the template --></main>
-  <footer class="cx-footer"><!-- site-footer.md --></footer>
-  <script src="{{ (resources.Get "motifspec/plate.js" | minify | fingerprint).RelPermalink }}" defer></script>
-</body>
-```
-
-From the bottom up: the canvas (`color.surface.base`), the contours (the specimen plate's `color.ornament.rest` lines and `color.ornament.strong` index contours, at `border.width.contour` and twice that, blurred by `size.backdrop.blur` and `color.backdrop.saturation`), the frost (`color.backdrop.tint` of the surface), the grain (monochrome noise at `color.backdrop.grain`), then the page, whose surface is solid between the two fades.
-
-## Do
-
-- Load `dist/plate.js` on every page that has the backdrop. It starts the drift as soon as it runs, easing up from rest over `motion.duration.plate` rather than jumping to full speed (and again whenever the drift resumes), and reveals the header's pause control; without it the contours stay still and the control stays hidden.
-- Let the header and footer sit on the frost. `cx-backdrop-page` removes their surfaces. Once the page scrolls, `dist/codex.js` makes the header sticky and fades its surface back in, so it never sits see-through on the text below; back at the top it returns to the frost (`site-header.md`). Without the script it scrolls away with the page.
-- Keep the layer's height at `size.backdrop.height`, the large viewport (`lvh`). On a phone the address bar slides away as you scroll; a layer pinned to the bottom of the screen, or sized in `dvh` or `svh`, resizes with it, re-fits the contours and makes them jump.
-- Tune the look through the backdrop tokens only.
-- Keep the opening statement inside the top fade, so it is the one piece of content that sits on the frost.
-
-## Don't
-
-- Don't give sections, panels or cards a frosted background of their own.
-- Don't position `<body>` or give it a `z-index`. The backdrop paints at `z-index: -1` in the root stacking context, under the page's own surface.
-- Don't raise `color.backdrop.grain` until the noise competes with text.
-- Don't switch the blur to `backdrop-filter`. Chromium blurs only what is on screen, so lines crossing the viewport edge stay sharp there; the CSS `filter` on the contours, over a layer that reaches past the edge, does not. Don't give the grain a `mix-blend-mode` either: in Chromium it brought sharp lines back.
-- Don't put text, links or controls in the backdrop.
-
-## Accessibility
-
-- The backdrop is `aria-hidden` and carries no information.
-- WCAG 2.2.2 (Pause, Stop, Hide): the drift runs longer than five seconds, so the header's pause control (a native checkbox named "Pause background animation"; checked means paused) stops it. It ships `hidden`; the script reveals it when the drift starts. The choice persists across pages, like the theme: it is stored as `paused` under the `cx-backdrop` key and restored before the drift starts, so a paused backdrop never moves on the next page. If storage is blocked, the pause still applies to the current page. The drift also stops off screen and in hidden tabs.
-- Under `prefers-reduced-motion: reduce` the contours never move and the pause control stays hidden.
-- Reading text below the top fade sits on `color.surface.base`, so the declared pairs apply. Text over the frost (the header, the footer, the opening of a page, and all of a short page) is measured against `color.surface.base` too: by design, contrast is not checked against the blurred contour lines beneath it.
-- The blur is a CSS `filter`, supported everywhere the rest of the system is, so contrast never depends on `backdrop-filter` support.
+---
+name: backdrop
+status: stable
+tokens:
+  - border.focus.offset
+  - border.focus.width
+  - border.width.contour
+  - color.backdrop.grain
+  - color.backdrop.saturation
+  - color.backdrop.tint
+  - color.focus.ring
+  - color.surface.base
+  - color.text.primary
+  - color.text.secondary
+  - motion.duration.drift
+  - motion.duration.fast
+  - motion.duration.plate
+  - motion.duration.slow
+  - motion.easing.standard
+  - radius.pill
+  - size.backdrop.blur
+  - size.backdrop.fade
+  - size.backdrop.height
+  - size.target.touch
+---
+
+# Backdrop
+
+The contour survey drawn full-bleed behind every page, under a grainy frost. The page's own surface fades out over its first and last `size.backdrop.fade`, so the frost shows behind the header and footer and reading happens on the plain surface.
+
+## When to use
+
+- On every page of a site built from the system, in all six templates (`templates.md`), 404 included.
+- Once per page: one `cx-backdrop`, the first child of `<body class="cx-backdrop-page">`.
+- With the backdrop pause control in the header (`site-header.md`), because the terrain drifts.
+
+## When not to use
+
+- On the same page as the specimen plate: one contour field per page. The showcase, which documents both, is the only exception.
+- Inside a component or as a section background. The frost is one layer for the whole page.
+- Behind layouts that need the plain surface from the very top, such as a full-screen app or a print stylesheet.
+
+## Markup
+
+The build writes the backdrop to `dist/backdrop.html` (the contours at time zero, sliced to cover the viewport). In Hugo, inline it first in `<body>` and load `dist/plate.js`, which drifts it:
+
+```html preview
+<body class="cx-backdrop-page">
+  {{ (resources.Get "motifspec/backdrop.html").Content | safeHTML }}
+  <!-- <div class="cx-backdrop" aria-hidden="true" data-plate-seed="3"><svg class="cx-plate__map" preserveAspectRatio="xMidYMid slice" …>…</svg></div> -->
+  <a class="cx-skip-link" href="#main">Skip to content</a>
+  <header class="cx-header"><!-- site-header.md, with the backdrop pause control --></header>
+  <main id="main"><!-- the template --></main>
+  <footer class="cx-footer"><!-- site-footer.md --></footer>
+  <script src="{{ (resources.Get "motifspec/plate.js" | minify | fingerprint).RelPermalink }}" defer></script>
+</body>
+```
+
+From the bottom up: the canvas (`color.surface.base`), the contours (the specimen plate's `color.ornament.rest` lines and `color.ornament.strong` index contours, at `border.width.contour` and twice that, blurred by `size.backdrop.blur` and `color.backdrop.saturation`), the frost (`color.backdrop.tint` of the surface), the grain (monochrome noise at `color.backdrop.grain`), then the page, whose surface is solid between the two fades.
+
+## Do
+
+- Load `dist/plate.js` on every page that has the backdrop. It starts the drift as soon as it runs, easing up from rest over `motion.duration.plate` rather than jumping to full speed (and again whenever the drift resumes), and reveals the header's pause control; without it the contours stay still and the control stays hidden.
+- Let the header and footer sit on the frost. `cx-backdrop-page` removes their surfaces. Once the page scrolls, `dist/codex.js` makes the header sticky and fades its surface back in, so it never sits see-through on the text below; back at the top it returns to the frost (`site-header.md`). Without the script it scrolls away with the page.
+- Keep the layer's height at `size.backdrop.height`, the large viewport (`lvh`). On a phone the address bar slides away as you scroll; a layer pinned to the bottom of the screen, or sized in `dvh` or `svh`, resizes with it, re-fits the contours and makes them jump.
+- Tune the look through the backdrop tokens only.
+- Keep the opening statement inside the top fade, so it is the one piece of content that sits on the frost.
+
+## Don't
+
+- Don't give sections, panels or cards a frosted background of their own.
+- Don't position `<body>` or give it a `z-index`. The backdrop paints at `z-index: -1` in the root stacking context, under the page's own surface.
+- Don't raise `color.backdrop.grain` until the noise competes with text.
+- Don't switch the blur to `backdrop-filter`. Chromium blurs only what is on screen, so lines crossing the viewport edge stay sharp there; the CSS `filter` on the contours, over a layer that reaches past the edge, does not. Don't give the grain a `mix-blend-mode` either: in Chromium it brought sharp lines back.
+- Don't put text, links or controls in the backdrop.
+
+## Accessibility
+
+- The backdrop is `aria-hidden` and carries no information.
+- WCAG 2.2.2 (Pause, Stop, Hide): the drift runs longer than five seconds, so the header's pause control (a native checkbox named "Pause background animation"; checked means paused) stops it. It ships `hidden`; the script reveals it when the drift starts. The choice persists across pages, like the theme: it is stored as `paused` under the `cx-backdrop` key and restored before the drift starts, so a paused backdrop never moves on the next page. If storage is blocked, the pause still applies to the current page. The drift also stops off screen and in hidden tabs.
+- Under `prefers-reduced-motion: reduce` the contours never move and the pause control stays hidden.
+- Reading text below the top fade sits on `color.surface.base`, so the declared pairs apply. Text over the frost (the header, the footer, the opening of a page, and all of a short page) is measured against `color.surface.base` too: by design, contrast is not checked against the blurred contour lines beneath it.
+- The blur is a CSS `filter`, supported everywhere the rest of the system is, so contrast never depends on `backdrop-filter` support.

package/docs/components/button-and-link.md

@@ -1,87 +1,87 @@
----
-name: button-and-link
-status: stable
-tokens:
-  - border.focus.offset
-  - border.focus.width
-  - border.width.emphasis
-  - border.width.hairline
-  - color.accent.fill.hover
-  - color.accent.fill.rest
-  - color.border.strong
-  - color.focus.ring
-  - color.link.hover
-  - color.link.rest
-  - color.surface.hover
-  - color.surface.raised
-  - color.text.muted
-  - color.text.on-accent
-  - color.text.primary
-  - font.family.body
-  - font.family.mono
-  - font.line-height.ui
-  - font.size.label
-  - font.size.small
-  - font.tracking.label
-  - font.weight.strong
-  - font.weight.ui
-  - motion.distance.nudge
-  - motion.duration.fast
-  - motion.easing.standard
-  - radius.pill
-  - size.target.control
-  - size.target.min
-  - space.inline.md
-  - space.inline.sm
-  - space.inline.xs
-  - space.inset.lg
----
-
-# Button and link
-
-Buttons start actions or journeys; standalone links and back links move between pages.
-
-## When to use
-
-- `cx-button--primary`: the one main action in a view ("View work").
-- `cx-button`: a secondary action beside it.
-- `cx-link`: a standalone forward link at the end of a section ("All projects" plus a forward arrow).
-- `cx-back`: the return link at the top of a post or case study (back arrow plus "All writing").
-
-## When not to use
-
-- For inline links in text; `prose` styles those.
-- Two primary buttons in one view. Make the second one secondary.
-- For navigation between sibling posts; use `pagination`.
-
-## Markup
-
-```html preview
-<div class="cx-actions">
-  <a class="cx-button cx-button--primary" href="/work/">View work <svg class="cx-icon cx-button__arrow" aria-hidden="true" focusable="false"><use href="#cx-icon-arrow-forward"></use></svg></a>
-  <a class="cx-button" href="/writing/">Read the writing</a>
-  <button class="cx-button" type="button" disabled>Not yet published</button>
-</div>
-<a class="cx-link" href="/work/">All projects <svg class="cx-icon cx-button__arrow" aria-hidden="true" focusable="false"><use href="#cx-icon-arrow-forward"></use></svg></a>
-<a class="cx-back" href="/writing/"><svg class="cx-icon cx-icon--sm cx-button__arrow" aria-hidden="true" focusable="false"><use href="#cx-icon-arrow-back"></use></svg>All writing</a>
-```
-
-## Do
-
-- Use `<a>` when it goes somewhere and `<button>` when it does something.
-- Write labels as verb plus object, in sentence case.
-- Keep `cx-button` pill-shaped (`radius.pill`). Pills are reserved for buttons, nav items and icon-only controls (the copy button, the theme toggle, the backdrop pause, heading anchors), so a pill always means "you can press this".
-- Use the `arrow-forward` and `arrow-back` icons (see `icon.md`) with `cx-button__arrow`; they nudge by `motion.distance.nudge` on hover, in their own direction.
-
-## Don't
-
-- Don't use buttons for decoration or as tags.
-- Don't round anything else: cards, tags, labels, tooltips and inputs stay square.
-- Don't make disabled buttons look clickable. They are dashed and muted, and should say why they're unavailable.
-- Don't add icons beyond the direction arrow.
-
-## Accessibility
-
-- Buttons are 40px tall (`size.target.control`); links at least 24px.
-- Focus shows `color.focus.ring` 2px off the element, so it never sits on the green fill.
-- Pairs: `color.text.on-accent` on `color.accent.fill.rest` and `.hover` (4.5:1); `color.accent.fill.rest` against the page (3:1); secondary border `color.border.strong` (3:1); `color.link.rest` (7:1).
+---
+name: button-and-link
+status: stable
+tokens:
+  - border.focus.offset
+  - border.focus.width
+  - border.width.emphasis
+  - border.width.hairline
+  - color.accent.fill.hover
+  - color.accent.fill.rest
+  - color.border.strong
+  - color.focus.ring
+  - color.link.hover
+  - color.link.rest
+  - color.surface.hover
+  - color.surface.raised
+  - color.text.muted
+  - color.text.on-accent
+  - color.text.primary
+  - font.family.body
+  - font.family.mono
+  - font.line-height.ui
+  - font.size.label
+  - font.size.small
+  - font.tracking.label
+  - font.weight.strong
+  - font.weight.ui
+  - motion.distance.nudge
+  - motion.duration.fast
+  - motion.easing.standard
+  - radius.pill
+  - size.target.control
+  - size.target.min
+  - space.inline.md
+  - space.inline.sm
+  - space.inline.xs
+  - space.inset.lg
+---
+
+# Button and link
+
+Buttons start actions or journeys; standalone links and back links move between pages.
+
+## When to use
+
+- `cx-button--primary`: the one main action in a view ("View work").
+- `cx-button`: a secondary action beside it.
+- `cx-link`: a standalone forward link at the end of a section ("All projects" plus a forward arrow).
+- `cx-back`: the return link at the top of a post or case study (back arrow plus "All writing").
+
+## When not to use
+
+- For inline links in text; `prose` styles those.
+- Two primary buttons in one view. Make the second one secondary.
+- For navigation between sibling posts; use `pagination`.
+
+## Markup
+
+```html preview
+<div class="cx-actions">
+  <a class="cx-button cx-button--primary" href="/work/">View work <svg class="cx-icon cx-button__arrow" aria-hidden="true" focusable="false"><use href="#cx-icon-arrow-forward"></use></svg></a>
+  <a class="cx-button" href="/writing/">Read the writing</a>
+  <button class="cx-button" type="button" disabled>Not yet published</button>
+</div>
+<a class="cx-link" href="/work/">All projects <svg class="cx-icon cx-button__arrow" aria-hidden="true" focusable="false"><use href="#cx-icon-arrow-forward"></use></svg></a>
+<a class="cx-back" href="/writing/"><svg class="cx-icon cx-icon--sm cx-button__arrow" aria-hidden="true" focusable="false"><use href="#cx-icon-arrow-back"></use></svg>All writing</a>
+```
+
+## Do
+
+- Use `<a>` when it goes somewhere and `<button>` when it does something.
+- Write labels as verb plus object, in sentence case.
+- Keep `cx-button` pill-shaped (`radius.pill`). Pills are reserved for buttons, nav items and icon-only controls (the copy button, the theme toggle, the backdrop pause, heading anchors), so a pill always means "you can press this".
+- Use the `arrow-forward` and `arrow-back` icons (see `icon.md`) with `cx-button__arrow`; they nudge by `motion.distance.nudge` on hover, in their own direction.
+
+## Don't
+
+- Don't use buttons for decoration or as tags.
+- Don't round anything else: cards, tags, labels, tooltips and inputs stay square.
+- Don't make disabled buttons look clickable. They are dashed and muted, and should say why they're unavailable.
+- Don't add icons beyond the direction arrow.
+
+## Accessibility
+
+- Buttons are 40px tall (`size.target.control`); links at least 24px.
+- Focus shows `color.focus.ring` 2px off the element, so it never sits on the green fill.
+- Pairs: `color.text.on-accent` on `color.accent.fill.rest` and `.hover` (4.5:1); `color.accent.fill.rest` against the page (3:1); secondary border `color.border.strong` (3:1); `color.link.rest` (7:1).