@apliteni/apliteni-ui 0.72.0 → 0.74.0

package/guidelines/accessibility-floor.md

@@ -6,13 +6,11 @@
 
 **Rule:** Give every pointer target at least 24x24 CSS px.
 
-**Why:** Larger targets are easier to activate accurately.
+**Do:** The dashed square is the hit area the box declares, not a drawing of one.
 
-**Do:** Use a centred 24x24 `::before` hit area for a 19x19 checkbox.
+**Don't:** The target stops where the 19x19 box stops.
 
-**Don't:** Leave a 19x19 target unchanged.
-
-**Except:** WCAG 2.5.8 permits spacing, equivalent controls, inline text, user-agent sizes and essential presentation. Overlays must not reach neighbours.
+**Except:** WCAG 2.5.8 permits spacing, equivalent controls, inline text, user-agent sizes and essential presentation. An overlay must not reach its neighbours.
 
 ## Tap target on a phone
 
@@ -48,27 +46,23 @@
 
 **Rule:** Keep a focus indicator at least 3:1 against every ground it reaches.
 
-**Why:** A solid band remains visible where glow alone may disappear.
-
-**Do:** Use G2’s solid band with a surface-coloured gap around accent-filled controls.
+**Do:** The solid band, with a surface-coloured gap around an accent-filled control.
 
-**Don't:** Use the halo alone as the focus indicator.
+**Don't:** The halo on its own, with no solid band inside it to measure.
 
-**Except:** The band must reach 4.22:1 on flat ground and 3:1 against actual gap and halo pixels.
+**Except:** The band must clear the bar against the gap and halo pixels too, not only against flat ground.
 
 ## Disabled control legibility
 
 <!-- rule: disabled-legibility -->
 
-**Rule:** Paint disabled controls with a different ink/surface pair from enabled controls.
+**Rule:** Give a disabled control its own ink and surface pair, and take the accent off it.
 
-**Why:** Opaque colours keep disabled text and surfaces readable.
+**Do:** Unavailable reads as unavailable with the pointer nowhere near it.
 
-**Do:** Use opaque `--disabled-ink`, `--disabled-surface` and `--disabled-border`.
+**Don't:** Unavailable keeps the live paint, so only the cursor reports the state.
 
-**Don't:** Fade the label and box together.
-
-**Except:** Labels must reach 3:1. Boxless ghosts use `--disabled-ink-bare`, floored at 4.89:1. Disabled controls must look weaker by changing the pair and removing accent. Only the label-free switch track may fade.
+**Except:** A disabled label must stay legible, so the pair changes rather than fades. Only the label-free switch track may fade.
 
 ## Touch field text
 
@@ -76,58 +70,60 @@
 
 **Rule:** Set coarse-pointer field text to 16px without scaling it down.
 
-**Why:** iOS Safari zooms fields below 16px and does not zoom out.
+**Why:** iOS Safari zooms into a field under 16px and does not zoom out. There is no specimen pair because the size answers to the pointer rather than the width, so both halves would draw the desktop size.
 
-**Do:** Apply real 16px text to `input`, `select` and `textarea`, including host fields.
+**Do:** Real 16px text in the field itself.
 
-**Don't:** Scale 16px down with transforms or smaller computed text.
+**Don't:** 16px scaled down, or a smaller computed size.
 
-**Except:** Preserve host fields above 16px with `!important` on a more specific selector. Checkbox, radio, range, colour, file and button types do not zoom. Do not remove pinch-zoom with `user-scalable=no` or `maximum-scale=1`. The host owns the viewport tag.
+**Except:** A host field above 16px keeps its size. Checkbox, radio, range, colour, file and button types do not zoom. Never take pinch-zoom away; the host owns the viewport tag.
 
 ## Body contrast
 
 <!-- rule: body-contrast -->
 
-**Rule:** Aim for body text contrast close to 7:1, not merely 4.5:1.
+**Rule:** Keep body text close to 7:1 at every size, not merely at 4.5:1.
 
