@charcuterie/ui 0.1.0

package/src/Skeleton/Skeleton.test.tsx

@@ -0,0 +1,47 @@
+import { composeStories } from "@storybook/react"
+import { expect } from "storybook/test"
+import { test } from "vitest"
+
+import { mountStory } from "../mountStory.testHelpers.ts"
+import { expectHiddenFromAgents } from "../testing/index.ts"
+import * as stories from "./Skeleton.stories.tsx"
+
+const { Default, Interactive } = composeStories(stories)
+
+test("a skeleton is hidden from assistive technology", async () => {
+  const { canvasElement } = await mountStory(Default)
+
+  const skeleton = canvasElement.querySelector(
+    "div[aria-hidden]",
+  )
+
+  if (!skeleton) {
+    throw new Error("Skeleton did not render")
+  }
+
+  // The inverse of every other component's gate: this one asserts
+  // the component is *not* reachable. A placeholder standing in for
+  // content that does not exist yet must not be read out as three
+  // empty bars.
+  expectHiddenFromAgents(skeleton)
+})
+
+test("it contributes no roles at all", async () => {
+  const { canvas, canvasElement } =
+    await mountStory(Interactive)
+
+  await expect(
+    canvas.queryAllByRole("status"),
+  ).toHaveLength(0)
+
+  await expect(
+    canvas.queryAllByRole("progressbar"),
+  ).toHaveLength(0)
+
+  // `lineCount` really produces that many bars — the fidelity
+  // obligation, since a placeholder that occupies the wrong box
+  // reflows the grid when the data lands.
+  await expect(
+    canvasElement.querySelectorAll(".charcuterie-shimmer"),
+  ).toHaveLength(3)
+})

package/src/Skeleton/Skeleton.tsx

@@ -0,0 +1,106 @@
+import type {
+  ComponentPropsWithRef,
+  ReactNode,
+} from "react"
+
+import { toClassName } from "../toClassName.ts"
+
+export type SkeletonShape = "block" | "circle" | "text"
+
+export type SkeletonProps = Omit<
+  ComponentPropsWithRef<"div">,
+  "children"
+> & {
+  blockSize?: string
+  inlineSize?: string
+  /**
+   * Text skeletons render this many bars, the last one short —
+   * because a paragraph placeholder whose every line is full width
+   * reads as a table, not as prose.
+   */
+  lineCount?: number
+  shape?: SkeletonShape
+}
+
+const SHAPE_CLASS: Record<SkeletonShape, string> = {
+  block: "rounded-md",
+  circle: "rounded-full",
+  text: "rounded-sm",
+}
+
+/**
+ * The bars of a multi-line text skeleton, described rather than
+ * indexed.
+ *
+ * The last line is **60%**, fixed. Not random: a placeholder that
+ * differs between two renders of the same list makes every
+ * screenshot diff useless, and visual regression over P0 x scheme x
+ * density is a planned addition once tokens stop moving.
+ */
+const buildLines = (lineCount: number) =>
+  Array.from({ length: lineCount }, (_, index) => ({
+    id: `charcuterie-skeleton-line-${index + 1}`,
+    inlineSize: index === lineCount - 1 ? "60%" : undefined,
+  }))
+
+/**
+ * **Also zero of these fleet-wide.** The counterpart to `Spinner`
+ * and the better answer wherever the shape of the incoming content
+ * is already known: a poster grid that skeletons does not reflow
+ * when the images land, and layout shift is the thing users
+ * actually notice.
+ *
+ * `aria-hidden` is not an optimisation, it is the contract. A
+ * skeleton is decoration standing in for content that does not
+ * exist yet; announcing it means a screen reader reading three
+ * empty bars. **The load has to be announced by the region that
+ * owns it** — a `Spinner`, or an `aria-busy` on the container — and
+ * a skeleton that AT can see is a bug, which is why the story
+ * asserts it cannot be found by role.
+ */
+export const Skeleton = ({
+  blockSize,
+  className,
+  inlineSize,
+  lineCount = 1,
+  shape = "block",
+  style,
+  ...divProps
+}: SkeletonProps): ReactNode => {
+  const barClassName = toClassName(
+    "charcuterie-shimmer block bg-surface-sunken",
+    SHAPE_CLASS[shape],
+    shape === "text" && "h-[1em]",
+  )
+
+  if (shape === "text" && lineCount > 1) {
+    return (
+      <div
+        {...divProps}
+        aria-hidden="true"
+        className={toClassName(
+          "flex flex-col gap-2",
+          className,
+        )}
+        style={{ inlineSize, ...style }}
+      >
+        {buildLines(lineCount).map((line) => (
+          <span
+            className={barClassName}
+            key={line.id}
+            style={{ inlineSize: line.inlineSize }}
+          />
+        ))}
+      </div>
+    )
+  }
+
+  return (
+    <div
+      {...divProps}
+      aria-hidden="true"
+      className={toClassName(barClassName, className)}
+      style={{ blockSize, inlineSize, ...style }}
+    />
+  )
+}

