@w5-ui/react 0.2.1 → 0.5.1

package/README.md

@@ -1,9 +1,123 @@
 # @w5-ui/react
 
-React component library for the Dash UI design system. Pairs with `@w5-ui/tokens` for tokens and
-`@w5-ui/assets` for brand SVGs.
+React 18 component library for the Dash UI design system. Pairs with `@w5-ui/tokens` for design
+tokens and `@w5-ui/assets` for brand SVGs.
+
+```bash
+yarn add @w5-ui/react
+```
+
+## Quick start
 
 ```tsx
-import '@w5-ui/react/styles.css'
-import { Card, Pill, Button, Topbar, Sidebar } from '@w5-ui/react'
+import '@w5-ui/react/styles.css' // ships @w5-ui/tokens/dashboard.css
+import { AppLayout, Topbar, Sidebar, PageHeader, Card, Stat, Pill } from '@w5-ui/react'
+
+export function App() {
+  return (
+    <AppLayout
+      pageLabel="Dashboard"
+      topbar={<Topbar siteName="HQ" activeApp="system" />}
+      sidebar={<Sidebar sections={SECTIONS} activeId={page} onChange={setPage} />}
+    >
+      <PageHeader title="Dashboard" />
+      <div className="grid">
+        <Stat span={4} label="Internet" value="847" unit="Mbps" />
+        <Stat span={4} label="Clients" value="124" />
+        <Stat span={4} label="Throughput" value="12.4" unit="Gbps" />
+        <Card span={8}>
+          <h3>
+            Traffic <Pill variant="success">healthy</Pill>
+          </h3>
+        </Card>
+        <Card span={4}>
+          <h3>Top clients</h3>
+        </Card>
+      </div>
+    </AppLayout>
+  )
+}
 ```
