altitude-design 0.2.0 → 0.3.0

package/dist/guidance/patterns/audit-log.json

@@ -0,0 +1,75 @@
+{
+  "schemaVersion": 1,
+  "id": "audit-log",
+  "version": 1,
+  "title": "Audit log",
+  "intents": [
+    "audit log",
+    "audit",
+    "activity",
+    "history",
+    "events",
+    "security log"
+  ],
+  "purpose": "Find who did what, to which resource, when and from where, and export it.",
+  "useWhen": [
+    "A workspace keeps a log of changes that people filter, inspect and export, or a record shows its own activity."
+  ],
+  "avoidWhen": [
+    "Notifications meant for someone to act on; use NotificationCenter."
+  ],
+  "alternatives": [
+    "Use the async-collection contract for other filtered lists, and NotificationCenter for things that need attention."
+  ],
+  "requiredInputs": [
+    "events with actor, action, resource, exact time, origin, before and after",
+    "a server query that filters and pages",
+    "an export job adapter with progress and a download",
+    "the retention period"
+  ],
+  "states": [
+    "loading",
+    "ready",
+    "page-loading",
+    "no-results",
+    "empty",
+    "expanded",
+    "exporting",
+    "exported",
+    "export-failed",
+    "live-arrival"
+  ],
+  "transitions": [
+    "ready → page-loading → ready on a page turn, keeping the rows",
+    "ready → ready or no-results on a filter change, back to the first page",
+    "ready → expanded on an entry's disclosure",
+    "ready → exporting → exported with a download, or export-failed"
+  ],
+  "rules": [
+    "ALT-AUDIT-001",
+    "ALT-COLLECTION-001",
+    "ALT-STATUS-001",
+    "ALT-VISUAL-003"
+  ],
+  "sources": [
+    "altitude-elevation",
+    "task-review",
+    "wcag22"
+  ],
+  "authority": "contextual-pattern",
+  "applicability": "Workspace audit logs and record activity feeds.",
+  "exceptions": [
+    "Require only states supported by the application; a log without export skips those states."
+  ],
+  "maturity": "provisional",
+  "evidenceStatus": "engineering-fixtures; human-effectiveness-unmeasured",
+  "document": "patterns/audit-log.md",
+  "implementation": "build/fixtures/patterns/audit-log.jsx",
+  "examples": [
+    "build/fixtures/patterns/audit-log.jsx"
+  ],
+  "verification": [
+    "build/checks/audit-log-pattern.mjs",
+    "build/checks/pattern-types.mjs"
+  ]
+}

package/dist/guidance/patterns/audit-log.md

@@ -0,0 +1,27 @@
+# Audit log
+
+Help someone find out who did what, to which resource, when and from where: a workspace audit log that can be filtered, paged, expanded to the change and exported, and a lighter activity feed on each record. It composes [Async collection](async-collection.md) for loading, filtering and paging.
+
+## Inputs and ownership
+
+Supply events with an actor, an action, a resource, a time with its exact value, the origin (IP address or client), and the before and after of what changed; a server query that filters and pages them; an export job adapter that reports progress and a download; and the retention period. The application owns event capture and integrity (an audit log the interface can edit is not an audit log), retention, access control (who may read the log), and the export's contents.
+
+## States and transitions
+
+**Entries are the record**: flush rows on the ground, never raised and never cards. Each entry reads as one sentence ("Theo Marsh changed Ines Duarte's role from Member to Admin") with its actor, time (`RelativeTime`, exact value on demand) and origin in columns. Only an entry that links somewhere lifts when pointed at. The **workspace log** is a `DataTable` with a `FilterBar` (actor, action, resource, date range) and server pagination; changing a filter returns to the first page and announces the result count; turning a page holds the current rows at half strength until the next page arrives. An entry **expands** to its change as a `DiffView` (properties before and after). A **record's activity** is a `Timeline` on the record, with details behind a disclosure; don't mix the record feed and the workspace log.
+
+**Export** is a job, a task under way: `Progress` with its percentage and the words ("Preparing export, 40%"), then a toast with the download, and the export itself appears in the log. Other states: loading (imprinted rows), empty for a new workspace (say what will appear here), no results for a filter (say so and how to widen it), live arrivals (new events land with the afterglow, announced politely and throttled), and retention ("kept for 90 days on the Pro plan") said in words near the log.
+
+## Content, keyboard, focus and announcements
+
+Write entries as sentences in the past tense with real names, not codes. The disclosure that expands an entry is named by the entry. The filter bar is one Tab stop with arrow keys inside it; results are announced after each change. Pagination keeps focus on the control used. The table keeps a minimum width and scrolls horizontally on narrow screens. Verify forced colors (disclosures and diff markers stay visible), reduced motion (no afterglow movement), zoom and RTL.
+
+## Recovery and working implementation
+
+A failed page load keeps the previous rows and offers to try again. A failed export says so in the toast and offers to retry; nothing partial is offered for download. The working example in `build/fixtures/patterns/audit-log.jsx` (shipped as `references/build/fixtures/patterns/audit-log.jsx`) composes a filtered, paged log with expandable changes, an export job and a record's activity. It is also the Storybook preview "Patterns/AuditLogPattern". [Metadata](audit-log.json) names the runtime and verification sources.
+
+## Rules, verification and evidence
+
+`ALT-AUDIT-001` covers flush sentence entries, the change on expansion and export as a job; `ALT-COLLECTION-001` covers loading, filtering and paging; `ALT-STATUS-001` covers announcements; `ALT-VISUAL-003` covers states that don't rise. `build/checks/audit-log-pattern.mjs` checks the example in a browser. See [rules](../rules.json). Whether people find what they're looking for still needs evaluation with representative users and real logs.
+
+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/auth.json

