@persona/design-system 0.10.1 → 0.10.3

package/skills/ui-authoring/PATTERNS.md

@@ -26,7 +26,11 @@ Which pattern to use, and for what. Patterns with a dedicated doc link to
 ## Page layouts
 
 Index pages backed by `DataTable` use `IndexTableLayout`, which owns its `Container`, `PageHeader`,
-`Section`, and `Card` shell. Other pages render `PageHeader`, then `SingleColumnLayout` or
+`Section`, and `Card` shell. Import it from `@persona/design-system/patterns/IndexTableLayout`;
+never copy it, persona-web's `DashboardDataTable` wrapper (PDS does not ship one), or
+`TableControls`/filter panels into an app. Pass app-specific filters through the `controls` prop
+(`controls={{ filters, filterResolver }}` or `controls={{ filterPanel }}`), and if the pattern lacks
+a slot you need, add it here instead of forking the layout. Other pages render `PageHeader`, then `SingleColumnLayout` or
 `SplitColumnLayout`. Do not wrap those templates in `Container` or `Section`.
 
 ```tsx

package/skills/ui-authoring/SKILL.md

@@ -8,6 +8,13 @@ metadata:
 
 # UI Authoring
 
+## Product UI standard
+
+Building a screen in an app? [STANDARD.md](STANDARD.md) holds the rules every screen meets: text the
+user reads is at least 11 px (8 px for a label inside a chart or diagram), contrast meets WCAG AA in light and dark, motion honours
+`prefers-reduced-motion`, and status never relies on colour alone. It also defines the `new-screen`
+lane for building one screen with no designer. Read it first, then the sections below.
+
 ## Design Tokens
 
 ```tsx
@@ -184,6 +191,7 @@ Add `ComponentName.stories.tsx` for every new component or visual variant.
 
 ## Resources
 
+- [STANDARD.md](STANDARD.md) — product UI standard: accessibility values, screen brief, `new-screen` lane ([lanes.json](lanes.json)), checks, departures
 - [TOKENS.md](TOKENS.md) — semantic color tokens (Fg / Surface / Border / Action / Input / Feedback / Status / Opacity), recipes and dark-mode checklist; Spacing / Typography catalog, radius, elevation, charts
 - [PATTERNS.md](PATTERNS.md) — forms, layout, panels, indicators, feedback, empty states
 - [COMPONENTS.md](COMPONENTS.md) — which PDS component to use, and its import path; APIs live in each component's `.mdx`

package/skills/ui-authoring/STANDARD.md

