@awarebydefault/display-case 1.0.0

package/src/ui/design-system/components/controls/SelectMenu.tsx

@@ -0,0 +1,377 @@
+import type { KeyboardEvent as ReactKeyboardEvent, ReactNode } from 'react'
+import { useEffect, useId, useLayoutEffect, useRef, useState } from 'react'
+import { createPortal } from 'react-dom'
+
+/**
+ * Display Case — SelectMenu
+ * An accessible custom single-select, built to the WAI-ARIA "select-only
+ * combobox" pattern: a `role="combobox"` trigger that owns a popup
+ * `role="listbox"` of `role="option"`s, with focus kept on the trigger and the
+ * active option tracked via `aria-activedescendant`. Screen readers announce and
+ * operate it like a native `<select>`, but it commits on click with no OS popup
+ * menu — so the bound value updates *instantly* (a native `<select>` on macOS
+ * defers its `change` event until the native menu finishes dismissing, which
+ * reads as a lag when the bound view updates live).
+ *
+ * Keyboard: ↑/↓ move the active option, Home/End jump to the ends, type-ahead
+ * matches by label, Enter/Space commit, Esc closes without change, Tab commits
+ * then moves on. The popup portals to `document.body` so an `overflow`-clipping
+ * or `position: fixed` ancestor can't trap it.
+ */
+
+export type SelectMenuSize = 'sm' | 'md'
+export type SelectMenuOption =
+  | string
+  /** A non-interactive option renders as a quiet group header — not selectable,
+   *  skipped by keyboard nav and type-ahead. */
+  | { value: string; label?: ReactNode; disabled?: boolean }
+
+export interface SelectMenuProps {
+  options: SelectMenuOption[]
+  value: string
+  onChange: (value: string) => void
+  size?: SelectMenuSize
+  disabled?: boolean
+  'aria-label'?: string
+  id?: string
+}
+
+interface NormOption {
+  value: string
+  label: ReactNode
+  /** Lowercased text used for type-ahead matching. */
+  text: string
+  /** A header row: rendered, but not selectable / navigable / matchable. */
+  disabled: boolean
+}
+
+function normalize(options: SelectMenuOption[]): NormOption[] {
+  return options.map((o) => {
+    if (typeof o === 'string')
+      return { value: o, label: o, text: o.toLowerCase(), disabled: false }
+    const text = typeof o.label === 'string' ? o.label : o.value
+    return {
+      value: o.value,
+      label: o.label ?? o.value,
+      text: text.toLowerCase(),
+      disabled: !!o.disabled,
+    }
+  })
+}
+
+/** Next option (by index, wrapping) whose label starts with the typed buffer.
+ *  Disabled headers are skipped. */
+function findMatch(opts: NormOption[], buffer: string, from: number): number {
+  const n = opts.length
+  if (n === 0) return -1
+  // A single character cycles forward (skip the current match); a longer buffer
+  // may need to land on the current option, so start inclusive.
+  const startK = buffer.length === 1 ? 1 : 0
+  for (let k = startK; k <= n; k++) {
+    const i = (from + k) % n
+    if (!opts[i].disabled && opts[i].text.startsWith(buffer)) return i
+  }
+  return -1
+}
+
+/** First selectable index, or 0 if none. */
+function firstEnabled(opts: NormOption[]): number {
+  const i = opts.findIndex((o) => !o.disabled)
+  return i < 0 ? 0 : i
+}
+
+/** Last selectable index, or `opts.length - 1` if none. */
+function lastEnabled(opts: NormOption[]): number {
+  for (let i = opts.length - 1; i >= 0; i--) if (!opts[i].disabled) return i
+  return opts.length - 1
+}
+
+/** Nearest selectable index strictly past `from` in `dir` (+1/-1); stays put if
+ *  there is none, so a header can never become the active row. */
+function moveEnabled(opts: NormOption[], from: number, dir: 1 | -1): number {
+  for (let i = from + dir; i >= 0 && i < opts.length; i += dir) {
+    if (!opts[i].disabled) return i
+  }
+  return from
+}
+
+interface Coords {
+  left: number
+  top: number
+  minWidth: number
+  maxHeight: number
+  placement: 'down' | 'up'
+}
+
+export function SelectMenu({
+  options,
+  value,
+  onChange,
+  size = 'md',
+  disabled = false,
+  'aria-label': ariaLabel,
+  id,
+}: SelectMenuProps) {
+  const opts = normalize(options)
+  const reactId = useId()
+  const baseId = id ?? reactId
+  const listboxId = `${baseId}-listbox`
+  const optionId = (i: number) => `${baseId}-opt-${i}`
+
+  const rawSelected = opts.findIndex((o) => o.value === value)
+  const selectedIndex = rawSelected >= 0 ? rawSelected : firstEnabled(opts)
+
+  const [open, setOpen] = useState(false)
+  const [activeIndex, setActiveIndex] = useState(selectedIndex)
+  const [coords, setCoords] = useState<Coords | null>(null)
+
+  const triggerRef = useRef<HTMLDivElement | null>(null)
+  const listRef = useRef<HTMLDivElement | null>(null)
+  const activeRef = useRef(activeIndex)
+  activeRef.current = activeIndex
+  // Type-ahead buffer + its reset timer.
+  const bufferRef = useRef('')
+  const timerRef = useRef<ReturnType<typeof setTimeout> | null>(null)
+
+  const openAt = (index: number) => {
+    setActiveIndex(index)
+    setOpen(true)
+  }
+  const close = (focusTrigger = true) => {
+    setOpen(false)
+    if (focusTrigger) triggerRef.current?.focus()
+  }
+  const commit = (index: number) => {
+    const opt = opts[index]
+    if (!opt || opt.disabled) return // headers aren't selectable
+    if (opt.value !== value) onChange(opt.value)
+    close()
+  }
+
+  const typeahead = (char: string) => {
+    bufferRef.current += char.toLowerCase()
+    if (timerRef.current) clearTimeout(timerRef.current)
+    timerRef.current = setTimeout(() => {
+      bufferRef.current = ''
+    }, 500)
+    const match = findMatch(opts, bufferRef.current, activeRef.current)
+    if (match >= 0) setActiveIndex(match)
+  }
+
+  // Position the portaled popup against the trigger, flipping above when there
+  // isn't room below. Measured before paint so it never flashes mispositioned.
+  useLayoutEffect(() => {
+    if (!open || !triggerRef.current) return
+    const r = triggerRef.current.getBoundingClientRect()
+    const margin = 8
+    const spaceBelow = window.innerHeight - r.bottom - margin
+    const spaceAbove = r.top - margin
+    const up = spaceBelow < 160 && spaceAbove > spaceBelow
+    setCoords({
+      left: r.left,
+      top: up ? r.top : r.bottom,
+      minWidth: r.width,
+      maxHeight: Math.max(96, up ? spaceAbove : spaceBelow),
+      placement: up ? 'up' : 'down',
+    })
+  }, [open])
+
+  // Keep the active option scrolled into view as it moves. `optionId` is a
+  // stable id formatter (baseId is fixed for the component's life).
+  // biome-ignore lint/correctness/useExhaustiveDependencies: optionId is stable; open/activeIndex drive the effect
+  useEffect(() => {
+    if (!open) return
+    document
+      .getElementById(optionId(activeIndex))
+      ?.scrollIntoView({ block: 'nearest' })
+  }, [open, activeIndex])
+
+  // While open, dismiss on an outside press or on any ancestor scroll/resize
+  // (the popup is fixed-positioned, so a scroll would otherwise strand it).
+  useEffect(() => {
+    if (!open) return
+    const onDown = (e: PointerEvent) => {
+      const t = e.target as Node
+      if (triggerRef.current?.contains(t) || listRef.current?.contains(t))
+        return
+      setOpen(false)
+    }
+    const onScroll = (e: Event) => {
+      // Ignore the popup's own internal scroll.
+      if (e.target instanceof Node && listRef.current?.contains(e.target))
+        return
+      setOpen(false)
+    }
+    const onResize = () => setOpen(false)
+    document.addEventListener('pointerdown', onDown, true)
+    window.addEventListener('scroll', onScroll, true)
+    window.addEventListener('resize', onResize)
+    return () => {
+      document.removeEventListener('pointerdown', onDown, true)
+      window.removeEventListener('scroll', onScroll, true)
+      window.removeEventListener('resize', onResize)
+    }
+  }, [open])
+
+  // Drop a stale type-ahead timer on unmount.
+  useEffect(
+    () => () => {
+      if (timerRef.current) clearTimeout(timerRef.current)
+    },
+    [],
+  )
+
+  const isPrintable = (e: ReactKeyboardEvent) =>
+    e.key.length === 1 && !e.metaKey && !e.ctrlKey && !e.altKey
+
+  const onKeyDown = (e: ReactKeyboardEvent<HTMLDivElement>) => {
+    if (disabled) return
+    if (!open) {
+      switch (e.key) {
+        case 'ArrowDown':
+        case 'ArrowUp':
+        case 'Enter':
+        case ' ':
+        case 'Spacebar':
+          e.preventDefault()
+          openAt(selectedIndex)
+          return
+        case 'Home':
+          e.preventDefault()
+          openAt(firstEnabled(opts))
+          return
+        case 'End':
+          e.preventDefault()
+          openAt(lastEnabled(opts))
+          return
+        default:
+          if (isPrintable(e)) {
+            e.preventDefault()
+            setOpen(true)
+            typeahead(e.key)
+          }
+          return
+      }
+    }
+    switch (e.key) {
+      case 'ArrowDown':
+        e.preventDefault()
+        setActiveIndex((i) => moveEnabled(opts, i, 1))
+        break
+      case 'ArrowUp':
+        e.preventDefault()
+        setActiveIndex((i) => moveEnabled(opts, i, -1))
+        break
+      case 'Home':
+        e.preventDefault()
+        setActiveIndex(firstEnabled(opts))
+        break
+      case 'End':
+        e.preventDefault()
+        setActiveIndex(lastEnabled(opts))
+        break
+      case 'Enter':
+      case ' ':
+      case 'Spacebar':
+        e.preventDefault()
+        commit(activeIndex)
+        break
+      case 'Escape':
+        e.preventDefault()
+        close()
+        break
+      case 'Tab':
+        // Commit the active option, then let focus move on naturally.
+        commit(activeIndex)
+        break
+      default:
+        if (isPrintable(e)) {
+          e.preventDefault()
+          typeahead(e.key)
+        }
+    }
+  }
+
+  const onTriggerClick = () => {
+    if (disabled) return
+    if (open) setOpen(false)
+    else openAt(selectedIndex)
+  }
+
+  const selected = opts[selectedIndex]
+
+  return (
+    <span className="dcui-selectmenu dcui-select" data-size={size}>
+      <div
+        ref={triggerRef}
+        role="combobox"
+        tabIndex={disabled ? -1 : 0}
+        aria-haspopup="listbox"
+        aria-expanded={open}
+        aria-controls={listboxId}
+        aria-label={ariaLabel}
+        aria-disabled={disabled || undefined}
+        aria-activedescendant={open ? optionId(activeIndex) : undefined}
+        className="dcui-select-el dcui-selectmenu-trigger"
+        onClick={onTriggerClick}
+        onKeyDown={onKeyDown}>
+        <span className="dcui-selectmenu-value">
+          {selected?.label ?? value}
+        </span>
+      </div>
+      <span className="dcui-select-caret" aria-hidden="true">
+        ▾
+      </span>
+      {open &&
+        coords &&
+        createPortal(
+          <div
+            ref={listRef}
+            id={listboxId}
+            role="listbox"
+            aria-label={ariaLabel}
+            className="dcui-selectmenu-list"
+            data-size={size}
+            style={{
+              left: coords.left,
+              minWidth: coords.minWidth,
+              maxHeight: coords.maxHeight,
+              ...(coords.placement === 'up'
+                ? { top: coords.top, transform: 'translateY(-100%)' }
+                : { top: coords.top }),
+            }}>
+            {opts.map((o, i) => {
+              const isSelected = !o.disabled && o.value === value
+              return (
+                // Options are pointer affordances only: focus stays on the
+                // combobox trigger (aria-activedescendant) and all keyboard
+                // handling lives there, so these two rules don't apply here.
+                // biome-ignore lint/a11y/useFocusableInteractive: combobox keeps focus; option is tracked via aria-activedescendant
+                // biome-ignore lint/a11y/useKeyWithClickEvents: keyboard handled on the combobox trigger, not per-option
+                <div
+                  key={o.value}
+                  id={optionId(i)}
+                  role="option"
+                  aria-selected={isSelected}
+                  aria-disabled={o.disabled || undefined}
+                  data-active={!o.disabled && i === activeIndex}
+                  className="dcui-selectmenu-option"
+                  onMouseEnter={
+                    o.disabled ? undefined : () => setActiveIndex(i)
+                  }
+                  // Keep focus on the combobox trigger (the menu commits on click).
+                  onMouseDown={(e) => e.preventDefault()}
+                  onClick={o.disabled ? undefined : () => commit(i)}>
+                  <span className="dcui-selectmenu-check" aria-hidden="true">
+                    {isSelected ? '✓' : ''}
+                  </span>
+                  {o.label}
+                </div>
+              )
+            })}
+          </div>,
+          document.body,
+        )}
+    </span>
+  )
+}

