@awarebydefault/display-case 1.0.0

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

@@ -0,0 +1,41 @@
+/**
+ * Display Case — FontFamilies
+ * A stack of font-family rows: a mono tag, a large sample set in the family, and
+ * a mono note listing the stack. Generic specimen primitive for a Primer — use
+ * it to document a type pairing (a UI sans, a code mono, …).
+ */
+
+export interface FontFamily {
+  /** Mono uppercase tag (e.g. `Sans · UI`); also the React key. */
+  tag: string
+  /** Large sample, rendered in this family. */
+  sample: string
+  /** Mono note under the sample — typically the font stack. */
+  note?: string
+  /** Render the sample in the mono family instead of the sans family. */
+  mono?: boolean
+}
+
+export interface FontFamiliesProps {
+  families: FontFamily[]
+}
+
+export function FontFamilies({ families }: FontFamiliesProps) {
+  return (
+    <div className="dcpl-fam">
+      {families.map((f) => (
+        <div className="dcpl-famrow" key={f.tag}>
+          <div className="dcpl-famtag">{f.tag}</div>
+          <div>
+            <div
+              className="dcpl-famsample"
+              data-font={f.mono ? 'mono' : 'sans'}>
+              {f.sample}
+            </div>
+            {f.note ? <div className="dcpl-famnote">{f.note}</div> : null}
+          </div>
+        </div>
+      ))}
+    </div>
+  )
+}

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

@@ -0,0 +1,27 @@
+import { defineCases, tweak } from '@awarebydefault/display-case'
+import { GlyphGrid, type GlyphSpec } from './GlyphGrid'
+
+const glyphs: GlyphSpec[] = [
+  { glyph: '☰', use: 'Toggle nav' },
+  { glyph: '▸', use: 'Disclosure' },
+  { glyph: '⟲', use: 'Rotate' },
+  { glyph: '✕', use: 'Close' },
+  { glyph: '★', use: 'Emphasis' },
+  { glyph: '←', use: 'Prev' },
+  { glyph: '→', use: 'Next' },
+  { glyph: '＋', use: 'Zoom in' },
+  { glyph: '−', use: 'Zoom out' },
+  { glyph: '×', use: 'Dimension' },
+]
+
+export default defineCases(
+  'GlyphGrid',
+  {
+    Playground: {
+      tweaks: { columns: tweak.number(5) },
+      render: (t) => <GlyphGrid glyphs={glyphs} columns={t.columns} />,
+    },
+    Vocabulary: () => <GlyphGrid glyphs={glyphs} />,
+  },
+  { level: 'molecule' },
+)

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

@@ -0,0 +1,13 @@
+**GlyphGrid** — a grid of glyph tiles, each a large glyph over a short usage caption; reach for it to document an icon vocabulary (Unicode glyphs, an icon-font codepoint set, or any single-character marks).
+
+```tsx
+<GlyphGrid
+  columns={5}
+  glyphs={[
+    { glyph: '☰', use: 'Toggle nav' },
+    { glyph: '✕', use: 'Close' },
+  ]}
+/>
+```
+
+`use` doubles as the React key — keep captions unique across the grid.

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

@@ -0,0 +1,34 @@
+/**
+ * Display Case — GlyphGrid
+ * A grid of glyph tiles, each a large glyph over a short usage caption. Generic
+ * specimen primitive for a Primer — use it to document an icon vocabulary
+ * (Unicode glyphs, an icon-font codepoint set, or any single-character marks).
+ */
+
+export interface GlyphSpec {
+  /** The glyph to render large. */
+  glyph: string
+  /** Short usage caption (also the React key). */
+  use: string
+}
+
+export interface GlyphGridProps {
+  glyphs: GlyphSpec[]
+  /** Number of columns in the grid. */
+  columns?: number
+}
+
+export function GlyphGrid({ glyphs, columns = 5 }: GlyphGridProps) {
+  return (
+    <div
+      className="dcpl-icongrid"
+      style={{ gridTemplateColumns: `repeat(${columns}, 1fr)` }}>
+      {glyphs.map((g) => (
+        <div className="dcpl-iconitem" key={g.use}>
+          <div className="dcpl-iconglyph">{g.glyph}</div>
+          <div className="dcpl-iconuse">{g.use}</div>
+        </div>
+      ))}
+    </div>
+  )
+}

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