-**Why:** Stronger contrast supports comfortable reading at every size.
+**Why:** Stronger contrast supports comfortable reading at every size. There is no specimen pair because a pale example would break this rule in front of the reader.
 
-**Do:** Use body ink at every size, then vary size, weight or spacing for hierarchy.
+**Do:** Body ink at every size, with size, weight and spacing carrying the hierarchy.
 
-**Don't:** Use pale body ink and rely on larger text for hierarchy.
+**Don't:** Pale ink propped up by larger text.
 
 ## Status labels
 
 <!-- rule: status-label -->
 
-**Rule:** Show every status with both a mark and a word.
+**Rule:** Name every status in words, not by its colour.
 
 **Why:** Colour alone is not reliably distinguishable.
 
-**Do:** Pair a status icon with text such as “Paused.”
+**Do:** The word carries the status; the tone fill agrees with it.
+
+**Don't:** A tone fill with the word taken out of it.
 
-**Don't:** Show success using green colour alone.
+**Except:** A status badge needs no glyph or dot. A callout or toast keeps its glyph, because its words sit in a sentence rather than in a fill.
 
 ## Measurable pairs
 
 <!-- rule: measurable-pair -->
 
-**Rule:** Prefer opaque grounds behind text so contrast can be measured.
+**Rule:** Keep text on opaque grounds so its contrast can be measured.
 
-**Why:** Gradients, filters and translucent layers make contrast uncertain.
+**Why:** A gradient, filter or translucent layer puts the ink on more than one ground, so no single pair can be read off it.
 
-**Do:** Place text on an opaque surface with a measurable ink pair.
+**Do:** One opaque ground under the whole sentence.
 
-**Don't:** Place text over a gradient, filter or translucent layer.
+**Don't:** The same sentence crossing a gradient, where each word sits on a different pair.
 
 ## Keyboard first
 
 <!-- rule: keyboard-first -->
 
-**Rule:** Implement keyboard behaviour before pointer behaviour and styling.
+**Rule:** Build keyboard behaviour before pointer behaviour and styling.
 
-**Why:** Keyboard access defines the interaction before visual polish.
+**Why:** Keyboard access defines the interaction before visual polish. There is no specimen pair because this is an order of work: both halves look the same once they are finished.
 
-**Do:** Make focus, order and keyboard actions work before styling controls.
+**Do:** Focus, order and keyboard actions working before anything is styled.
 
-**Don't:** Style pointer interactions before implementing keyboard behaviour.
+**Don't:** Pointer styling first and keyboard behaviour afterwards.

package/guidelines/text-length.md

@@ -6,6 +6,8 @@
 
 **Rule:** Labels, buttons, badges and status text name the field, action or state in a few words.
 
+**Why:** A control is read in the moment before acting, not studied.
+
 **Do:** “Save invoice.”
 
 **Don't:** “Click here to save your invoice.”
@@ -16,6 +18,8 @@
 
 **Rule:** Use one sentence for needed units, dates or limits.
 
+**Why:** The figure above the caption cannot say its unit, its period or what it leaves out.
+
 **Do:** “March revenue in EUR, excluding refunds.”
 
 **Don't:** “An overview of your revenue.”
@@ -26,6 +30,8 @@
 
 **Rule:** Add a short introduction only for a purpose or step the title and controls leave unclear.
 
+**Why:** An introduction that repeats the title costs the reader their place on the page.
+
 **Do:** “Upload a CSV with invoice numbers, dates and amounts.”
 
 **Don't:** “Manage your invoices here.”
@@ -36,6 +42,8 @@
 
 **Rule:** Explain a consequence or next step in one or two sentences.
 
+**Why:** A callout earns its interruption by naming the consequence and what to do about it.
+
 **Do:** “Deleting this workspace deletes its reports. Export them first.”
 
 **Don't:** “Think carefully before proceeding.”
@@ -48,6 +56,8 @@
 
 **Rule:** Cut text readers can decide and finish without.
 
