@awarebydefault/display-case 1.0.0

package/src/ui/design-system/components/showcase/A11yBadge.case.tsx

@@ -0,0 +1,46 @@
+import { defineCases } from '@awarebydefault/display-case'
+import { A11yBadge } from './A11yBadge'
+import { NavItem } from './NavItem'
+import { Sidebar } from './Sidebar'
+
+export default defineCases(
+  'A11yBadge',
+  {
+    // The two forms: a counted pill and the bare dot.
+    Forms: () => (
+      <div style={{ display: 'flex', gap: '0.75rem', alignItems: 'center' }}>
+        <A11yBadge value={1} />
+        <A11yBadge value={3} />
+        <A11yBadge value={12} />
+        <A11yBadge value="dot" />
+      </div>
+    ),
+    // In context: a collapsed component shows its summed count; an expanded
+    // parent shows the dot while its case rows carry the per-variant counts.
+    'In the nav rail': () => (
+      <Sidebar style={{ width: '15rem' }}>
+        <NavItem
+          kind="component"
+          label="Input"
+          count={2}
+          alert={5}
+          onToggle={() => {}}
+          onSelect={() => {}}
+        />
+        <NavItem
+          kind="component"
+          label="Button"
+          count={3}
+          alert="dot"
+          expanded
+          onToggle={() => {}}
+          onSelect={() => {}}
+        />
+        <NavItem kind="case" label="Playground" alert={2} onSelect={() => {}} />
+        <NavItem kind="case" label="Variants" alert={3} onSelect={() => {}} />
+        <NavItem kind="case" label="Sizes" onSelect={() => {}} />
+      </Sidebar>
+    ),
+  },
+  { level: 'atom' },
+)

package/src/ui/design-system/components/showcase/A11yBadge.css

@@ -0,0 +1,27 @@
+.dcui-a11y-badge {
+  flex: 0 0 auto;
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  min-width: 0.95rem;
+  height: 0.95rem;
+  padding: 0 0.2rem;
+  border-radius: 999px;
+  /* The fixed ramp red, not --dc-danger: this pill carries white text, so it
+     needs a fill dark enough for AA in both themes. --dc-danger is the lighter
+     text-role hue in dark (for danger *text* on charcoal) and would drop the
+     white count below AA here. */
+  background: var(--dc-red-600);
+  color: #ffffff;
+  font-family: var(--dc-font-mono);
+  font-size: var(--dc-text-xs);
+  font-weight: var(--dc-weight-medium);
+  line-height: 1;
+}
+/* Dot variant: a bare danger dot (no number — the counts live on the case rows). */
+.dcui-a11y-badge[data-dot="true"] {
+  min-width: 0;
+  width: 0.5rem;
+  height: 0.5rem;
+  padding: 0;
+}

package/src/ui/design-system/components/showcase/A11yBadge.placard.md

@@ -0,0 +1,11 @@
+**A11yBadge** — the nav-rail accessibility marker: a small danger pill carrying a violation count, or a bare dot. [NavItem](./NavItem.placard.md) renders it from its `alert` prop; reach for it directly only when building a custom nav row.
+
+```tsx
+<A11yBadge value={3} />        {/* counted pill */}
+<A11yBadge value="dot" />      {/* bare dot — no number */}
+```
+
+- `value` — a positive number renders the counted pill; `'dot'` renders the unnumbered dot. Use `'dot'` on an **expanded** component whose per-variant counts have moved onto its case rows, so the parent still flags "issues here" without competing with the child numbers. The caller decides whether to render it at all (omit for a clean / unmarked row — there is no zero state).
+- `testId` — optional `data-testid` for locating the marker in tests.
+
+It carries an accessible name (`"N accessibility violations"`) via `role="img"`, so the count is announced even though it reads as a glyph.

package/src/ui/design-system/components/showcase/A11yBadge.test.tsx

@@ -0,0 +1,31 @@
+import { describe, expect, test } from 'bun:test'
+import { renderToStaticMarkup } from 'react-dom/server'
+import { A11yBadge } from './A11yBadge'
+
+describe('A11yBadge', () => {
+  test('renders a numbered pill with a pluralized accessible name', () => {
+    const html = renderToStaticMarkup(<A11yBadge value={3} />)
+    expect(html).toContain('>3<')
+    expect(html).toContain('aria-label="3 accessibility violations"')
+    expect(html).toContain('role="img"')
+    expect(html).not.toContain('data-dot')
+  })
+
+  test('uses the singular form for a single violation', () => {
+    const html = renderToStaticMarkup(<A11yBadge value={1} />)
+    expect(html).toContain('aria-label="1 accessibility violation"')
+  })
+
+  test('renders a bare, unnumbered dot for the "dot" value', () => {
+    const html = renderToStaticMarkup(<A11yBadge value="dot" />)
+    expect(html).toContain('data-dot="true"')
+    expect(html).toContain(
+      'aria-label="Has accessibility violations across variants"',
+    )
+  })
+
+  test('threads through the optional test id', () => {
+    const html = renderToStaticMarkup(<A11yBadge value={2} testId="badge-x" />)
+    expect(html).toContain('data-testid="badge-x"')
+  })
+})