package/src/ui/design-system/components/index.ts

@@ -0,0 +1,66 @@
+/**
+ * Display Case design-system components — "The Vitrine".
+ * Self-contained, pure React components (each brings its own CSS). Used by the
+ * browse chrome and dogfooded as Display Case's own showcased components.
+ */
+
+export type { ButtonProps, ButtonSize, ButtonVariant } from './controls/Button'
+export { Button } from './controls/Button'
+export type {
+  IconButtonProps,
+  IconButtonSize,
+  IconButtonVariant,
+} from './controls/IconButton'
+export { IconButton } from './controls/IconButton'
+export type { InputProps, InputSize } from './controls/Input'
+export { Input } from './controls/Input'
+export type {
+  SelectItem,
+  SelectOption,
+  SelectOptionGroup,
+  SelectProps,
+  SelectSize,
+} from './controls/Select'
+export { Select } from './controls/Select'
+export type {
+  SelectMenuOption,
+  SelectMenuProps,
+  SelectMenuSize,
+} from './controls/SelectMenu'
+export { SelectMenu } from './controls/SelectMenu'
+// Reusable Primer foundation specimens (ramps, swatches, type scale, glyphs…)
+// — generic, prop-driven primitives for building a Primer.
+export * from './primer-specimen'
+export type { A11yBadgeProps } from './showcase/A11yBadge'
+export { A11yBadge } from './showcase/A11yBadge'
+export type { A11yPanelProps } from './showcase/A11yPanel'
+export { A11yPanel } from './showcase/A11yPanel'
+export type { ChipProps, ChipVariant } from './showcase/Chip'
+export { Chip } from './showcase/Chip'
+export type { EyebrowProps, EyebrowTone } from './showcase/Eyebrow'
+export { Eyebrow } from './showcase/Eyebrow'
+export type { FlowNavProps, FlowStep } from './showcase/FlowNav'
+export { FlowNav } from './showcase/FlowNav'
+export type { ImpactTagProps } from './showcase/ImpactTag'
+export { ImpactTag, impactRank } from './showcase/ImpactTag'
+export type { NavItemKind, NavItemProps } from './showcase/NavItem'
+export { NavItem } from './showcase/NavItem'
+export type { RenderAddressProps } from './showcase/RenderAddress'
+export { RenderAddress } from './showcase/RenderAddress'
+export type {
+  SegmentedOption,
+  SegmentedToggleProps,
+} from './showcase/SegmentedToggle'
+export { SegmentedToggle } from './showcase/SegmentedToggle'
+export type { SidebarProps } from './showcase/Sidebar'
+export { Sidebar } from './showcase/Sidebar'
+export type { StageProps } from './showcase/Stage'
+export { Stage } from './showcase/Stage'
+export type {
+  TweakItem,
+  TweaksMode,
+  TweaksPanelProps,
+} from './showcase/TweaksPanel'
+export { Row as TweakRow, TweaksPanel } from './showcase/TweaksPanel'
+export type { WordmarkProps } from './showcase/Wordmark'
+export { Wordmark } from './showcase/Wordmark'

