@charcuterie/ui 2.0.1 → 2.1.0

package/dist/Swatch/Swatch.d.ts

@@ -0,0 +1,83 @@
+import type { ComponentPropsWithRef, ReactNode } from "react";
+export type SwatchAppearance = "outline" | "solid";
+export type SwatchSize = keyof typeof SWATCH_SIZE_CLASS;
+export type SwatchProps = Omit<ComponentPropsWithRef<"span">, "children" | "color"> & {
+    /**
+     * `outline` keeps the hue and drops the fill — for a swatch whose
+     * subject is present but inactive. It is the one visual state a
+     * status colour cannot borrow from `intent`, because the colour is
+     * not an intent.
+     */
+    appearance?: SwatchAppearance;
+    /**
+     * Any CSS colour, and this is the whole reason the component
+     * exists: it is a **value from data** — a physical sticker, an
+     * album's extracted accent, a user-chosen tag — not a token. A
+     * design system owns `intent.danger`; it does not own the colour
+     * of the dot somebody stuck on a game controller, and re-theming
+     * that would be re-theming the hardware. So it is a prop and lands
+     * in an inline `style`, the one sanctioned escape hatch for a
+     * runtime value.
+     */
+    color: string;
+    isLabelVisible?: boolean;
+    /**
+     * Required, and it is the point. A colour is not a name: a screen
+     * reader gets nothing at all from a `background-color`, and
+     * `getByRole("img", { name })` — the query an agent writes — has
+     * nothing to match. So the type asks for the name and there is no
+     * way to render the component without one.
+     */
+    label: string;
+    size?: SwatchSize;
+};
+/**
+ * The scale is the component's own, and deliberately larger than
+ * `DOT_SIZE_CLASS`.
+ *
+ * That map tops out at 10px, which is right for a status dot beside
+ * a line of text and far too small for a swatch that is the primary
+ * way a user tells one row from another across a room. A swatch is
+ * content, not punctuation.
+ */
+declare const SWATCH_SIZE_CLASS: {
+    readonly sm: "size-4";
+    readonly md: "size-6";
+    readonly lg: "size-9";
+};
+/**
+ * A colour presented **as content**, with a name attached.
+ *
+ * It is not `LiveStatusIndicator`'s dot and not a `Badge`. Both of
+ * those take an `intent`, because both show a *state* whose colour
+ * the design system owns and can name in English. This shows a
+ * colour the system does **not** own and **cannot** name — the red
+ * sticker on a controller, red because someone put a red sticker on
+ * it; the accent castkit pulls off an album; a user's tag colour.
+ * `DOT_SIZE_CLASS` is exported precisely so an app can hand-roll one
+ * of these, and three of them across the fleet did, each without a
+ * name a screen reader could read.
+ *
+ * ### `role="img"`, and the name is required
+ *
+ * A swatch is a graphic that carries meaning, so it is an image with
+ * an accessible name — which makes it findable by
+ * `getByRole("img", { name })` in **both** the dot-only and
+ * labelled forms, one stable handle regardless of whether the text
+ * is on screen. The dot and any visible label are inside it and go
+ * `aria-hidden` by virtue of the name on the wrapper, exactly as an
+ * inline SVG with a caption would.
+ *
+ * ### The ring is not a token
+ *
+ * `solid` sits a translucent white ring inside the fill so a white
+ * or near-white swatch stays visible against `surface-raised` in
+ * both schemes; a hairline border alone disappears on one of the
+ * two. `outline` drops the fill to a faint tint of the same hue and
+ * draws the ring in the colour itself — via an inline `box-shadow`,
+ * because the ring colour has to come from the data and
+ * `--tw-ring-color` is not something `CSSProperties` will type.
+ */
+export declare const Swatch: ({ appearance, className, color, isLabelVisible, label, size, ...spanProps }: SwatchProps) => ReactNode;
+export {};
+//# sourceMappingURL=Swatch.d.ts.map