package/src/Spinner/Spinner.mdx

@@ -0,0 +1,36 @@
+import { Canvas, Controls, Meta } from "@storybook/addon-docs/blocks";
+
+import * as SpinnerStories from "./Spinner.stories";
+
+<Meta of={SpinnerStories} />
+
+# Spinner
+
+**Zero of these exist anywhere in the fleet.** Not one repo has a spinner; every app
+renders bare `"loading…"` text. Best effort-to-payoff component in M3.
+
+<Canvas of={SpinnerStories.Default} />
+
+## Props
+
+<Controls />
+
+## Three things a hand-rolled `animate-spin` does not do
+
+1. **It is a live region.** `role="status"` with the label inside, so the load is
+   announced. A rotating `<div>` announces nothing.
+2. **It stops.** The animation runs at `--duration-loop-fast`, which
+   `prefers-reduced-motion` zeroes and `@charcuterie/ui/styles.css` then switches off
+   outright. Tailwind's `animate-spin` hardcodes 1s straight past the media query.
+3. **It is findable.** `role="status"` takes **no accessible name from its content** — it
+   is a live region, not a widget — so the component sets `aria-label` as well. Without
+   that, `getByRole("status", { name: "Loading…" })` matches nothing, and axe never
+   mentions it.
+
+## Reduced motion
+
+There is deliberately no "reduced motion" story: it is a browser state, not a prop. Toggle
+it (DevTools → Rendering → Emulate `prefers-reduced-motion`) against `AllStates` — the
+ring must stop, stay a ring, and keep its label.
+
+<Canvas of={SpinnerStories.AllStates} />

package/src/Spinner/Spinner.stories.tsx