@@ -0,0 +1,36 @@
+import { defineCases, tweak } from '@awarebydefault/display-case'
+import { LayoutMock } from './LayoutMock'
+
+export default defineCases(
+  'LayoutMock',
+  {
+    Playground: {
+      tweaks: {
+        header: tweak.text('header'),
+        sidebar: tweak.text('sidebar'),
+        main: tweak.text('main · the stage'),
+        sidebarWidth: tweak.text('32%'),
+      },
+      render: (t) => (
+        <LayoutMock
+          header={t.header}
+          sidebar={t.sidebar}
+          main={t.main}
+          sidebarWidth={t.sidebarWidth || undefined}
+        />
+      ),
+    },
+    Shell: () => (
+      <LayoutMock header="header" sidebar="sidebar" main="main · the stage" />
+    ),
+    WideSidebar: () => (
+      <LayoutMock
+        header="toolbar"
+        sidebar="nav tree"
+        main="preview"
+        sidebarWidth="44%"
+      />
+    ),
+  },
+  { level: 'molecule' },
+)

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

@@ -0,0 +1,7 @@
+**LayoutMock** — a miniature three-region wireframe (header over a sidebar + main split); reach for it to sketch an app's shell layout without committing to real chrome.
+
+```tsx
+<LayoutMock header="header" sidebar="sidebar" main="main · the stage" />
+```
+
+Each region takes any node; omit one to leave it empty. `sidebarWidth` defaults `32%`.

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

@@ -0,0 +1,36 @@
+import type { ReactNode } from 'react'
+
+/**
+ * Display Case — LayoutMock
+ * A miniature three-region wireframe — header over a sidebar + main split.
+ * Generic specimen primitive for a Primer — use it to sketch an app's shell
+ * layout without committing to real chrome. Each region accepts any label or
+ * node; omit a region to leave it empty.
+ */
+
+export interface LayoutMockProps {
+  header?: ReactNode
+  sidebar?: ReactNode
+  main?: ReactNode
+  /** Width of the sidebar region (any CSS length). */
+  sidebarWidth?: string
+}
+
+export function LayoutMock({
+  header = 'header',
+  sidebar = 'sidebar',
+  main = 'main',
+  sidebarWidth = '32%',
+}: LayoutMockProps) {
+  return (
+    <div className="dcpl-layout">
+      <div className="dcpl-layout-head">{header}</div>
+      <div className="dcpl-layout-body">
+        <div className="dcpl-layout-side" style={{ width: sidebarWidth }}>
+          {sidebar}
+        </div>
+        <div className="dcpl-layout-main">{main}</div>
+      </div>
+    </div>
+  )
+}

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

@@ -0,0 +1,20 @@
+import { defineCases } from '@awarebydefault/display-case'
+import { type SpaceStep, SpacingScale } from './SpacingScale'
+
+const steps: SpaceStep[] = [
+  { token: 'space-1', value: '2px', width: 2 },
+  { token: 'space-2', value: '4px', width: 4 },
+  { token: 'space-4', value: '8px', width: 8 },
+  { token: 'space-6', value: '12px', width: 12 },
+  { token: 'space-8', value: '16px', width: 16 },
+  { token: 'space-10', value: '20px', width: 20 },
+  { token: 'space-16', value: '32px', width: 32 },
+]
+
+export default defineCases(
+  'SpacingScale',
+  {
+    Scale: () => <SpacingScale steps={steps} />,
+  },
+  { level: 'molecule' },
+)

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