package/dist/Swatch/Swatch.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Swatch.d.ts","sourceRoot":"","sources":["../../src/Swatch/Swatch.tsx"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,qBAAqB,EACrB,SAAS,EACV,MAAM,OAAO,CAAA;AAId,MAAM,MAAM,gBAAgB,GAAG,SAAS,GAAG,OAAO,CAAA;AAElD,MAAM,MAAM,UAAU,GAAG,MAAM,OAAO,iBAAiB,CAAA;AAEvD,MAAM,MAAM,WAAW,GAAG,IAAI,CAC5B,qBAAqB,CAAC,MAAM,CAAC,EAC7B,UAAU,GAAG,OAAO,CACrB,GAAG;IACF;;;;;OAKG;IACH,UAAU,CAAC,EAAE,gBAAgB,CAAA;IAC7B;;;;;;;;;OASG;IACH,KAAK,EAAE,MAAM,CAAA;IACb,cAAc,CAAC,EAAE,OAAO,CAAA;IACxB;;;;;;OAMG;IACH,KAAK,EAAE,MAAM,CAAA;IACb,IAAI,CAAC,EAAE,UAAU,CAAA;CAClB,CAAA;AAED;;;;;;;;GAQG;AACH,QAAA,MAAM,iBAAiB;;;;CAIb,CAAA;AAEV;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AACH,eAAO,MAAM,MAAM,GAAI,6EAQpB,WAAW,KAAG,SAqChB,CAAA"}

package/dist/Swatch/Swatch.js

@@ -0,0 +1,57 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { toClassName } from "../toClassName.js";
+/**
+ * The scale is the component's own, and deliberately larger than
+ * `DOT_SIZE_CLASS`.
+ *
+ * That map tops out at 10px, which is right for a status dot beside
+ * a line of text and far too small for a swatch that is the primary
+ * way a user tells one row from another across a room. A swatch is
+ * content, not punctuation.
+ */
+const SWATCH_SIZE_CLASS = {
+    sm: "size-4",
+    md: "size-6",
+    lg: "size-9",
+};
+/**
+ * A colour presented **as content**, with a name attached.
+ *
+ * It is not `LiveStatusIndicator`'s dot and not a `Badge`. Both of
+ * those take an `intent`, because both show a *state* whose colour
+ * the design system owns and can name in English. This shows a
+ * colour the system does **not** own and **cannot** name — the red
+ * sticker on a controller, red because someone put a red sticker on
+ * it; the accent castkit pulls off an album; a user's tag colour.
+ * `DOT_SIZE_CLASS` is exported precisely so an app can hand-roll one
+ * of these, and three of them across the fleet did, each without a
+ * name a screen reader could read.
+ *
+ * ### `role="img"`, and the name is required
+ *
+ * A swatch is a graphic that carries meaning, so it is an image with
+ * an accessible name — which makes it findable by
+ * `getByRole("img", { name })` in **both** the dot-only and
+ * labelled forms, one stable handle regardless of whether the text
+ * is on screen. The dot and any visible label are inside it and go
+ * `aria-hidden` by virtue of the name on the wrapper, exactly as an
+ * inline SVG with a caption would.
+ *
+ * ### The ring is not a token
+ *
+ * `solid` sits a translucent white ring inside the fill so a white
+ * or near-white swatch stays visible against `surface-raised` in
+ * both schemes; a hairline border alone disappears on one of the
+ * two. `outline` drops the fill to a faint tint of the same hue and
+ * draws the ring in the colour itself — via an inline `box-shadow`,
+ * because the ring colour has to come from the data and
+ * `--tw-ring-color` is not something `CSSProperties` will type.
+ */
+export const Swatch = ({ appearance = "solid", className, color, isLabelVisible = false, label, size = "md", ...spanProps }) => (_jsxs("span", { ...spanProps, "aria-label": label, className: toClassName("inline-flex items-center gap-2 align-middle", className), role: "img", children: [_jsx("span", { "aria-hidden": "true", className: toClassName("inline-block shrink-0 rounded-full", SWATCH_SIZE_CLASS[size], appearance === "solid" &&
+                "shadow-low ring-2 ring-white/25 ring-inset"), style: appearance === "solid"
+                ? { backgroundColor: color }
+                : {
+                    backgroundColor: `color-mix(in srgb, ${color} 12%, transparent)`,
+                    boxShadow: `inset 0 0 0 3px ${color}`,
+                } }), isLabelVisible ? (_jsx("span", { "aria-hidden": "true", className: "text-content-primary text-sm", children: label })) : null] }));
+//# sourceMappingURL=Swatch.js.map