package/src/ui/design-system/components/primer-specimen/ColorRamp.case.tsx

@@ -0,0 +1,44 @@
+import { defineCases, tweak } from '@awarebydefault/display-case'
+import { ColorRamp, type ColorStop } from './ColorRamp'
+
+const marigold: ColorStop[] = [
+  { name: 'marigold-300', color: 'var(--dc-marigold-300)', caption: '#f6c878' },
+  { name: 'marigold-400', color: 'var(--dc-marigold-400)', caption: '#f0a23b' },
+  { name: 'marigold-500', color: 'var(--dc-marigold-500)', caption: '#e0820b' },
+  {
+    name: 'marigold-600',
+    color: 'var(--dc-marigold-600)',
+    caption: '#c2690a',
+    star: true,
+  },
+  { name: 'marigold-700', color: 'var(--dc-marigold-700)', caption: '#9a4f0a' },
+]
+
+const paper: ColorStop[] = [
+  { name: 'paper-100', color: 'var(--dc-paper-100)', caption: '#f4f1e9' },
+  { name: 'paper-300', color: 'var(--dc-paper-300)', caption: '#d6cebe' },
+  { name: 'paper-500', color: 'var(--dc-paper-500)', caption: '#8a8073' },
+  { name: 'paper-700', color: 'var(--dc-paper-700)', caption: '#4a423a' },
+  { name: 'paper-900', color: 'var(--dc-paper-900)', caption: '#211d18' },
+]
+
+export default defineCases(
+  'ColorRamp',
+  {
+    Playground: {
+      tweaks: {
+        chipHeight: tweak.number(56),
+        star: tweak.boolean(true),
+      },
+      render: (t) => (
+        <ColorRamp
+          chipHeight={t.chipHeight}
+          stops={marigold.map((s) => ({ ...s, star: s.star && t.star }))}
+        />
+      ),
+    },
+    Accent: () => <ColorRamp stops={marigold} />,
+    Neutral: () => <ColorRamp stops={paper} chipHeight={48} />,
+  },
+  { level: 'molecule' },
+)

