@aitrien/motifspec 1.13.0 → 1.13.2

package/docs/components/specimen-plate.md

@@ -1,92 +1,92 @@
----
-name: specimen-plate
-status: stable
-tokens:
-  - border.focus.offset
-  - border.focus.width
-  - border.width.contour
-  - border.width.emphasis
-  - border.width.hairline
-  - color.backdrop.saturation
-  - color.border.default
-  - color.border.strong
-  - color.focus.ring
-  - color.ornament.muted
-  - color.ornament.rest
-  - color.ornament.strong
-  - color.surface.hover
-  - color.surface.raised
-  - color.text.muted
-  - color.text.primary
-  - color.text.secondary
-  - font.family.mono
-  - font.size.label
-  - font.tracking.ui
-  - motion.duration.drift
-  - motion.duration.fast
-  - motion.duration.plate
-  - motion.easing.enter
-  - motion.easing.standard
-  - radius.pill
-  - size.backdrop.blur
-  - size.column.card
-  - size.mark.tick
-  - size.target.touch
-  - space.inset.md
-  - space.inset.sm
-  - space.stack.sm
----
-
-# Specimen plate
-
-A contour survey of generated terrain: simplex-noise height lines drawn as a static SVG, which slowly reshape as the terrain drifts. Framed with registration ticks and captioned as Plate 0.
-
-## When to use
-
-- Once, beside the statement on a product's landing page that does not use the backdrop.
-- As the only decorative graphic on that page, and its only looping motion.
-
-## When not to use
-
-- On a page with the backdrop (`backdrop.md`), which already draws the survey behind it: one contour field per page. The showcase, which documents both, is the only exception.
-- On article, index or 404 pages.
-- As a loading indicator, or as a map of a real place. It is generated, not surveyed.
-- Without its pause control.
-
-## Markup
-
-The build writes the plate to `dist/plate.html` (the contours at time zero) and ships the script as `dist/plate.js`. In Hugo, inline the markup and load the script; it finds every `.cx-plate[data-plate-seed]` on its own:
-
-```html preview
-<figure class="cx-plate-frame">
-  <label class="cx-plate__pause" hidden>
-    <input class="cx-visually-hidden" type="checkbox" aria-label="Pause animation">
-    <svg class="cx-icon" data-when="running" aria-hidden="true" focusable="false"><use href="#cx-icon-pause"></use></svg>
-    <svg class="cx-icon" data-when="paused" aria-hidden="true" focusable="false"><use href="#cx-icon-play"></use></svg>
-    <span class="cx-tooltip" aria-hidden="true"><span data-when="running">Pause animation</span><span data-when="paused">Play animation</span></span>
-  </label>
-  {{ (resources.Get "motifspec/plate.html").Content | safeHTML }}
-  <figcaption>Plate 0 <span class="cx-sep" aria-hidden="true">|</span> Contour survey <span class="cx-sep" aria-hidden="true">|</span> Simplex noise, 14 levels, index every fifth</figcaption>
-</figure>
-<script src="{{ (resources.Get "motifspec/plate.js" | minify | fingerprint).RelPermalink }}" defer></script>
-```
-
-## Do
-
-- Keep the survey conventions: 14 contour levels, every fifth an index contour (`color.ornament.strong`, `border.width.emphasis`), the rest hairlines in `color.ornament.rest`, over a quarter grid in `color.ornament.muted`.
-- Let each contour draw in once on load (`motion.duration.plate`, `motion.easing.enter`, staggered from the lowest line), then let the script start the drift: it eases up from rest over `motion.duration.plate`, then the terrain moves one noise unit every `motion.duration.drift`, linearly, and the lines are recomputed on every second frame.
-- Change the terrain with `data-plate-seed` (and the matching `seed` option at build time), never by editing path data.
-- Keep the caption factual: what it is, the method and the contour count.
-
-## Don't
-
-- Don't speed up the drift, add a second animated plate, or make it react to the pointer.
-- Don't add elevation numbers, place names or a north arrow. It must not read as a real map.
-- Don't put text or links inside the plate.
-
-## Accessibility
-
-- The plate is `aria-hidden`; the caption is the only text.
-- WCAG 2.2.2 (Pause, Stop, Hide): the drift runs longer than five seconds, so the pause control (a native checkbox named "Pause animation") is reachable by keyboard and its checked state means paused. It ships `hidden` and the script reveals it only when the drift starts, so no dead control appears without JavaScript.
-- The script stops drawing while the plate is off screen or the tab is hidden, and never starts under `prefers-reduced-motion: reduce`; there, the contours render complete and still and the pause control stays hidden.
-- Contours are decorative: `color.ornament.rest` has no text-contrast requirement.
+---
+name: specimen-plate
+status: stable
+tokens:
+  - border.focus.offset
+  - border.focus.width
+  - border.width.contour
+  - border.width.emphasis
+  - border.width.hairline
+  - color.backdrop.saturation
+  - color.border.default
+  - color.border.strong
+  - color.focus.ring
+  - color.ornament.muted
+  - color.ornament.rest
+  - color.ornament.strong
+  - color.surface.hover
+  - color.surface.raised
+  - color.text.muted
+  - color.text.primary
+  - color.text.secondary
+  - font.family.mono
+  - font.size.label
+  - font.tracking.ui
+  - motion.duration.drift
+  - motion.duration.fast
+  - motion.duration.plate
+  - motion.easing.enter
+  - motion.easing.standard
+  - radius.pill
+  - size.backdrop.blur
+  - size.column.card
+  - size.mark.tick
+  - size.target.touch
+  - space.inset.md
+  - space.inset.sm
+  - space.stack.sm
+---
+
+# Specimen plate
+
+A contour survey of generated terrain: simplex-noise height lines drawn as a static SVG, which slowly reshape as the terrain drifts. Framed with registration ticks and captioned as Plate 0.
+
+## When to use
+
+- Once, beside the statement on a product's landing page that does not use the backdrop.
+- As the only decorative graphic on that page, and its only looping motion.
+
+## When not to use
+
+- On a page with the backdrop (`backdrop.md`), which already draws the survey behind it: one contour field per page. The showcase, which documents both, is the only exception.
+- On article, index or 404 pages.
+- As a loading indicator, or as a map of a real place. It is generated, not surveyed.
+- Without its pause control.
+
+## Markup
+
+The build writes the plate to `dist/plate.html` (the contours at time zero) and ships the script as `dist/plate.js`. In Hugo, inline the markup and load the script; it finds every `.cx-plate[data-plate-seed]` on its own:
+
+```html preview
+<figure class="cx-plate-frame">
+  <label class="cx-plate__pause" hidden>
+    <input class="cx-visually-hidden" type="checkbox" aria-label="Pause animation">
+    <svg class="cx-icon" data-when="running" aria-hidden="true" focusable="false"><use href="#cx-icon-pause"></use></svg>
+    <svg class="cx-icon" data-when="paused" aria-hidden="true" focusable="false"><use href="#cx-icon-play"></use></svg>
+    <span class="cx-tooltip" aria-hidden="true"><span data-when="running">Pause animation</span><span data-when="paused">Play animation</span></span>
+  </label>
+  {{ (resources.Get "motifspec/plate.html").Content | safeHTML }}
+  <figcaption>Plate 0 <span class="cx-sep" aria-hidden="true">|</span> Contour survey <span class="cx-sep" aria-hidden="true">|</span> Simplex noise, 14 levels, index every fifth</figcaption>
+</figure>
+<script src="{{ (resources.Get "motifspec/plate.js" | minify | fingerprint).RelPermalink }}" defer></script>
+```
+
+## Do
+
+- Keep the survey conventions: 14 contour levels, every fifth an index contour (`color.ornament.strong`, `border.width.emphasis`), the rest hairlines in `color.ornament.rest`, over a quarter grid in `color.ornament.muted`.
+- Let each contour draw in once on load (`motion.duration.plate`, `motion.easing.enter`, staggered from the lowest line), then let the script start the drift: it eases up from rest over `motion.duration.plate`, then the terrain moves one noise unit every `motion.duration.drift`, linearly, and the lines are recomputed on every second frame.
+- Change the terrain with `data-plate-seed` (and the matching `seed` option at build time), never by editing path data.
+- Keep the caption factual: what it is, the method and the contour count.
+
+## Don't
+
+- Don't speed up the drift, add a second animated plate, or make it react to the pointer.
+- Don't add elevation numbers, place names or a north arrow. It must not read as a real map.
+- Don't put text or links inside the plate.
+
+## Accessibility
+
+- The plate is `aria-hidden`; the caption is the only text.
+- WCAG 2.2.2 (Pause, Stop, Hide): the drift runs longer than five seconds, so the pause control (a native checkbox named "Pause animation") is reachable by keyboard and its checked state means paused. It ships `hidden` and the script reveals it only when the drift starts, so no dead control appears without JavaScript.
+- The script stops drawing while the plate is off screen or the tab is hidden, and never starts under `prefers-reduced-motion: reduce`; there, the contours render complete and still and the pause control stays hidden.
+- Contours are decorative: `color.ornament.rest` has no text-contrast requirement.