package/dist/Swatch/Swatch.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"Swatch.js","sourceRoot":"","sources":["../../src/Swatch/Swatch.tsx"],"names":[],"mappings":";AAKA,OAAO,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAA;AAwC/C;;;;;;;;GAQG;AACH,MAAM,iBAAiB,GAAG;IACxB,EAAE,EAAE,QAAQ;IACZ,EAAE,EAAE,QAAQ;IACZ,EAAE,EAAE,QAAQ;CACJ,CAAA;AAEV;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AACH,MAAM,CAAC,MAAM,MAAM,GAAG,CAAC,EACrB,UAAU,GAAG,OAAO,EACpB,SAAS,EACT,KAAK,EACL,cAAc,GAAG,KAAK,EACtB,KAAK,EACL,IAAI,GAAG,IAAI,EACX,GAAG,SAAS,EACA,EAAa,EAAE,CAAC,CAC5B,mBACM,SAAS,gBACD,KAAK,EACjB,SAAS,EAAE,WAAW,CACpB,6CAA6C,EAC7C,SAAS,CACV,EACD,IAAI,EAAC,KAAK,aAEV,8BACc,MAAM,EAClB,SAAS,EAAE,WAAW,CACpB,oCAAoC,EACpC,iBAAiB,CAAC,IAAI,CAAC,EACvB,UAAU,KAAK,OAAO;gBACpB,4CAA4C,CAC/C,EACD,KAAK,EACH,UAAU,KAAK,OAAO;gBACpB,CAAC,CAAC,EAAE,eAAe,EAAE,KAAK,EAAE;gBAC5B,CAAC,CAAC;oBACE,eAAe,EAAE,sBAAsB,KAAK,oBAAoB;oBAChE,SAAS,EAAE,mBAAmB,KAAK,EAAE;iBACtC,GAEP,EAED,cAAc,CAAC,CAAC,CAAC,CAChB,8BACc,MAAM,EAClB,SAAS,EAAC,8BAA8B,YAEvC,KAAK,GACD,CACR,CAAC,CAAC,CAAC,IAAI,IACH,CACR,CAAA"}

package/dist/index.d.ts

@@ -94,6 +94,8 @@ export type { SortableTableHeaderProps, SortDirection, } from "./SortableTableHe
 export { SortableTableHeader } from "./SortableTableHeader/SortableTableHeader.tsx";
 export type { SpinnerProps } from "./Spinner/Spinner.tsx";
 export { Spinner } from "./Spinner/Spinner.tsx";
+export type { SwatchAppearance, SwatchProps, SwatchSize, } from "./Swatch/Swatch.tsx";
+export { Swatch } from "./Swatch/Swatch.tsx";
 export type { SlotProps } from "./slotProps.ts";
 export { mergeSlotProps } from "./slotProps.ts";
 export { getAsyncIntent, getAsyncLabel, getConnectionIntent, getConnectionLabel, getIsConnectionBusy, } from "./statusIntent.ts";

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}

package/dist/index.js

@@ -62,6 +62,7 @@ export { Select } from "./Select/Select.js";
 export { Skeleton } from "./Skeleton/Skeleton.js";
 export { SortableTableHeader } from "./SortableTableHeader/SortableTableHeader.js";
 export { Spinner } from "./Spinner/Spinner.js";