package/src/ui/design-system/components/primer-specimen/ColorRamp.placard.md

@@ -0,0 +1,15 @@
+**ColorRamp** — a horizontal ramp of an ORDERED single-family palette (an accent ramp, a neutral ramp), each stop a chip over a label and optional caption. Reach for it when the stops have a meaningful sequence.
+
+```tsx
+<ColorRamp
+  chipHeight={56}
+  stops={[
+    { name: 'marigold-500', color: 'var(--dc-marigold-500)', caption: '#e0820b' },
+    { name: 'marigold-600', color: 'var(--dc-marigold-600)', caption: '#c2690a', star: true },
+  ]}
+/>
+```
+
+For unordered semantic role tokens, reach for `SwatchGrid`.
+
+Keep each `color` as the whole `var(--dc-…)` literal so the token check resolves it. `star` marks the canonical stop with a marigold ★.

package/src/ui/design-system/components/primer-specimen/ColorRamp.tsx

@@ -0,0 +1,51 @@
+/**
+ * Display Case — ColorRamp
+ * A horizontal ramp of colour stops with a label + caption under each chip.
+ * Generic specimen primitive for a Primer: feed it any ordered set of stops
+ * (an accent ramp, a neutral ramp, a brand palette) and it renders the swatches.
+ *
+ * Pass each stop's colour as a complete CSS value (`var(--dc-marigold-600)` or
+ * `#c2690a`) — keep the whole `var(...)` string literal rather than templating
+ * it, so the token-conformance check can statically resolve the reference.
+ */
+
+export interface ColorStop {
+  /** Display label under the chip (also the React key). */
+  name: string
+  /** Complete CSS colour value painted on the chip, e.g. `var(--dc-marigold-600)`. */
+  color: string
+  /** Optional caption under the name — typically the resolved hex. */
+  caption?: string
+  /** Marks the canonical stop with a marigold star. */
+  star?: boolean
+}
+
+export interface ColorRampProps {
+  stops: ColorStop[]
+  /** Chip height in pixels. */
+  chipHeight?: number
+}
+
+export function ColorRamp({ stops, chipHeight = 56 }: ColorRampProps) {
+  return (
+    <div
+      className="dcpl-ramp"
+      style={{ gridTemplateColumns: `repeat(${stops.length}, 1fr)` }}>
+      {stops.map((s) => (
+        <div className="dcpl-sw" key={s.name}>
+          <div
+            className="dcpl-sw-chip"
+            style={{ height: `${chipHeight}px`, background: s.color }}
+          />
+          <div className="dcpl-sw-meta">
+            <div className="dcpl-sw-name">
+              {s.name}
+              {s.star ? <span className="dcpl-sw-star"> ★</span> : null}
+            </div>
+            {s.caption ? <div className="dcpl-sw-hex">{s.caption}</div> : null}
+          </div>
+        </div>
+      ))}
+    </div>
+  )
+}