@@ -0,0 +1,86 @@
+{
+  "schemaVersion": 1,
+  "id": "auth",
+  "version": 1,
+  "title": "Auth",
+  "intents": [
+    "sign in",
+    "login",
+    "log in",
+    "sign up",
+    "signup",
+    "register",
+    "two-factor",
+    "2fa",
+    "mfa",
+    "reset password",
+    "forgot password",
+    "magic link",
+    "sso"
+  ],
+  "purpose": "Sign in, sign up, verify, pass two-factor and reset a password without revealing whether an account exists.",
+  "useWhen": [
+    "A product authenticates people with passwords, SSO, emailed links or one-time codes."
+  ],
+  "avoidWhen": [
+    "Re-confirming identity before one sensitive action inside the product; use the consequential-action contract with the provider's re-authentication."
+  ],
+  "alternatives": [
+    "Use the provider's hosted sign-in page when the product delegates authentication entirely."
+  ],
+  "requiredInputs": [
+    "the sign-in methods offered",
+    "step adapters that never reveal whether an account exists",
+    "rate-limit state with its wait",
+    "link and code lifetimes",
+    "the destination after sign-in"
+  ],
+  "states": [
+    "sign-in",
+    "submitting",
+    "credentials-rejected",
+    "rate-limited",
+    "link-sent",
+    "sign-up",
+    "verify-email",
+    "two-factor",
+    "recovery-code",
+    "reset",
+    "link-expired",
+    "signed-in"
+  ],
+  "transitions": [
+    "sign-in → submitting → two-factor or signed-in, or credentials-rejected keeping the email",
+    "credentials-rejected → rate-limited after the service's limit",
+    "sign-in → link-sent, with a resend after a countdown",
+    "sign-up → verify-email → signed-in",
+    "two-factor → recovery-code → signed-in",
+    "reset → link-sent"
+  ],
+  "rules": [
+    "ALT-AUTH-001",
+    "ALT-EDIT-002",
+    "ALT-STATUS-001"
+  ],
+  "sources": [
+    "owasp-auth",
+    "wcag22",
+    "task-review"
+  ],
+  "authority": "contextual-pattern",
+  "applicability": "Sign-in, sign-up, verification, two-factor and password reset screens.",
+  "exceptions": [
+    "Require only the methods the product offers; the security of authentication itself is the application's."
+  ],
+  "maturity": "provisional",
+  "evidenceStatus": "engineering-fixtures; human-effectiveness-unmeasured",
+  "document": "patterns/auth.md",
+  "implementation": "build/fixtures/patterns/auth.jsx",
+  "examples": [
+    "build/fixtures/patterns/auth.jsx"
+  ],
+  "verification": [
+    "build/checks/auth-pattern.mjs",
+    "build/checks/pattern-types.mjs"
+  ]
+}