+export { Swatch } from "./Swatch/Swatch.js";
 export { mergeSlotProps } from "./slotProps.js";
 export { getAsyncIntent, getAsyncLabel, getConnectionIntent, getConnectionLabel, getIsConnectionBusy, } from "./statusIntent.js";
 export { Tabs } from "./Tabs/Tabs.js";

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@charcuterie/ui",
-  "version": "2.0.1",
+  "version": "2.1.0",
   "description": "The Charcuterie components. Tokens for look, @charcuterie/logic for state, ARIA that agents can actually drive.",
   "license": "MIT",
   "type": "module",
@@ -44,7 +44,7 @@
   },
   "dependencies": {
     "@charcuterie/logic": "1.1.0",
-    "@charcuterie/tokens": "1.1.0",
+    "@charcuterie/tokens": "1.1.1",
     "@floating-ui/react": "^0.27.20",
     "@tanstack/react-virtual": "^3.13.12"
   },

package/src/Swatch/Swatch.mdx

@@ -0,0 +1,50 @@
+import { Canvas, Controls, Meta } from "@storybook/addon-docs/blocks";
+
+import * as SwatchStories from "./Swatch.stories";
+
+<Meta of={SwatchStories} />
+
+# Swatch
+
+A colour presented **as content**, with a name attached. It is the one colour the design
+system does not own: the red sticker on a game controller, the accent castkit pulls off an
+album, a user's tag colour. Not a token — a value from data.
+
+<Canvas of={SwatchStories.Default} />
+
+## Props
+
+<Controls />
+
+## Why it is not a `Badge` or a status dot
+
+`Badge` and `LiveStatusIndicator` both take an `intent`, because both show a *state* whose
+colour the system owns and can name — `danger` is red and is called "danger". A swatch
+shows a colour the system cannot name, so the colour is a `color` prop that lands in an
+inline `style`, and the meaning travels in a **required** `label`. A `background-color` is
+nothing to a screen reader and nothing to `getByRole`, so the type asks for the name and
+there is no way to render one without it.
+
+`DOT_SIZE_CLASS` is exported so an app *can* hand-roll one of these — and three across the
+fleet did, each without a name. This is that dot, named, and sized as content rather than
+punctuation.
+
+## `outline` — present but inactive
+
+<Canvas of={SwatchStories.AllVariants} />
+
+`outline` keeps the hue and drops the fill. It is the one visual state a status colour
+cannot borrow from `intent`: a subject that is there but not active — a powered-off
+controller beside its live siblings. The ring is drawn in the colour itself, so it survives
+where a token could not follow.
+
+## Findable, and white stays visible
+
+<Canvas of={SwatchStories.AllStates} />
+
+It is a `role="img"` with an accessible name, so `getByRole("img", { name })` resolves in
+both the dot-only and labelled forms — one stable handle whether or not the text is on
+screen. The translucent inset ring on `solid` is what keeps a white or near-white swatch
+from vanishing against `surface-raised` in one of the two schemes.
+
+<Canvas of={SwatchStories.InAList} />

package/src/Swatch/Swatch.stories.tsx