package/docs/components/table-of-contents.md

@@ -1,83 +1,83 @@
----
-name: table-of-contents
-status: stable
-tokens:
-  - border.focus.offset
-  - border.focus.width
-  - border.width.emphasis
-  - border.width.hairline
-  - color.accent.border
-  - color.border.default
-  - color.border.strong
-  - color.focus.ring
-  - color.text.muted
-  - color.text.primary
-  - color.text.secondary
-  - font.family.mono
-  - font.line-height.ui
-  - font.size.label
-  - font.size.small
-  - font.tracking.label
-  - font.weight.ui
-  - motion.duration.base
-  - motion.easing.standard
-  - size.column.sidebar
-  - size.target.min
-  - size.target.touch
-  - space.inline.sm
-  - space.inset.md
-  - space.inset.xs
-  - space.section.sm
-  - space.stack.xl
----
-
-# Table of contents
-
-A numbered list of an article's sections, beside the text on wide screens and above it on narrow ones.
-
-## When to use
-
-- On posts with three or more `<h2>` sections, and on every case study.
-- Inside the `cx-article` layout, before `cx-article__main` in the DOM.
-
-## When not to use
-
-- On short posts (fewer than three sections).
-- For site navigation; use `site-header`.
-
-## Markup
-
-```html preview
-<div class="cx-article">
-  <nav class="cx-toc" aria-labelledby="toc-title">
-    <details open>
-      <summary id="toc-title">On this page<svg class="cx-icon cx-icon--sm cx-toc__chevron" aria-hidden="true" focusable="false"><use href="#cx-icon-expand"></use></svg></summary>
-      <ol>
-        <li><a href="#why"><span class="cx-toc__no">01</span>Why tokens need rules</a></li>
-        <li><a href="#pairs"><span class="cx-toc__no">02</span>The pairs contract</a>
-          <ol><li><a href="#fail"><span class="cx-toc__no">2.1</span>Failure modes</a></li></ol>
-        </li>
-      </ol>
-    </details>
-  </nav>
-  <div class="cx-article__main cx-prose"><!-- content with matching ids --></div>
-</div>
-```
-
-## Do
-
-- Number sections because the order is real; nest `<h3>` entries one level only.
-- Ship `<details open>` so it works without script. Readers can collapse it on phones; the chevron rotates with `motion.duration.base`.
-- Let the script add `is-docked` (sticky) only when the TOC sits beside the text, and set `aria-current="true"` on the visible section.
-
-## Don't
-
-- Don't make the TOC sticky in CSS alone; when wrapped above the text it would cover content.
-- Don't list more than about eight entries.
-
-## Accessibility
-
-- `<nav aria-labelledby>` points at the summary text.
-- The active entry is announced through `aria-current`, not colour alone (it also gets the accent rule).
-- Entries are at least 24px tall.
-- Pairs: `color.text.secondary` on `color.surface.base` (7:1); active rule `color.accent.border` (3:1).
+---
+name: table-of-contents
+status: stable
+tokens:
+  - border.focus.offset
+  - border.focus.width
+  - border.width.emphasis
+  - border.width.hairline
+  - color.accent.border
+  - color.border.default
+  - color.border.strong
+  - color.focus.ring
+  - color.text.muted
+  - color.text.primary
+  - color.text.secondary
+  - font.family.mono
+  - font.line-height.ui
+  - font.size.label
+  - font.size.small
+  - font.tracking.label
+  - font.weight.ui
+  - motion.duration.base
+  - motion.easing.standard
+  - size.column.sidebar
+  - size.target.min
+  - size.target.touch
+  - space.inline.sm
+  - space.inset.md
+  - space.inset.xs
+  - space.section.sm
+  - space.stack.xl
+---
+
+# Table of contents
+
+A numbered list of an article's sections, beside the text on wide screens and above it on narrow ones.
+
+## When to use
+
+- On posts with three or more `<h2>` sections, and on every case study.
+- Inside the `cx-article` layout, before `cx-article__main` in the DOM.
+
+## When not to use
+
+- On short posts (fewer than three sections).
+- For site navigation; use `site-header`.
+
+## Markup
+
+```html preview
+<div class="cx-article">
+  <nav class="cx-toc" aria-labelledby="toc-title">
+    <details open>
+      <summary id="toc-title">On this page<svg class="cx-icon cx-icon--sm cx-toc__chevron" aria-hidden="true" focusable="false"><use href="#cx-icon-expand"></use></svg></summary>
+      <ol>
+        <li><a href="#why"><span class="cx-toc__no">01</span>Why tokens need rules</a></li>
+        <li><a href="#pairs"><span class="cx-toc__no">02</span>The pairs contract</a>
+          <ol><li><a href="#fail"><span class="cx-toc__no">2.1</span>Failure modes</a></li></ol>
+        </li>
+      </ol>
+    </details>
+  </nav>
+  <div class="cx-article__main cx-prose"><!-- content with matching ids --></div>
+</div>
+```
+
+## Do
+
+- Number sections because the order is real; nest `<h3>` entries one level only.
+- Ship `<details open>` so it works without script. Readers can collapse it on phones; the chevron rotates with `motion.duration.base`.
+- Let the script add `is-docked` (sticky) only when the TOC sits beside the text, and set `aria-current="true"` on the visible section.
+
+## Don't
+
+- Don't make the TOC sticky in CSS alone; when wrapped above the text it would cover content.
+- Don't list more than about eight entries.
+
+## Accessibility
+
+- `<nav aria-labelledby>` points at the summary text.
+- The active entry is announced through `aria-current`, not colour alone (it also gets the accent rule).
+- Entries are at least 24px tall.
+- Pairs: `color.text.secondary` on `color.surface.base` (7:1); active rule `color.accent.border` (3:1).