@@ -0,0 +1,118 @@
+import type { Meta, StoryObj } from "@storybook/react"
+
+import { controlSizeArgType } from "../argTypes.storyHelpers.ts"
+import { Button } from "../Button/Button.tsx"
+import {
+  ContainerBoard,
+  StoryCell,
+  StoryGrid,
+  StorySection,
+} from "../board.storyHelpers.tsx"
+import { Spinner } from "./Spinner.tsx"
+
+const meta = {
+  title: "Components/Spinner",
+  component: Spinner,
+  parameters: { layout: "padded" },
+  argTypes: { size: controlSizeArgType },
+  args: {
+    isLabelVisible: false,
+    label: "Loading…",
+    size: "md",
+  },
+} satisfies Meta<typeof Spinner>
+
+export default meta
+
+type Story = StoryObj<typeof meta>
+
+/**
+ * The name comes from the *hidden* label, which is the whole reason
+ * this beats a rotating `<div>`: the state is announced even though
+ * nothing is printed.
+ */
+export const Default: Story = {
+  args: {},
+}
+
+export const AllVariants: Story = {
+  args: {},
+  render: (spinnerProps) => (
+    <StorySection title="Three sizes, and inside a button — where `border-current` makes it inherit the button's own text colour with nothing passed in.">
+      <StoryGrid columns={4}>
+        <StoryCell label="sm">
+          <Spinner {...spinnerProps} size="sm" />
+        </StoryCell>
+
+        <StoryCell label="md">
+          <Spinner {...spinnerProps} size="md" />
+        </StoryCell>
+
+        <StoryCell label="lg">
+          <Spinner {...spinnerProps} size="lg" />
+        </StoryCell>
+
+        <StoryCell label="inside a solid button">
+          <Button isLoading>Ripping</Button>
+        </StoryCell>
+      </StoryGrid>
+    </StorySection>
+  ),
+}
+
+export const AllStates: Story = {
+  args: {},
+  render: (spinnerProps) => (
+    <StoryGrid columns={3}>
+      <StoryCell label="label hidden (default)">
+        <Spinner {...spinnerProps} />
+      </StoryCell>
+
+      <StoryCell label="label visible">
+        <Spinner {...spinnerProps} isLabelVisible />
+      </StoryCell>
+
+      <StoryCell label="custom label">
+        <Spinner
+          {...spinnerProps}
+          isLabelVisible
+          label="Reading disc structure…"
+        />
+      </StoryCell>
+
+      <StoryCell label="on a tinted surface">
+        <span className="inline-flex rounded-md bg-intent-info-surface p-2 text-intent-info-content">
+          <Spinner {...spinnerProps} />
+        </span>
+      </StoryCell>
+    </StoryGrid>
+  ),
+}
+
+/**
+ * There is no "reduced motion" story, deliberately — it is a
+ * *browser* state, not a prop, so faking it here would prove
+ * nothing. Toggle the OS setting (or DevTools → Rendering → Emulate
+ * `prefers-reduced-motion`) against this board: the ring must stop
+ * and still read as a ring, and the label must still be announced.
+ */
+export const Responsive: Story = {
+  args: { isLabelVisible: true },
+  render: (spinnerProps) => (
+    <ContainerBoard>
+      <Spinner {...spinnerProps} />
+    </ContainerBoard>
+  ),
+}
+
+/**
+ * A named region with a visible label, and a ring that stays *out*
+ * of the accessibility tree — otherwise a screen reader reads the
+ * label twice, once as the region and once as an unnamed child.
+ */
+export const Interactive: Story = {
+  args: {
+    isLabelVisible: true,
+    label: "Reading disc structure…",
+  },
+}

package/src/Spinner/Spinner.test.tsx

@@ -0,0 +1,38 @@
+import { composeStories } from "@storybook/react"
+import { expect } from "storybook/test"
+import { test } from "vitest"
+
+import { mountStory } from "../mountStory.testHelpers.ts"
+import { expectAgentDrivable } from "../testing/index.ts"
+import * as stories from "./Spinner.stories.tsx"
+
+const { Default, Interactive } = composeStories(stories)
+
+test("the hidden label is the accessible name", async () => {
+  const { canvas } = await mountStory(Default)
+
+  // A live region takes **no** accessible name from its content, so
+  // `Spinner` sets both — text for the announcement, `aria-label`
+  // for the name. Without that this query matches nothing:
+  // announced, but unfindable, and axe stays silent about it.
+  expectAgentDrivable(canvas, {
+    name: "Loading…",
+    role: "status",
+  })
+})
+
+test("the ring is decoration and stays out of the tree", async () => {
+  const { canvas } = await mountStory(Interactive)
+
+  const status = expectAgentDrivable(canvas, {
+    name: "Reading disc structure…",
+    role: "status",
+  })
+
+  // Otherwise a screen reader reads the label twice — once as the
+  // region, once as an unnamed child.
+  const ring = status.querySelector("[aria-hidden='true']")
+
+  await expect(ring).toBeInTheDocument()
+  await expect(ring).toHaveClass("charcuterie-spin")
+})

package/src/Spinner/Spinner.tsx