@@ -0,0 +1,137 @@
+# Product UI standard
+
+The rules every screen built on PDS meets, above the shared accessibility floor. This is the product
+UI area standard of the Persona design harness. It cites `persona-id/design-harness` at
+**`core-v0.3`**, where the product UI area's entry is `areas/product-ui.md`.
+
+- **Owner:** Michael Hu.
+- **Covers:** screens in Persona apps built on `@persona/design-system` (the dashboard, internal
+  apps, App Builder).
+- **Pinned by the app's PDS version.** The installed package is the live source and beats any
+  description of it, this file included (PDH-S1).
+
+## Ranks
+
+PDH-P1 (honesty) and PDH-P2 (brand) rank first and second. Then:
+
+3. **Component-first.** A PDS pattern or component over custom code. Tokens only style what no
+   component covers. The failure this guards against is one-off UI that drifts from every other
+   screen.
+4. **Craft.** Hierarchy, spacing, copy and every state (loading, empty, error, disabled) finished,
+   not just working.
+
+## Parameters
+
+| Rule | Product UI value |
+| ---- | ---------------- |
+| PDH-F1 contrast | The core value, WCAG 2.2 AA, in every colour mode the screen ships (light and dark) |
+| PDH-F2 copy | **11 CSS px** for text the user reads, the core web-copy value. 10 px styles are below it (see Checks); use `TextSmall` or `TextSmallMono` (12 px) |
+| PDH-F2 label inside a graphic | **8 CSS px** for a label inside a chart, a diagram or rebuilt product UI, the core value |
+| PDH-F3 reduced motion | Every animation and transition honours `prefers-reduced-motion`; flashing follows PDH-F3 |
+| PDH-F4 status | An icon or label as well as colour. `StatusIndicator` and `Sticker` already do this |
+
+Product UI shown in a fixed frame (a slide, a video) takes the core's fixed-frame value instead.
+
+## Types
+
+| Type | What | Governed by |
+| ---- | ---- | ----------- |
+| `screen` | A route, page, panel or modal flow in app code | This file. It bends nothing here without a departure row |
+| `component` | A component or pattern in PDS itself | `REVIEW.md` and the `design-system-component-authoring` skill, plus this file's parameters |
+
+No type bends the floor or PDH-P1.
+
+## What `persona` means here
+
+Product UI is always `persona` (PDH-M4): PDS as shipped, in the app's theme. Briefs and receipts
+record `brand: persona` without asking. Work that needs to be `unbranded` isn't covered by this
+standard.
+
+## Screen brief
+
+Record these in the PR body before building, so the source is consulted at intake (PDH-S2):
+
+- **Intent:** who uses the screen, to do what, in one line.
+- **Source:** the live product, a Figma link, or none. Say so if a source couldn't be reached.
+- **PDS version:** from the app's lockfile.
+- **Brand:** `persona`.
+- **Lane:** `new-screen`, or none.
+
+## Lanes
+
+A lane is a strict path for one common task. A PR opts in with a commit trailer, and the diff is then
+held to the lane's allow-list. Work that fits no lane goes without a trailer, through normal review;
+don't stretch a lane to fit it.
+
+Lanes are data, in [lanes.json](lanes.json). They name roles, not paths. Each app's harness config
+maps roles to its own paths, so one lane works in any app.
+
+### `new-screen`
+
+One new screen built from PDS, with no designer (App Builder, internal apps).
+
+- **Opt in:** a `Harness-Task: new-screen` trailer on any commit in the PR.
+- **Allowed:** one new screen directory (`screen`), its tests and stories (`screen-tests`), and
+  locale files (`locale`).
+- **Reported, not failed:** edits to the route table (`route-table`), so the screen can be reached.
+- **Forbidden:** shared components (`shared`), theme (`theme`), and code mirrored from PDS
+  (`pds-mirror`). A change there is its own PR, or a PDS change.
+- A file that matches no allowed or reported role fails. A file that matches a forbidden role is
+  forbidden, even if it also matches another role.
+- Build only from PDS patterns, components and tokens, per [SKILL.md](SKILL.md), and finish with the
+  "Before you hand it over" list in [TOKENS.md](TOKENS.md).
+
+### Adding a lane
+
+Add an entry under `lanes` in `lanes.json`: a `description`, `newScreens` (how many new screen
+directories the diff may add; `0` for an edit-only lane), and `allow`, `note` and `forbid` role
+lists. Add a role only when no existing one covers the paths. Then describe the lane here.
+Specialized work gets its own lane; never loosen `new-screen` to fit it.
+
+## Checks
+
+All of these are review until the screen checker ships. When it does, it fails only on new findings;
+existing ones are grandfathered.
+
+| Rule | Source | Check |
+| ---- | ------ | ----- |
+| Painted colours are semantic: no hex, no `Color.*` outside the `semanticColor` fallback | PDS; keeps PDH-F1 in dark mode | Review |
+| Complete `Typography` styles, never individual font properties or a raw `font-size` | PDS; makes PDH-F2 checkable | Review |
+| No copy under 11 px. The 10 px routes are `Typography.TextExtraSmall` and `TextExtraSmallMono`, `theme.text.paragraph.xs`, the text mixin's `xs` (`Paragraph` / `Label` `size="xs"`), and the `TextMono` + `TextExtraSmall.fontSize` composite | PDH-F2 | Review. Report-only once automated, since a text check can't tell copy from a label inside a graphic |
+| `@keyframes`, `animation` or `transition` only with a `prefers-reduced-motion` block | PDH-F3 | Review. Report-only once automated |
+| No hand-rolled `<table>`, `<th>` or `<td>` | PDS (Table Guidelines in SKILL.md) | Review |
+| Contrast | PDH-F1 | Review |
+| Status not by colour alone | PDH-F4 | Review |
+| The diff stays within its lane | `lanes.json` | Review |
+
+## Departure ledger
+
+Departures from this file or the core that aren't tightenings, one row each, in the PDH-M3 format:
+`rule ID · what changed · scope · reason (medium or audience) · owner · expiry or "standing" · date`.
+A one-screen departure goes in that PR's brief instead.
+
+| Rule | What changed | Scope | Reason | Owner | Expiry | Date |
+| ---- | ------------ | ----- | ------ | ----- | ------ | ---- |
+| PDH-F2 | 10 px mono text (`TextMono` + `TextExtraSmall.fontSize`) | `components/TechnicalSticker/TechnicalSticker.tsx`, the `font-size` in the `TechnicalText` style | PDS's existing 10 px step for dense technical identifiers; predates this standard | Michael Hu | standing | 2026-10-26 |
+| PDH-F2 | 10 px mono pill text (`Typography.TextExtraSmall`, mono family) | `components/SmartTextInput/PillType.tsx`, the `PillType` style | PDS's existing 10 px step for type pills in the editor; predates this standard | Michael Hu | standing | 2026-10-26 |
+| PDH-F2 | 10 px helper copy (`paragraphMixins.xs`); copy, not a label inside a graphic | `components/DataTable/TableControls/FiltersV2/FilterPopover/FilterPopover.tsx`, the `Footer` style | PDS's existing 10 px step for the filter popover's field note; predates this standard | Michael Hu | standing | 2026-10-26 |
+| PDH-F2 | 10 px `xs` paragraph mixin (`Typography.TextExtraSmall`), reached by `Paragraph` / `Label` `size="xs"` | `mixins/text.ts` `xs` | PDS's existing 10 px step, kept for current callers; predates this standard | Michael Hu | standing | 2026-10-26 |
+| PDH-F2 | 10 px theme value (`Typography.TextExtraSmall`) | `theme.ts` `text.paragraph.xs` | Part of the theme contract consumers compile against; predates this standard | Michael Hu | standing | 2026-10-26 |
+
+`lib/middleTruncateText.ts` needs no row: its 10 px `DEFAULT_FONT` only measures text on a canvas
+and paints nothing.
+
+## Receipt
+
+Each screen records the receipt core (design-harness `spec/receipt.md`) plus `brand: persona`,
+`departures`, and `shared_components_touched` (the shared components changed, with every screen they
+reach). Until the screen receipt is automated, the screen brief in the PR body stands in for it.
+
+## Citations and tightenings
+
+No tightenings for now: every value above is the core's value.
+
+Core rules cited, all at `persona-id/design-harness` `core-v0.3`: PDH-P1, PDH-P2 (ranks 1–2) · PDH-F1 to PDH-F4 ·
+PDH-S1, PDH-S2 · PDH-M1, host side (a screen hosting an illustration, such as an empty state, sets the
+surface it sits on) · PDH-M3 · PDH-M4 · PDH-M5 (a correction meant to hold lands as a PR to this
+file). Not cited: PDH-M2, campaigns don't apply to product UI.