package/docs/components/tag.md

@@ -1,70 +1,70 @@
----
-name: tag
-status: stable
-tokens:
-  - border.focus.offset
-  - border.focus.width
-  - border.width.hairline
-  - color.accent.border
-  - color.border.default
-  - color.focus.ring
-  - color.surface.sunken
-  - color.text.muted
-  - color.text.primary
-  - color.text.secondary
-  - font.family.mono
-  - font.line-height.ui
-  - font.size.label
-  - font.tracking.ui
-  - motion.duration.fast
-  - motion.easing.standard
-  - radius.none
-  - size.target.min
-  - space.inline.sm
-  - space.inline.xs
-  - space.inset.sm
-  - space.stack.sm
----
-
-# Tag
-
-A small mono label for a topic or technology, optionally linking to its index.
-
-## When to use
-
-- For taxonomy terms on cards, post rows and post footers ("Filed under").
-- As filters on index pages, with `aria-current="page"` on the active one.
-
-## When not to use
-
-- For status; use `cx-status` in an accession label.
-- For actions; use `button-and-link`.
-- For more than three tags on a card or five on a post.
-
-## Markup
-
-```html preview
-<ul class="cx-tags">
-  <li><a class="cx-tag" href="/tags/webgl/">webgl<span class="cx-tag__count">4</span></a></li>
-  <li><a class="cx-tag" href="/tags/accessibility/" aria-current="page">accessibility</a></li>
-  <li><span class="cx-tag">draft</span></li>
-</ul>
-```
-
-## Do
-
-- Write terms in lowercase kebab-case, matching the taxonomy slug.
-- Show counts only on filter lists.
-- Use `<span class="cx-tag">` when the tag doesn't link anywhere.
-
-## Don't
-
-- Don't colour tags by category.
-- Don't round the corners or add icons.
-
-## Accessibility
-
-- Tags are at least 24px tall (`size.target.min`).
-- Wrap groups in `<ul>` so the count is announced.
-- The current filter uses `aria-current="page"` as well as the accent border.
-- Pairs: `color.text.secondary` on `color.surface.sunken` (7:1); hover border `color.accent.border` (3:1).
+---
+name: tag
+status: stable
+tokens:
+  - border.focus.offset
+  - border.focus.width
+  - border.width.hairline
+  - color.accent.border
+  - color.border.default
+  - color.focus.ring
+  - color.surface.sunken
+  - color.text.muted
+  - color.text.primary
+  - color.text.secondary
+  - font.family.mono
+  - font.line-height.ui
+  - font.size.label
+  - font.tracking.ui
+  - motion.duration.fast
+  - motion.easing.standard
+  - radius.none
+  - size.target.min
+  - space.inline.sm
+  - space.inline.xs
+  - space.inset.sm
+  - space.stack.sm
+---
+
+# Tag
+
+A small mono label for a topic or technology, optionally linking to its index.
+
+## When to use
+
+- For taxonomy terms on cards, post rows and post footers ("Filed under").
+- As filters on index pages, with `aria-current="page"` on the active one.
+
+## When not to use
+
+- For status; use `cx-status` in an accession label.
+- For actions; use `button-and-link`.
+- For more than three tags on a card or five on a post.
+
+## Markup
+
+```html preview
+<ul class="cx-tags">
+  <li><a class="cx-tag" href="/tags/webgl/">webgl<span class="cx-tag__count">4</span></a></li>
+  <li><a class="cx-tag" href="/tags/accessibility/" aria-current="page">accessibility</a></li>
+  <li><span class="cx-tag">draft</span></li>
+</ul>
+```
+
+## Do
+
+- Write terms in lowercase kebab-case, matching the taxonomy slug.
+- Show counts only on filter lists.
+- Use `<span class="cx-tag">` when the tag doesn't link anywhere.
+
+## Don't
+
+- Don't colour tags by category.
+- Don't round the corners or add icons.
+
+## Accessibility
+
+- Tags are at least 24px tall (`size.target.min`).
+- Wrap groups in `<ul>` so the count is announced.
+- The current filter uses `aria-current="page"` as well as the accent border.
+- Pairs: `color.text.secondary` on `color.surface.sunken` (7:1); hover border `color.accent.border` (3:1).