@@ -0,0 +1,92 @@
+import type { ControlSize } from "@charcuterie/tokens"
+import type {
+  ComponentPropsWithRef,
+  ReactNode,
+} from "react"
+
+import { SPINNER_SIZE_CLASS } from "../controlStyles.ts"
+import { toClassName } from "../toClassName.ts"
+import { VisuallyHidden } from "../VisuallyHidden/VisuallyHidden.tsx"
+
+export type SpinnerProps = Omit<
+  ComponentPropsWithRef<"span">,
+  "children"
+> & {
+  /**
+   * Required by omission of a default that could be wrong.
+   * "Loading…" is right for a fetch and wrong for "Ripping disc 3",
+   * and the label is the *only* thing a screen-reader user gets —
+   * the animation says nothing.
+   */
+  label?: string
+  isLabelVisible?: boolean
+  size?: ControlSize
+}
+
+/**
+ * **Zero of these exist anywhere in the fleet.** Not one repo has a
+ * spinner; every app renders bare `"loading…"` text, which is why
+ * this is the best effort-to-payoff component in the M3 list.
+ *
+ * Three things it does that a hand-rolled `animate-spin` does not:
+ *
+ *  - **It is a live region.** `role="status"` with the label inside
+ *    means a screen reader announces the load starting. A bare
+ *    rotating `<div>` announces nothing, which is the state of the
+ *    art in every repo that renders `"loading…"` into a `<span>`.
+ *  - **It stops.** The animation is `--duration-loop-fast`, which
+ *    `prefers-reduced-motion` zeroes and
+ *    `@charcuterie/ui/styles.css` then switches off outright —
+ *    vestibular-triggering motion is the single most common a11y
+ *    complaint about spinners, and Tailwind's `animate-spin`
+ *    hardcodes 1s past the media query.
+ *  - **It leaves a static fallback that still reads.** With motion
+ *    off, the ring stays a ring and the label stays a label, so the
+ *    component degrades to "there is a thing here, and it says
+ *    loading" rather than to nothing.
+ */
+export const Spinner = ({
+  className,
+  isLabelVisible = false,
+  label = "Loading…",
+  size = "md",
+  ...spanProps
+}: SpinnerProps): ReactNode => (
+  <span
+    {...spanProps}
+    // Both, and neither is redundant. `role="status"` takes **no
+    // accessible name from its content** — it is a live region, not
+    // a widget — so without `aria-label` the spinner is announced on
+    // change but cannot be *found*:
+    // `getByRole("status", { name: "Loading…" })` matches nothing,
+    // which is a gap an agent hits and axe never reports. The text
+    // child is what a screen reader reads when the region appears;
+    // the label is what names it for navigation and for Playwright.
+    aria-label={label}
+    className={toClassName(
+      "inline-flex items-center gap-2 align-middle text-current",
+      className,
+    )}
+    role="status"
+  >
+    <span
+      aria-hidden="true"
+      className={toClassName(
+        // `border-current` on three sides and a transparent fourth
+        // is the whole trick: it inherits the parent's text colour,
+        // so a spinner inside a solid button is legible without the
+        // button telling it anything.
+        "charcuterie-spin inline-block shrink-0 rounded-full border-current border-t-transparent",
+        SPINNER_SIZE_CLASS[size],
+      )}
+    />
+
+    {isLabelVisible ? (
+      <span className="text-content-secondary">
+        {label}
+      </span>
+    ) : (
+      <VisuallyHidden>{label}</VisuallyHidden>
+    )}
+  </span>
+)

package/src/Tabs/TabTrigger.tsx