@@ -0,0 +1,12 @@
+**SpacingScale** — a column of spacing rows, each a mono token tag, its resolved value, and a bar whose width visualises the step; reach for it to show a spacing scale to scale.
+
+```tsx
+<SpacingScale
+  steps={[
+    { token: 'space-4', value: '8px', width: 8 },
+    { token: 'space-8', value: '16px', width: 16 },
+  ]}
+/>
+```
+
+`value` (the display string) and `width` (the bar length in px) are independent inputs the caller keeps in sync — neither is derived from the other, so a mismatch will silently render a misleading bar.

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

@@ -0,0 +1,33 @@
+/**
+ * Display Case — SpacingScale
+ * A column of spacing rows: a mono token tag, its resolved value, and a bar
+ * whose width visualises the step. Generic specimen primitive for a Primer —
+ * use it to show a spacing scale to scale.
+ */
+
+export interface SpaceStep {
+  /** Mono token tag (e.g. `space-4`); also the React key. */
+  token: string
+  /** Resolved value shown in mono (e.g. `8px`). */
+  value: string
+  /** Bar width in pixels — visualises the step. */
+  width: number
+}
+
+export interface SpacingScaleProps {
+  steps: SpaceStep[]
+}
+
+export function SpacingScale({ steps }: SpacingScaleProps) {
+  return (
+    <div className="dcpl-spacescale">
+      {steps.map((s) => (
+        <div className="dcpl-spacerow" key={s.token}>
+          <div className="dcpl-spacetag">{s.token}</div>
+          <div className="dcpl-spacepx">{s.value}</div>
+          <div className="dcpl-spacebar" style={{ width: `${s.width}px` }} />
+        </div>
+      ))}
+    </div>
+  )
+}

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

@@ -0,0 +1,56 @@
+import { defineCases } from '@awarebydefault/display-case'
+import { type BoxSpec, SpecimenBoxRow } from './SpecimenBoxRow'
+
+const radii: BoxSpec[] = [
+  { label: 'none', note: '0', boxStyle: { borderRadius: '0' } },
+  {
+    label: 'sm',
+    note: '5px · controls',
+    boxStyle: { borderRadius: 'var(--dc-radius-sm)' },
+  },
+  {
+    label: 'md',
+    note: '8px · panels',
+    boxStyle: { borderRadius: 'var(--dc-radius-md)' },
+  },
+  {
+    label: 'full',
+    note: 'pills · dots',
+    boxStyle: { borderRadius: 'var(--dc-radius-full)', width: '48px' },
+  },
+]
+
+const elevation: BoxSpec[] = [
+  {
+    note: 'border-line',
+    content: '1px border',
+    boxStyle: {
+      width: '134px',
+      height: '56px',
+      background: 'var(--dc-surface)',
+      borderRadius: 'var(--dc-radius-md)',
+      border: 'var(--dc-border-line)',
+    },
+  },
+  {
+    note: 'menus / popovers only',
+    content: 'overlay',
+    boxStyle: {
+      width: '134px',
+      height: '56px',
+      background: 'var(--dc-surface)',
+      borderRadius: 'var(--dc-radius-md)',
+      border: 'var(--dc-border-line)',
+      boxShadow: 'var(--dc-shadow-overlay)',
+    },
+  },
+]
+
+export default defineCases(
+  'SpecimenBoxRow',
+  {
+    Radius: () => <SpecimenBoxRow items={radii} />,
+    Elevation: () => <SpecimenBoxRow items={elevation} />,
+  },
+  { level: 'molecule' },
+)

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

@@ -0,0 +1,17 @@
+**SpecimenBoxRow** — a row of labelled boxes, each a flat surface whose own style carries the thing
+being shown (a corner radius, a border weight, an elevation shadow), over a
+label + note. A reusable Primer specimen that generalises the radius and
+elevation rows, so one component documents any box-led token.
+
+```tsx
+<SpecimenBoxRow
+  items={[
+    { label: 'md', note: '8px · panels', boxStyle: { borderRadius: 'var(--dc-radius-md)' } },
+    { note: 'overlay', content: 'overlay', boxStyle: { boxShadow: 'var(--dc-shadow-overlay)' } },
+  ]}
+/>
+```
+
+`boxStyle` paints the specimen itself (radius, border, shadow…); `content` is an optional node centred inside the box.
+
+Use this when the token IS the box's own shape. For a flat colour chip beside a token use `SwatchGrid`; for a width bar use `SpacingScale`; for a glyph tile use `GlyphGrid`.

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

