altitude-design 0.2.0 → 0.3.0

package/dist/guidance/patterns/edit-record.md

@@ -0,0 +1,51 @@
+# Edit record
+
+Help someone change a durable record without losing work. Use this for settings, profiles and ordinary record forms. Prefer `InlineEdit` for a contextual single value and a route for extended work, history or deep links; a dialog is only for a bounded interruption. Do not use this hook as a backend, authorization layer or autosave engine.
+
+## Inputs and ownership
+
+Supply an initial value, synchronous business validation, an explicit `validationMode` (`submit` or `blur`), and a `save` adapter that returns a successful canonical value only when the promised persistence succeeds. Supply localized field labels, error messages and status text. The default equality is shallow; provide `isEqual` for nested records. The app owns service concurrency (revision/ETag or idempotency), authorization and navigation. Use server validation as authoritative where required.
+
+## States and transitions
+
+The runtime phases are `editing`, `invalid`, `submitting`, `saved` and `failed`; `dirty` distinguishes pristine from edited input. Pristine becomes editing when input changes. Invalid submission reveals inline errors and a summary from the same error model. Valid submit becomes pending immediately and rejects duplicate activation. Rejected persistence becomes failure while preserving input; retry revalidates and saves again. Success updates the baseline only after the adapter confirms it. A response for an older draft must never replace newer input. Only explicit reset/discard restores the baseline. Unmounting does not undo a dispatched request.
+
+## Content, keyboard, focus and announcements
+
+Use a named native form, persistent visible labels and outcome-specific buttons such as “Save settings”. Errors say what happened and how to fix it; transport errors belong to the operation, not an arbitrary field. `ErrorSummary` links to actual control IDs and takes focus on invalid submit via `focusKey={form.submitCount}`. Keep hint and error references valid and preserve external descriptions. `WorkflowStatus` announces operation feedback without unnecessary focus movement. Do not announce success on click or clear errors on unrelated events. Enter submits a form; Tab follows meaningful DOM order; focus remains visible.
+
+Choose submit validation by default; blur validation is an explicit product choice. Avoid scolding during incomplete typing. Keep related labels, errors and controls together when narrow; allow long translations to wrap, use logical spacing, and preserve every action with RTL, zoom and forced colors. Pending is text/semantics as well as height.
+
+## Recovery and unsaved work
+
+Wire `requestLeave(reason, confirmDiscard)` to cancel, router Back and every internal navigation path. Clean forms need no prompt; pending forms cannot claim cancellation. The supplied confirmation must obtain a real decision; refusing leaves the draft intact, accepting discards deliberately. Integrate `beforeunload` separately when appropriate: browsers limit its custom text and may not fire it in all lifecycle cases. Persist resumable drafts in the application when loss across reload/session termination is unacceptable. Restore focus logically after leaving, especially when the originating control is removed.
+
+## Working implementation
+
+The package exports `useEditRecord`, `ErrorSummary` and `WorkflowStatus`. This minimal composition is supplemented by the executable fixture linked in metadata:
+
+```tsx
+const form = useEditRecord({
+  initialValue: { name: 'Northwind' }, validationMode: 'submit',
+  validate: value => value.name.trim() ? {} : { name: 'Enter a workspace name.' },
+  save: async value => ({ ok: true, value: await api.saveSettings(value) }),
+});
+return <form onSubmit={event => { event.preventDefault(); void form.submit(); }}>
+  <ErrorSummary focusKey={form.submitCount} errors={form.errors.name
+    ? [{ id: 'name', label: 'Workspace name', message: form.errors.name }] : []} />
+  <Field label="Workspace name" error={form.errors.name}>
+    <Input id="name" value={form.draft.name}
+      onChange={event => form.setField('name', event.target.value)} />
+  </Field>
+  <Button type="submit" disabled={form.phase === 'submitting'}>Save settings</Button>
+  <WorkflowStatus>{form.status}</WorkflowStatus>
+</form>;
+```
+
+The `api` is application supplied and must reject failure or return the documented `{ok:false,error,errors?}` result through the save adapter; this example does not manufacture a service. Use the full fixture for cancellation, failure and newer-edit cases.
+
+## Rules, verification and evidence
+
+Read [metadata](edit-record.json) for stable identity, applicability, exceptions, maturity, source IDs, implementation and executable test references. `ALT-EDIT-001` covers retained input and truthful persistence; `ALT-EDIT-002` covers error relationships; `ALT-EDIT-003` requires contextual validation/navigation choices; `ALT-STATUS-001` and `ALT-VISUAL-001` cover equivalent feedback. Run the linked browser fixtures with delayed, rejected, retried and stale saves, asserting saved data as well as text. Verify summary links and keyboard correction manually with supported assistive technology. Normative WCAG requirements are scoped; the error-summary composition and validation timing are contextual guidance. Engineering fixtures do not establish improved human task performance.
+
+See [running examples and verification](../principles.md#run-the-examples-and-verification) for the installed example command, repository test command, and the limits of shipped test-reference snapshots.

package/dist/guidance/patterns/import.json

@@ -0,0 +1,77 @@
+{
+  "schemaVersion": 1,
+  "id": "import",
+  "version": 1,
+  "title": "Import",
+  "intents": [
+    "import",
+    "upload csv",
+    "csv",
+    "bulk import",
+    "map columns",
+    "spreadsheet upload"
+  ],
+  "purpose": "Upload a file, map its columns, fix the rows with problems, review and import with a receipt.",
+  "useWhen": [
+    "People bring many records in from a CSV or spreadsheet file."
+  ],
+  "avoidWhen": [
+    "Attaching files to a record; use DropZone with its upload queue."
+  ],
+  "alternatives": [
+    "Use DropZone for attachments, and the review-submit contract for a short form."
+  ],
+  "requiredInputs": [
+    "accepted file types and size limit",
+    "a parser returning columns and rows with line numbers",
+    "target fields with which are required",
+    "validation per field and the duplicate rule",
+    "an import job adapter with progress and cancellation where supported"
+  ],
+  "states": [
+    "upload",
+    "uploading",
+    "upload-failed",
+    "mapping",
+    "required-unmapped",
+    "fixing",
+    "reviewing",
+    "importing",
+    "cancelled",
+    "import-failed",
+    "complete"
+  ],
+  "transitions": [
+    "upload → uploading → mapping, or upload-failed with Retry",
+    "mapping → fixing once every required field is mapped",
+    "fixing → reviewing; rows with problems are skipped",
+    "reviewing → importing → complete with a receipt",
+    "importing → cancelled or import-failed, saying what was imported"
+  ],
+  "rules": [
+    "ALT-IMPORT-001",
+    "ALT-REVIEW-001",
+    "ALT-STATUS-001"
+  ],
+  "sources": [
+    "altitude-elevation",
+    "task-review",
+    "wcag22"
+  ],
+  "authority": "contextual-pattern",
+  "applicability": "Importing many records from a file.",
+  "exceptions": [
+    "Require only states supported by the application; an import that can't be cancelled omits Cancel and says so."
+  ],
+  "maturity": "provisional",
+  "evidenceStatus": "engineering-fixtures; human-effectiveness-unmeasured",
+  "document": "patterns/import.md",
+  "implementation": "build/fixtures/patterns/import.jsx",
+  "examples": [
+    "build/fixtures/patterns/import.jsx"
+  ],
+  "verification": [
+    "build/checks/import-pattern.mjs",
+    "build/checks/pattern-types.mjs"
+  ]
+}

package/dist/guidance/patterns/import.md

@@ -0,0 +1,31 @@
+# Import
+
+Help someone bring records in from a file: upload it, map its columns to fields, see and fix the rows with problems, review what will happen, and import it as a job with a receipt of what was imported, skipped and why. It composes [Review and submit](review-submit.md) for the review and receipt; the steps use `Stepper`.
+
+## Inputs and ownership
+
+Supply the accepted file types and size limit, a parser that returns columns and rows (with line numbers), the target fields and which are required, validation per field, the duplicate rule, an import job adapter that reports progress and supports cancellation where the service can, and a way to download the rows that weren't imported. The application owns parsing, encoding detection, validation on the server (the interface's checks are a preview), duplicate detection, the import itself and what a cancelled import leaves behind.
+
+## States and transitions
+
+Steps: **upload → map → fix → review → import**, shown in a `Stepper`; completed steps can be revisited until the import starts.
+
+- **Upload** follows the DropZone queue: uploading with progress, processing, done (move to mapping) or failed with the reason and Retry.
+- **Map**: one `Select` per source column, labelled with the column's header and a sample value. An unmapped Select is an opening that **fills when mapped** (the Completeness signal), so what's left is visible. Required fields still unmapped are listed in words ("Map these required fields: Name, Email.") and Continue waits for them. "Don't import" is an explicit choice.
+- **Fix** happens in a `DataGrid` with `showInvalid`: **invalid cells lie in a trench on critical-soft** (the Validity signal) and each cell's description says its problem, so the work left shows at a glance. Editing a cell revalidates it. The problem count is said as it changes ("2 problems left in 2 rows"). "Only rows with problems" narrows the grid. Rows still with problems are skipped, and the page says so.
+- **Review** is one sentence of consequences ("5 contacts will be imported. 3 rows will be skipped: 1 duplicate and 2 with problems.") and a button that names the outcome ("Import 5 contacts").
+- **Import** is a job: `Progress` with the count in words ("Importing 3 of 5"), cancellable where the service supports it (and the cancelled state says what was already imported), then a receipt of imported, skipped and failed counts with the skipped rows downloadable, and an entry in the activity log.
+
+## Content, keyboard, focus and announcements
+
+Each step change moves focus to its heading. The grid follows spreadsheet keys (arrows, Enter to edit, Escape to discard); each cell's name includes its row ("Email, row 3"). Counts are announced politely when they change, never per keystroke. The mapping grid reflows to one column on narrow screens; the data grid scrolls horizontally. Verify forced colors (invalid cells keep a dashed outline), reduced motion, zoom and RTL.
+
+## Recovery and working implementation
+
+A failed upload offers Retry. Leaving the fix step keeps the edits. A failed import says how many rows were imported before it stopped and offers to continue. The working example in `build/fixtures/patterns/import.jsx` (shipped as `references/build/fixtures/patterns/import.jsx`) composes the five steps with a sample file, mapping, invalid cells to fix, a review, a cancellable import and a receipt. It is also the Storybook preview "Patterns/ImportPattern". [Metadata](import.json) names the runtime and verification sources.
+
+## Rules, verification and evidence
+
+`ALT-IMPORT-001` covers mapping as completeness, invalid cells as trenches with their problem, and the job with its receipt; `ALT-REVIEW-001` covers review and receipt; `ALT-STATUS-001` covers announcements. `build/checks/import-pattern.mjs` checks the example in a browser, including DataGrid's `showInvalid`. See [rules](../rules.json). How people handle large files with many problems still needs evaluation with representative users and real data.
+
+See [running examples and verification](../principles.md#run-the-examples-and-verification) for the installed example command, repository test command, and the limits of shipped test-reference snapshots.

package/dist/guidance/patterns/members.json

@@ -0,0 +1,77 @@
+{
+  "schemaVersion": 1,
+  "id": "members",
+  "version": 1,
+  "title": "Members",
+  "intents": [
+    "members",
+    "invite teammates",
+    "invite",
+    "roles",
+    "permissions",
+    "team"
+  ],
+  "purpose": "Invite people, change roles and remove access without misdrawing invitations or breaking ownership.",
+  "useWhen": [
+    "A workspace or account has members with roles, invitations and removal."
+  ],
+  "avoidWhen": [
+    "Sharing a single document with a link; use that product's sharing dialog instead."
+  ],
+  "alternatives": [
+    "Use the settings contract for workspace preferences, and the consequential-action contract for a single removal outside a members list."
+  ],
+  "requiredInputs": [
+    "members and invitations with roles",
+    "the acting person's identity and permissions",
+    "an invite adapter with a result per address",
+    "role-change and removal adapters",
+    "a sentence per role saying what it can do"
+  ],
+  "states": [
+    "ready",
+    "invite-sending",
+    "invitation-settled",
+    "role-pending",
+    "role-committed",
+    "role-failed",
+    "guarded",
+    "confirming-removal",
+    "removal-pending",
+    "removed"
+  ],
+  "transitions": [
+    "ready → invite-sending on Send",
+    "invite-sending → invitation-settled per sent address, with the result said",
+    "ready → role-pending on a role change",
+    "role-pending → role-committed, or role-failed with the role restored",
+    "ready → confirming-removal → removal-pending → removed"
+  ],
+  "rules": [
+    "ALT-MEMBERS-001",
+    "ALT-ACTION-001",
+    "ALT-STATUS-001",
+    "ALT-VISUAL-003"
+  ],
+  "sources": [
+    "altitude-elevation",
+    "task-review",
+    "wcag22"
+  ],
+  "authority": "contextual-pattern",
+  "applicability": "Workspaces or accounts whose members have roles, invitations and removal.",
+  "exceptions": [
+    "Require only states supported by the application; products without invitations skip those states."
+  ],
+  "maturity": "provisional",
+  "evidenceStatus": "engineering-fixtures; human-effectiveness-unmeasured",
+  "document": "patterns/members.md",
+  "implementation": "build/fixtures/patterns/members.jsx",
+  "examples": [
+    "build/fixtures/patterns/members.jsx"
+  ],
+  "verification": [
+    "build/checks/members-pattern.mjs",
+    "build/checks/pattern-types.mjs"
+  ]
+}

package/dist/guidance/patterns/members.md

@@ -0,0 +1,27 @@
+# Members
+
+Help someone manage who belongs to a workspace: invite people by email with a role, see invitations still waiting, resend or revoke them, change someone's role, remove someone, and transfer ownership. It composes [Consequential action](consequential-action.md) for removal and ownership transfer; role changes apply immediately, as in [Settings](settings.md).
+
+## Inputs and ownership
+
+Supply the current members and invitations with their roles, the acting person's identity and permissions, an invite adapter that reports a result per address (sent, already a member, refused), a role-change adapter, a removal adapter, and for each role a sentence that says what it can do. The application owns authorization (every guard below must also be enforced by the server), invitation delivery and expiry, seat limits, and what happens to a removed person's work.
+
+## States and transitions
+
+An invitation awaiting acceptance is **settled**: it is a record of an offer and nothing is in flight. Draw it on the ground with a flush `Badge` "Invited", the role it grants, when it was sent, and Resend and Revoke. Only the moment of sending is pending. Invite: addresses enter a `TagInput`, which refuses an invalid address with the reason ("nope isn't an email address."); the role is chosen from a `RadioGroup` whose options say what each role can do; Send is pending until the service answers, then each new invitation lands with the afterglow and the result is said per address ("2 invites sent, 1 address is already in the workspace."). Role change: applies immediately per row; pending hovers ("Changing role…"), committed lands ("Role changed"), failed drops into a trench, says so and restores the previous role. Custom roles are edited with `PermissionMatrix`. Remove: a consequential action whose confirmation names what the person loses ("Theo loses access to 9 projects…") and whether their work stays; it is said once the service confirms. Revoke: removes the invitation and says so.
+
+**Guards**: nobody can remove the last owner or demote themselves out of the last admin or owner role. Don't offer a disabled control; say the reason in words where the action would be ("You're the only owner, so your role can't change. Transfer ownership first."). Transferring ownership is itself a consequential action.
+
+## Content, keyboard, focus and announcements
+
+Every row's controls are named with the person ("Role for Theo Marsh"). The Send button says how many invites it sends. Results are announced politely in one status region, never one announcement per address. After a removal or revocation, focus goes to a logical neighbour or the section heading, never the page body. Tables keep a minimum width and scroll horizontally on narrow screens rather than crushing names; long names and addresses wrap at word boundaries. Verify forced colors (the Invited plate's outline and a failed row's dashed border remain), reduced motion, zoom and RTL.
+
+## Recovery and working implementation
+
+A failed invite keeps the addresses that weren't sent in the field. A failed role change restores the role and can be repeated. A failed removal keeps the person and says nothing changed. The working example in `build/fixtures/patterns/members.jsx` (shipped as `references/build/fixtures/patterns/members.jsx`) composes invitations, a per-row role change with a failing demo service, the only-owner guard, removal with consequence and revocation. It is also the Storybook preview "Patterns/MembersPattern". [Metadata](members.json) names the runtime and verification sources.
+
+## Rules, verification and evidence
+
+`ALT-MEMBERS-001` covers settled invitations and guards stated in words; `ALT-ACTION-001` covers removal and transfer; `ALT-STATUS-001` covers announcements; `ALT-VISUAL-003` covers states that don't rise. `build/checks/members-pattern.mjs` checks the example in a browser: refused addresses, the pending send, settled invitation rows, per-address results, the owner guard, the role change's three states, removal and revocation. See [rules](../rules.json). How well people understand role descriptions still needs evaluation with representative users.
+
+See [running examples and verification](../principles.md#run-the-examples-and-verification) for the installed example command, repository test command, and the limits of shipped test-reference snapshots.

package/dist/guidance/patterns/onboarding.json

@@ -0,0 +1,78 @@
+{
+  "schemaVersion": 1,
+  "id": "onboarding",
+  "version": 1,
+  "title": "Onboarding",
+  "intents": [
+    "onboarding",
+    "getting started",
+    "setup checklist",
+    "product tour",
+    "tour",
+    "what's new",
+    "whats new",
+    "first run",
+    "empty state"
+  ],
+  "purpose": "Get someone new to value with a stamped setup checklist, empty states before tours, and what's new.",
+  "useWhen": [
+    "A new workspace or account needs a few setup tasks, or an existing interface changed."
+  ],
+  "avoidWhen": [
+    "Teaching the whole product up front with a modal carousel or a long tour."
+  ],
+  "alternatives": [
+    "Use EmptyState alone for a single empty region, and Tour only for a change to an interface people already use."
+  ],
+  "requiredInputs": [
+    "setup tasks with where each is done",
+    "application events when each task happens",
+    "per-person dismissal",
+    "empty regions with their one next step",
+    "the list of changes and which are unseen"
+  ],
+  "states": [
+    "guide-open",
+    "task-done",
+    "guide-complete",
+    "guide-skipped",
+    "guide-hidden",
+    "empty",
+    "tour-offered",
+    "touring",
+    "news-unseen",
+    "news-seen"
+  ],
+  "transitions": [
+    "guide-open → task-done when the application reports the task happened",
+    "guide-open → guide-skipped, or guide-complete → guide-hidden; Help reopens it",
+    "empty → filled by its one action, stamping the task",
+    "tour-offered → touring only when asked → done or skipped",
+    "news-unseen → news-seen when opened"
+  ],
+  "rules": [
+    "ALT-ONBOARD-001",
+    "ALT-STATUS-001",
+    "ALT-VISUAL-003"
+  ],
+  "sources": [
+    "altitude-elevation",
+    "task-review"
+  ],
+  "authority": "contextual-pattern",
+  "applicability": "First-run setup, empty states, tours of changes and release notes.",
+  "exceptions": [
+    "Require only the parts the product offers; products without setup tasks still prefer empty states to tours."
+  ],
+  "maturity": "provisional",
+  "evidenceStatus": "engineering-fixtures; human-effectiveness-unmeasured",
+  "document": "patterns/onboarding.md",
+  "implementation": "build/fixtures/patterns/onboarding.jsx",
+  "examples": [
+    "build/fixtures/patterns/onboarding.jsx"
+  ],
+  "verification": [
+    "build/checks/onboarding-pattern.mjs",
+    "build/checks/pattern-types.mjs"
+  ]
+}

package/dist/guidance/patterns/onboarding.md

@@ -0,0 +1,31 @@
+# Onboarding
+
+Help someone new reach value quickly: a setup checklist for the few things a workspace needs, empty states that lead to the first record, a short tour only for changes to an interface they already know, and a "What's new" for launches. Prefer empty states over tours and carousels.
+
+## Inputs and ownership
+
+Supply the setup tasks with what each does and where it's done, events from the application when each task actually happens, whether onboarding was dismissed (stored per person), the empty regions with their one next step, any tour's steps with the elements they point at, and the list of changes with which ones this person has seen. The application owns task detection (a task is done when the thing happened, not when someone clicked the item), where dismissal is remembered, and when a tour may be offered.
+
+## States and transitions
+
+**Setup checklist.** A read-only list of tasks: each is **stamped done by the application when the task actually happens**, wherever it happens, never by clicking the item; an unfinished task offers one button that goes to where it's done. Progress is a **`Meter`** ("2 of 4"), because completeness is a reading, not a task under way: never `Progress`. The checklist never blocks the app. It can be skipped while unfinished ("Skip for now") and hidden once finished ("Hide setup guide"); either way it can be found again from Help, and the page says so. (The editable `Checklist` is for lists people write; a setup list is read-only, so it's a plain list with Done plates.)
+
+**Empty states before tours.** Each empty region is an `EmptyState` that says what's empty, what will appear, and opens with its one action ("Connect a data source"). Doing it fills the region and stamps the matching setup task.
+
+**Tours** (`Tour`) only for changes to an interface someone already uses, at most a few steps, never dimming the page and **never starting on their own on every visit**: offer them ("Show me what changed in the sidebar"), and let Escape or Skip end them.
+
+**What's new** is a `Popover` or `Sheet` listing changes as a `Timeline` (newest first), with a count `Badge` only for unseen items; opening it marks them seen and the count goes.
+
+## Content, keyboard, focus and announcements
+
+Write tasks as outcomes ("Invite your team") with one line on why. Stamped tasks keep their text readable (muted, not struck through). Hiding the guide announces where to find it. The tour's cards are non-modal dialogs that take focus and return it; What's new is reachable by keyboard and closes with Escape. Everything fits at 320px. Verify forced colors (Done plates and the meter stay visible), reduced motion, zoom and RTL.
+
+## Recovery and working implementation
+
+Onboarding is optional: dismissing it never loses anything, and every surface can be reopened. If task detection fails, the task stays unstamped and its button still works. The working example in `build/fixtures/patterns/onboarding.jsx` (shipped as `references/build/fixtures/patterns/onboarding.jsx`) composes a stamped setup checklist with a Meter, an empty state whose action stamps a task, an opt-in tour, and What's new with an unseen count. It is also the Storybook preview "Patterns/OnboardingPattern". [Metadata](onboarding.json) names the runtime and verification sources.
+
+## Rules, verification and evidence
+
+`ALT-ONBOARD-001` covers stamped tasks, progress as a reading, empty states before tours, opt-in tours and dismissible, re-findable surfaces; `ALT-STATUS-001` covers announcements; `ALT-VISUAL-003` covers what must not rise. `build/checks/onboarding-pattern.mjs` checks the example in a browser. See [rules](../rules.json). Which tasks belong on a setup list still needs evaluation with representative users.
+
+See [running examples and verification](../principles.md#run-the-examples-and-verification) for the installed example command, repository test command, and the limits of shipped test-reference snapshots.

package/dist/guidance/patterns/review-submit.json

@@ -0,0 +1,72 @@
+{
+  "schemaVersion": 1,
+  "id": "review-submit",
+  "version": 1,
+  "title": "Review and submit",
+  "intents": [
+    "review",
+    "submit",
+    "process",
+    "application",
+    "wizard",
+    "answers"
+  ],
+  "purpose": "Review and correct answers before final commitment.",
+  "useWhen": [
+    "A process benefits from reviewing meaningful choices before submission."
+  ],
+  "avoidWhen": [
+    "Use edit-record for a short simple save; avoid extra steps without a task need."
+  ],
+  "alternatives": [
+    "Use edit-record for a short simple save; avoid extra steps without a task need."
+  ],
+  "requiredInputs": [
+    "initial answers",
+    "validation",
+    "submission promise returning receipt",
+    "step and correction routing",
+    "durable draft/receipt storage if needed"
+  ],
+  "states": [
+    "editing",
+    "invalid",
+    "reviewing",
+    "submitting",
+    "failure",
+    "complete"
+  ],
+  "transitions": [
+    "editing \u2192 reviewing after validation",
+    "reviewing \u2192 editing to correct",
+    "reviewing \u2192 submitting",
+    "submitting \u2192 failure or complete",
+    "failure \u2192 retry with retained applicable data"
+  ],
+  "rules": [
+    "ALT-REVIEW-001",
+    "ALT-EDIT-001",
+    "ALT-EDIT-002",
+    "ALT-STATUS-001"
+  ],
+  "sources": [
+    "govuk-validation",
+    "wcag22"
+  ],
+  "authority": "contextual-pattern",
+  "applicability": "A process benefits from reviewing meaningful choices before submission.",
+  "exceptions": [
+    "Require only states supported by the application; do not fabricate capabilities."
+  ],
+  "maturity": "provisional",
+  "evidenceStatus": "engineering-fixtures; human-effectiveness-unmeasured",
+  "document": "patterns/review-submit.md",
+  "implementation": "project/components/src/pattern-review-submit.tsx",
+  "examples": [
+    "build/fixtures/pattern-workflows.tsx",
+    "scripts/build-framework-fixture.mjs"
+  ],
+  "verification": [
+    "build/checks/pattern-workflows.mjs"
+  ]
+}

package/dist/guidance/patterns/review-submit.md

@@ -0,0 +1,27 @@
+# Review and submit
+
+Help someone inspect and correct meaningful answers before final commitment. Use a review stage for processes whose consequences or complexity warrant it. Prefer edit-record for a simple save; an extra review step is not automatically more usable. Do not invent steps or progress percentages unsupported by the real process.
+
+## Inputs and ownership
+
+Supply initial answers, business validation, final submission and a meaningful receipt returned by the service. The app owns step navigation, applicable conditional answers, authorization, durable draft storage, server idempotency and a receipt destination. Reuse known information rather than requiring redundant entry unless a scoped exception applies. If interruption recovery across reload is required, store it in the app or service; in-memory state is not durable recovery.
+
+## States and transitions
+
+Runtime phases are `editing`, `review`, `submitting` and `complete`; validation is represented by `errors`, and rejected submission returns to `review` with `error` while retaining answers. Editing becomes reviewing after validation succeeds; invalid answers remain editable with clear errors. Review shows the actual submitted values and labels, including omitted/optional answers where useful. Correction returns to editing while preserving still-applicable data. Explicit final commitment becomes submitting, then failure or complete. Failed submission keeps answers and permits retry. A service-confirmed receipt establishes complete; correcting a completed process must follow product rules rather than silently resubmitting. Newer edits and stale responses follow edit-record protections.
+
+## Content, keyboard, focus and announcements
+
+Say where the person is in the process using meaningful step labels. Give each Change action an accessible name tied to the answer. Focus the heading or relevant field after stage changes and return logically to the review item after correction. Errors use inline text plus a linked summary when appropriate. Use native form semantics and named buttons; Enter must not accidentally bypass a required review. Announce submission progress and failure with `WorkflowStatus`. Completion states what was received, the real reference and next steps; retain it visibly instead of relying on a transient toast.
+
+On narrow screens place each answer near its Change action and allow long values to wrap. Avoid a wide stepper as the only indication of position. Preserve logical order in RTL and test zoom, forced colors and reduced motion. Never convey completion only through green or elevation.
+
+## Recovery and working implementation
+
+Compose `useReviewSubmit`, `ErrorSummary`, `WorkflowStatus` and ordinary controls from the main package export. The working composition in `build/fixtures/pattern-workflows.tsx` exercises review, correction, retained answers, rejected submission, retry and a service result. Its shipped snapshot is `references/build/fixtures/pattern-workflows.tsx`; [metadata](review-submit.json) maps implementation and tests. Use the hook's explicit review/correct/submit operations and render the returned receipt. Adapters must reconcile ambiguous network failure before retrying consequential submissions and restore drafts/receipts across reload when promised.
+
+## Rules, verification and evidence
+
+`ALT-REVIEW-001` covers correction, retained applicable information and truthful persistent confirmation. `ALT-EDIT-001`, `ALT-EDIT-002` and `ALT-STATUS-001` carry save/error/feedback obligations into the process. Verify the complete journey and data outcome, not only each isolated step. Check repeated activation, correction after invalid review, failed submission and interruption recovery in the application. [Metadata](review-submit.json) records contextual authority, sources, applicability, exceptions and provisional evidence. Human comprehension and process suitability remain unmeasured by the engineering suite.
+
+See [running examples and verification](../principles.md#run-the-examples-and-verification) for the installed example command, repository test command, and the limits of shipped test-reference snapshots.

package/dist/guidance/patterns/screen-layout.json

@@ -0,0 +1,79 @@
+{
+  "schemaVersion": 1,
+  "id": "screen-layout",
+  "version": 1,
+  "title": "Screen layout",
+  "intents": [
+    "screen layout",
+    "page layout",
+    "new screen",
+    "new page",
+    "compose a screen",
+    "dashboard",
+    "focused editor",
+    "approve",
+    "approval",
+    "report",
+    "triage",
+    "inbox",
+    "setup flow"
+  ],
+  "purpose": "Choose a screen's frame from the person's task, the one thing that leads and the one primary action, instead of inheriting a sidebar, a top bar and a grid of cards.",
+  "useWhen": [
+    "Composing a new screen or a new app, before choosing where anything goes."
+  ],
+  "avoidWhen": [
+    "Copying the records frame (sidebar, filtered table, record in a sheet) for a screen whose task isn't working through many similar records."
+  ],
+  "alternatives": [
+    "Inside a chosen frame, follow the task pattern for the work itself: edit record, consequential action, review and submit, async collection."
+  ],
+  "requiredInputs": [
+    "the task in one sentence: who is here and what they came to do",
+    "the one thing that leads the screen",
+    "the one primary action, or none",
+    "what the person does next once the task is done"
+  ],
+  "states": [
+    "task-named",
+    "frame-chosen",
+    "built",
+    "checked-against-task",
+    "task-done"
+  ],
+  "transitions": [
+    "task-named → frame-chosen from the frame table, never by default",
+    "frame-chosen → built with the lead first in reading order and largest in the view",
+    "built → checked-against-task: each stated choice is visible, or the record or the screen changes",
+    "task-done → the next thing, said where the lead was"
+  ],
+  "rules": [
+    "ALT-LAYOUT-001",
+    "ALT-VISUAL-002",
+    "ALT-VISUAL-003"
+  ],
+  "sources": [
+    "altitude-elevation",
+    "task-review"
+  ],
+  "authority": "contextual-pattern",
+  "applicability": "Any new screen: its frame, what leads it and where its one primary action sits.",
+  "exceptions": [
+    "An existing product keeps its navigation frame; choose the frame of the view inside it from the task."
+  ],
+  "maturity": "provisional",
+  "evidenceStatus": "engineering-fixtures; human-effectiveness-unmeasured",
+  "document": "patterns/screen-layout.md",
+  "implementation": "build/fixtures/patterns/screen-layout-editor.jsx",
+  "examples": [
+    "build/fixtures/patterns/screen-layout-editor.jsx",
+    "build/fixtures/patterns/screen-layout-decision.jsx",
+    "build/fixtures/patterns/screen-layout-report.jsx",
+    "build/fixtures/patterns/app-skeleton.jsx"
+  ],
+  "verification": [
+    "build/checks/screen-layout-pattern.mjs",
+    "build/checks/render-tells.mjs",
+    "build/checks/pattern-types.mjs"
+  ]
+}

package/dist/guidance/patterns/screen-layout.md

@@ -0,0 +1,40 @@
+# Screen layout
+
+Choose a screen's frame from the person's task. The same sidebar, top bar and grid of cards or table on every screen is the most recognisable structure of a generated app, and it fits only one task: working through many similar records. Name the task first, then choose the frame that fits it.
+
+## Inputs and ownership
+
+Before placing anything, write down four things in the application's design record: **the task** in one sentence (who is here and what they came to do), **the lead** (the one thing the screen is about), **the primary action** (one, or none), and **what comes next** once the task is done. The application owns them; this pattern only turns them into a frame. If two leads compete, the screen is two screens, or one of them is secondary.
+
+## States and transitions
+
+Name the task, choose the frame from the table, build it, then check the build against what you wrote. Every stated choice must be visible on the screen: if the record says the draft leads, the draft is the first thing after the title and the largest thing in the view. If it isn't, change the screen or the record. When the task is done, say so where the lead was, with the next thing to do.
+
+| Frame | Fits when the person came to | What leads | Built from |
+| --- | --- | --- | --- |
+| Records | find, compare and act on many similar records | the table, filtered | `AppShell`, `FilterBar`, `DataTable`, `Sheet`: the [app skeleton](../app-skeleton.md) |
+| List and detail | triage: work through items one at a time | the open item | `ResizablePanelGroup` (it stacks when narrow), a list, a `PropertyList` |
+| Focused editor | make or change one thing | the thing being made | `Breadcrumb` back, `PageHeader` with one primary action, the editor, `SyncIndicator` or `SaveBar` |
+| Guided flow | set something up in order | the current step | `Stepper` and the [review and submit](review-submit.md) contract |
+| Decision | approve, choose or confirm | the choice and its consequence | the [consequential action](consequential-action.md) contract, `PlanPicker`, `Confirmation` |
+| Report | read and understand | a chart with a `takeaway`, or one `Stat size="hero"` | `ChartContainer`, `Stat`, `StatGroup` for the secondary numbers ([Charts](../../Charts.md)) |
+
+**Focused editor.** No navigation sidebar: a breadcrumb back is enough. The thing being made fills the column; details about it sit beside it, narrower and quieter. The one primary action (Publish, Send) is in the page header; saving is a status, not a second button.
+
+**Decision.** The question is the title. The consequence, in words, and the two choices sit together straight under it, before the evidence; the evidence follows for whoever needs it. Declining asks for its reason in place. Once decided, the outcome replaces the choice and points to the next request.
+
+**Report.** The takeaway is the heading of the chart that leads, written from the data. Secondary numbers follow, smaller and grouped, never as a row of equal cards above the chart.
+
+## Content, keyboard, focus and announcements
+
+The title says the task's object ("Week 44 release note", "Refund €420 to Northwind?"). Reading order follows importance: title, lead, primary action, then the rest. Each frame keeps a keyboard path through the lead and returns focus where an action started: cancelling a decline returns to Decline, and an outcome takes focus when it replaces the control that had it. Saving and outcomes are announced as status. Every frame fits at 320px, where the side column stacks under the lead.
+
+## Recovery and working implementation
+
+If the task changes, re-choose the frame instead of adding a second lead. The working examples are `build/fixtures/patterns/screen-layout-editor.jsx`, `screen-layout-decision.jsx` and `screen-layout-report.jsx` (shipped under `references/build/fixtures/patterns/`), each with its design record in its first lines. They're also the Storybook previews "Patterns/ScreenLayoutEditor", "Patterns/ScreenLayoutDecision" and "Patterns/ScreenLayoutReport"; the records frame is the [app skeleton](../app-skeleton.md). [Metadata](screen-layout.json) names the verification sources.
+
+## Rules, verification and evidence
+
+`ALT-LAYOUT-001` covers naming the task, the lead and the primary action before choosing a frame; `ALT-VISUAL-002` covers one primary action per view; `ALT-VISUAL-003` covers what must not rise. `build/checks/screen-layout-pattern.mjs` checks each example in a browser: the stated lead is first after the title and the largest region, there's at most one primary action, and its keyboard and focus behaviour. `build/checks/render-tells.mjs` reports unled equal sets and flat stacks. Structure is where generated interfaces converge most (Research, "Generated interfaces converge"); whether naming the task first moves agents away from the default is unmeasured until the distinctiveness benchmark runs with and without this pattern.
+
+See [running examples and verification](../principles.md#run-the-examples-and-verification) for the installed example command, repository test command, and the limits of shipped test-reference snapshots.