package/src/ui/design-system/components/showcase/A11yBadge.tsx

@@ -0,0 +1,41 @@
+/**
+ * Display Case — A11yBadge
+ * The nav-rail accessibility marker. A positive number renders a counted danger
+ * pill; `'dot'` renders an unnumbered danger dot — used on an *expanded*
+ * component whose per-variant counts have moved onto its case rows, so the parent
+ * still flags "issues here" without competing with the child numbers. The caller
+ * decides whether to render it (omit for a clean / unmarked row).
+ */
+
+export interface A11yBadgeProps {
+  /** A positive count renders a numbered pill; `'dot'` renders a bare dot. */
+  value: number | 'dot'
+  /** `data-testid` for locating the marker in tests. */
+  testId?: string
+}
+
+export function A11yBadge({ value, testId }: A11yBadgeProps) {
+  if (value === 'dot') {
+    return (
+      <span
+        className="dcui-a11y-badge"
+        data-dot="true"
+        role="img"
+        data-testid={testId}
+        title="Accessibility violations across variants"
+        aria-label="Has accessibility violations across variants"
+      />
+    )
+  }
+  const text = `${value} accessibility violation${value === 1 ? '' : 's'}`
+  return (
+    <span
+      className="dcui-a11y-badge"
+      role="img"
+      data-testid={testId}
+      title={text}
+      aria-label={text}>
+      {value}
+    </span>
+  )
+}

package/src/ui/design-system/components/showcase/A11yPanel.case.tsx

@@ -0,0 +1,121 @@
+import { type A11yViolation, defineCases } from '@awarebydefault/display-case'
+import type { ReactNode } from 'react'
+import { A11yPanel } from './A11yPanel'
+
+// Real-shaped violations (axe rule id, help, node count, severity).
+const VIOLATIONS: A11yViolation[] = [
+  {
+    id: 'color-contrast',
+    help: 'Elements must meet minimum color contrast ratio thresholds',
+    nodes: 3,
+    impact: 'serious',
+  },
+  {
+    id: 'label',
+    help: 'Form elements must have labels',
+    nodes: 1,
+    impact: 'critical',
+  },
+  {
+    id: 'select-name',
+    help: 'Select element must have an accessible name',
+    nodes: 1,
+    impact: 'serious',
+  },
+]
+
+// Enough violations to overflow the height cap and exercise the internal scroll.
+const MANY: A11yViolation[] = [
+  ...VIOLATIONS,
+  {
+    id: 'button-name',
+    help: 'Buttons must have discernible text',
+    nodes: 2,
+    impact: 'critical',
+  },
+  {
+    id: 'image-alt',
+    help: 'Images must have alternate text',
+    nodes: 5,
+    impact: 'critical',
+  },
+  {
+    id: 'link-name',
+    help: 'Links must have discernible text',
+    nodes: 3,
+    impact: 'serious',
+  },
+  {
+    id: 'list',
+    help: 'Lists must only directly contain li elements',
+    nodes: 2,
+    impact: 'serious',
+  },
+  {
+    id: 'heading-order',
+    help: 'Heading levels should only increase by one',
+    nodes: 1,
+    impact: 'moderate',
+  },
+  {
+    id: 'region',
+    help: 'All page content should be contained by landmarks',
+    nodes: 6,
+    impact: 'moderate',
+  },
+  {
+    id: 'duplicate-id',
+    help: 'id attribute values must be unique',
+    nodes: 3,
+    impact: 'minor',
+  },
+]
+
+// The panel is height-capped and otherwise full-width; give it a realistic
+// column to sit in.
+function Frame({ children }: { children: ReactNode }) {
+  return <div style={{ width: '34rem', maxWidth: '100%' }}>{children}</div>
+}
+
+export default defineCases(
+  'A11yPanel',
+  {
+    // Violations: danger bar + collapsible list, ordered worst-first with tags.
+    Violations: () => (
+      <Frame>
+        <A11yPanel violations={VIOLATIONS} />
+      </Frame>
+    ),
+    // Scanning: a calm, pulsing single bar (no list, no toggle).
+    Scanning: () => (
+      <Frame>
+        <A11yPanel violations="pending" />
+      </Frame>
+    ),
+    // Clean: the reassuring green pass bar.
+    'All clear': () => (
+      <Frame>
+        <A11yPanel violations={[]} />
+      </Frame>
+    ),
+    // Unavailable: the scan prerequisite can't run.
+    Unavailable: () => (
+      <Frame>
+        <A11yPanel violations="unavailable" />
+      </Frame>
+    ),
+    // A long list overflows the height cap and scrolls under the sticky header.
+    Scrolling: () => (
+      <Frame>
+        <A11yPanel violations={MANY} />
+      </Frame>
+    ),
+    // With the ⟳ re-scan control wired (click logs in this exhibit).
+    'With re-scan': () => (
+      <Frame>
+        <A11yPanel violations={VIOLATIONS} onRescan={() => {}} />
+      </Frame>
+    ),
+  },
+  { level: 'organism' },
+)