+
+That single skeleton (`AppLayout` then `PageHeader` then `<div className="grid">` then
+`<Card span={n}>`) carries every padding, gap, and column value the reference dashboards use.
+Reproduce it verbatim and spacing falls into place automatically.
+
+## The contract (read this before styling anything)
+
+The reference dashboards (`apps/dashboard-react`, rendered in Storybook under **Dashboard**) all
+share one skeleton. Userland looking different almost always comes down to one of these:
+
+| Don't                                                          | Do                                                                                 |
+| -------------------------------------------------------------- | ---------------------------------------------------------------------------------- |
+| Wrap `.grid` in your own `<div style={{ padding }}>`           | Render `.grid` as a direct child of `<main>`. It already pads 16px x 24px.         |
+| `display: flex; gap: ...` on the page root                     | Render `<Banner>`, `<PageHeader>`, `.grid` as siblings. They own their spacing.    |
+| Re-implement `.card` with a `<div>` and a custom border-radius | Use `<Card>` or `<Stat>`. The radius, padding, and `<h3>` rhythm ship together.    |
+| `<h3>` outside a `<Card>`                                      | Keep titles inside `<Card>`. The `.card h3` selector sizes and colours them.       |
+| `<span style={{ color: 'green' }}>online</span>`               | Use `<Pill variant="success">online</Pill>` (also `<Badge>`, `<StatusIndicator>`). |
+| Mix `span={5}` and `span={7}`                                  | Use 4 / 6 / 8 / 12 so rows divide cleanly into the 12-column grid.                 |
+| Skip `AppLayout` and roll your own `.app` grid                 | Use `AppLayout` once at the root. `.app`, `.workspace`, and `<main>` line up.      |
+| Hand-pick hex colours                                          | Use tokens via the `data-motif` CSS variables. See `@w5-ui/tokens`.                |
+
+## Grid math
+
+`.grid` is `repeat(12, 1fr)` with a 12px gap and 16px x 24px outer padding.
+
+| Tile width | `span` | Typical use                          |
+| ---------- | ------ | ------------------------------------ |
+| Third      | `4`    | Single-stat card, donut              |
+| Half       | `6`    | Two-column comparison                |
+| Two-thirds | `8`    | Wide table, line chart               |
+| Full       | `12`   | Time series, sankey, page-wide table |
+
+4+4+4, 8+4, 6+6, and 12 all snap cleanly. Avoid 5 and 7. They leave dead pixels and force the next
+row to wrap unevenly.
+
+## What lives where
+
+| Package         | Description                                              |
+| --------------- | -------------------------------------------------------- |
+| `@w5-ui/react`  | ~170 React components (this package)                     |
+| `@w5-ui/svelte` | The same component surface for Svelte                    |
+| `@w5-ui/tokens` | CSS variables (`data-motif="dark"` / `"light"`) + JS map |
+| `@w5-ui/assets` | Brand mark, wordmark, app-rail SVGs                      |
+
+`@w5-ui/react/styles.css` re-exports `@w5-ui/tokens/dashboard.css`, so importing it once is enough
+for tokens, the `.app` / `.workspace` / `.grid` / `.card` classes, and component styles.
+
+## Themes
+
+Two motifs ship in tokens:
+
+```html
+<html data-motif="dark">
+  <!-- the default -->
+</html>
+<html data-motif="light"></html>
+```
+
+Set the attribute on `<html>` (or any ancestor of the app root) to switch.
+
+## CSS hooks you can rely on
+
+Stable class names that ship from `@w5-ui/tokens/dashboard.css`:
+
+- `.app`, `.workspace`, `.content`: outer chrome, wired up by `AppLayout`
+- `.grid`: 12-column page grid with the canonical gutter
+- `.card`, `.card h3`: tile shell and title rhythm. Use through `<Card>` or `<Stat>`.
+- `.ph-bar`, `.ph-title`, `.ph-actions`: page header primitives. Use through `<PageHeader>`.
+- `.field-stack`, `.form-row`, `.form-actions`: form rhythm primitives
+- `.mac`, `.name-cell`: monospace and avatar-style cell layouts
+
+Anything else (raw colours, ad-hoc paddings) should come from tokens, not bespoke values.
+
+## Reference
+
+- **Storybook**: full component catalogue plus every Foundations page
+- **Foundations / Page layout**: the canonical recipe in full, with anatomy and pitfalls
+- **Foundations / Spacing**: the 12-token spacing scale and rhythm rules
+- **Foundations / Colours**, **Type**, **Icons**, **Forms**, **Tables**, **Charts**, **Status &
+  feedback**, **Navigation**, **Overlays**, **Actions**: pick-by-question tables for every primitive
+
+The Storybook **Dashboard** section renders the reference pages 1:1. When your page looks different,
+open the matching story and diff the markup.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@w5-ui/react",
-  "version": "0.2.1",
+  "version": "0.5.1",
   "description": "React 18 components for the Dash UI design system - ~170 dashboard-focused components with full type defs and SSR support. Part of Webber's design systems.",
   "keywords": [
     "react",
@@ -39,7 +39,7 @@
   },
   "dependencies": {
     "@w5-ui/assets": "^0.2.1",
-    "@w5-ui/tokens": "^0.2.1"
+    "@w5-ui/tokens": "^0.5.0"
   },
   "devDependencies": {
     "@types/react": "^18.3.0",

package/src/components/AppLayout.tsx

@@ -0,0 +1,38 @@
+import type { ReactNode } from 'react'
+import { SkipLink } from './SkipLink.js'
+
+export interface AppLayoutProps {
+  /** Rendered above the workspace, typically `<Topbar />`. */
+  topbar: ReactNode
+  /** Rendered to the left of the main content, typically `<Sidebar />`. */
+  sidebar: ReactNode
+  /** Page title for the visually-hidden `<h1>` that labels `<main>` (WCAG 2.4.6). */
+  pageLabel: string
+  children?: ReactNode
+}
+
+/**
+ * Outer dashboard chrome: `<SkipLink>`, `<Topbar>` slot, `<Sidebar>` slot, and
+ * a `<main className="content">` region with the page-title `<h1>` wired up.
+ *
+ * Reproducing this skeleton in userland is the #1 source of spacing drift —
+ * `<AppLayout>` guarantees the `.app` grid, the `.workspace` columns, and the
+ * sticky scroll container line up the same way the reference dashboards do.
+ */
+export function AppLayout({ topbar, sidebar, pageLabel, children }: AppLayoutProps) {
+  return (
+    <div className="app">
+      <SkipLink />
+      {topbar}
+      <div className="workspace">
+        {sidebar}
+        <main className="content" id="main-content" tabIndex={-1} aria-labelledby="page-title">
+          <h1 id="page-title" className="sr-only">
+            {pageLabel}
+          </h1>
+          {children}
+        </main>
+      </div>
+    </div>
+  )
+}

package/src/components/AppShell.tsx

@@ -1,8 +1,8 @@
 import { appLogos, logos } from '@w5-ui/assets'
 import { Fragment, type ReactNode } from 'react'
-import { CaretIcon, SearchIcon, UpdatesIcon, BellIcon, HelpIcon } from '../icons.js'
-import { Avatar } from './Avatar.js'
-import { IconButton } from './Button.js'
+import { CaretIcon } from '../icons.js'
+import { StatusRing, type StatusRingStatus } from './StatusRing.js'
+import { TopbarActions } from './TopbarActions.js'
 
 void logos
 
@@ -25,6 +25,17 @@ export interface TopbarProps {
   onAppChange?: (id: string) => void
   initials?: string
   notificationCount?: number
+  /** Health colour of the site-name status ring. Defaults to `'ok'` (green).
+   * Drive from userland health state to surface degraded / down conditions
+   * without replacing the canonical site-switcher chrome. */
+  status?: StatusRingStatus
+  /** When false, the site label renders as a static element instead of a
+   * site-switcher dropdown trigger. Use for single-site dashboards. */
+  siteSwitchable?: boolean
+  /** Custom right-side actions. When provided, replaces the default
+   * Search/Updates/Notifications/Help/Avatar block in full. Use to slot in
+   * app-specific controls (theme toggle, status pill, etc.). */
+  actions?: ReactNode
 }
 
 export function Topbar({
@@ -34,21 +45,35 @@ export function Topbar({
   onAppChange,
   initials = 'MS',
   notificationCount = 1,
+  status = 'ok',
+  siteSwitchable = true,
+  actions,
 }: TopbarProps) {
+  const siteLabel = (
+    <>
+      <StatusRing status={status} />
+      <span className="site-name" aria-hidden={siteSwitchable ? 'true' : undefined}>
+        {siteName}
+      </span>
+      {siteSwitchable && <CaretIcon className="caret" aria-hidden="true" />}
+    </>
+  )
   return (
     <header className="topbar">
-      <button
-        type="button"
-        className="site-switch"
-        aria-label={`Switch site: ${siteName}`}
-        aria-haspopup="menu"
-      >
-        <span className="status-ring" />
-        <span className="site-name" aria-hidden="true">
-          {siteName}
-        </span>
-        <CaretIcon className="caret" aria-hidden="true" />
-      </button>
+      {siteSwitchable ? (
+        <button
+          type="button"
+          className="site-switch"
+          aria-label={`Switch site: ${siteName}`}
+          aria-haspopup="menu"
+        >
+          {siteLabel}
+        </button>
+      ) : (
+        <div className="site-switch" role="presentation">
+          {siteLabel}
+        </div>
+      )}
       <nav className="app-tabs" aria-label="Apps">
         {apps.map((a) => (
           <button
@@ -65,40 +90,7 @@ export function Topbar({
       </nav>
       <div className="topbar-spacer" />
       <div className="topbar-right">
-        <IconButton aria-label="Search" title="Search">
-          <SearchIcon />
-        </IconButton>
-        <IconButton aria-label="Updates" title="Updates">
-          <UpdatesIcon />
-        </IconButton>
-        <IconButton
-          aria-label={
-            notificationCount > 0 ? `Notifications, ${notificationCount} new` : 'Notifications'
-          }
-          title="Notifications"
-          style={{ position: 'relative' }}
-        >
-          <BellIcon />
-          {notificationCount > 0 && (
-            <span
-              aria-hidden="true"
-              style={{
-                position: 'absolute',
-                top: 6,
-                right: 6,
-                width: 6,
-                height: 6,
-                background: '#F03A3A',
-                borderRadius: '50%',
-                border: '1.5px solid #0A0A0B',
-              }}
-            />
-          )}
-        </IconButton>
-        <IconButton aria-label="Help" title="Help">
-          <HelpIcon />
-        </IconButton>
-        <Avatar initials={initials} size="sm" alt={`Account, ${initials}`} />
+        {actions ?? <TopbarActions initials={initials} notificationCount={notificationCount} />}
       </div>
     </header>
   )

package/src/components/Body.tsx

@@ -0,0 +1,32 @@
+import type { HTMLAttributes, ReactNode } from 'react'
+
+export interface BodyProps extends HTMLAttributes<HTMLParagraphElement> {
+  children?: ReactNode
+}
+
+/**
+ * Default body paragraph - the 14 px / regular / 1.4 / `--text-2` rhythm
+ * that runs across table cells, paragraphs, and most user-readable copy
+ * in the dashboard. Renders `<p class="dash-ui-body">` so the
+ * `.dash-ui-body` rule in `@w5-ui/tokens/tokens.css` pins the canonical
+ * size, weight, line-height, and colour. Stops userland reaching for a
+ * one-off `font-size: 14px; line-height: 1.4;` duo (or worse, leaving the
+ * 16 px browser default in place and getting the #1 documented spacing
+ * drift: "page text looks too big vs the reference dashboard").
+ *
+ * Typed equivalent of `<p className="dash-ui-body">`. This is the
+ * userland-facing semantic class documented in **Foundations / Type**.
+ * Body copy is "almost always inherited, almost never overridden" inside
+ * `.card` / `.table-shell` / page chrome - reach for `<Body>` when
+ * wrapping standalone prose in userland (empty states, onboarding
+ * paragraphs, info banners) or when a parent stylesheet has reset the
+ * default size and you need to opt back in explicitly. For 16 px
+ * settings descriptions prefer `<BodyLg>`.
+ */
+export function Body({ className = '', children, ...rest }: BodyProps) {
+  return (
+    <p className={`dash-ui-body ${className}`.trim()} {...rest}>
+      {children}
+    </p>
+  )
+}

package/src/components/BodyLg.tsx

@@ -0,0 +1,29 @@
+import type { HTMLAttributes, ReactNode } from 'react'
+
+export interface BodyLgProps extends HTMLAttributes<HTMLParagraphElement> {
+  children?: ReactNode
+}
+
+/**
+ * Longer-form prose paragraph - settings descriptions, onboarding copy,
+ * empty-state explanations, anywhere the default 14 px body feels too
+ * cramped for multi-sentence reading. Renders `<p class="dash-ui-body-lg">`
+ * so the `.dash-ui-body-lg` rule in `@w5-ui/tokens/tokens.css` applies the
+ * canonical 16 px / regular weight, 1.55 line-height, and `--text-2`
+ * colour pair. Stops userland reaching for a one-off `font-size: 16px;
+ * line-height: 1.6;` duo on every settings description.
+ *
+ * Typed equivalent of `<p className="dash-ui-body-lg">`. This is the
+ * userland-facing semantic class documented in **Foundations / Type**.
+ * Reach for `<BodyLg>` when the cliff between 1.25 (heading) and 1.4
+ * (default body) feels too dense for a 2-3 sentence paragraph; keep the
+ * default `.dash-ui-body` (14 / 1.4) for table cells, table footnotes,
+ * and single-line labels.
+ */
+export function BodyLg({ className = '', children, ...rest }: BodyLgProps) {
+  return (
+    <p className={`dash-ui-body-lg ${className}`.trim()} {...rest}>
+      {children}
+    </p>
+  )
+}

package/src/components/Caption.tsx

@@ -0,0 +1,29 @@
+import type { HTMLAttributes, ReactNode } from 'react'
+
+export interface CaptionProps extends HTMLAttributes<HTMLSpanElement> {
+  children?: ReactNode
+}
+
+/**
+ * Small helper / metadata text - "last updated 5 min ago", table footnote,
+ * timestamp under a chart, byline beneath a section heading. Renders
+ * `<span class="dash-ui-caption">` so the `.dash-ui-caption` rule in
+ * `@w5-ui/tokens/tokens.css` applies the canonical 12 px / regular weight,
+ * 1.25 line-height, and the muted `--text-3` colour. Stops userland
+ * reaching for a one-off `font-size: 12px; color: #a4a7b5;` trio on every
+ * caption.
+ *
+ * Typed equivalent of `<span className="dash-ui-caption">`. This is the
+ * userland-facing semantic class documented in **Foundations / Type**.
+ * Use `<Caption>` for non-essential metadata only - on `--depthBg-3`
+ * (popovers, drawers) the `--text-3` contrast slides toward 4.0:1, so
+ * keep primary copy on `.dash-ui-body` / `--text-2`. Pair with `<Muted>`
+ * when you want the same colour at the default 14 px body size.
+ */
+export function Caption({ className = '', children, ...rest }: CaptionProps) {
+  return (
+    <span className={`dash-ui-caption ${className}`.trim()} {...rest}>
+      {children}
+    </span>
+  )
+}

package/src/components/Card.tsx

@@ -18,6 +18,19 @@ export interface CardTitleProps extends HTMLAttributes<HTMLHeadingElement> {
   children?: ReactNode
 }
 
+/**
+ * Title row inside a `<Card>` tile. Renders a plain `<h3>` so the `.card h3`
+ * rule in `@w5-ui/tokens/dashboard.css` sets the canonical 12 px size, weight
+ * 500, `--text-3` (muted) colour, and flex layout (title on the left, any trailing
+ * `<Pill>` / `<CardMore>` pushed to the right edge). Stops userland reaching
+ * for an `<h2>` or a custom `<div className="title">` that would skip the
+ * rule and read broken inside the tile.
+ *
+ * Use the typed wrapper instead of a raw `<h3>` when the markup is awkward
+ * (codegen, MDX, mixed JSX trees); otherwise a plain `<h3>` works equally
+ * well. Pair with `<CardMore>` for a trailing "View all →" affordance and
+ * `<Pill>` for inline status.
+ */
 export function CardTitle({ children, className = '', ...rest }: CardTitleProps) {
   return (
     <h3 className={className} {...rest}>

package/src/components/CardMore.tsx

@@ -0,0 +1,22 @@
+import type { AnchorHTMLAttributes, ReactNode } from 'react'
+
+export interface CardMoreProps extends AnchorHTMLAttributes<HTMLAnchorElement> {
+  children?: ReactNode
+}
+
+/**
+ * Trailing "View all" / "More →" affordance inside a `<Card>` title row.
+ * Renders an `<a class="more">` so the `.card h3 .more` rule in
+ * `@w5-ui/tokens/dashboard.css` styles it (muted colour, pointer cursor) and
+ * the parent `<h3>` flex pushes it to the right edge of the title.
+ *
+ * Typed equivalent of `<a className="more">` inside `<h3>` for the canonical
+ * card title pattern; pair with `<Card>` / `<CardTitle>` for full ergonomics.
+ */
+export function CardMore({ className = '', children, ...rest }: CardMoreProps) {
+  return (
+    <a className={`more ${className}`.trim()} {...rest}>
+      {children}
+    </a>
+  )
+}

package/src/components/Code.tsx

@@ -0,0 +1,27 @@
+import type { HTMLAttributes, ReactNode } from 'react'
+
+export interface CodeProps extends HTMLAttributes<HTMLElement> {
+  children?: ReactNode
+}
+
+/**
+ * Inline code snippet for key names, config paths, environment variables
+ * and other short literal strings that read inside body copy. Renders a
+ * `<code class="dash-ui-code">` so the `.dash-ui-code` rule in
+ * `@w5-ui/tokens/css` applies the canonical JetBrains Mono family, 12 px
+ * size, muted text colour, and the inset `--depthBg-2` chip background
+ * with a 1 px border. Stops userland reaching for bare `<code>` (which
+ * falls back to a serif monospace on `#fff`) or inline `font-family` /
+ * `background` overrides on every snippet.
+ *
+ * Typed equivalent of `<code className="dash-ui-code">`. Reach for
+ * `<CodeBlock>` when the snippet wraps to multiple lines and wants a
+ * full block surface; this primitive is for the inline case.
+ */
+export function Code({ className = '', children, ...rest }: CodeProps) {
+  return (
+    <code className={`dash-ui-code ${className}`.trim()} {...rest}>
+      {children}
+    </code>
+  )
+}

package/src/components/ColumnToggle.tsx

@@ -87,6 +87,7 @@ export function ColumnToggle({ columns, visible, onChange }: ColumnToggleProps)
                 <label className="col-toggle__label">
                   <input
                     type="checkbox"
+                    aria-label={col.label}
                     className="col-toggle__check"
                     checked={visible.has(col.key)}
                     disabled={col.required}

package/src/components/CommandPalette.tsx

@@ -110,6 +110,7 @@ export function CommandPalette({
             className="cp-input"
             type="text"
             role="combobox"
+            aria-label={placeholder}
             aria-expanded={filtered.length > 0}
             aria-autocomplete="list"
             aria-controls={listId}

package/src/components/ContextMenu.tsx

@@ -4,7 +4,10 @@ import type { KeyboardEvent } from 'react'
 export interface ContextMenuItem {
   id: string
   label: string
+  /** Red tone (destructive). Mutually exclusive with `warning`. */
   danger?: boolean
+  /** Yellow tone (caution / heads-up). Mutually exclusive with `danger`. */
+  warning?: boolean
   disabled?: boolean
 }
 
@@ -100,7 +103,7 @@ export function ContextMenu({
     >
       {items.map((entry, i) => {
         if ('separator' in entry) {
-          return <li key={i} role="separator" className="ctx-menu-sep" />
+          return <li key={i} role="separator" aria-hidden="true" className="ctx-menu-sep" />
         }
         const ai = actionItems.indexOf(entry)
         return (
@@ -111,6 +114,7 @@ export function ContextMenu({
             aria-disabled={entry.disabled || undefined}
             data-active={ai === activeIdx ? 'true' : undefined}
             data-danger={entry.danger || undefined}
+            data-warning={entry.warning || undefined}
             className="ctx-menu-item"
             onMouseEnter={() => setActiveIdx(ai)}
             onMouseDown={(e) => {

package/src/components/DateRangePicker.tsx

@@ -145,8 +145,23 @@ export function DateRangePicker({
         setPicking(null)
       }
     }
+    // Escape closes the dialog and restores focus to the trigger. Handled
+    // at the document level (rather than a JSX onKeyDown on the dialog) so
+    // it works regardless of focus position inside the popover.
+    function onKey(e: KeyboardEvent) {
+      if (e.key === 'Escape') {
+        e.preventDefault()
+        setOpen(false)
+        setPicking(null)
+        triggerRef.current?.focus()
+      }
+    }
     document.addEventListener('mousedown', handler)
-    return () => document.removeEventListener('mousedown', handler)
+    document.addEventListener('keydown', onKey)
+    return () => {
+      document.removeEventListener('mousedown', handler)
+      document.removeEventListener('keydown', onKey)
+    }
   }, [open])
 
   function renderCalendar(grid: Date[], gridMonth: number, gridYear: number) {
@@ -302,14 +317,6 @@ export function DateRangePicker({
           aria-modal="true"
           aria-label="Select date range"
           className="drp-cal"
-          onKeyDown={(e) => {
-            if (e.key === 'Escape') {
-              e.preventDefault()
-              setOpen(false)
-              setPicking(null)
-              triggerRef.current?.focus()
-            }
-          }}
         >
           <div className="drp-months">
             {renderCalendar(leftGrid, viewMonth, viewYear)}

package/src/components/Delta.tsx

@@ -0,0 +1,29 @@
+import type { HTMLAttributes, ReactNode } from 'react'
+
+export interface DeltaProps extends HTMLAttributes<HTMLSpanElement> {
+  dir: 'up' | 'down' | 'flat'
+  children?: ReactNode
+}
+
+/**
+ * Trend indicator span used inside `<Submeta>` or any inline copy where a delta
+ * needs to be colour-coded (success/green when up, danger/red when down,
+ * neutral when flat). Emits a visually-hidden `Trend: ` prefix so screen
+ * readers announce the direction independent of the arrow glyph the caller
+ * supplies in the copy.
+ *
+ * Typed equivalent of `<span className="delta-up | delta-down">` from
+ * `@w5-ui/tokens/dashboard.css`.
+ */
+export function Delta({ dir, className = '', children, ...rest }: DeltaProps) {
+  const cls = dir === 'flat' ? '' : `delta-${dir}`
+  const merged = `${cls} ${className}`.trim()
+  return (
+    <>
+      <span className="sr-only">Trend: </span>
+      <span className={merged || undefined} {...rest}>
+        {children}
+      </span>
+    </>
+  )
+}

package/src/components/Display1.tsx

@@ -0,0 +1,33 @@
+import type { HTMLAttributes, ReactNode } from 'react'
+
+export interface Display1Props extends HTMLAttributes<HTMLHeadingElement> {
+  children?: ReactNode
+}
+
+/**
+ * Display-1 - the 64 px / bold / `--lh-tight` / `--tracking-display`
+ * (-0.02em) rhythm reserved for onboarding splashes and marketing
+ * heroes (the top of the type scale, one step above the 48 px
+ * `<Display2>`). Renders `<h1 class="dash-ui-display-1">` so the
+ * `.dash-ui-display-1` rule in `@w5-ui/tokens/tokens.css` pins the
+ * canonical size, weight, line-height, letter-spacing, and `--text-1`
+ * colour.
+ *
+ * Stops userland reaching for an ad-hoc `<h1 style={{ fontSize: 64 }}>`
+ * that almost always forgets `--lh-tight` (1.1) and the negative
+ * tracking, which is the documented "headings break awkwardly across
+ * two lines" drift in **Foundations / Type**.
+ *
+ * Typed equivalent of `<h1 className="dash-ui-display-1">`. Use for
+ * onboarding splashes or large marketing heroes. In-app pages should
+ * reach for `<PageHeader>` (page title) and `<H2>` (section heads);
+ * never substitute `<Display1>` for an in-app screen — its 64 px
+ * rhythm dwarfs dashboard chrome.
+ */
+export function Display1({ className = '', children, ...rest }: Display1Props) {
+  return (
+    <h1 className={`dash-ui-display-1 ${className}`.trim()} {...rest}>
+      {children}
+    </h1>
+  )
+}

package/src/components/Display2.tsx

@@ -0,0 +1,32 @@
+import type { HTMLAttributes, ReactNode } from 'react'
+
+export interface Display2Props extends HTMLAttributes<HTMLHeadingElement> {
+  children?: ReactNode
+}
+
+/**
+ * Display-2 - the 48 px / bold / `--lh-tight` / `--tracking-display`
+ * (-0.02em) rhythm used for login and large marketing surfaces (the
+ * step below the 64 px Display-1 hero). Renders
+ * `<h1 class="dash-ui-display-2">` so the `.dash-ui-display-2` rule in
+ * `@w5-ui/tokens/tokens.css` pins the canonical size, weight,
+ * line-height, letter-spacing, and `--text-1` colour.
+ *
+ * Stops userland reaching for an ad-hoc `<h1 style={{ fontSize: 48 }}>`
+ * that almost always forgets `--lh-tight` (1.1) and the negative
+ * tracking, which is the documented "headings break awkwardly across
+ * two lines" drift in **Foundations / Type**.
+ *
+ * Typed equivalent of `<h1 className="dash-ui-display-2">`. Use for
+ * login-page titles or large marketing heroes one step down from
+ * `<Display1>`. In-app pages should reach for `<PageHeader>` (page
+ * title) and `<H2>` (section heads); never substitute `<Display2>` for
+ * an in-app screen — its 48 px rhythm dominates dashboard chrome.
+ */
+export function Display2({ className = '', children, ...rest }: Display2Props) {
+  return (
+    <h1 className={`dash-ui-display-2 ${className}`.trim()} {...rest}>
+      {children}
+    </h1>
+  )
+}

package/src/components/ExpandableRow.tsx

@@ -22,6 +22,7 @@ export function ExpandableRow({
           <button
             type="button"
             className="exp-toggle"
+            aria-label={open ? 'Collapse row' : 'Expand row'}
             aria-expanded={open}
             aria-controls={detailId}
             onClick={() => setOpen((o) => !o)}