package/docs/components/tooltip.md

@@ -1,67 +1,67 @@
----
-name: tooltip
-status: stable
-tokens:
-  - color.surface.inverse
-  - color.text.inverse
-  - font.family.mono
-  - font.line-height.ui
-  - font.size.label
-  - font.tracking.ui
-  - font.weight.ui
-  - motion.duration.fast
-  - motion.easing.standard
-  - size.column.card
-  - space.inset.sm
-  - space.inset.xs
----
-
-# Tooltip
-
-A short label that appears beside an icon-only control on hover or keyboard focus, saying what the control does.
-
-## When to use
-
-- On icon-only controls, such as the theme toggle ("Switch to dark theme").
-- On a version number that links to the changelog ("View changelog"), where the text alone doesn't say it's a link.
-- When the label is an action of five words or fewer.
-
-## When not to use
-
-- On controls that already show text. Their label is enough.
-- For explanations, definitions or anything a reader needs in order to continue. Put that in the page.
-- On touch-only interactions, where hover doesn't exist. The control's accessible name has to carry the meaning on its own.
-- For links, form errors or rich content.
-
-## Markup
-
-The tooltip is a child of the control, so hover and focus on the control reveal it:
-
-```html preview
-<button class="cx-theme-toggle" type="button" aria-label="Switch to dark theme">
-  <svg class="cx-icon" aria-hidden="true" focusable="false"><use href="#cx-icon-theme-dark"></use></svg>
-  <span class="cx-tooltip" aria-hidden="true">Switch to dark theme</span>
-</button>
-```
-
-It opens below the control, aligned to its right edge. Add `cx-tooltip--start` to align it to the left edge instead, for controls near the left of the screen, and `cx-tooltip--above` to open it above the control, for controls near the bottom of the page (the footer version link).
-
-## Do
-
-- Keep the text identical to the control's `aria-label`, and update both together when the action changes.
-- Write the action, not the state: "Switch to dark theme", not "Light theme".
-- Let Escape dismiss it (`is-tooltip-dismissed` on the control until the pointer leaves or focus moves).
-- Use the inverse surface (`color.surface.inverse`, `color.text.inverse`) so it reads on every background, in both themes.
-
-## Don't
-
-- Don't round it. Tooltips are labels, and pills are reserved for buttons.
-- Don't add a delay longer than `motion.duration.fast` or animate its position.
-- Don't put interactive content inside it; it ignores the pointer.
-
-## Accessibility
-
-- The tooltip is `aria-hidden="true"` because it repeats the accessible name. Screen readers hear the `aria-label` once.
-- It shows on `:focus-visible` as well as `:hover`, so keyboard users see it too.
-- Escape hides it without moving the pointer or focus (WCAG 1.4.13).
-- Pair: `color.text.inverse` on `color.surface.inverse` (7:1 in both themes).
+---
+name: tooltip
+status: stable
+tokens:
+  - color.surface.inverse
+  - color.text.inverse
+  - font.family.mono
+  - font.line-height.ui
+  - font.size.label
+  - font.tracking.ui
+  - font.weight.ui
+  - motion.duration.fast
+  - motion.easing.standard
+  - size.column.card
+  - space.inset.sm
+  - space.inset.xs
+---
+
+# Tooltip
+
+A short label that appears beside an icon-only control on hover or keyboard focus, saying what the control does.
+
+## When to use
+
+- On icon-only controls, such as the theme toggle ("Switch to dark theme").
+- On a version number that links to the changelog ("View changelog"), where the text alone doesn't say it's a link.
+- When the label is an action of five words or fewer.
+
+## When not to use
+
+- On controls that already show text. Their label is enough.
+- For explanations, definitions or anything a reader needs in order to continue. Put that in the page.
+- On touch-only interactions, where hover doesn't exist. The control's accessible name has to carry the meaning on its own.
+- For links, form errors or rich content.
+
+## Markup
+
+The tooltip is a child of the control, so hover and focus on the control reveal it:
+
+```html preview
+<button class="cx-theme-toggle" type="button" aria-label="Switch to dark theme">
+  <svg class="cx-icon" aria-hidden="true" focusable="false"><use href="#cx-icon-theme-dark"></use></svg>
+  <span class="cx-tooltip" aria-hidden="true">Switch to dark theme</span>
+</button>
+```
+
+It opens below the control, aligned to its right edge. Add `cx-tooltip--start` to align it to the left edge instead, for controls near the left of the screen, and `cx-tooltip--above` to open it above the control, for controls near the bottom of the page (the footer version link).
+
+## Do
+
+- Keep the text identical to the control's `aria-label`, and update both together when the action changes.
+- Write the action, not the state: "Switch to dark theme", not "Light theme".
+- Let Escape dismiss it (`is-tooltip-dismissed` on the control until the pointer leaves or focus moves).
+- Use the inverse surface (`color.surface.inverse`, `color.text.inverse`) so it reads on every background, in both themes.
+
+## Don't
+
+- Don't round it. Tooltips are labels, and pills are reserved for buttons.
+- Don't add a delay longer than `motion.duration.fast` or animate its position.
+- Don't put interactive content inside it; it ignores the pointer.
+
+## Accessibility
+
+- The tooltip is `aria-hidden="true"` because it repeats the accessible name. Screen readers hear the `aria-label` once.
+- It shows on `:focus-visible` as well as `:hover`, so keyboard users see it too.
+- Escape hides it without moving the pointer or focus (WCAG 1.4.13).
+- Pair: `color.text.inverse` on `color.surface.inverse` (7:1 in both themes).