package/skills/ui-authoring/TOKENS.md

@@ -634,9 +634,11 @@ Typography.TextMediumLink     // 14px, regular, underlined
 Typography.TextSmall          // 12px, regular
 Typography.TextSmallBold      // 12px, bold
 Typography.TextSmallLink      // 12px, regular, underlined
-Typography.TextExtraSmall     // 10px
+Typography.TextExtraSmall     // 10px, below the 11px minimum for text the user reads (STANDARD.md)
 
 Typography.TextMono           // 14px, monospace
+Typography.TextSmallMono      // 12px, monospace
+Typography.TextExtraSmallMono // 10px, monospace, below the 11px minimum for text the user reads (STANDARD.md)
 ```
 
 ## Radius

package/skills/ui-authoring/lanes.json

@@ -0,0 +1,22 @@
+{
+  "version": 1,
+  "trailer": "Harness-Task",
+  "roles": {
+    "screen": "Files inside the screen or route directory the lane adds. The app's harness config names where screen directories live.",
+    "screen-tests": "Tests and stories for that screen kept outside its directory.",
+    "locale": "Locale (translation) files.",
+    "route-table": "The app's route or navigation table.",
+    "shared": "Components, hooks and layouts used by more than one screen.",
+    "theme": "Theme, global styles and token overrides.",
+    "pds-mirror": "Code mirrored or copied from @persona/design-system."
+  },
+  "lanes": {
+    "new-screen": {
+      "description": "One new screen built from PDS patterns and components, with no designer.",
+      "newScreens": 1,
+      "allow": ["screen", "screen-tests", "locale"],
+      "note": ["route-table"],
+      "forbid": ["shared", "theme", "pds-mirror"]
+    }
+  }
+}