stylegallery 0.1.4 → 0.1.7

package/design-engineering/component-contract.md

@@ -0,0 +1,114 @@
+---
+type: Domain Guide
+title: Component Contract
+description: Define product component semantics, states, events, asynchronous ownership, and verification before visual treatment.
+domain: design-engineering
+lifecycle: experimental
+provenance_kind: local
+---
+
+# Component Contract
+
+Primary role: product component implementation handoff.
+
+## Repository Boundary
+
+This contract describes consumer-owned behavior. It does not create a shared component library, new Layout primitive, or default visual values. Existing profile records have their own closed schema; this planning template cannot substitute for their evidence records.
+
+## Reusable Method
+
+Start with semantic HTML or the platform's native control. Name the public inputs, emitted events, internal state, and owner of persisted data. Then describe each transition and its observable outcome. Use the [Worked Examples](worked-examples.md) to check common failure paths.
+
+For reusable ownership and transition mechanisms, use the [State Management catalog](state-management/index.md). The [submitted snapshot pattern](state-management/patterns/submitted-snapshot.md) provides an executable model of the save contract below.
+
+## Contract Template
+
+| Field | Required answer |
+| --- | --- |
+| Task | The user action and the outcome the component supports |
+| Semantics | Element/control, accessible name, description, value, relationships |
+| Inputs | Data and callbacks, required/optional values, identity and revision |
+| Outputs | Events, payload meaning, when they are emitted, who commits the result |
+| State | Initial, active, selected, disabled, pending, empty, error, completed as applicable |
+| State ownership | Controlled inputs versus internal temporary state; reconciliation rule |
+| Input and focus | Keyboard, pointer, touch, focus entry/return and unavailable actions; for any drag operation, the separate single-pointer and keyboard alternatives |
+| Async ownership | Request identity, duplicate action policy, stale result handling, cancellation |
+| Content | Empty, long, localized, unbroken and unavailable data |
+| Spatial composition | Layout source, parent constraints, scroll owner and overflow behavior |
+| Presentation | Product-owned values, density, visual hierarchy and optional motion brief |
+| Lifecycle | Creation, navigation, rerender, removal, event/listener cleanup |
+| Evidence | Expected behavior, actual result, runtime, source revision and artifacts |
+| Handoff | `consumer_reference` record or `not_applicable` with a reason |
+
+## Worked Contract: Save Action
+
+Task: persist the current editable document. The form owns the draft; the save operation owns a submitted snapshot; the server owns the persisted result. A success for snapshot A must not mark newer draft B as saved.
+
+| Current state | Event | Next state | Required effect |
+| --- | --- | --- | --- |
+| Clean | Edit | Dirty | Keep entered values; mark unsaved changes |
+| Dirty | Submit valid draft A | Saving A | Capture A and a request identity; acknowledge pending |
+| Saving A | Submit again | Saving A | Apply the declared duplicate policy; this example ignores the duplicate |
+| Saving A | Edit to B | Saving A with dirty B | Preserve B and distinguish it from submitted A |
+| Saving A | Matching success | Clean if draft still A; otherwise dirty B | Record persisted A without discarding B |
+| Saving A | Matching failure | Dirty current draft with error | Keep values and offer retry |
+| Any | Stale response | Unchanged | Ignore responses outside the active operation |
+| Any | Unmount/navigation | Disposed | Stop UI updates; cancellation does not imply the server rolled back |
+
+Implementation sketch, independent of framework:
+
+```text
+on submit:
+  if a request is active: return
+  validate the current draft
+  copy the draft into submittedSnapshot
+  create requestIdentity
+  start persistence(requestIdentity, submittedSnapshot)
+on result(identity, result):
+  if disposed or identity is not active: return
+  clear the active request
+  if successful: set persistedSnapshot to submittedSnapshot
+  else: expose a recoverable error
+  derive dirty state by comparing current draft with persistedSnapshot
+```
+
+A real application also defines revision conflicts, server normalization, and retry semantics. The sketch is not a distributed consistency protocol. Its handoff is `consumer_reference: not_applicable` because this fictional example selects no consumer profile or conformance record.
+
+## Drag Operations Need Two Alternatives
+
+When a component commits a value through dragging (reorder, slider thumb, resize handle, board column move), answer the Input and focus field once per input path:
+
+| Path | Required answer |
+| --- | --- |
+| Drag | What previews, what release commits, what cancellation restores |
+| Single pointer without dragging | Which click or tap controls reach the same committed value, and where they are visible without hover |
+| Keyboard | Which keys reach the same committed value, and where focus rests afterwards |
+
+[WCAG 2.2 Success Criterion 2.5.7](https://www.w3.org/TR/WCAG22/#dragging-movements) (Level AA) is the named source for the second row. Its Understanding document evaluates it independently from keyboard operation, so a keyboard handler does not answer it and pointer-only buttons do not answer the keyboard row. The criterion excepts dragging that is essential and functionality the user agent determines without author modification; a custom slider, sortable list, or pan surface owns all three rows. A swipe or flick is not an acceptable second row because it is still a path-based gesture. All paths emit the same output event with the same payload meaning, so validation, duplicate policy, and stale-result handling are not bypassed by the alternative. The motion and cancellation side is in [Drag And Settle](../motion/interaction-recipes.md#drag-and-settle).
+
+This contract names what to declare. It does not establish conformance; that requires the consuming product's rendered behavior under the [accessibility evidence gate](../quality/gates/accessibility-evidence.md). [Target Size (Minimum)](https://www.w3.org/WAI/WCAG22/Understanding/target-size-minimum.html) is a different criterion for the size of those pointer controls and is measured in CSS pixels, not platform dp or pt.
+
+## Opinionated Guidance
+
+Use state names that expose meaningful differences. Two booleans can accidentally permit “saved and failed”; a state transition table helps reveal impossible combinations. Do not merge input validity, request state, and persisted revision into one visual status.
+
+## Platform-Specific Guidance
+
+For web forms, preserve native label and form relationships. Validate custom semantics against the applicable [accessibility evidence gate](../quality/gates/accessibility-evidence.md). Framework scheduling, request abort behavior, and server idempotency require separate implementation evidence.
+
+## Unsupported Absolutes
+
+A state table does not prove accessibility, successful persistence, race freedom, or device coverage. Cancelling a client request does not prove its remote side effects stopped.
+
+## Verification Contract
+
+Resolve responses out of order, edit during saving, fail then retry, activate repeatedly, and remove the component before completion. Inspect both persisted and displayed values. Include keyboard-only operation, long content, and constrained parents. For a drag operation, complete the task by drag, by click or tap without movement, and by keyboard, then compare the committed value, emitted event, and focus position. Record actual outcomes; the table above is an unexecuted reference contract. Review when a public input, event, or state meaning changes.
+
+## Source, License, And Attribution
+
+Locally authored contract and pseudocode; no framework or upstream implementation is copied. WCAG 2.2 (W3C Recommendation, 12 December 2024) and the informative Understanding pages for Success Criteria 2.5.7 (updated 10 August 2026) and 2.5.8 were rechecked on 2026-09-19 for the statements attributed to them; the three-path table is local synthesis and has not been executed against a product. Shared quality gates own evidence admissibility.
+
+## IA Navigation
+
+Parent: [Design Engineering](index.md).
+Next: [Design Engineering Worked Examples](worked-examples.md).

package/design-engineering/decision-tree.md

@@ -0,0 +1,70 @@
+---
+type: Domain Guide
+title: Design Engineering Decision Tree
+description: Route product craft work from the uncertain decision to a contract, example, and appropriate evidence.
+domain: design-engineering
+lifecycle: experimental
+provenance_kind: local
+---
+
+# Design Engineering Decision Tree
+
+Primary role: product implementation planning route.
+
+## Repository Boundary
+
+This route turns a product request into a bounded implementation decision. It owns neither shared quality policy nor a default design system. Use the existing Layout corpus for geometry and Motion for temporal behavior.
+
+## Reusable Method
+
+1. Write the user's action and the expected result in one sentence.
+2. Identify what is uncertain: content, structure, state, identity, platform behavior, or perception.
+3. Select the route below and produce its named artifact.
+4. Implement the smallest slice containing the risky state, including failure and recovery.
+5. Verify the observable and record the remaining limitation using [Interface Craft Decisions](interface-craft.md).
+
+## Task Routes
+
+| Uncertain decision | Primary route | Artifact to produce |
+| --- | --- | --- |
+| What should this screen contain? | [Webpage Generation Workflow](../guides/webpage-generation-workflow.md) | Content inventory and task model |
+| What owns size, flow, and scroll? | [Layout Planning Guide](../GUIDE.md) | Layout brief and pattern composition |
+| Where should state live, and how do its transitions compose? | [State Management](state-management/index.md) | Owner map, selected patterns, and acceptance traces |
+| What happens after activation or failure? | [Component Contract](component-contract.md) | State, event, focus, and asynchronous ownership tables |
+| How should a form, search, or destructive action recover? | [Worked Examples](worked-examples.md) | Scenario-specific acceptance cases |
+| Does a product detail serve the task? | [Interface Craft Decisions](interface-craft.md) | Claim with an observable and evidence boundary |
+| How do distinct identities use one Layout contract? | [Reference Profiles](reference-profiles/index.md) | Explicit profile selection and value ownership |
+| Will an existing consumer survive migration? | [Consumer Migration Readiness](consumer-migration-readiness.md) | Thirteen-dimension consumer-owned conformance record |
+| What should move and why? | [Motion Decision Tree](../motion/decision-tree.md) | Motion brief with interruption policy |
+| Is a platform convention transferable? | [Platform Adaptation Workflow](../platform-guides/adaptation-workflow.md) | Native fact, web mapping, fallback, and runtime matrix |
+
+## Worked Intake
+
+Request: “Make saving settings feel responsive.” The risky decision is whether acknowledgement means persistence. Begin with a component contract: clean, dirty, saving, saved, and failed. A saving label acknowledges submission; the saved state waits for the persistence response. Preserve unsaved edits when requests fail. Only then evaluate a completion treatment through Motion. This order exposes duplicate writes and lost edits before visual review.
+
+An acceptance statement can be: “A failed save leaves the entered values available for retry.” “Feels responsive” remains a human perception hypothesis until measured in the relevant task.
+
+## Opinionated Guidance
+
+Prototype the uncertain state rather than an entire polished screen. A good first slice includes the initiating action, its failure, and a recovery path. Add complexity when it resolves an observed limitation.
+
+## Platform-Specific Guidance
+
+Distinguish browser, OS, assistive technology, framework, and component library versions in evidence. A library's state name is an implementation detail, not the user's task definition.
+
+## Unsupported Absolutes
+
+No selected framework, profile, token set, or prototype proves product quality. Component completion does not demonstrate migration readiness for an entire consumer.
+
+## Verification Contract
+
+The route succeeds when a reviewer can find the decision owner, artifact, failure case, and evidence needed without guessing. Verify one ordinary, one exceptional, and one interrupted task. Revisit when a route sends the reader to the wrong domain or cannot produce a testable acceptance statement.
+
+## Source, License, And Attribution
+
+Locally authored routing and settings example. Linked repository documents remain authoritative for their own contracts.
+
+## IA Navigation
+
+Parent: [Design Engineering](index.md).
+Next: [Component Contract](component-contract.md).

package/design-engineering/index.md

@@ -8,6 +8,58 @@ In scope: purpose, frequency, interaction detail, implementation review, prototy
 
 Out of scope: a second universal principle set, unsupported claims of beauty or adoption, and overrides of semantic, accessibility, Layout, or shared quality contracts.
 
+## Start Here
+
+| Task | Route |
+| --- | --- |
+| Route the uncertain product decision. | [Design Engineering Decision Tree](decision-tree.md) |
+| Specify semantics, state, requests, and focus. | [Component Contract](component-contract.md) |
+| Apply settings, search, and destructive-action contracts. | [Design Engineering Worked Examples](worked-examples.md) |
+
+These workflows and worked cases are usable experimental guidance. Expected-result tables are test designs; actual product, engine, and reader evidence must be recorded separately. Review on a failed task, a source change, or a changed ownership contract.
+
+## State Management
+
+Choose [State Management](state-management/index.md) for UI state ownership, transitions, asynchronous consistency, and lifetime. The collection contains 12 patterns and four behavior recipes within this domain.
+
+### Planning And Verification
+
+- [State decision tree](state-management/decision-tree.md)
+- [State brief](state-management/state-brief.md)
+- [State verification matrix](state-management/verification.md)
+- [State recipes and composition matrix](state-management/recipes/index.md)
+
+### Ownership And Derivation
+
+- [Single owner and controlled inputs](state-management/patterns/single-owner.md)
+- [Derived state](state-management/patterns/derived-state.md)
+- [Selection by stable identity](state-management/patterns/id-selection.md)
+
+### Editing And Persistence
+
+- [Draft and persisted baseline](state-management/patterns/draft-and-baseline.md)
+- [Submitted snapshot](state-management/patterns/submitted-snapshot.md)
+- [Unsaved navigation](state-management/patterns/unsaved-navigation.md)
+
+### Asynchronous Consistency
+
+- [Latest request wins](state-management/patterns/latest-request-wins.md)
+- [Single flight](state-management/patterns/single-flight.md)
+- [Optimistic overlay](state-management/patterns/optimistic-overlay.md)
+
+### Navigation And Lifetime
+
+- [URL state](state-management/patterns/url-state.md)
+- [Identity reset](state-management/patterns/identity-reset.md)
+- [Versioned restore](state-management/patterns/versioned-restore.md)
+
+### Screen Compositions
+
+- [Settings save](state-management/recipes/settings-save.md)
+- [Search and detail](state-management/recipes/search-detail.md)
+- [Multi-step form](state-management/recipes/multi-step-form.md)
+- [Delete and supported undo](state-management/recipes/delete-undo.md)
+
 ## Documents
 
 - [Interface Craft Decisions](interface-craft.md) connects product purpose, implementation detail, and verification without treating taste as proof.
@@ -18,11 +70,17 @@ Out of scope: a second universal principle set, unsupported claims of beauty or
 
 This domain proposes product-layer questions. [Quality Gates](../quality/index.md) remain the shared authority for claims, evidence families, accessibility precedence, rationale, and debt.
 
+## Source-Backed Deep Dives
+
+- [Native Interaction Contracts](native-interaction-contracts.md). Choose dialog, disclosure, menu, popover, and combobox behavior.
+- [Text Input And Internationalization](text-input-and-internationalization.md). Preserve IME composition, text units, mixed direction, and editing intent.
+- [Loading, Progress, And Feedback](loading-and-feedback.md). Separate pending work, accepted results, announcements, and responsiveness.
+
 ## Domain Contract
 
-See [StyleGallery Domains](../DOMAINS.md) for lifecycle, provenance, page membership, and promotion rules.
+See [StyleGallery Domains](../DOMAINS.md) for lifecycle, provenance, page membership, and staleness rules.
 
 ## IA Navigation
 
 Parent: [StyleGallery](../index.md).
-Next: [Consumer Migration Readiness](consumer-migration-readiness.md).
+Next: [Design Engineering Decision Tree](decision-tree.md).

package/design-engineering/loading-and-feedback.md

@@ -0,0 +1,91 @@
+---
+type: Domain Guide
+title: Loading, Progress, And Feedback
+description: Separate input acknowledgement, pending work, stale content, confirmed completion, and measurable responsiveness.
+domain: design-engineering
+lifecycle: experimental
+provenance_kind: local
+reviewed_on: 2026-09-21
+---
+
+# Loading, Progress, And Feedback
+
+Primary role: asynchronous presentation and measurement guide.
+
+## Repository Boundary
+
+This page owns the product's account of pending work and results. Request authority remains in [State Management](state-management/index.md), motion in [Motion](../motion/index.md), and evidence claims in [Quality](../quality/index.md). A loading treatment is not a reusable Layout pattern.
+
+## Reusable Method
+
+Identify the fact behind each displayed state. Distinguish input received, request started, work in progress, result accepted, result rendered, and result announced. Select a feedback mechanism only after its state owner and truth condition are explicit.
+
+### Source Findings
+
+| Source | Bounded finding | Implication |
+| --- | --- | --- |
+| [HTML progress element](https://html.spec.whatwg.org/multipage/form-elements.html#the-progress-element) | A progress element can represent determinate or indeterminate task completion; omitting `value` expresses indeterminate progress. | Do not fabricate a percent complete when total work is unknown. |
+| [WAI-ARIA 1.2 busy state](https://www.w3.org/TR/wai-aria-1.2/#aria-busy) | `aria-busy` indicates an element is being modified; assistive technologies may defer exposing changes while it is busy. | Clear the state on every terminal path and verify actual announcements. |
+| [Status Messages explanation](https://www.w3.org/WAI/WCAG22/Understanding/status-messages.html) | A result summary may be a status message, while the entire returned result list is not thereby a status message. | Announce concise state/result information rather than every changing node. |
+| [Interaction to Next Paint](https://web.dev/articles/inp) | INP measures interaction responsiveness through the next paint; good field responsiveness is described as at most 200 ms at the 75th percentile, assessed by device category. | Do not use that number as a required animation duration or server-response deadline. |
+| [Optimize INP](https://web.dev/articles/optimize-inp) | Input delay, event processing, and presentation delay contribute to the interaction latency. | Diagnose which interval is slow before changing a loading indicator. |
+| [Event Timing API](https://www.w3.org/TR/event-timing/) | The API defines event timing observations with implementation and exposure constraints. | Record the instrument and observation scope rather than treating callback time as total latency. |
+| [Cumulative Layout Shift](https://web.dev/articles/cls) | CLS measures unexpected layout movement with defined exclusions and aggregation. | A stable placeholder can help spatial stability without proving timely or correct completion. |
+
+Sources were inspected 2026-09-21. Browser metric guidance is a measurement convention, not a guarantee of perceived quality. Standards-track drafts and actual browser instrumentation must be distinguished.
+
+### State-To-Presentation Contract
+
+| State | Required truth | Local presentation proposal |
+| --- | --- | --- |
+| Initial pending | No accepted content exists for this request. | Explain what is loading; use stationary structure if useful. |
+| Refreshing | Previously accepted content remains visible while a new request runs. | Identify its freshness/query boundary and avoid implying it is the new result. |
+| Partial result | Some units are accepted and others remain pending or failed. | Distinguish completed units from missing units and provide a bounded retry. |
+| Determinate progress | A meaningful completed/total measure exists. | Expose that measure and its scope; distinguish upload from server processing. |
+| Indeterminate progress | The operation runs but no honest completion ratio exists. | Explain the current stage without a fabricated percentage. |
+| Success | The relevant authoritative result was accepted. | Make the result durable and expose the next action. |
+| Failure or unknown outcome | Failure is confirmed, or acknowledgement is missing. | Preserve recoverable input; distinguish safe retry from possible duplicate work. |
+| Cancel requested | A request to stop was issued. | Avoid claiming cancellation is complete until the contract supports that fact. |
+
+These treatments are local proposals. A skeleton, toast, or spinner is neither mandatory nor sufficient for any row.
+
+### Worked Scenario: Search While Keeping Results
+
+The user has query A results and submits B. Keep A visible under an explicit refreshing state. Accept B only if its request identity remains current. If A's late failure arrives while B is pending, it cannot clear B's busy state. If B fails, label the retained content as A and provide a retry tied to B.
+
+The result summary, busy state, empty state, and visible records must describe the same accepted request. “No results” is a completed result, not a synonym for “nothing rendered yet.” A late finally handler can violate this even when success callbacks are guarded; use the [latest-request contract](state-management/patterns/latest-request-wins.md).
+
+### Worked Scenario: Save With An Unknown Outcome
+
+The editor submits a snapshot. Connectivity drops after the server may have received it. The consumer must decide how to reconcile that uncertainty: a supported operation identity, refetch, or a documented recovery flow. Merely showing a retry button cannot prove that retrying is safe.
+
+Keep the submitted snapshot distinct from edits made while saving. A successful acknowledgement for the earlier snapshot cannot mark the newer draft saved. Compose [submitted snapshot](state-management/patterns/submitted-snapshot.md) with [draft and baseline](state-management/patterns/draft-and-baseline.md).
+
+## Opinionated Guidance
+
+Prefer feedback that explains the actual stage and preserves a useful next action. Evaluate delays before showing indicators against measured task frequency and latency distribution; do not turn a borrowed delay into a universal rule. Avoid artificially holding completed content merely to finish a decorative loading cycle.
+
+Keep repeated announcements bounded. When several regions update, establish which summary owns the user-facing completion message instead of making every region assertive.
+
+## Platform-Specific Guidance
+
+Native progress controls and web progress semantics differ in APIs and announcement behavior. Real screen-reader tests are needed for the selected combination. For reduced-motion loading treatment, use [Accessible Motion](../motion/accessible-motion.md); for app suspension and navigation lifetime, preserve the state owner's contract.
+
+## Unsupported Absolutes
+
+A spinner cannot prove ongoing backend work. A good INP cannot prove a successful save. A zero CLS measurement cannot prove usable loading feedback. `aria-busy` alone does not guarantee that a specific message is spoken.
+
+## Verification Contract
+
+The unexecuted scenario set includes immediate completion, slow completion, stale success, stale error, partial response, cancelled request, lost acknowledgement, retry, unmount, and reduced motion. Observe focus and announcements as well as the displayed status.
+
+For latency claims, collect a timestamp for input, first useful presentation, authoritative result, and final presentation where each is observable. Name the clock boundary; client and server timestamps cannot be subtracted without a supported synchronization method. Separate local repeatable scenarios from field distributions. Re-review after request policy, feedback ownership, or instrumentation changes.
+
+## Source, License, And Attribution
+
+Locally authored synthesis. The linked specifications and first-party performance guidance were inspected 2026-09-21. No source samples are reproduced. `consumer_reference: not_applicable` because no consumer request or evidence record is selected.
+
+## IA Navigation
+
+Parent: [Design Engineering](index.md).
+Next: [State Verification Matrix](state-management/verification.md).

package/design-engineering/native-interaction-contracts.md

@@ -0,0 +1,94 @@
+---
+type: Domain Guide
+title: Native Interaction Contracts
+description: Choose disclosure, dialog, popover, menu, and combobox behavior by semantics, focus, dismissal, and input ownership.
+domain: design-engineering
+lifecycle: experimental
+provenance_kind: local
+reviewed_on: 2026-09-21
+---
+
+# Native Interaction Contracts
+
+Primary role: product component selection and behavior guide.
+
+## Repository Boundary
+
+This guide extends the [Component Contract](component-contract.md) with source-backed decisions for native HTML and custom composites. It owns product behavior, not reusable Layout CSS. The [shared accessibility evidence contract](../quality/evidence/accessibility.md) remains the authority for evidence claims.
+
+## Reusable Method
+
+Write the user's task, the information being exposed, whether background interaction remains available, and what closes the surface. Choose semantics before appearance. Then assign keyboard, focus, pointer, and state ownership. A floating rectangle is insufficient information to choose a component.
+
+### Mechanisms And Obligations
+
+| Source | Bounded finding | Consumer responsibility |
+| --- | --- | --- |
+| [HTML interactive elements](https://html.spec.whatwg.org/multipage/interactive-elements.html) | `details` is a disclosure; `dialog` supports distinct modal and nonmodal presentation. `showModal()` participates in the modal/inert model. | Choose the right behavior, accessible name, initial focus, and close policy. |
+| [HTML popover](https://html.spec.whatwg.org/multipage/popover.html) | The attribute adds presentation behavior to elements with their own semantics; custom menu keyboard behavior still needs implementation. | Select a semantic element or role and implement its interaction contract. |
+| [APG modal dialog](https://www.w3.org/WAI/ARIA/apg/patterns/dialog-modal/) | The pattern describes contained keyboard navigation, focus placement, and return. Initial focus depends on content and task. | Test focus with long content and a missing invocation control. |
+| [APG menu button](https://www.w3.org/WAI/ARIA/apg/patterns/menu-button/) | A menu button opens a menu of actions or functions with the menu keyboard model. | Do not assign menu roles solely because links appear in a dropdown. |
+| [APG combobox](https://www.w3.org/WAI/ARIA/apg/patterns/combobox/) | A combobox has a value and a popup with defined keyboard/state relationships. | Specify text editing, suggestion navigation, selection, and escape separately. |
+| [APG disclosure](https://www.w3.org/WAI/ARIA/apg/patterns/disclosure/) | The disclosure control exposes expanded/collapsed state and toggles associated content. | Keep the control name, state, and controlled content consistent. |
+| [WAI-ARIA 1.2](https://www.w3.org/TR/wai-aria-1.2/#aria-disabled) | `aria-disabled` communicates disabled semantics. It does not implement event suppression. | Prevent disallowed activation in the application's actual event paths. |
+
+HTML is a Living Standard; WAI-ARIA 1.2 is a Recommendation; APG is informative implementation guidance. Sources were inspected 2026-09-21. Pattern examples do not establish support for an unspecified browser and assistive-technology combination.
+
+### Selection Questions
+
+| User need | Starting point | Question that can change the choice |
+| --- | --- | --- |
+| Reveal optional explanatory content | Native disclosure | Does this actually switch mutually exclusive views or choose a value? |
+| Complete a bounded task while background interaction is unavailable | Modal dialog | Must the user compare or interact with the background during this task? |
+| Temporarily expose nonmodal related content | Semantically appropriate element with popover behavior | Is the content a menu, a list of links, a form, or plain information? |
+| Invoke commands from a compact control | Menu button and menu behavior | Are these ordinary navigation links better served by ordinary link navigation? |
+| Edit a value with selectable suggestions | Combobox | Is an ordinary input, select, or separate search-result list sufficient? |
+
+These are local selection heuristics. Similar visuals can correctly produce different DOM, focus, and keyboard behavior.
+
+### Worked Contract: Edit A Record
+
+The user opens an editor from a list row. The consumer chooses a modal because this task intentionally suspends interaction with the list. Save commits a submitted snapshot; Close requests dismissal; an unsaved-change decision belongs to the state owner.
+
+| Stage | Decision to record | Adversarial case |
+| --- | --- | --- |
+| Open | Accessible name and initial focus target | Long introduction would be scrolled out of view by focusing the first input. |
+| Edit | Draft lifetime and field-error relationship | Background data refresh replaces the edited row. |
+| Save | Request identity and pending activation rule | Enter and a pointer click arrive before the request settles. |
+| Dismiss | Which paths request close and which discard changes | Escape, an outside interaction, and an explicit Cancel have different intended meanings. |
+| Return | Valid focus destination after closing | The original row was deleted or filtered out. |
+
+Compose [submitted snapshot](state-management/patterns/submitted-snapshot.md), [single flight](state-management/patterns/single-flight.md), and [unsaved navigation](state-management/patterns/unsaved-navigation.md) as needed. Animation completion cannot authorize a write or decide whether a draft is disposable.
+
+### Preserve Editing Inside Composites
+
+An editable combobox has at least two responsibilities: editing text and navigating candidate options. Specify when Arrow keys move a candidate, when Enter accepts it, and when Escape dismisses suggestions while retaining the typed text. During IME composition, those keys may belong to the input method; follow [Text Input And Internationalization](text-input-and-internationalization.md).
+
+A disabled-looking control needs a deliberate discoverability policy. Native `disabled` and `aria-disabled` have different behavior; choose which focus and activation behavior the task requires, and explain why an action is unavailable without relying only on color.
+
+## Opinionated Guidance
+
+Prefer native semantics when they fit the task, and build the smallest custom behavior that remains necessary. Name the semantic reason for every role override. Treat multiple open surfaces as an ownership question: which surface receives Escape, where focus stays, and which state survives dismissal.
+
+## Platform-Specific Guidance
+
+Native HTML behavior, browser support, and accessibility mappings are separate from framework component names. Record the browser, framework adapter, and assistive technology used in verification. A native platform's “popover” does not settle the web contract; compare [Interaction Semantics](../design-terminology/interaction-semantics.md) and [Platform Adaptation](../platform-guides/adaptation-workflow.md).
+
+## Unsupported Absolutes
+
+Top-layer presentation does not imply modality. A role does not supply keyboard handlers. Native HTML does not remove the need for an accessible name or target verification. Escape does not intrinsically mean “discard all work.”
+
+## Verification Contract
+
+The proposed matrix includes keyboard-only opening and closing, forward/backward Tab, active popup navigation, IME input, a removed opener, nested surface dismissal, long content, zoom, and reduced motion. Check visible behavior, DOM state, accessibility semantics, and the actual announcement path separately.
+
+Record the selected widget model and expected key behavior before testing. Passing a self-written handler test establishes that handler's behavior, not conformance with APG or the platform. Compare observed behavior with the cited contract. No browser or screen-reader execution is claimed by this guide. Re-review when the widget model, browser, or focus owner changes.
+
+## Source, License, And Attribution
+
+Locally authored synthesis of the official sources linked above, inspected 2026-09-21. No upstream examples or implementation are reproduced. `consumer_reference: not_applicable` because this guide selects no consumer component record.
+
+## IA Navigation
+
+Parent: [Design Engineering](index.md).
+Next: [Text Input And Internationalization](text-input-and-internationalization.md).

package/design-engineering/state-management/decision-tree.md

@@ -0,0 +1,60 @@
+---
+type: Domain Guide
+title: State Management Decision Tree
+description: Route UI state problems to the smallest ownership or transition contract.
+domain: design-engineering
+lifecycle: experimental
+provenance_kind: local
+---
+
+# State Management Decision Tree
+
+## Repository Boundary
+
+This route selects consumer behavior within Design Engineering. It does not choose a global store or redefine Layout patterns.
+
+## Reusable Method
+
+| Question | Route | Decision to record |
+| --- | --- | --- |
+| Can the value be calculated from current inputs? | [Derived state](patterns/derived-state.md) | Source inputs and equality/invalidation |
+| Do several controls write one accepted value? | [Single owner](patterns/single-owner.md) | Nearest surviving owner and intent API |
+| Does selection change when rows reorder? | [ID selection](patterns/id-selection.md) | Stable identity and missing-item policy |
+| Must edits survive Cancel or a failed save? | [Draft and baseline](patterns/draft-and-baseline.md) | Draft owner and baseline meaning |
+| Can editing continue during saving? | [Submitted snapshot](patterns/submitted-snapshot.md) | Captured data and acknowledgement identity |
+| Can leaving discard work? | [Unsaved navigation](patterns/unsaved-navigation.md) | Cancel, discard, and save-and-leave policy |
+| Can replaceable reads finish out of order? | [Latest request wins](patterns/latest-request-wins.md) | Result acceptance identity |
+| Can an operation be activated repeatedly? | [Single flight](patterns/single-flight.md) | Share, ignore, queue, or replace |
+| Should a change appear before acknowledgement? | [Optimistic overlay](patterns/optimistic-overlay.md) | Rollback scope and uncertain outcome recovery |
+| Should Back, reload, and links restore the view? | [URL state](patterns/url-state.md) | Committed route versus input buffer |
+| Is the screen reused for another identity? | [Identity reset](patterns/identity-reset.md) | Generation and cleanup scope |
+| Must state survive a new session? | [Versioned restore](patterns/versioned-restore.md) | Schema, account scope, migration and retention |
+
+These questions can select several patterns. For search, first separate the input buffer from the committed URL, then attach a latest-wins request owner and selected ID. The [search recipe](recipes/search-detail.md) defines the joint contract.
+
+Before adding another pattern, name a failure the existing set cannot express. Put a new combination in a recipe; add a primitive only when its owner or invariant is independently reusable.
+
+## Opinionated Guidance
+
+Choose the failure and lifetime before the library. A cache, URL, form buffer, and session preference may share a screen without sharing an owner.
+
+## Platform-Specific Guidance
+
+Transport cancellation, router guards, and storage hooks vary by framework and runtime. Record those adapter choices in the brief instead of assuming the abstract model implements them.
+
+## Unsupported Absolutes
+
+A decision tree is not an exhaustive treatment of offline replication, collaboration, or server transactions. Escalate those requirements to a separately specified consistency protocol.
+
+## Verification Contract
+
+Try routing a stale search result, lost edit, and wrong-account restore. Each must reach a named pattern and concrete failure trace. Revisit when two routes prescribe conflicting owners.
+
+## Source, License, And Attribution
+
+Locally authored synthesis and examples. No upstream implementation is copied. These experimental contracts describe consumer-owned behavior; review when a failure, ownership change, or platform change invalidates an assumption.
+
+## IA Navigation
+
+Parent: [State Management](index.md).
+Next: [Continue the state management route](state-brief.md).

package/design-engineering/state-management/index.md

@@ -0,0 +1,61 @@
+# State Management
+
+Domain classification: design-engineering. Lifecycle: `experimental`.
+
+## Repository Boundary
+
+State management is a Design Engineering topic, not a seventh domain. It owns consumer UI decisions about authoritative values, events, effects, reconciliation, and lifetime. Layout continues to own spatial composition; Motion owns optional presentation timing. Server transaction protocols, universal library rankings, and shared component implementations are outside this collection.
+
+## Reusable Method
+
+Start with [the decision tree](decision-tree.md), fill in the [state brief](state-brief.md), select the smallest relevant patterns, then compose a [screen recipe](recipes/index.md). The [verification matrix](verification.md) separates expected behavior from observed evidence.
+
+한국어 검색 안내: 상태 관리, 상태 소유권, 파생 상태, 초안과 저장본, 비동기 요청 경합, URL 동기화, 상태 복원은 아래 패턴에서 찾을 수 있습니다.
+
+### Pattern Catalog
+
+| Category | Pattern | Failure prevented |
+| --- | --- | --- |
+| Ownership and derivation | [Single Owner And Controlled Inputs](patterns/single-owner.md) | Keep one authoritative value when several controls edit the same setting. |
+| Ownership and derivation | [Derived State From Authoritative Inputs](patterns/derived-state.md) | Prevent totals, filtered lists, and dirty flags from drifting away from their inputs. |
+| Ownership and derivation | [Selection By Stable Identity](patterns/id-selection.md) | Keep selection attached to an entity while a collection reorders or refreshes. |
+| Editing and persistence | [Draft And Persisted Baseline](patterns/draft-and-baseline.md) | Preserve editable work while distinguishing it from the last acknowledged saved value. |
+| Editing and persistence | [Submitted Snapshot And Save Acknowledgement](patterns/submitted-snapshot.md) | Keep later edits dirty when an earlier submitted snapshot finishes saving. |
+| Editing and persistence | [Unsaved Changes And Navigation](patterns/unsaved-navigation.md) | Make leaving an edited screen an explicit decision without losing the current draft. |
+| Asynchronous consistency | [Latest Request Wins](patterns/latest-request-wins.md) | Prevent an older read response from replacing the result of a newer user intent. |
+| Asynchronous consistency | [Single Flight And Duplicate Submission](patterns/single-flight.md) | Apply an explicit policy to repeated activation of one pending operation. |
+| Asynchronous consistency | [Optimistic Overlay And Recovery](patterns/optimistic-overlay.md) | Show a speculative change while preserving an authoritative base for recovery. |
+| Navigation and lifetime | [URL State And History](patterns/url-state.md) | Keep shareable screen state consistent across links, refresh, and browser history. |
+| Navigation and lifetime | [Identity Boundary And Reset](patterns/identity-reset.md) | Prevent temporary state and pending outcomes from leaking across entity or account changes. |
+| Navigation and lifetime | [Versioned And Scoped State Restore](patterns/versioned-restore.md) | Restore persisted preferences only when their schema and ownership scope are valid. |
+
+### Relationship To Existing Contracts
+
+The [Component Contract](../component-contract.md) remains the public handoff for semantics, events, focus, and asynchronous ownership. Its save example remains in place. [Worked Examples](../worked-examples.md) supplies existing product scenarios; these patterns make their mechanisms individually selectable.
+
+This collection contains 12 patterns in four categories and four [recipes](recipes/index.md). The [composition matrix](recipes/index.md#composition-matrix) records essential and replaceable choices. Plain JavaScript examples are the local executable reference; framework adapters must preserve their declared invariants.
+
+## Opinionated Guidance
+
+Start by locating the authoritative value and its lifetime. Introduce a shared store only when shared ownership or subscriptions require it. Keep remote data authority distinct from local cache ownership, and model request status separately from draft validity and persisted revision.
+
+## Platform-Specific Guidance
+
+Choose native controls and platform navigation before adapters. URL parsing, storage access, focus recovery, and framework disposal each need target-runtime checks beyond the Node examples.
+
+## Unsupported Absolutes
+
+Neither a reducer nor a state machine guarantees race freedom. No library is the default for this collection. Local executable examples do not establish backend, accessibility, or browser conformance.
+
+## Verification Contract
+
+A reader should find a pattern from a failure symptom, identify its owner and minimal implementation, compose it into a screen, and locate a repeatable acceptance sequence. Run `npm run test:state-management` for the 12 local examples; record browser and backend checks separately.
+
+## Source, License, And Attribution
+
+Locally authored synthesis and examples. No upstream implementation is copied. These experimental contracts describe consumer-owned behavior; review when a failure, ownership change, or platform change invalidates an assumption.
+
+## IA Navigation
+
+Parent: [Design Engineering](../index.md).
+Next: [Continue the state management route](decision-tree.md).