+**Why:** Every spare word is read before it can be discarded.
+
 **Do:** “Exports include only filtered rows.”
 
 **Don't:** “Export quickly and easily.”

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@apliteni/apliteni-ui",
-  "version": "0.72.0",
+  "version": "0.74.0",
   "workspaces": [
     "react"
   ],

package/react/README.md

@@ -43,7 +43,7 @@ Both forward a span ref and native span attributes, including `className`.
 <span><StatusDot live /> API online</span>
 ```
 
-`Snippet` accepts `label`, `code`, `reveal`, and `copyLabel` props. It treats `code`
+`Snippet` accepts `label`, `code`, `reveal`, `copy`, `copyLabel`, and `children` props. It treats `code`
 as plain text and copies it exactly as provided. After a successful clipboard write,
 it shows “Copied” for 1.4 seconds. If copying fails, it shows “Copy failed” so readers
 can try again or select the text manually.
@@ -52,6 +52,32 @@ can try again or select the text manually.
 <Snippet label="Terminal" code="npm install @apliteni/apliteni-ui" />
 ```
 
+Set `copy={false}` to omit the copy button. Supply React children for highlighted
+text using the existing `.k` (command), `.f` (flag), `.s` (string), `.u` (URL), and
+`.c` (comment) classes. Keep `code` as the original source: copying always uses it,
+regardless of the displayed children. Neither strings nor children are parsed as HTML.
+
+Build the children from `code` with `codeTokens`, the same tokenizer the vanilla
+`hlShell` and `hlCode` use, so the text on screen cannot drift from the text the
+button copies. Writing the spans out by hand means keeping two copies of the string
+in step. The second argument is the language — `shell` (the default), `json` or
+`ts`; `codeLanguages` lists them.
+
+```tsx
+import { codeTokens } from '@apliteni/apliteni-ui';
+
+const code = '{ "url": "https://example.com/mcp" }';
+
+<Snippet label="mcp.json" code={code} copyLabel="Copy configuration">
+  {codeTokens(code, 'json').map(({ cls, text }, at) =>
+    cls ? <span key={at} className={cls}>{text}</span> : text)}
+</Snippet>
+```
+
+The copy button is icon-only: `copyLabel` is its accessible name and its tooltip
+rather than visible text, so name what is being copied — “Copy command”, “Copy
+configuration”. It still shows words while it confirms.
+
 Before a reveal snippet, explain that the secret is stored hashed and will not be
 shown again, and ask the reader to copy it now. The page decides when to remove it.
 

package/react/dist/index.d.ts