package/src/ui/design-system/components/showcase/A11yPanel.css

@@ -0,0 +1,198 @@
+.dcui-a11y {
+  flex: 0 0 auto;
+  max-height: 13rem;
+  overflow-y: auto;
+  border: var(--dc-border-line);
+  border-left: 3px solid var(--dc-danger);
+  border-radius: var(--dc-radius-md);
+  background: var(--dc-surface);
+  /* Ease the left accent between states (neutral while scanning → green/danger
+     on the verdict) instead of snapping. */
+  transition: border-left-color var(--dc-transition-base);
+}
+.dcui-a11y[data-state="pass"] {
+  border-left-color: var(--dc-success);
+}
+/* Scanning / unavailable: a calm neutral accent — no verdict yet. */
+.dcui-a11y[data-state="pending"],
+.dcui-a11y[data-state="unavailable"] {
+  border-left-color: var(--dc-border);
+}
+/* Collapsed: only the header bar shows, so no need to reserve scroll height. */
+.dcui-a11y[data-open="false"] {
+  overflow: hidden;
+}
+.dcui-a11y-head {
+  position: sticky;
+  top: 0;
+  z-index: 1;
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  gap: var(--dc-space-4);
+  padding: var(--dc-space-3) var(--dc-space-6);
+  background: var(--dc-surface);
+}
+.dcui-a11y[data-open="true"] .dcui-a11y-head {
+  border-bottom: var(--dc-border-line);
+}
+.dcui-a11y-head-right {
+  display: flex;
+  align-items: center;
+  gap: var(--dc-space-2);
+  /* Reserve the control-row height (the size-sm IconButton) so every state's bar
+     is the same height — the scanning/pass bars have no button, the violations
+     bar does, and without this the bar would jump size between them. */
+  min-height: 26px;
+}
+.dcui-a11y-status {
+  font-family: var(--dc-font-mono);
+  font-size: var(--dc-text-xs);
+  font-weight: var(--dc-weight-medium);
+  color: var(--dc-danger);
+  /* Match the accent: ease the verdict text colour across state changes too. */
+  transition: color var(--dc-transition-base);
+}
+/* On navigation the panel fades out, its state swaps to the new exhibit (behind
+   the fade), then fades back in. Hard-switch the accent + status colour during
+   that window — easing it would flash the previous exhibit's colour as the panel
+   returns, the wrong colour for the now-current state. The ease still applies to
+   in-place state changes (a scan resolving while the panel stays visible). */
+.dcui-a11y[data-instant-color],
+.dcui-a11y[data-instant-color] .dcui-a11y-status {
+  transition: none;
+}
+.dcui-a11y[data-state="pass"] .dcui-a11y-status {
+  color: var(--dc-success);
+  /* Fade the "Passes WCAG A/AA" verdict in (a slow, gentle fade). */
+  animation: dcui-a11y-fade-in 0.45s var(--dc-ease) both;
+}
+.dcui-a11y[data-state="unavailable"] .dcui-a11y-status {
+  color: var(--dc-fg-subtle);
+  font-weight: var(--dc-weight-normal);
+}
+.dcui-a11y[data-state="pending"] .dcui-a11y-status {
+  color: var(--dc-fg-subtle);
+  font-weight: var(--dc-weight-normal);
+  /* Pulse the "Scanning…" text so the in-progress state reads as live. */
+  animation: dcui-a11y-scan 1.4s ease-in-out infinite;
+}
+@keyframes dcui-a11y-scan {
+  0%,
+  100% {
+    opacity: 1;
+  }
+  50% {
+    opacity: 0.35;
+  }
+}
+@keyframes dcui-a11y-fade-in {
+  from {
+    opacity: 0;
+  }
+  to {
+    opacity: 1;
+  }
+}
+/* Each violation row fades + rises in; the per-row stagger (animation-delay, set
+   inline by index) makes the list cascade. */
+@keyframes dcui-a11y-item-in {
+  from {
+    opacity: 0;
+    transform: translateY(4px);
+  }
+  to {
+    opacity: 1;
+    transform: translateY(0);
+  }
+}
+@media (prefers-reduced-motion: reduce) {
+  /* No pulse on Scanning…, no fade on the pass verdict. (The violations cascade
+     is disabled separately, after its rule — see the end of this sheet.) */
+  .dcui-a11y[data-state="pending"] .dcui-a11y-status,
+  .dcui-a11y[data-state="pass"] .dcui-a11y-status {
+    animation: none;
+  }
+}
+/* Base list reset. Declared before the `.dcui-a11y-collapse > .dcui-a11y-list`
+   rule below so specificity ascends in source order (the descendant rule only
+   adds overflow clipping for the collapse animation). */
+.dcui-a11y-list {
+  list-style: none;
+  margin: 0;
+  padding: var(--dc-space-3) var(--dc-space-6) var(--dc-space-4);
+  display: flex;
+  flex-direction: column;
+  gap: var(--dc-space-2);
+}
+/* The violations body lives in a grid row. minmax(0, …fr) — not a bare 0fr/1fr —
+   so the collapsed row truly reaches 0 (a bare 0fr keeps a min-content floor and
+   leaves a sliver of the first row showing). The expand TRANSITION is enabled
+   only for a live-scan reveal, so a cached/already-scanned panel appears fully
+   expanded at once rather than animating open on load. */
+.dcui-a11y-collapse {
+  display: grid;
+  grid-template-rows: minmax(0, 0fr);
+  /* Clip the row: the child overflows the 0-height track when collapsed, so the
+     wrapper must hide it or a sliver of the first row shows. */
+  overflow: hidden;
+}
+.dcui-a11y[data-open="true"] .dcui-a11y-collapse {
+  grid-template-rows: minmax(0, 1fr);
+}
+.dcui-a11y-collapse > .dcui-a11y-list {
+  overflow: hidden;
+  min-height: 0;
+}
+.dcui-a11y[data-reveal="cascade"] .dcui-a11y-collapse {
+  transition: grid-template-rows var(--dc-transition-base);
+}
+@media (prefers-reduced-motion: reduce) {
+  .dcui-a11y,
+  .dcui-a11y-status,
+  .dcui-a11y[data-reveal="cascade"] .dcui-a11y-collapse {
+    transition: none;
+  }
+}
+.dcui-a11y-item {
+  display: flex;
+  align-items: baseline;
+  gap: var(--dc-space-3);
+  font-size: var(--dc-text-sm);
+}
+.dcui-a11y-id {
+  flex: 0 0 auto;
+  font-family: var(--dc-font-mono);
+  font-size: var(--dc-text-xs);
+  color: var(--dc-danger);
+}
+.dcui-a11y-help {
+  flex: 1 1 auto;
+  min-width: 0;
+  color: var(--dc-fg);
+}
+.dcui-a11y-nodes {
+  flex: 0 0 auto;
+  font-family: var(--dc-font-mono);
+  font-size: var(--dc-text-xs);
+  color: var(--dc-fg-subtle);
+}
+/* Reveal modes (set by the panel's data-reveal). 'cascade' = the verdict just
+   resolved from a live scan: rows fade + rise with a per-row stagger (inline
+   animation-delay). 'all' = already scanned (e.g. cache hit / navigation): the
+   whole list fades in at once, like the stage and tweaks panel. */
+.dcui-a11y[data-reveal="cascade"] .dcui-a11y-item {
+  animation: dcui-a11y-item-in 0.6s var(--dc-ease) both;
+}
+.dcui-a11y[data-reveal="all"] .dcui-a11y-list {
+  animation: dcui-a11y-fade-in 0.4s var(--dc-ease) both;
+}
+/* Under reduced motion: no cascade, no fade — the verdict and every row appear
+   at once. Placed after the reveal rules (and matching their specificity) so it
+   wins; animation: none also nullifies the inline per-row delay. */
+@media (prefers-reduced-motion: reduce) {
+  .dcui-a11y[data-reveal="cascade"] .dcui-a11y-item,
+  .dcui-a11y[data-reveal="all"] .dcui-a11y-list {
+    animation: none;
+  }
+}