package/src/ui/design-system/components/primer-specimen/DefinitionList.case.tsx

@@ -0,0 +1,38 @@
+import { defineCases, tweak } from '@awarebydefault/display-case'
+import { type DefEntry, DefinitionList } from './DefinitionList'
+
+const voice: DefEntry[] = [
+  {
+    term: 'Voice',
+    description:
+      'Plain, confident, technical-but-warm. It explains why, briefly, then moves on.',
+  },
+  {
+    term: 'Casing',
+    description: (
+      <>
+        Sentence case everywhere. The one exception is the{' '}
+        <strong>eyebrow label</strong>: uppercase mono with wide tracking.
+      </>
+    ),
+  },
+  {
+    term: 'Length',
+    description:
+      'Terse. Buttons are one or two words; labels are a single token.',
+  },
+]
+
+export default defineCases(
+  'DefinitionList',
+  {
+    Playground: {
+      tweaks: { termWidth: tweak.text('7.5rem') },
+      render: (t) => (
+        <DefinitionList entries={voice} termWidth={t.termWidth || undefined} />
+      ),
+    },
+    Voice: () => <DefinitionList entries={voice} />,
+  },
+  { level: 'molecule' },
+)

package/src/ui/design-system/components/primer-specimen/DefinitionList.placard.md