@@ -519,12 +519,16 @@ declare function DrawerSection({ title, headingLevel, className, children, ...re
 
 type SnippetProps = {
     label?: string;
-    /** Plain text, displayed and copied without HTML parsing. */
+    /** Original text to copy; displayed when children are absent. */
     code?: string;
+    /** Token markup for display only. Strings are never parsed as HTML. */
+    children?: ReactNode;
+    copy?: boolean;
     reveal?: boolean;
+    /** Accessible name and tooltip for the icon-only copy button; name what it copies. */
     copyLabel?: string;
 };
-declare function Snippet({ label, code, reveal, copyLabel }: SnippetProps): react.JSX.Element;
+declare function Snippet({ label, code, children, copy, reveal, copyLabel }: SnippetProps): react.JSX.Element;
 
 type TabItem = {
     value: string;

package/react/dist/index.js

@@ -2048,8 +2048,8 @@ function DrawerSection({ title, headingLevel = 3, className, children, ...rest }
 
 // src/Snippet.tsx
 import { useEffect as useEffect7, useRef as useRef12, useState as useState8 } from "react";
-import { jsx as jsx25, jsxs as jsxs20 } from "react/jsx-runtime";
-function Snippet({ label = "shell", code = "", reveal = false, copyLabel = "Copy" }) {
+import { Fragment as Fragment6, jsx as jsx25, jsxs as jsxs20 } from "react/jsx-runtime";
+function Snippet({ label = "shell", code = "", children, copy = true, reveal = false, copyLabel = "Copy code" }) {
   const [status, setStatus] = useState8("idle");
   const request = useRef12(0);
   const timer = useRef12(void 0);
@@ -2059,8 +2059,8 @@ function Snippet({ label = "shell", code = "", reveal = false, copyLabel = "Copy
       request.current++;
       clearTimeout(timer.current);
     };
-  }, [code]);
-  async function copy() {
+  }, [code, copy]);
+  async function handleCopy() {
     const current = ++request.current;
     clearTimeout(timer.current);
     setStatus("idle");
@@ -2076,19 +2076,29 @@ function Snippet({ label = "shell", code = "", reveal = false, copyLabel = "Copy
   return /* @__PURE__ */ jsxs20("div", { className: reveal ? "ui-snippet ui-snippet--reveal" : "ui-snippet", children: [
     /* @__PURE__ */ jsxs20("div", { className: "ui-snippet__bar", children: [
       /* @__PURE__ */ jsx25("span", { children: label }),
-      /* @__PURE__ */ jsxs20("button", { type: "button", className: "ui-snippet__copy", "aria-live": "polite", "aria-atomic": "true", onClick: copy, children: [
-        /* @__PURE__ */ jsx25(Icon, { name: status === "copied" ? "check" : "copy" }),
-        status === "copied" ? "Copied" : status === "failed" ? "Copy failed" : copyLabel
+      copy && /* @__PURE__ */ jsxs20(Fragment6, { children: [
+        /* @__PURE__ */ jsx25(
+          "button",
+          {
+            type: "button",
+            className: "ui-snippet__copy",
+            "aria-label": copyLabel,
+            title: copyLabel,
+            onClick: handleCopy,
+            children: /* @__PURE__ */ jsx25(Icon, { name: status === "idle" ? "copy" : "check" })
+          }
+        ),
+        /* @__PURE__ */ jsx25("span", { className: "ui-sr ui-snippet__status", role: "status", "aria-live": "polite", children: status === "copied" ? "Copied" : status === "failed" ? "Copy failed" : "" })
       ] })
     ] }),
-    /* @__PURE__ */ jsx25("pre", { children: code })
+    /* @__PURE__ */ jsx25("pre", { children: children ?? code })
   ] });
 }
 
 // src/Tabs.tsx
 import { useEffect as useEffect8, useId as useId9, useRef as useRef13 } from "react";
 import { playEntrance } from "@apliteni/apliteni-ui/motion";
-import { Fragment as Fragment6, jsx as jsx26, jsxs as jsxs21 } from "react/jsx-runtime";
+import { Fragment as Fragment7, jsx as jsx26, jsxs as jsxs21 } from "react/jsx-runtime";
 function Tabs({ items, value, onChange, label }) {
   const id = useId9();
   const previous = useRef13(value);
@@ -2137,7 +2147,7 @@ function Tabs({ items, value, onChange, label }) {
         },
         children: [
           item.label,
-          item.count != null && /* @__PURE__ */ jsxs21(Fragment6, { children: [
+          item.count != null && /* @__PURE__ */ jsxs21(Fragment7, { children: [
             " ",
             item.count
           ] })
@@ -2524,7 +2534,7 @@ import { applyTheme, paletteHotkey, prism, railCollapsed, themeIcon, themeName }
 // src/SidebarNav.tsx
 import { forwardRef as forwardRef8, useEffect as useEffect12, useId as useId11, useState as useState11 } from "react";
 import { ENTRANCE_FALLBACK_MS } from "@apliteni/apliteni-ui/motion";
-import { Fragment as Fragment7, jsx as jsx31, jsxs as jsxs26 } from "react/jsx-runtime";
+import { Fragment as Fragment8, jsx as jsx31, jsxs as jsxs26 } from "react/jsx-runtime";
 var badgeText = (badge) => typeof badge === "object" ? badge.text : badge;
 function Row({ item, active, activeIs, collapsed, renderLink, sub }) {
   const uid = useId11();
@@ -2550,7 +2560,7 @@ function Row({ item, active, activeIs, collapsed, renderLink, sub }) {
     item.disabled && "is-disabled",
     item.danger && "is-danger"
   ].filter(Boolean).join(" ");
-  const children = /* @__PURE__ */ jsxs26(Fragment7, { children: [
+  const children = /* @__PURE__ */ jsxs26(Fragment8, { children: [
     (item.leading ?? item.icon) && /* @__PURE__ */ jsx31("span", { className: "ui-nav__ic", children: item.leading ?? /* @__PURE__ */ jsx31(Icon, { name: item.icon }) }),
     /* @__PURE__ */ jsx31("span", { className: "ui-nav__label", children: item.label }),
     count != null && count !== "" && /* @__PURE__ */ jsx31("span", { className: `ui-nav__badge is-${typeof item.badge === "object" ? item.badge.tone ?? "neutral" : "neutral"}`, children: count }),
@@ -2619,7 +2629,7 @@ var SidebarNav = forwardRef8(function SidebarNav2({
 });
 
 // src/AppShell.tsx
-import { Fragment as Fragment8, jsx as jsx32, jsxs as jsxs27 } from "react/jsx-runtime";
+import { Fragment as Fragment9, jsx as jsx32, jsxs as jsxs27 } from "react/jsx-runtime";
 var path = (value) => value.split(/[?#]/)[0].replace(/\/+$/, "") || "/";
 function AppShell({
   sections,
@@ -2692,7 +2702,7 @@ function AppShell({
       onClick: (event) => {
         if (!event.metaKey && !event.ctrlKey && !event.shiftKey && !event.altKey) setMore(false);
       },
-      children: /* @__PURE__ */ jsxs27(Fragment8, { children: [
+      children: /* @__PURE__ */ jsxs27(Fragment9, { children: [
         /* @__PURE__ */ jsx32("span", { className: "ui-nav__ic", children: /* @__PURE__ */ jsx32(Icon, { name: section.icon }) }),
         /* @__PURE__ */ jsx32("span", { className: "ui-nav__label", children: section.label }),
         section.count != null && /* @__PURE__ */ jsx32("span", { className: "ui-nav__badge is-neutral", children: section.count })

package/src/components/index.js

@@ -289,30 +289,103 @@ export function emptyState({ art, icon: ic, title, sub, actions } = {}) {
 }
 
 // ---- Snippet -------------------------------------------------------------
-// `copyLabel` is both the visible text and the accessible name of the copy
-// button. wireTopbar() swaps that text to "✓ Copied" and back, so the button is
-// never left nameless — the glyph beside it is decorative (aria-hidden).
+// The copy button is icon-only: `copy` is on the closed list in
+// src/assets/icons.js, the bar is narrow, and the word said nothing the glyph
+// does not. `copyLabel` is therefore the accessible name and the tooltip rather
+// than visible text, and it should name what is being copied — "Copy command",
+// "Copy configuration" — the way every other icon-only control in the kit is
+// named (aria-label plus title, as button() and the theme toggle write it).
+// The confirmation is a glyph swap, not a word: the button holds its 24px box
+// through it, and the word goes to the live region beside it. A permanent
+// aria-label outranks an element's contents, so swapping text into the button
+// would have changed the pixels and left the announced name frozen — the region
+// is what carries "Copied" to a reader who cannot see the check. It ships empty
+// and is filled later, because a role="status" inserted together with its text is
+// silent on several screen readers. The button's own name stays the action, which
+// is still available; wireTopbar() fills the region. `data-orig` records the
+// resting label for a caller that wants it.
 // `type="button"`: without it a snippet dropped inside a <form> submits the form.
-export function snippet({ label = 'shell', code = '', reveal = false, copy = true, copyLabel = 'Copy' } = {}) {
+export function snippet({ label = 'shell', code = '', reveal = false, copy = true, copyLabel = 'Copy code' } = {}) {
   const copyBtn = copy
-    ? `<button type="button" class="ui-snippet__copy" data-orig="${esc(copyLabel)}">${icon('copy')}${esc(copyLabel)}</button>`
+    ? `<button type="button" class="ui-snippet__copy" aria-label="${esc(copyLabel)}" title="${esc(copyLabel)}" data-orig="${esc(copyLabel)}">${icon('copy')}</button>`
+      + '<span class="ui-sr ui-snippet__status" role="status" aria-live="polite"></span>'
     : '';
   return `<div class="${cx('ui-snippet', reveal && 'ui-snippet--reveal')}"><div class="ui-snippet__bar"><span>${esc(label)}</span>${copyBtn}</div><pre>${code}</pre></div>`;
 }
 
-// Tiny shell highlighter: escapes first, then wraps comments/strings/URLs/flags/command.
-// Matches the class names in styles/code.css (.k .f .s .u .c). Ported from viz/account.mjs.
-export const hlShell = (raw) =>
-  esc(raw).replace(
-    /(#[^\n]*)|(&quot;(?:[^&]|&(?!quot;))*&quot;|'[^']*')|(https?:\/\/[^\s"'&]+)|(\B--?[A-Za-z][\w-]*)|(^[a-z][\w.-]*)/gm,
-    (m, c, s, u, f, cmd) =>
-      c ? `<span class="c">${c}</span>`
-        : s ? `<span class="s">${s}</span>`
-        : u ? `<span class="u">${u}</span>`
-        : f ? `<span class="f">${f}</span>`
-        : cmd ? `<span class="k">${cmd}</span>`
-        : m,
-  );
+// Tiny highlighters. Each escapes first, then wraps the tokens its language
+// shows, using the class names in styles/code.css (.k .f .s .u .c). Shell is
+// ported from viz/account.mjs; JSON and TypeScript were added for the snippets
+// the kit's own docs show.
+//
+// Every pattern runs over ESCAPED text, so a quoted string ends at &quot; and a
+// shell URL stops at any entity. The group order is the class order beside it.
+//
+// They are small on purpose — they colour short documentation snippets, not
+// arbitrary programs. Known limits: no nested template expressions, no regex
+// literals, and in TypeScript a `//` inside a string reads as a comment unless a
+// `:` precedes it, which is what keeps a URL in a string whole.
+const LANGUAGES = {
+  shell: {
+    pattern: /(#[^\n]*)|(&quot;(?:[^&]|&(?!quot;))*&quot;|'[^']*')|(https?:\/\/[^\s"'&]+)|(\B--?[A-Za-z][\w-]*)|(^[a-z][\w.-]*)/gm,
+    classes: ['c', 's', 'u', 'f', 'k'],
+  },
+  // A key is a string followed by a colon, matched by lookahead so the colon
+  // stays unpainted. Keys, string values and scalars take three different
+  // classes, because a number that looks exactly like a key is not highlighting.
+  json: {
+    pattern: /(&quot;(?:[^&]|&(?!quot;))*&quot;)(?=\s*:)|(&quot;(?:[^&]|&(?!quot;))*&quot;)|(\b(?:true|false|null)\b|-?\d+(?:\.\d+)?(?:[eE][+-]?\d+)?)/g,
+    classes: ['k', 's', 'f'],
+  },
+  ts: {
+    pattern: /(\/\*[\s\S]*?\*\/|(?<![:/])\/\/[^\n]*)|(&quot;(?:[^&]|&(?!quot;))*&quot;|'[^']*'|`[^`]*`)|(\b(?:import|export|from|const|let|var|function|return|async|await|class|extends|implements|interface|type|enum|new|if|else|for|while|of|in|as|default|readonly|void)\b)|(\b(?:true|false|null|undefined)\b|\b\d+(?:\.\d+)?\b)/g,
+    classes: ['c', 's', 'k', 'f'],
+  },
+};
+
+/** The languages codeTokens and hlCode understand, so a gate can discover them. */
+export const codeLanguages = Object.keys(LANGUAGES);
+
+const ENTITY = { amp: '&', lt: '<', gt: '>', quot: '"' };
+// The exact inverse of esc: every & in escaped text starts one of these four.
+const unesc = (text) => text.replace(/&(amp|lt|gt|quot);/g, (_, name) => ENTITY[name]);
+
+/**
+ * A language's tokens, as `[{ cls, text }]` with `cls` null between tokens and
+ * `text` the original unescaped source. Concatenating `text` returns `raw`, so a
+ * React caller renders the spans from the same string it copies instead of
+ * keeping a second hand-written copy in step. hlCode joins the same tokens into
+ * HTML; neither can drift from the other. An unrecognised `lang` is read as
+ * shell, the way the kit reads every other unknown option name.
+ *
+ * No pattern ever matches inside an entity — `#`, `h`, `-`, `/`, `*`, a digit and
+ * `^[a-z]` do not occur in `&amp;`, `&lt;`, `&gt;` or `&quot;`, no keyword is one
+ * of `amp`, `lt`, `gt` or `quot`, and every alternative either stops before `&` or
+ * consumes a whole `&quot;` — so each slice is entity-complete and
+ * `esc(unesc(slice))` returns the slice unchanged. hlCode's output is therefore
+ * byte-identical to wrapping the matches in place, which
+ * src/components/snippet-tokens.test.js holds for every language, against a copy
+ * of the one-pass implementation hlShell had before #474.
+ */
+export function codeTokens(raw, lang = 'shell') {
+  const { pattern, classes } = LANGUAGES[lang] || LANGUAGES.shell;
+  const escaped = esc(raw);
+  const out = [];
+  let at = 0;
+  pattern.lastIndex = 0;
+  for (const match of escaped.matchAll(pattern)) {
+    if (match.index > at) out.push({ cls: null, text: unesc(escaped.slice(at, match.index)) });
+    out.push({ cls: classes[match.slice(1).findIndex(Boolean)], text: unesc(match[0]) });
+    at = match.index + match[0].length;
+  }
+  if (at < escaped.length) out.push({ cls: null, text: unesc(escaped.slice(at)) });
+  return out;
+}
+
+export const hlCode = (raw, lang = 'shell') =>
+  codeTokens(raw, lang).map(({ cls, text }) => (cls ? `<span class="${cls}">${esc(text)}</span>` : esc(text))).join('');
+
+export const hlShell = (raw) => hlCode(raw, 'shell');
 
 export { icon };
 export { illo, illoNames } from '../assets/illustrations.js';

package/src/components/topbar.js

@@ -242,11 +242,26 @@ export function wireTopbar(root = document) {
       });
     });
   });
-  // Copy buttons
+  // Copy buttons. The confirmation is a glyph swap plus a word in the live region
+  // beside the button, so the control holds its 24px box and a reader who cannot
+  // see the check still hears it. Writing the word into the button would do
+  // neither: the box jumps, and the permanent aria-label outranks the contents, so
+  // the announced name would never move. The restore reads the markup the button
+  // started with — putting `data-orig` back wrote the label as words and dropped
+  // the glyph, which only looked harmless while a word sat beside it. #474
   root.querySelectorAll('.ui-snippet__copy').forEach((btn) => {
+    const resting = btn.innerHTML;
+    const status = btn.parentElement?.querySelector('.ui-snippet__status');
     btn.addEventListener('click', () => {
       const pre = btn.closest('.ui-snippet')?.querySelector('pre');
-      if (pre) { navigator.clipboard?.writeText(pre.innerText); btn.innerHTML = '✓ Copied'; setTimeout(() => { btn.innerHTML = btn.dataset.orig || 'Copy'; }, 1400); }
+      if (!pre) return;
+      navigator.clipboard?.writeText(pre.innerText);
+      btn.innerHTML = icon('check');
+      if (status) status.textContent = 'Copied';
+      setTimeout(() => {
+        btn.innerHTML = resting;
+        if (status) status.textContent = '';
+      }, 1400);
     });
   });
 }

package/src/index.d.ts

@@ -83,6 +83,12 @@ export declare function topbar(opts?: Record<string, unknown>): string;
 export declare function commandPaletteList(groups?: readonly Record<string, unknown>[], opts?: { uid?: string; from?: number }): string;
 export declare function deckTextSwitch(active?: string): string;
 export declare function hlShell(raw: string): string;
+/** Token class from styles/code.css, or null for the text between tokens. */
+export type CodeTokenClass = 'c' | 'f' | 'k' | 's' | 'u';
+export type CodeLanguage = 'shell' | 'json' | 'ts';
+export declare const codeLanguages: readonly CodeLanguage[];
+export declare function codeTokens(raw: string, lang?: CodeLanguage): { cls: CodeTokenClass | null; text: string }[];
+export declare function hlCode(raw: string, lang?: CodeLanguage): string;
 export declare function pill(label: string, variant?: string): string;
 export declare function statusDot(live?: boolean): string;
 export declare function successCheck(variant?: 'line' | 'circled'): string;

package/src/styles/base.css

@@ -138,6 +138,7 @@ svg:where(:not([width]):not([height])) {
 
 /* Focus-visible ring, shared by all interactive controls */
 .ui-focusable:focus-visible,
+.ui-snippet :focus-visible,
 .ui-btn:focus-visible,
 .ui-input:focus-visible,
 .ui-seg button:focus-visible,

package/src/styles/code.css

@@ -30,6 +30,27 @@
   white-space: pre;
   font-family: var(--font-mono);
 }
+/* Scrollable code is a keyboard target, but a <pre> flush with the card and
+   without its radius draws a square ring that cuts across the card and squares
+   its corners. The card carries the ring instead, so it follows --radius-md and
+   survives `overflow: hidden`, which clips descendants and not the card's own
+   shadow. --ring-gap comes from the page here, matching the container rule in
+   tokens.css: a ring outside its own surface cannot use that surface as its gap.
+   The card also keeps a transparent outline, which forced colors repaints as the
+   focus signal once box-shadow is gone; the block below is why only one box has
+   one there. See stories/snippet-focus.test.js. */
+.ui-snippet pre:focus-visible { box-shadow: none; }
+.ui-snippet:has(pre:focus-visible) { outline: 2px solid transparent; --ring-gap: inherit; box-shadow: var(--ring); }
+
+/* Forced colors drops box-shadow, so both boxes fall back to their outlines and
+   the system repaints the pre's transparent one as the square this rule set out
+   to remove — with the card's rounded one 2px further out, two indicators for one
+   focus. The card's outline is the one that survives, so the pre keeps none.
+   Emulated in stories/snippet-focus.test.js and captured in Chromium. #474 */
+@media (forced-colors: active) {
+  .ui-snippet pre:focus-visible { outline: none; }
+}
+
 .ui-snippet__copy {
   background: none;
   border: 0;
@@ -39,14 +60,16 @@
   font-size: calc(var(--text-xs) + 1px);
   display: inline-flex;
   align-items: center;
-  gap: 6px;
   padding: 2px 4px;
   /* WCAG 2.5.8's 24 CSS px target floor, taken as a real box rather than as an
-     overlay: 2 + a 12px label at line-height 1.62 + 2 came to 23.44, so the
-     drawn button grows by 0.56px and the bar it sits in grows with it. Nothing
-     smaller than a rounding error moves, which is why this one is not a hit
-     area. Measured in stories/guidelines/accessibility-floor.test.js. #219 */
+     overlay. The height came first (#219): 2 + a 12px label at line-height 1.62
+     + 2 came to 23.44, so the drawn button grew by 0.56px and the bar with it.
+     The width is the same floor on the other axis, and it is load-bearing now
+     that the label is gone: 4 + a 13px glyph + 4 is 21px. Both are measured in
+     stories/guidelines/accessibility-floor.test.js. #474 */
   min-height: 24px;
+  min-width: 24px;
+  justify-content: center;
   transition: color var(--dur-fast) var(--ease);
 }
 .ui-snippet__copy:hover { color: var(--accent); }