package/src/ui/design-system/components/showcase/A11yPanel.placard.md

@@ -0,0 +1,19 @@
+**A11yPanel** — the stage's accessibility verdict for the variant on the stage. A height-capped, internally-scrolling card with a sticky header; it composes [Eyebrow](./Eyebrow.placard.md), [IconButton](../controls/IconButton.placard.md), and [ImpactTag](./ImpactTag.placard.md).
+
+```tsx
+<A11yPanel violations={violations} onRescan={() => refetch()} />
+<A11yPanel violations="pending" />
+<A11yPanel violations={[]} />          {/* clean pass */}
+<A11yPanel violations="unavailable" />
+```
+
+`violations` drives the whole component — one of four states:
+
+- `'pending'` — a calm, pulsing **Scanning…** bar (single bar, no controls).
+- `'unavailable'` — the scan prerequisite can't run; a neutral **Unavailable** bar.
+- `[]` — a green **Passes WCAG A/AA** bar.
+- `A11yViolation[]` — a danger bar plus a collapsible list, ordered worst-first (by `impact`, then node count), each row tagged with an `ImpactTag`.
+
+Only the violations state has a body to expand/collapse; the others are a single self-explaining bar. Pass `onRescan` to show the ⟳ re-scan control (hidden while pending, and absent entirely when no handler is wired).
+
+The panel is otherwise full-width and `flex: 0 0 auto`, so place it in a sized column. In the chrome it's mounted only when a11y scanning is configured, beneath the Tweaks panel.