@@ -0,0 +1,177 @@
+import type { Meta, StoryObj } from "@storybook/react"
+
+import {
+  StoryCell,
+  StoryGrid,
+  StoryRow,
+  StorySection,
+} from "../board.storyHelpers.tsx"
+import { Card } from "../Card/Card.tsx"
+import { Swatch } from "./Swatch.tsx"
+
+/**
+ * Colours that are **data**, not tokens — the whole reason the
+ * component exists. These stand in for stickers on a controller, and
+ * a design system re-theming them would be re-theming the hardware.
+ */
+const STICKERS = [
+  { color: "#E5484D", label: "Red" },
+  { color: "#3B82F6", label: "Blue" },
+  { color: "#35D07F", label: "Green" },
+  { color: "#F5C518", label: "Yellow" },
+] as const
+
+const meta = {
+  title: "Components/Swatch",
+  component: Swatch,
+  parameters: { layout: "padded" },
+  argTypes: { color: { control: "color" } },
+  args: {
+    appearance: "solid",
+    color: "#E5484D",
+    isLabelVisible: true,
+    label: "Red",
+    size: "md",
+  },
+} satisfies Meta<typeof Swatch>
+
+export default meta
+
+type Story = StoryObj<typeof meta>
+
+/**
+ * A named graphic — `getByRole("img", { name: "Red" })` resolves,
+ * because a colour a screen reader cannot see needs a name it can
+ * read.
+ */
+export const Default: Story = {}
+
+/**
+ * `solid` fills; `outline` keeps the hue and drops the fill. The
+ * second is the one state a status colour cannot borrow from
+ * `intent` — "this thing is present but inactive" — which is what a
+ * powered-off controller looks like beside its live siblings.
+ */
+export const AllVariants: Story = {
+  render: (swatchProps) => (
+    <StorySection title="`outline` is the same colour with the fill taken away — for a subject that is there but not active.">
+      <StoryGrid columns={2}>
+        <StoryCell label="solid">
+          <StoryRow>
+            {STICKERS.map((sticker) => (
+              <Swatch
+                {...swatchProps}
+                appearance="solid"
+                color={sticker.color}
+                isLabelVisible={false}
+                key={sticker.label}
+                label={sticker.label}
+              />
+            ))}
+          </StoryRow>
+        </StoryCell>
+
+        <StoryCell label="outline">
+          <StoryRow>
+            {STICKERS.map((sticker) => (
+              <Swatch
+                {...swatchProps}
+                appearance="outline"
+                color={sticker.color}
+                isLabelVisible={false}
+                key={sticker.label}
+                label={sticker.label}
+              />
+            ))}
+          </StoryRow>
+        </StoryCell>
+      </StoryGrid>
+    </StorySection>
+  ),
+}
+
+export const AllStates: Story = {
+  render: (swatchProps) => (
+    <StoryGrid columns={2}>
+      <StoryCell label="dot only — name still read">
+        <Swatch {...swatchProps} isLabelVisible={false} />
+      </StoryCell>
+
+      <StoryCell label="label visible">
+        <Swatch {...swatchProps} isLabelVisible />
+      </StoryCell>
+
+      <StoryCell label="sizes">
+        <StoryRow>
+          <Swatch
+            {...swatchProps}
+            isLabelVisible={false}
+            size="sm"
+          />
+
+          <Swatch
+            {...swatchProps}
+            isLabelVisible={false}
+            size="md"
+          />
+
+          <Swatch
+            {...swatchProps}
+            isLabelVisible={false}
+            size="lg"
+          />
+        </StoryRow>
+      </StoryCell>
+
+      <StoryCell label="white stays visible in both schemes">
+        <StoryRow>
+          <Swatch
+            {...swatchProps}
+            color="#FFFFFF"
+            isLabelVisible={false}
+            label="White"
+          />
+
+          <Swatch
+            {...swatchProps}
+            appearance="outline"
+            color="#FFFFFF"
+            isLabelVisible={false}
+            label="White"
+          />
+        </StoryRow>
+      </StoryCell>
+    </StoryGrid>
+  ),
+}
+
+/**
+ * The real placement: a row per item, the swatch answering "which
+ * one" before the words do. This is castkit's album accent and
+ * plex-channels' channel colours as much as it is a controller
+ * sticker.
+ */
+export const InAList: Story = {
+  render: () => (
+    <Card heading="Controllers">
+      <ul className="flex list-none flex-col gap-2 p-0">
+        {STICKERS.map((sticker) => (
+          <li
+            className="flex items-center gap-3"
+            key={sticker.label}
+          >
+            <Swatch
+              color={sticker.color}
+              label={`${sticker.label} sticker`}
+              size="sm"
+            />
+
+            <span className="text-content-secondary text-sm">
+              {sticker.label} controller
+            </span>
+          </li>
+        ))}
+      </ul>
+    </Card>
+  ),
+}

package/src/Swatch/Swatch.test.tsx