@@ -0,0 +1,45 @@
+import type { CSSProperties, ReactNode } from 'react'
+
+/**
+ * Display Case — SpecimenBoxRow
+ * A row of labelled boxes — each a flat surface whose own style carries the
+ * thing being shown (a corner radius, a border weight, an elevation shadow),
+ * over a label + note. Generic specimen primitive for a Primer: it generalises
+ * the radius and elevation rows, so one component documents any box-led token.
+ */
+
+export interface BoxSpec {
+  /** Bold label under the box (also the React key when `note` is absent). */
+  label?: string
+  /** Mono caption under the label. */
+  note?: string
+  /** Style applied to the box — the specimen itself (radius, border, shadow…). */
+  boxStyle?: CSSProperties
+  /** Optional content rendered inside the box (centred). */
+  content?: ReactNode
+}
+
+export interface SpecimenBoxRowProps {
+  items: BoxSpec[]
+}
+
+export function SpecimenBoxRow({ items }: SpecimenBoxRowProps) {
+  return (
+    <div className="dcpl-boxrow">
+      {items.map((item, i) => (
+        <div
+          className="dcpl-boxitem"
+          // Labels/notes may repeat across a row, so fall back to the index.
+          key={item.label ?? item.note ?? i}>
+          <div className="dcpl-box" style={item.boxStyle}>
+            {item.content}
+          </div>
+          <div className="dcpl-boxlbl">
+            {item.label ? <b>{item.label}</b> : null}
+            {item.note ? <span>{item.note}</span> : null}
+          </div>
+        </div>
+      ))}
+    </div>
+  )
+}

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

@@ -0,0 +1,17 @@
+import { defineCases } from '@awarebydefault/display-case'
+import { type StatusItem, StatusList } from './StatusList'
+
+const hues: StatusItem[] = [
+  { name: 'success', color: 'var(--dc-success)', caption: 'green-600' },
+  { name: 'warning', color: 'var(--dc-warning)', caption: 'amber-500' },
+  { name: 'danger', color: 'var(--dc-danger)', caption: 'red-600' },
+]
+
+export default defineCases(
+  'StatusList',
+  {
+    Statuses: () => <StatusList items={hues} />,
+    Single: () => <StatusList items={[hues[0]]} />,
+  },
+  { level: 'molecule' },
+)

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

@@ -0,0 +1,16 @@
+**StatusList** — a row of status items, a coloured dot beside a name and a short caption, each
+boxed in a hairline card. A reusable Primer specimen for documenting a small
+reserved set of status hues (pass, warn, fail) or any dot-keyed legend.
+
+```tsx
+<StatusList
+  items={[
+    { name: 'success', color: 'var(--dc-success)', caption: 'green-600' },
+    { name: 'danger', color: 'var(--dc-danger)', caption: 'red-600' },
+  ]}
+/>
+```
+
+Keep each `color` as the whole `var(--dc-…)` literal so the token check resolves it.
+
+Use this for a fixed legend of named statuses. For an ordered single-family ramp reach for `ColorRamp`; for a grid of semantic role tokens reach for `SwatchGrid`.

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