@@ -0,0 +1,15 @@
+**DefinitionList** — a bordered list of term / description rows, the term a mono uppercase accent eyebrow; reach for it to lay out voice rules, content fundamentals, or any keyed reference prose.
+
+```tsx
+<DefinitionList
+  termWidth="7.5rem"
+  entries={[
+    { term: 'Voice', description: 'Plain, confident, technical-but-warm.' },
+    { term: 'Casing', description: <>Sentence case, except the <strong>eyebrow</strong>.</> },
+  ]}
+/>
+```
+
+Use this for free-form prose keyed by a term. For a fixed legend of dot-keyed statuses, reach for `StatusList`.
+
+`description` accepts rich nodes (`<strong>` and other emphasis welcome), not just plain text.

package/src/ui/design-system/components/primer-specimen/DefinitionList.tsx

@@ -0,0 +1,41 @@
+import type { CSSProperties, ReactNode } from 'react'
+
+/**
+ * Display Case — DefinitionList
+ * A bordered list of term / description rows. The term is a mono uppercase
+ * eyebrow in the accent colour; the description is body text that may include
+ * `<strong>` emphasis. Generic specimen primitive for a Primer — use it to lay
+ * out voice rules, content fundamentals, or any keyed reference.
+ */
+
+export interface DefEntry {
+  /** Mono uppercase term shown in the accent colour (also the React key). */
+  term: string
+  /** Description body — plain text or rich nodes (e.g. `<strong>`). */
+  description: ReactNode
+}
+
+export interface DefinitionListProps {
+  entries: DefEntry[]
+  /** Width of the term column (any CSS length). */
+  termWidth?: string
+}
+
+export function DefinitionList({
+  entries,
+  termWidth = '7.5rem',
+}: DefinitionListProps) {
+  return (
+    <div className="dcpl-deflist">
+      {entries.map((e) => (
+        <div
+          className="dcpl-defrow"
+          key={e.term}
+          style={{ '--dcpl-term-width': termWidth } as CSSProperties}>
+          <div className="dcpl-defterm">{e.term}</div>
+          <div className="dcpl-defdesc">{e.description}</div>
+        </div>
+      ))}
+    </div>
+  )
+}

package/src/ui/design-system/components/primer-specimen/FontFamilies.case.tsx

@@ -0,0 +1,24 @@
+import { defineCases } from '@awarebydefault/display-case'
+import { FontFamilies, type FontFamily } from './FontFamilies'
+
+const pairing: FontFamily[] = [
+  {
+    tag: 'Sans · UI',
+    sample: 'Display Case shows the work, not itself',
+    note: 'Hanken Grotesk, ui-sans-serif, system-ui…',
+  },
+  {
+    tag: 'Mono · Code',
+    sample: '/render/<component>/<case>?theme=dark',
+    note: 'JetBrains Mono, ui-monospace, "SF Mono", Menlo…',
+    mono: true,
+  },
+]
+
+export default defineCases(
+  'FontFamilies',
+  {
+    Pairing: () => <FontFamilies families={pairing} />,
+  },
+  { level: 'molecule' },
+)

package/src/ui/design-system/components/primer-specimen/FontFamilies.placard.md

@@ -0,0 +1,12 @@
+**FontFamilies** — a stack of font-family rows, each a mono tag, a large sample in the family, and a mono note listing the stack; reach for it to document a type pairing (a UI sans, a code mono).
+
+```tsx
+<FontFamilies
+  families={[
+    { tag: 'Sans · UI', sample: 'The quick brown fox', note: 'Hanken Grotesk, system-ui…' },
+    { tag: 'Mono · Code', sample: 'render(case)', note: 'JetBrains Mono…', mono: true },
+  ]}
+/>
+```
+
+This documents which families exist. For size steps reach for `TypeScale`; for weights reach for `WeightSpecimen`.