package/dist/guidance/patterns/auth.md

@@ -0,0 +1,29 @@
+# Auth
+
+Help someone sign in, create an account, verify their email, pass two-factor, or reset a password, with states and copy that keep them moving without revealing anything to someone else. The layout is simple; the states and words are not.
+
+## Inputs and ownership
+
+Supply the sign-in methods the product offers (password, SSO, emailed link), adapters for each step that return a result without saying whether an account exists, the rate-limit state with its wait, link and code lifetimes, and where to go once signed in. The application owns authentication, session handling, rate limiting and lockout, link and code generation and expiry, bot protection, and account recovery. This contract covers the interface; it does not certify the security of the implementation.
+
+## States and transitions
+
+Put the form on **a raised `Card` at level 1, never a level-5 `Dialog`**: nothing is behind it to recede from, and the summit stays for moments that interrupt. Flows: **sign in** (SSO first when offered, then email and password, then "Email me a sign-in link" and "Forgot your password?"); **sign up** (name, email, a new password whose requirements `PasswordInput` stamps as met); **verify email** (`InputOTP` with the code's lifetime and a resend that counts down in words); **two-factor** (`InputOTP`, "Use a recovery code instead", "Trust this device for 30 days"); **reset** (email, then the same "check your email" screen); **expired or used link** (say which and offer a new one).
+
+Submitting holds the button pressed with its words ("Signing in"). Failure keeps the email and clears only what must be re-entered. A step change moves focus to the new step's heading.
+
+**Security copy rules.** Never reveal whether an account exists: "That email and password don't match", "If that address has an account, we've sent a link". State rate limits in words with the wait ("Too many attempts. Wait 5 minutes, then try again, or reset your password."). Never submit a password or code for the person: Verify stays a button even when the code is complete. Keep the email across steps and offer to change it on every "check your email" screen.
+
+## Content, keyboard, focus and announcements
+
+Every field has its `autocomplete` token (`username` or `email`, `current-password`, `new-password`, `one-time-code`, `name`) so password managers and autofill work; pasting is never blocked. An unsuccessful submit focuses the error summary, whose links go to the fields. Don't make a cognitive test the only path: no CAPTCHA without an alternative, no transcribing codes without paste. Enter submits the current form; Tab follows the visual order. The card fits at 320px; text wraps. Verify forced colors, zoom, RTL and screen readers announcing each step's heading.
+
+## Recovery and working implementation
+
+A wrong password, wrong code or expired link says what to do next. A rate limit says when to try again and offers reset. Losing access to the authenticator offers recovery codes. The working example in `build/fixtures/patterns/auth.jsx` (shipped as `references/build/fixtures/patterns/auth.jsx`) composes sign-in with SSO, password and emailed link, sign-up with email verification, two-factor with recovery codes, reset, rate limiting and the security copy. It is also the Storybook preview "Patterns/AuthPattern". [Metadata](auth.json) names the runtime and verification sources.
+
+## Rules, verification and evidence
+
+`ALT-AUTH-001` covers the security copy, autocomplete tokens and no auto-submission; `ALT-EDIT-002` covers errors linked to fields; `ALT-STATUS-001` covers announcements. WCAG 2.2's accessible authentication and input-purpose criteria apply. The OWASP authentication cheat sheet is the source for generic responses and rate limiting. `build/checks/auth-pattern.mjs` checks the example in a browser. See [rules](../rules.json) and [evidence](../evidence.json).
+
+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/billing.json

@@ -0,0 +1,80 @@
+{
+  "schemaVersion": 1,
+  "id": "billing",
+  "version": 1,
+  "title": "Billing",
+  "intents": [
+    "billing",
+    "change plan",
+    "upgrade",
+    "downgrade",
+    "usage",
+    "invoices",
+    "subscription",
+    "pricing"
+  ],
+  "purpose": "Show usage against limits as readings and change plan with the cost reviewed before it's confirmed.",
+  "useWhen": [
+    "A product shows what someone pays for, how much they've used, and lets them change plan."
+  ],
+  "avoidWhen": [
+    "A one-off checkout for a single purchase; use the review-submit contract with the payment provider's checkout."
+  ],
+  "alternatives": [
+    "Use the review-submit contract for a one-off purchase, and the settings contract for billing contact details."
+  ],
+  "requiredInputs": [
+    "plans with prices per period",
+    "current plan and period",
+    "usage per quota with limits and thresholds",
+    "an estimate and how it's computed",
+    "a proration preview from the billing service",
+    "losses a downgrade would cause",
+    "payment status and invoices"
+  ],
+  "states": [
+    "ready",
+    "choosing",
+    "reviewing",
+    "changing",
+    "changed",
+    "change-failed",
+    "downgrade-review",
+    "payment-failed",
+    "feature-locked"
+  ],
+  "transitions": [
+    "ready → choosing → reviewing with the proration",
+    "reviewing → changing on confirm, or choosing to pick again",
+    "changing → changed when the service confirms, or change-failed with nothing charged",
+    "choosing → downgrade-review when the plan removes access",
+    "ready → payment-failed when a charge fails, until the payment method is updated"
+  ],
+  "rules": [
+    "ALT-BILLING-001",
+    "ALT-REVIEW-001",
+    "ALT-ACTION-001",
+    "ALT-VISUAL-003"
+  ],
+  "sources": [
+    "wcag22",
+    "altitude-elevation",
+    "task-review"
+  ],
+  "authority": "contextual-pattern",
+  "applicability": "Products with plans, usage limits, plan changes and invoices.",
+  "exceptions": [
+    "Require only states supported by the application; flat-priced products without usage skip the quota states."
+  ],
+  "maturity": "provisional",
+  "evidenceStatus": "engineering-fixtures; human-effectiveness-unmeasured",
+  "document": "patterns/billing.md",
+  "implementation": "build/fixtures/patterns/billing.jsx",
+  "examples": [
+    "build/fixtures/patterns/billing.jsx"
+  ],
+  "verification": [
+    "build/checks/billing-pattern.mjs",
+    "build/checks/pattern-types.mjs"
+  ]
+}

package/dist/guidance/patterns/billing.md

@@ -0,0 +1,29 @@
+# Billing
+
+Help someone understand what they pay for and change it safely: usage against plan limits, an estimate of the next bill, changing plan or billing period, locked features, a failed payment, and invoices. It composes [Review and submit](review-submit.md) for a plan change and [Consequential action](consequential-action.md) for a downgrade that removes access.
+
+## Inputs and ownership
+
+Supply the plans (prices in minor units, per period and unit), the current plan and period, usage per quota with its limit and the thresholds where it is near or over, usage history, an estimate of the next bill and how it's computed, a proration preview from the billing service for any proposed change, the losses a downgrade would cause (seats over the new limit, features in use), the payment status, and the invoices. The application and its billing provider own prices, proration, tax, entitlements and payment retries. Never compute a charge in the interface that the service hasn't quoted.
+
+## States and transitions
+
+**Usage is a reading, not a task under way.** Each quota is a `Meter`: flat ink in a flush track, a notch at the threshold, and the state said in words ("8 of 10", "Near limit", "Over limit"). Never draw a quota as `Progress`, which means work moving toward completion. History is a `BarChart` whose remaining cycle is `status="projected"`, hatched and said ("Projected"), never raised. The estimate is a `Stat` whose help text says how it's computed and when it updates.
+
+**Change plan**: choose in `PlanPicker` (the current plan is a "Current plan" plate and the recommended plan a "Recommended" plate, never extra height), then review: the heading names the change ("Upgrade to Business?") and takes focus, and the proration is a sentence ("You'll pay €84 today for the rest of this cycle, then €480/month"). Confirming is pending until the service confirms; only then does the page say "You're on Business". Changing the period is the same flow. A **downgrade that removes access** is consequential: its review lists what will be lost and when, and its button is a danger one named by the outcome ("Downgrade to Free"). Reviewing with no change says why it can't proceed.
+
+A **locked feature** uses `FeatureGate`: the control stays live with the plan it needs as a plate, and activating it explains and offers the upgrade (or "Ask an admin" when this person can't). A **failed payment** is a page banner (`Alert placement="page" variant="raised" tone="critical"`) that says what failed, by when to act, and offers to update the payment method; if access becomes restricted, app mode makes the page read-only and says why. **Invoices** are a `Table` whose amounts use `FormattedNumber` currency.
+
+## Content, keyboard, focus and announcements
+
+Prices and limits are always words as well as numbers ("€20 per seat per month"). The review moves focus to its heading; completion moves focus to the result heading; the change's progress is announced politely in one status region. Plans are a radio group with arrow-key movement; the period switch is a segmented control. Tables scroll horizontally on narrow screens. Verify forced colors (meter notches, hatched projections and plan plates stay visible), reduced motion, zoom and RTL; meaning never depends on colour alone.
+
+## Recovery and working implementation
+
+A failed plan change says nothing was charged and offers to try again, keeping the chosen plan. A failed payment banner stays until the payment method is updated. The working example in `build/fixtures/patterns/billing.jsx` (shipped as `references/build/fixtures/patterns/billing.jsx`) composes quotas, a projected usage chart, an explained estimate, an upgrade and a downgrade with losses, a locked feature, a failed payment banner and invoices. It is also the Storybook preview "Patterns/BillingPattern". [Metadata](billing.json) names the runtime and verification sources.
+
+## Rules, verification and evidence
+
+`ALT-BILLING-001` covers readings, reviewed changes and stated losses; `ALT-REVIEW-001` covers the review and receipt; `ALT-ACTION-001` covers the downgrade; `ALT-VISUAL-003` covers what must not rise (the current and recommended plan, the projection). `build/checks/billing-pattern.mjs` checks the example in a browser. WCAG 2.2's error prevention for financial transactions applies to the confirmation. See [rules](../rules.json). Whether people read proration sentences correctly 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/consequential-action.json

@@ -0,0 +1,76 @@
+{
+  "schemaVersion": 1,
+  "id": "consequential-action",
+  "version": 1,
+  "title": "Consequential action",
+  "intents": [
+    "delete",
+    "remove",
+    "revoke",
+    "publish",
+    "undo",
+    "recover",
+    "approve"
+  ],
+  "purpose": "Complete a consequential operation with appropriate review or real recovery.",
+  "useWhen": [
+    "The action has meaningful impact on data or other people."
+  ],
+  "avoidWhen": [
+    "Use direct action when application-backed recovery is appropriate; avoid ritual confirmation for trivial operations."
+  ],
+  "alternatives": [
+    "Use direct action when application-backed recovery is appropriate; avoid ritual confirmation for trivial operations."
+  ],
+  "requiredInputs": [
+    "named target and consequence",
+    "execute promise",
+    "confirmation policy",
+    "optional real undo",
+    "logical focus destination"
+  ],
+  "states": [
+    "idle",
+    "confirming",
+    "pending",
+    "failure",
+    "complete",
+    "undo-pending",
+    "undo-failure",
+    "undone"
+  ],
+  "transitions": [
+    "idle \u2192 confirming or pending",
+    "confirming \u2192 idle on cancel",
+    "confirming \u2192 pending on confirm",
+    "pending \u2192 failure or complete",
+    "complete \u2192 undo-pending only with actual undo",
+    "undo-pending \u2192 undone or undo-failure"
+  ],
+  "rules": [
+    "ALT-ACTION-001",
+    "ALT-STATUS-001",
+    "ALT-EXP-001"
+  ],
+  "sources": [
+    "hold-hypothesis",
+    "task-review",
+    "wcag22"
+  ],
+  "authority": "contextual-pattern",
+  "applicability": "The action has meaningful impact on data or other people.",
+  "exceptions": [
+    "Require only states supported by the application; do not fabricate capabilities."
+  ],
+  "maturity": "provisional",
+  "evidenceStatus": "engineering-fixtures; human-effectiveness-unmeasured",
+  "document": "patterns/consequential-action.md",
+  "implementation": "project/components/src/pattern-consequential-action.tsx",
+  "examples": [
+    "build/fixtures/pattern-workflows.tsx",
+    "scripts/build-framework-fixture.mjs"
+  ],
+  "verification": [
+    "build/checks/pattern-workflows.mjs"
+  ]
+}

package/dist/guidance/patterns/consequential-action.md

@@ -0,0 +1,27 @@
+# Consequential action
+
+Help someone understand and complete an action whose consequences matter: deletion, revocation, publishing or bulk changes. Match protection to actual impact. Prefer direct action with genuine recovery where appropriate, or a focused review/confirmation when correction before commitment matters. Avoid confirmation rituals for trivial operations. A hold gesture is a scoped option, never the universal destructive-action policy.
+
+## Inputs and ownership
+
+Supply the exact target, scope and consequence, an `execute` adapter, explicit confirmation policy, optional genuine `undo`, and a logical focus destination. Explain what becomes unavailable, who is affected, and whether recovery expires. The application owns authorization, persistence, idempotency and recovery durability; an Undo label does not create an inverse operation. Legal/financial/data error prevention criteria have specific applicability and alternatives, not a blanket “confirm all deletes” rule.
+
+## States and transitions
+
+Runtime phases are `idle`, `confirming`, `pending`, `failed`, `succeeded`, `undoing` and `undone`; failed execution and failed undo share `failed`, and `retry` repeats the correct operation. Request moves from idle to confirming or pending according to policy. Cancel before execution returns to idle without a mutation. Confirm records intent and starts pending; it does not establish completion. Pending blocks repeated activation. Rejection becomes failure and offers a useful retry; success only follows a resolved execution result. Undo is available only when supplied and truthful: complete → undo-pending → undone or undo-failure. Keep a failed undo recoverable and do not report restoration before the inverse succeeds. Do not claim an in-flight operation was cancelled because its UI closed.
+
+## Content, keyboard, focus and announcements
+
+Name actions by outcome (“Delete Northwind workspace”), not “OK”. Make the target and consequence visible before commitment. Use native buttons, and an accessible Dialog for bounded confirmation; its name, inert background, contained Tab/Shift+Tab, dismissal and initial focus must remain correct. Initial focus may favor the safe option for irreversible consequences. On cancel return to the trigger; after a removed record, focus a surviving logical neighbor or heading via the application callback. Persistent failure belongs near the task; concise status uses `WorkflowStatus` without stealing focus.
+
+Long target names and consequences must wrap on narrow screens; keep cancellation and commitment visible and keyboard reachable. Verify RTL, zoom, forced colors, reduced motion and touch. Meaning must survive without animation, shadow or color.
+
+## Recovery and working implementation
+
+Compose `useConsequentialAction`, named buttons, `Dialog` when required, and `WorkflowStatus`. Wire `execute` to the real mutation and `undo` only to its real inverse. The executable `build/fixtures/pattern-workflows.tsx` demonstrates intent cancellation, delayed execution, failure/retry, true removal and restoration; the distributed snapshot is `references/build/fixtures/pattern-workflows.tsx`. [Metadata](consequential-action.json) names runtime and verification sources. App adapters must handle deletion races, permission changes and ambiguous transport outcomes; retries need idempotency or reconciliation where duplicate effects matter. Recovery should have a durable destination beyond an ephemeral toast when its availability requires it.
+
+## Rules, verification and evidence
+
+`ALT-ACTION-001` checks the integration boundary between confirmation and actual completion, including real undo and logical focus. `ALT-STATUS-001` covers feedback. `ALT-EXP-001` explicitly marks hold-to-confirm task benefit as unvalidated. See [rules](../rules.json) and [metadata](consequential-action.json) for source authority, applicability, exceptions, provisional maturity and executable references. Browser tests establish operation sequences; representative-user evaluation is still needed for the suitability and comprehensibility of the protection.
+
+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/developer-settings.json

@@ -0,0 +1,79 @@
+{
+  "schemaVersion": 1,
+  "id": "developer-settings",
+  "version": 1,
+  "title": "Developer settings",
+  "intents": [
+    "api keys",
+    "api key",
+    "webhooks",
+    "webhook",
+    "integrations",
+    "developer settings",
+    "developers",
+    "oauth"
+  ],
+  "purpose": "Create, roll and revoke API keys, manage webhooks and connect integrations without treating them as ordinary forms.",
+  "useWhen": [
+    "A product exposes API keys, webhooks or third-party integrations to its customers."
+  ],
+  "avoidWhen": [
+    "Personal access tokens for the product's own sign-in; use the auth contract and SecretField."
+  ],
+  "alternatives": [
+    "Use the settings contract for ordinary preferences, and SecretField alone for one stored secret."
+  ],
+  "requiredInputs": [
+    "keys with name, masked tail and last use",
+    "a create adapter returning the secret once",
+    "roll and revoke adapters with the roll's overlap window",
+    "webhook endpoints, events, deliveries and retry and test adapters",
+    "integrations with OAuth start and completion"
+  ],
+  "states": [
+    "key-creating",
+    "secret-shown",
+    "secret-acknowledged",
+    "rolling",
+    "revoking",
+    "delivery-failed",
+    "delivery-retrying",
+    "test-sent",
+    "oauth-pending",
+    "connected",
+    "disconnecting"
+  ],
+  "transitions": [
+    "key-creating → secret-shown → secret-acknowledged before the dialog can close",
+    "rolling → the new key, with the old one working for the overlap",
+    "revoking → the key removed, said",
+    "delivery-failed → delivery-retrying → delivered or failed with its attempt",
+    "oauth-pending → connected, or back to Connect when abandoned",
+    "connected → disconnecting → not connected"
+  ],
+  "rules": [
+    "ALT-DEV-001",
+    "ALT-ACTION-001",
+    "ALT-STATUS-001"
+  ],
+  "sources": [
+    "task-review",
+    "altitude-elevation"
+  ],
+  "authority": "contextual-pattern",
+  "applicability": "Developer areas with API keys, webhooks and integrations.",
+  "exceptions": [
+    "Require only the parts the product offers; products that allow revealing a stored secret must still mask it by default."
+  ],
+  "maturity": "provisional",
+  "evidenceStatus": "engineering-fixtures; human-effectiveness-unmeasured",
+  "document": "patterns/developer-settings.md",
+  "implementation": "build/fixtures/patterns/developer-settings.jsx",
+  "examples": [
+    "build/fixtures/patterns/developer-settings.jsx"
+  ],
+  "verification": [
+    "build/checks/developer-settings-pattern.mjs",
+    "build/checks/pattern-types.mjs"
+  ]
+}

package/dist/guidance/patterns/developer-settings.md

@@ -0,0 +1,29 @@
+# Developer settings
+
+Help someone manage how other software reaches their account: API keys (create, list, roll, revoke), webhooks (endpoints, events, deliveries, retries, test events), and integrations (connect through OAuth, disconnect). These screens look like forms but carry production consequences: a leaked or revoked key breaks a live service. It composes [Consequential action](consequential-action.md) for revoke, roll and disconnect.
+
+## Inputs and ownership
+
+Supply keys with a name, a masked tail and when each was last used (and by what); a create adapter that returns the secret once; roll and revoke adapters, with the overlap window a roll allows; webhook endpoints with their events, recent deliveries with results and attempts, a retry adapter and a test-event adapter returning the payload; integrations with their state and an OAuth start and completion. The application owns secret generation and storage (a secret is shown once and never retrievable from the interface afterwards unless the product deliberately supports it), signing, retry schedules, OAuth scopes and token revocation.
+
+## States and transitions
+
+**API keys.** Creation happens in a `Dialog` that **can't be closed by Escape or the backdrop until the secret is acknowledged**: `SecretField once` shows the secret in full with "You won't see this key again", and Done waits for "I've saved this key". The list shows keys **masked** (prefix and last characters) with their name and last use ("Used 3 minutes ago by 3 services"), never in full. **Roll** says the overlap in words ("The old key keeps working for 24 hours") before confirming, and afterwards. **Revoke** is a consequential action that names what breaks ("Requests that use it fail immediately. Used 3 minutes ago by 3 services."), behind a danger button.
+
+**Webhooks.** An endpoint shows its URL, whether it's active, and its events as `Checkbox`es. **Deliveries are a `Timeline`**: each entry is the event with a status plate (Delivered, Failed). A failed delivery offers Retry; a retry in progress is a dispatched write, so it **hovers as pending** with its attempt in words ("Retrying (attempt 4 of 5)"), then lands. "Send test event" shows the payload it sent in a `CodeBlock`. The signing secret is a stored `SecretField`.
+
+**Integrations.** Each is a `Card` with what it does and one action. Connected ones carry a "Connected" `Badge`. An OAuth handoff in progress is pending ("Waiting for authorization") until the provider returns; a cancelled or failed handoff says so and offers to try again. **Disconnect** is consequential and says what stops. A card holds its own action buttons, so the card itself doesn't lift; make a card `interactive` only when the whole card is one action (opening the integration's page).
+
+## Content, keyboard, focus and announcements
+
+Every row action is named with its target ("Revoke CI pipeline key"). Results are announced politely in one status region; focus returns to a logical place after a dialog. Secrets use a monospace face and copy buttons; never put a secret in a URL, a toast or a log entry. Tables scroll horizontally on narrow screens. Verify forced colors (masked keys, status plates and the pending retry stay distinguishable), reduced motion, zoom and RTL.
+
+## Recovery and working implementation
+
+A failed create, roll or revoke says nothing changed and offers to try again; a failed retry returns the delivery to Failed with the attempt count; an abandoned OAuth handoff returns the card to Connect. The working example in `build/fixtures/patterns/developer-settings.jsx` (shipped as `references/build/fixtures/patterns/developer-settings.jsx`) composes key creation shown once, a masked list, roll, revoke, webhook deliveries with a pending retry and a test payload, and integrations with an OAuth handoff. It is also the Storybook preview "Patterns/DeveloperSettingsPattern". [Metadata](developer-settings.json) names the runtime and verification sources.
+
+## Rules, verification and evidence
+
+`ALT-DEV-001` covers secrets shown once behind acknowledgement, masked lists, roll overlaps and revocation that names what breaks; `ALT-ACTION-001` covers the confirmations; `ALT-STATUS-001` covers announcements. `build/checks/developer-settings-pattern.mjs` checks the example in a browser. See [rules](../rules.json). Sample secrets in examples are obviously fake (`ak_live_EXAMPLE…`).
+
+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/edit-record.json

@@ -0,0 +1,74 @@
+{
+  "schemaVersion": 1,
+  "id": "edit-record",
+  "version": 1,
+  "title": "Edit record",
+  "intents": [
+    "edit",
+    "settings",
+    "form",
+    "save",
+    "record",
+    "profile"
+  ],
+  "purpose": "Edit a durable record without losing work.",
+  "useWhen": [
+    "A record has editable fields and an explicit persistence operation."
+  ],
+  "avoidWhen": [
+    "Use InlineEdit for a contextual single value; use a route for extended work."
+  ],
+  "alternatives": [
+    "Use InlineEdit for a contextual single value; use a route for extended work."
+  ],
+  "requiredInputs": [
+    "initialValue",
+    "business validation",
+    "save promise returning canonical persisted value",
+    "unsaved-work/navigation policy"
+  ],
+  "states": [
+    "pristine",
+    "editing",
+    "invalid",
+    "pending",
+    "failure",
+    "success"
+  ],
+  "transitions": [
+    "editing \u2192 invalid on failed validation",
+    "editing \u2192 pending on valid submit",
+    "pending \u2192 failure on rejected persistence",
+    "failure \u2192 pending on retry",
+    "pending \u2192 success only after current response; newer edits remain dirty"
+  ],
+  "rules": [
+    "ALT-EDIT-001",
+    "ALT-EDIT-002",
+    "ALT-EDIT-003",
+    "ALT-STATUS-001",
+    "ALT-VISUAL-001"
+  ],
+  "sources": [
+    "altitude-elevation",
+    "govuk-validation",
+    "task-review",
+    "wcag22"
+  ],
+  "authority": "contextual-pattern",
+  "applicability": "A record has editable fields and an explicit persistence operation.",
+  "exceptions": [
+    "Require only states supported by the application; do not fabricate capabilities."
+  ],
+  "maturity": "provisional",
+  "evidenceStatus": "engineering-fixtures; human-effectiveness-unmeasured",
+  "document": "patterns/edit-record.md",
+  "implementation": "project/components/src/pattern-edit-record.tsx",
+  "examples": [
+    "build/fixtures/pattern-workflows.tsx",
+    "scripts/build-framework-fixture.mjs"
+  ],
+  "verification": [
+    "build/checks/pattern-workflows.mjs"
+  ]
+}