@@ -0,0 +1,39 @@
+/**
+ * Display Case — StatusList
+ * A row of status items: a coloured dot beside a name and a short caption, each
+ * boxed in a hairline card. Generic specimen primitive for a Primer — use it to
+ * document a small reserved set of status hues (pass, warn, fail) or any other
+ * dot-keyed legend.
+ *
+ * Each item's `color` is a complete CSS value (`var(--dc-success)` or a hex);
+ * keep the whole `var(...)` literal so the token-conformance check resolves it.
+ */
+
+export interface StatusItem {
+  /** Status name shown in bold (also the React key). */
+  name: string
+  /** Complete CSS colour value painted on the dot. */
+  color: string
+  /** Short caption under the name (e.g. the underlying token). */
+  caption?: string
+}
+
+export interface StatusListProps {
+  items: StatusItem[]
+}
+
+export function StatusList({ items }: StatusListProps) {
+  return (
+    <div className="dcpl-status">
+      {items.map((s) => (
+        <div className="dcpl-statusitem" key={s.name}>
+          <div className="dcpl-statusdot" style={{ background: s.color }} />
+          <div>
+            <b>{s.name}</b>
+            {s.caption ? <span>{s.caption}</span> : null}
+          </div>
+        </div>
+      ))}
+    </div>
+  )
+}

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

@@ -0,0 +1,26 @@
+import { defineCases, tweak } from '@awarebydefault/display-case'
+import { type Swatch, SwatchGrid } from './SwatchGrid'
+
+const roles: Swatch[] = [
+  { token: 'bg', color: 'var(--dc-bg)', role: 'canvas' },
+  { token: 'bg-subtle', color: 'var(--dc-bg-subtle)', role: 'sidebar' },
+  { token: 'surface', color: 'var(--dc-surface)', role: 'inputs' },
+  { token: 'border', color: 'var(--dc-border)', role: 'hairline' },
+  { token: 'fg', color: 'var(--dc-fg)', role: 'text' },
+  { token: 'fg-muted', color: 'var(--dc-fg-muted)', role: 'labels' },
+  { token: 'brand', color: 'var(--dc-brand)', role: 'accent' },
+  { token: 'brand-subtle', color: 'var(--dc-brand-subtle)', role: 'wash' },
+]
+
+export default defineCases(
+  'SwatchGrid',
+  {
+    Playground: {
+      tweaks: { columns: tweak.number(4) },
+      render: (t) => <SwatchGrid swatches={roles} columns={t.columns} />,
+    },
+    Roles: () => <SwatchGrid swatches={roles} />,
+    TwoUp: () => <SwatchGrid swatches={roles} columns={2} />,
+  },
+  { level: 'molecule' },
+)

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

@@ -0,0 +1,15 @@
+**SwatchGrid** — a grid of UNORDERED semantic role tokens, each a colour chip beside a token name and a short role note; reach for it to document the roles a system exposes (canvas, surface, border, text, accent…).
+
+```tsx
+<SwatchGrid
+  columns={4}
+  swatches={[
+    { token: 'surface', color: 'var(--dc-surface)', role: 'inputs' },
+    { token: 'brand', color: 'var(--dc-brand)', role: 'accent' },
+  ]}
+/>
+```
+
+For an ordered single family shown as a ramp, reach for `ColorRamp`.
+
+Keep each `color` as the whole `var(--dc-…)` literal so the token check resolves it.

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

@@ -0,0 +1,42 @@
+/**
+ * Display Case — SwatchGrid
+ * A grid of role swatches: a colour chip beside a token name and a short role
+ * note. Generic specimen primitive for a Primer — use it to document the
+ * semantic role tokens a system exposes (canvas, surface, border, text, accent…).
+ *
+ * Each swatch's `color` is a complete CSS value (`var(--dc-surface)` or a hex);
+ * keep the whole `var(...)` literal so the token-conformance check resolves it.
+ */
+
+export interface Swatch {
+  /** Token name shown in bold (also the React key). */
+  token: string
+  /** Complete CSS colour value painted on the chip. */
+  color: string
+  /** Short role note under the token. */
+  role?: string
+}
+
+export interface SwatchGridProps {
+  swatches: Swatch[]
+  /** Number of columns in the grid. */
+  columns?: number
+}
+
+export function SwatchGrid({ swatches, columns = 4 }: SwatchGridProps) {
+  return (
+    <div
+      className="dcpl-swgrid"
+      style={{ gridTemplateColumns: `repeat(${columns}, 1fr)` }}>
+      {swatches.map((s) => (
+        <div className="dcpl-swrow" key={s.token}>
+          <div className="dcpl-swchip" style={{ background: s.color }} />
+          <div className="dcpl-swtok">
+            <b>{s.token}</b>
+            {s.role ? <span>{s.role}</span> : null}
+          </div>
+        </div>
+      ))}
+    </div>
+  )
+}

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