package/src/ui/design-system/components/showcase/A11yPanel.test.tsx

@@ -0,0 +1,81 @@
+import { describe, expect, test } from 'bun:test'
+import { renderToStaticMarkup } from 'react-dom/server'
+import type { A11yViolation } from '../../../../index'
+import { A11yPanel } from './A11yPanel'
+
+const violation = (over: Partial<A11yViolation>): A11yViolation => ({
+  id: 'color-contrast',
+  help: 'Elements must meet contrast',
+  impact: 'serious',
+  nodes: 1,
+  ...over,
+})
+
+describe('A11yPanel', () => {
+  test('shows a pending scan as the "Scanning…" state', () => {
+    const html = renderToStaticMarkup(<A11yPanel violations="pending" />)
+    expect(html).toContain('data-state="pending"')
+    expect(html).toContain('Scanning…')
+  })
+
+  test('shows the unavailable state when the scan cannot run', () => {
+    const html = renderToStaticMarkup(<A11yPanel violations="unavailable" />)
+    expect(html).toContain('data-state="unavailable"')
+    expect(html).toContain('Unavailable')
+  })
+
+  test('an empty array is a clean pass', () => {
+    const html = renderToStaticMarkup(<A11yPanel violations={[]} />)
+    expect(html).toContain('data-state="pass"')
+    expect(html).toContain('Passes WCAG A/AA')
+  })
+
+  test('violations render the fail state with a pluralized count', () => {
+    const one = renderToStaticMarkup(<A11yPanel violations={[violation({})]} />)
+    expect(one).toContain('data-state="fail"')
+    expect(one).toContain('1 violation')
+
+    const many = renderToStaticMarkup(
+      <A11yPanel
+        violations={[violation({ id: 'a' }), violation({ id: 'b' })]}
+      />,
+    )
+    expect(many).toContain('2 violations')
+  })
+
+  test('orders the list worst-impact first, then most-affected first', () => {
+    const html = renderToStaticMarkup(
+      <A11yPanel
+        violations={[
+          violation({ id: 'minor-one', impact: 'minor', nodes: 9 }),
+          violation({ id: 'critical-one', impact: 'critical', nodes: 1 }),
+          violation({ id: 'serious-few', impact: 'serious', nodes: 2 }),
+          violation({ id: 'serious-many', impact: 'serious', nodes: 8 }),
+        ]}
+      />,
+    )
+    const order = [
+      'critical-one',
+      'serious-many',
+      'serious-few',
+      'minor-one',
+    ].map((id) => html.indexOf(id))
+    expect(order).toEqual([...order].sort((a, b) => a - b))
+  })
+
+  test('renders the re-scan control only when a handler is wired', () => {
+    const withRescan = renderToStaticMarkup(
+      <A11yPanel violations={[]} onRescan={() => {}} />,
+    )
+    const without = renderToStaticMarkup(<A11yPanel violations={[]} />)
+    expect(withRescan).toContain('Re-scan accessibility')
+    expect(without).not.toContain('Re-scan accessibility')
+  })
+
+  test('hides the re-scan control while a scan is pending', () => {
+    const html = renderToStaticMarkup(
+      <A11yPanel violations="pending" onRescan={() => {}} />,
+    )
+    expect(html).not.toContain('Re-scan accessibility')
+  })
+})