@@ -0,0 +1,57 @@
+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 "./Swatch.stories.tsx"
+
+const { Default, InAList } = composeStories(stories)
+
+test("a colour is findable by the name a screen reader can read", async () => {
+  const { canvas } = await mountStory(Default)
+
+  // The whole contract: a `background-color` is nothing to an agent
+  // or a screen reader, so the swatch is an `img` with a name.
+  const swatch = expectAgentDrivable(canvas, {
+    name: "Red",
+    role: "img",
+  })
+
+  // The name comes from `aria-label`, not the dot, which carries no
+  // information of its own.
+  await expect(swatch.firstElementChild).toHaveAttribute(
+    "aria-hidden",
+    "true",
+  )
+})
+
+test("the name survives with no visible label", async () => {
+  // `InAList` renders the dot-only form — `isLabelVisible` defaults
+  // false — with a distinct name per row, which is the placement
+  // that has to stay drivable: the swatch answers "which one" before
+  // any text does.
+  const { canvas } = await mountStory(InAList)
+
+  for (const name of [
+    "Red sticker",
+    "Blue sticker",
+    "Green sticker",
+    "Yellow sticker",
+  ]) {
+    expectAgentDrivable(canvas, { name, role: "img" })
+  }
+})
+
+test("solid rings its fill; the ring is what keeps white visible", async () => {
+  const { canvas } = await mountStory(Default)
+
+  const dot = canvas.getByRole("img", {
+    name: "Red",
+  }).firstElementChild
+
+  // Not decoration: a hairline border on a white swatch disappears
+  // against `surface-raised` in one of the two schemes, and the
+  // inset ring is what stops that.
+  await expect(dot).toHaveClass("ring-inset")
+})

package/src/Swatch/Swatch.tsx