@@ -0,0 +1,23 @@
+import { defineCases } from '@awarebydefault/display-case'
+import { TypeScale, type TypeStep } from './TypeScale'
+
+const scale: TypeStep[] = [
+  { tag: 'xl · 28', size: '28px', sample: 'Doc heading' },
+  { tag: 'lg · 20', size: '20px', sample: 'Section title' },
+  { tag: 'md · 16', size: '16px', sample: 'Emphasis' },
+  {
+    tag: 'base · 14',
+    size: '14px',
+    sample: 'Chrome baseline — nav, buttons, body',
+  },
+  { tag: 'sm · 12', size: '12px', sample: 'Secondary — captions' },
+  { tag: 'xs · 11', size: '11px', sample: 'Eyebrow labels' },
+]
+
+export default defineCases(
+  'TypeScale',
+  {
+    Scale: () => <TypeScale steps={scale} />,
+  },
+  { level: 'molecule' },
+)

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

@@ -0,0 +1,14 @@
+**TypeScale** — a column of type-size rows, a mono tag beside a live sample rendered at the
+step's size. A reusable Primer specimen for documenting a type scale at its
+real sizes.
+
+```tsx
+<TypeScale
+  steps={[
+    { tag: 'lg · 20', size: '20px', sample: 'Section title' },
+    { tag: 'base · 14', size: '14px', sample: 'Body baseline' },
+  ]}
+/>
+```
+
+Use this for size steps. For weights reach for `WeightSpecimen`; for which families exist reach for `FontFamilies`.

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

@@ -0,0 +1,34 @@
+/**
+ * Display Case — TypeScale
+ * A column of type-size rows: a mono tag beside a live sample rendered at the
+ * step's size. Generic specimen primitive for a Primer — use it to document a
+ * type scale at its real sizes.
+ */
+
+export interface TypeStep {
+  /** Mono tag on the left (e.g. `base · 14`); also the React key. */
+  tag: string
+  /** CSS font-size the sample renders at (e.g. `14px`, `1.5rem`). */
+  size: string
+  /** The sample text rendered at `size`. */
+  sample: string
+}
+
+export interface TypeScaleProps {
+  steps: TypeStep[]
+}
+
+export function TypeScale({ steps }: TypeScaleProps) {
+  return (
+    <div className="dcpl-scale">
+      {steps.map((s) => (
+        <div className="dcpl-scalerow" key={s.tag}>
+          <div className="dcpl-scaletag">{s.tag}</div>
+          <div className="dcpl-scalespec" style={{ fontSize: s.size }}>
+            {s.sample}
+          </div>
+        </div>
+      ))}
+    </div>
+  )
+}

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

@@ -0,0 +1,28 @@
+import { defineCases } from '@awarebydefault/display-case'
+import { Eyebrow } from '../showcase/Eyebrow'
+import { type WeightSpec, WeightSpecimen } from './WeightSpecimen'
+
+const weights: WeightSpec[] = [
+  { weight: 400, name: 'Normal', role: 'body' },
+  { weight: 500, name: 'Medium', role: 'active' },
+  { weight: 600, name: 'Semibold', role: 'titles' },
+]
+
+export default defineCases(
+  'WeightSpecimen',
+  {
+    Weights: () => <WeightSpecimen weights={weights} />,
+    WithFooter: () => (
+      <WeightSpecimen
+        weights={weights}
+        footer={
+          <>
+            <div className="dcpl-divider" />
+            <Eyebrow>Group label · 11px / 500 / 0.08em uppercase</Eyebrow>
+          </>
+        }
+      />
+    ),
+  },
+  { level: 'molecule' },
+)