@@ -0,0 +1,126 @@
+import type { ReactNode } from "react"
+import { useEffect } from "react"
+
+import { FOCUS_RING_CLASS } from "../intentStyles.ts"
+import { toClassName } from "../toClassName.ts"
+import type { TabItem, TabsOrientation } from "./Tabs.tsx"
+
+/**
+ * The selected marker runs along the edge the tab list itself
+ * sits on — under a horizontal bar, down the inline-end of a
+ * vertical rail — and the negative margin pulls it over the
+ * list's own border so the two read as one line rather than two.
+ *
+ * Logical properties throughout, which is the house rule and also
+ * the only way a vertical rail lands on the correct side in RTL.
+ */
+const ORIENTATION_EDGE_CLASS: Record<
+  TabsOrientation,
+  { base: string; selected: string }
+> = {
+  horizontal: {
+    base: "-mb-px border-b-2",
+    selected: "border-b-intent-accent-solid",
+  },
+  vertical: {
+    base: "-me-px border-e-2 text-start",
+    selected: "border-e-intent-accent-solid",
+  },
+}
+
+export type TabTriggerProps = {
+  id: string
+  isSelected: boolean
+  onSelect: (key: string) => void
+  orientation: TabsOrientation
+  panelId: string
+  /** `RovingFocus.register` — membership of the arrow-key group. */
+  registerFocus: (value: string) => () => void
+  /** `SinglePicker.register` — membership of the choice. */
+  registerSelection: (value: string) => () => void
+  tab: TabItem
+  tabIndex: number
+  trackElement: (
+    key: string,
+    element: HTMLButtonElement | null,
+  ) => void
+}
+
+/**
+ * Its own file for a reason that is not style: **both
+ * registrations are effects**, and an effect cannot run in a loop.
+ * Any member of a registering group ends up shaped like this, so
+ * it is worth seeing on its own.
+ *
+ * The two registrations are separate on purpose. A disabled tab
+ * joins the *choice* — it is still one of the options, still owns
+ * a panel and an id, and can still be the one selected when a
+ * consumer says so — and stays out of the *focus* group, so the
+ * arrow keys skip it without any command in `RovingFocus` having
+ * to know what "disabled" means. Registration is membership; that
+ * is the whole mechanism.
+ */
+export const TabTrigger = ({
+  id,
+  isSelected,
+  onSelect,
+  orientation,
+  panelId,
+  registerFocus,
+  registerSelection,
+  tab,
+  tabIndex,
+  trackElement,
+}: TabTriggerProps): ReactNode => {
+  const { isDisabled = false, key, label } = tab
+
+  const edge = ORIENTATION_EDGE_CLASS[orientation]
+
+  useEffect(
+    () => registerSelection(key),
+    [key, registerSelection],
+  )
+
+  useEffect(() => {
+    if (isDisabled) {
+      return
+    }
+
+    return registerFocus(key)
+  }, [isDisabled, key, registerFocus])
+
+  return (
+    <button
+      aria-controls={panelId}
+      aria-selected={isSelected}
+      className={toClassName(
+        "cursor-pointer border-transparent px-3 py-2 font-medium text-sm whitespace-nowrap transition-colors duration-(--duration-fast) ease-standard",
+        edge.base,
+        // Two entries rather than one interpolated string:
+        // `tailwindCandidates.test.ts` rejects a template literal
+        // in a className outright, because Tailwind's scanner
+        // cannot see a class that only exists at runtime.
+        isSelected && edge.selected,
+        isSelected
+          ? "text-content-primary"
+          : "text-content-secondary hover:text-content-primary",
+        isDisabled &&
+          "cursor-not-allowed text-content-disabled hover:text-content-disabled",
+        FOCUS_RING_CLASS,
+      )}
+      disabled={isDisabled}
+      id={id}
+      onClick={() => {
+        onSelect(key)
+      }}
+      ref={(element) => {
+        trackElement(key, element)
+      }}
+      role="tab"
+      tabIndex={tabIndex}
+      type="button"
+    >
+      {label}
+    </button>
+  )
+}

package/src/Tabs/Tabs.mdx