@@ -0,0 +1,139 @@
+import type {
+  ComponentPropsWithRef,
+  ReactNode,
+} from "react"
+
+import { toClassName } from "../toClassName.ts"
+
+export type SwatchAppearance = "outline" | "solid"
+
+export type SwatchSize = keyof typeof SWATCH_SIZE_CLASS
+
+export type SwatchProps = Omit<
+  ComponentPropsWithRef<"span">,
+  "children" | "color"
+> & {
+  /**
+   * `outline` keeps the hue and drops the fill — for a swatch whose
+   * subject is present but inactive. It is the one visual state a
+   * status colour cannot borrow from `intent`, because the colour is
+   * not an intent.
+   */
+  appearance?: SwatchAppearance
+  /**
+   * Any CSS colour, and this is the whole reason the component
+   * exists: it is a **value from data** — a physical sticker, an
+   * album's extracted accent, a user-chosen tag — not a token. A
+   * design system owns `intent.danger`; it does not own the colour
+   * of the dot somebody stuck on a game controller, and re-theming
+   * that would be re-theming the hardware. So it is a prop and lands
+   * in an inline `style`, the one sanctioned escape hatch for a
+   * runtime value.
+   */
+  color: string
+  isLabelVisible?: boolean
+  /**
+   * Required, and it is the point. A colour is not a name: a screen
+   * reader gets nothing at all from a `background-color`, and
+   * `getByRole("img", { name })` — the query an agent writes — has
+   * nothing to match. So the type asks for the name and there is no
+   * way to render the component without one.
+   */
+  label: string
+  size?: SwatchSize
+}
+
+/**
+ * The scale is the component's own, and deliberately larger than
+ * `DOT_SIZE_CLASS`.
+ *
+ * That map tops out at 10px, which is right for a status dot beside
+ * a line of text and far too small for a swatch that is the primary
+ * way a user tells one row from another across a room. A swatch is
+ * content, not punctuation.
+ */
+const SWATCH_SIZE_CLASS = {
+  sm: "size-4",
+  md: "size-6",
+  lg: "size-9",
+} as const
+
+/**
+ * A colour presented **as content**, with a name attached.
+ *
+ * It is not `LiveStatusIndicator`'s dot and not a `Badge`. Both of
+ * those take an `intent`, because both show a *state* whose colour
+ * the design system owns and can name in English. This shows a
+ * colour the system does **not** own and **cannot** name — the red
+ * sticker on a controller, red because someone put a red sticker on
+ * it; the accent castkit pulls off an album; a user's tag colour.
+ * `DOT_SIZE_CLASS` is exported precisely so an app can hand-roll one
+ * of these, and three of them across the fleet did, each without a
+ * name a screen reader could read.
+ *
+ * ### `role="img"`, and the name is required
+ *
+ * A swatch is a graphic that carries meaning, so it is an image with
+ * an accessible name — which makes it findable by
+ * `getByRole("img", { name })` in **both** the dot-only and
+ * labelled forms, one stable handle regardless of whether the text
+ * is on screen. The dot and any visible label are inside it and go
+ * `aria-hidden` by virtue of the name on the wrapper, exactly as an
+ * inline SVG with a caption would.
+ *
+ * ### The ring is not a token
+ *
+ * `solid` sits a translucent white ring inside the fill so a white
+ * or near-white swatch stays visible against `surface-raised` in
+ * both schemes; a hairline border alone disappears on one of the
+ * two. `outline` drops the fill to a faint tint of the same hue and
+ * draws the ring in the colour itself — via an inline `box-shadow`,
+ * because the ring colour has to come from the data and
+ * `--tw-ring-color` is not something `CSSProperties` will type.
+ */
+export const Swatch = ({
+  appearance = "solid",
+  className,
+  color,
+  isLabelVisible = false,
+  label,
+  size = "md",
+  ...spanProps
+}: SwatchProps): ReactNode => (
+  <span
+    {...spanProps}
+    aria-label={label}
+    className={toClassName(
+      "inline-flex items-center gap-2 align-middle",
+      className,
+    )}
+    role="img"
+  >
+    <span
+      aria-hidden="true"
+      className={toClassName(
+        "inline-block shrink-0 rounded-full",
+        SWATCH_SIZE_CLASS[size],
+        appearance === "solid" &&
+          "shadow-low ring-2 ring-white/25 ring-inset",
+      )}
+      style={
+        appearance === "solid"
+          ? { backgroundColor: color }
+          : {
+              backgroundColor: `color-mix(in srgb, ${color} 12%, transparent)`,
+              boxShadow: `inset 0 0 0 3px ${color}`,
+            }
+      }
+    />
+
+    {isLabelVisible ? (
+      <span
+        aria-hidden="true"
+        className="text-content-primary text-sm"
+      >
+        {label}
+      </span>
+    ) : null}
+  </span>
+)

package/src/index.ts

@@ -165,6 +165,12 @@ export type {
 export { SortableTableHeader } from "./SortableTableHeader/SortableTableHeader.tsx"
 export type { SpinnerProps } from "./Spinner/Spinner.tsx"
 export { Spinner } from "./Spinner/Spinner.tsx"
+export type {
+  SwatchAppearance,
+  SwatchProps,
+  SwatchSize,
+} from "./Swatch/Swatch.tsx"
+export { Swatch } from "./Swatch/Swatch.tsx"
 export type { SlotProps } from "./slotProps.ts"
 export { mergeSlotProps } from "./slotProps.ts"
 export {

package/src/sourceRules.test.ts

@@ -300,7 +300,10 @@ test("the barrel is the only place components are re-exported", async () => {
   // `Dialog` and reintroduces `Modal` as the base layer, so both are
   // components: +1 → 29. The picker family adds `Listbox` (single-select)
   // and `Combobox` (searchable/virtualized): +2 → 31.
-  expect(componentNames.length).toBe(31)
+  // `Swatch` — a colour as content with a required name, the one
+  // colour the system does not own — comes out of `portly-controllers`,
+  // the fleet's newest consumer: +1 -> 32.
+  expect(componentNames.length).toBe(32)
 
   for (const name of componentNames) {
     expect(barrel).toContain(`export { ${name} }`)