@@ -0,0 +1,126 @@
+import { Canvas, Controls, Meta } from "@storybook/addon-docs/blocks";
+
+import * as TabsStories from "./Tabs.stories";
+
+<Meta of={TabsStories} />
+
+# Tabs
+
+**The state layer's falsification test.** Tabs is P0 for that reason and no other — the
+fifteen ad-hoc tab bars that used to justify it were in the withdrawn evidence. The plan
+was explicit: if this came out ugly, stop and reconsider the state layer before building
+fifteen more components.
+
+It did not come out ugly. The composition is two hooks and one decision.
+
+<Canvas of={TabsStories.Default} />
+
+## Props
+
+<Controls />
+
+## The composition
+
+```ts
+const selection = useSinglePicker({ selectedValue: initialKey })  // which tab is chosen
+const focus = useRovingFocus({ activeValue: initialKey })         // which tab is tabbable
+
+// `automatic` is this line. `manual` is its absence.
+if (activation === "automatic") selection.select(focus.activeValue)
+```
+
+That one line is the whole difference between the two ARIA activation modes, and it is
+only that small because **focus and selection are separate kinds**. In `manual`, focus
+lands on a tab that is *not* chosen — a state the original three-kind model could not
+represent at all, because it had one notion of "the current one" doing both jobs. The
+`Interactive` story asserts both halves against the same component.
+
+## Selection, not visibility
+
+M4 built this on `VisibilityGroup`, and the panels come out one-at-a-time either way: the
+two cores are the same shape, deliberately. What settled it is **what registers**. The
+thing that calls `register` here is the *tab*, not the panel, and the question a tab bar
+asks is *which one did you pick* — so the kind that answers it is `SinglePicker`, and the
+panel's `hidden` is derived from the answer rather than being the answer.
+
+That is not bookkeeping. Reading it the other way made `aria-selected` a report about a
+panel's visibility, so a tab bar with **no panels at all** — a segmented filter, a view
+switcher that swaps a route — had to model its choice as a group of visibilities it did not
+have. `SegmentedControl` is exactly that consumer, and it shares this core rather than
+hand-rolling a fourth one.
+[Decision](../../../docs/decisions/2026-07-30-tab-selection-is-a-single-picker.md).
+
+## What it does not use, and why that is the answer
+
+The plan expected `createLinkedIds` here too, alongside Visibility, VisibilityGroup, and
+RovingFocus. **It does not fit, and forcing it would have been wrong.**
+
+That kind exists for a *dynamic* trigger↔target pair — a `Popover` whose panel mounts and
+unmounts, where the multiset is what stops `aria-controls` pointing at a node React has
+already removed. A tab bar's pairing is static and known at render, so the ids are derived
+from one `useUniqueId` and cannot get out of step at all. Three of the four kinds, and a
+specific reason for the fourth.
+
+## Registration is membership
+
+A disabled tab joins the **choice** — it is still one of the options, still owns a panel
+and an id — and stays out of the **focus** group. That is all "disabled" means here: the
+arrow keys skip it because it is not a member, and nothing in `RovingFocus` has to know the
+word.
+
+`TabTrigger` is its own file for a reason that is not style: both registrations are
+effects, and an effect cannot run in a loop. Any member of a registering group ends up
+shaped like this.
+
+<Canvas of={TabsStories.AllVariants} />
+
+## `activeKey` is initial, not controlled
+
+Read once, on the first render. A parent that needs to push a value calls the hook's own
+setter; there is no controlled mode and no prop-sync effect, which is
+[the M2 decision](../../../docs/decisions/2026-07-29-logic-hooks-are-uncontrolled.md) and
+the thing that keeps the fleet's existing echo loops out of this library.
+
+## Focus is moved deliberately, and only then
+
+`RovingFocus` is state; something still has to call `.focus()`. It happens only while the
+tablist already contains the focused element — otherwise mounting a tab bar, or any parent
+re-render that moved `activeValue`, yanks the caret out of whatever the user was doing.
+
+<Canvas of={TabsStories.AllStates} />
+
+## What Tabs found in M3's own testing helper
+
+`expectAgentDrivable` rejected every tab outright:
+
+> Not agent-drivable: role "tab" named "Log" has a negative tabindex, so it can be clicked
+> but never reached with Tab.
+
+Correct for a standalone button, wrong for a tab. **A roving group's whole design is that
+exactly one member is in the tab order** and the arrow keys reach the rest; a tab list
+where every tab had `tabindex="0"` would be the bug.
+
+So the rejection was not skipped for composite widgets — it was **replaced by the roving
+rule itself**, which is the stronger assertion: inside a `tablist` / `listbox` / `menu` /
+`radiogroup` / `tree` / `grid` / `toolbar`, exactly one enabled member may be in the tab
+order. Zero strands the widget; several mean the pattern was never implemented.
+`AllStates` proves the failing half too, with a four-line stub standing in for the canvas —
+`AgentQueries` is structural precisely so that it can.
+
+<Canvas of={TabsStories.Responsive} />
+
+## A tab bar scrolls, it does not wrap
+
+A wrapped tablist puts tabs on two rows, which breaks the visual row and the mental model
+the arrow keys give — "right" stops meaning right. `ContainerBoard` appears here as a width
+harness rather than a container-query claim: `Tabs` declares no container, because nothing
+about it needs to *know* its width. It only has to survive being narrow.
+
+## Manual activation is the falsification test
+
+`automatic` and `manual` differ only in whether moving focus also *chooses* — and that
+difference is *one line*, because focus and selection are separate kinds. Arrow through the
+bar below and the underline stays put until Enter: focus has moved to a tab that is not
+selected, which is a state a three-kind model cannot represent at all.
+
+<Canvas of={TabsStories.Manual} />