ai-design-context 0.4.0

package/patterns/consequential-action-confirmation.md

@@ -0,0 +1,127 @@
+---
+id: PAT-00007
+alias: PAT-007
+slug: consequential-action-confirmation
+title: Consequential Action Confirmation
+object_type: pattern
+status: active
+version: 0.1.0
+category: ux
+tags:
+  - ux
+  - confirmation
+  - recovery
+  - finance
+  - ai
+maturity: validated
+risk_level: high
+last_reviewed_at: 2026-08-12
+relationships:
+  - type: requires
+    target: RULE-00017
+  - type: requires
+    target: RULE-00007
+  - type: requires
+    target: RULE-00010
+  - type: requires
+    target: RULE-00016
+  - type: related_to
+    target: PAT-00005
+  - type: related_to
+    target: PAT-00006
+---
+
+# Consequential Action Confirmation
+
+## Purpose
+
+Let users verify and recover from actions with meaningful side effects without losing the object, inputs, or scope they are acting on.
+
+## User Goal
+
+Make a high-consequence decision with enough context to confirm, cancel, edit, retry, or hand control back from an agent.
+
+## Product Context
+
+Wallets, trading products, admin tools, account-security flows, publishing flows, destructive durable-data actions, and agentic systems that can act on the user's behalf.
+
+## Use When
+
+- The action can move money, change account access, publish externally, delete durable data, or affect other people.
+- The action requires 2FA, passkey, KYC, server approval, permissions, or human approval.
+- An agent is about to perform a consequential action outside a read-only summary.
+- The user must compare critical inputs before execution.
+
+## Do Not Use When
+
+- The action is low-risk, reversible, and better handled with undo.
+- The confirmation would interrupt a safe repeated expert workflow without adding review value.
+- The UI cannot truthfully describe the side effects or recovery path yet.
+- Legal, compliance, security, or trading policy is unclear and must be resolved outside design.
+
+## UX Rules
+
+- `UX-006` Confirm Consequential Actions With Preserved Context
+- `UX-003` Preserve Context During Inspection
+- `UX-005` Expose Agent Work And Intervention
+
+## Accessibility Rules
+
+- `A11Y-002` Textual Input Error Recovery
+- `A11Y-001` 44x44 Touch Targets when controls are present
+- `A11Y-003` Visible Keyboard Focus when the confirmation is keyboard-operable
+
+## Mobile Behavior
+
+Use a focused screen, bottom sheet, or modal that keeps critical context readable: object, amount, recipient, destination, scope, side effects, and primary recovery action. Preserve safe-area spacing and reachable controls. Do not hide the acted-on object behind a generic confirmation title.
+
+## Desktop Behavior
+
+Use a modal, side panel, inline challenge step, or review page depending on consequence and density. Keep the source context visible when it helps comparison. Dense operational products may use a review pane beside the original form.
+
+## Empty State
+
+Do not open a confirmation without a selected object or valid action. Show the missing prerequisite and a route back to the required selection or setup step.
+
+## Loading State
+
+Keep the reviewed object and critical inputs visible while the challenge or submission is pending. Disable only controls that would create duplicate execution. Show cancelability truthfully.
+
+## Error State
+
+Preserve entered data and add only the missing or failed challenge field. Explain what failed, what remains unchanged, and what the user can do next. Avoid raw backend codes as product copy.
+
+## Required Rules
+
+- `UX-006` Confirm Consequential Actions With Preserved Context
+- `UX-003` Preserve Context During Inspection
+- `A11Y-002` Textual Input Error Recovery
+- `UX-005` Expose Agent Work And Intervention
+
+## Related Research
+
+- `research/ux/high-risk-operational-flows.md`
+- `research/ux/contextual-agentic-interface.md`
+- `research/accessibility/textual-error-recovery.md`
+
+## Related Patterns
+
+- Parent: none
+- Child: none
+- Alternative: lightweight undo for low-risk reversible actions
+- Depends on: `context-preserving-preview.md` when source context must remain inspectable
+- Adjacent: `object-status-list.md` when multiple affected objects must be reviewed
+
+## Examples
+
+- A wallet withdrawal challenge keeps provider, amount, destination, fee, and selected asset visible while requesting 2FA.
+- An admin bulk delete confirmation lists affected objects and explains reversibility before execution.
+- An agent asks approval before sending a message, changing permissions, running a paid operation, or publishing externally.
+
+## Agent Checklist
+
+- What is the consequence and how reversible is it?
+- Which object, amount, recipient, scope, or side effects must remain visible?
+- Can the user cancel, edit critical inputs, and retry without restarting unrelated work?
+- Does the error state preserve entered data and ask only for the missing challenge?
+- For agentic work, is explicit approval required before the side effect and is interruption still available?

package/patterns/context-preserving-preview.md

@@ -0,0 +1,145 @@
+---
+id: PAT-00005
+alias: PAT-005
+slug: context-preserving-preview
+title: Context-Preserving Preview
+object_type: pattern
+status: draft
+version: 0.2.0
+category: ux
+tags:
+  - ux
+  - preview
+maturity: seed
+risk_level: medium
+relationships:
+  - type: requires
+    target: RULE-00007
+  - type: requires
+    target: RULE-00004
+  - type: requires
+    target: RULE-00003
+  - type: requires
+    target: RULE-00009
+  - type: requires
+    target: RULE-00013
+  - type: requires
+    target: RULE-00015
+  - type: related_to
+    target: PAT-00006
+---
+
+# Context-Preserving Preview
+
+## Purpose
+
+Let users inspect detail without losing their source context.
+
+## User Goal
+
+Compare, inspect, or triage items while keeping place in the list or workspace.
+
+## Product Context
+
+Lists, workspaces, conversations, and browsers where users inspect multiple items in sequence.
+
+## Use When
+
+- Users need to open several items quickly.
+- The source context, filters, or scroll position matter.
+- Detail is inspection-heavy rather than a long edit flow.
+
+## Do Not Use When
+
+- The detail view is a long editing workflow.
+- The preview would hide critical primary actions.
+- The source list is not important after selection.
+
+## UX Rules
+
+- `UX-003` Preserve Context During Inspection
+- `IA-002` Define The Object Model Before Screens
+- `IA-001` One Stable Home Surface
+- `UX-004` Use Motion To Explain State Continuity
+
+## Accessibility Rules
+
+- `A11Y-001` 44x44 Touch Targets
+- `A11Y-004` Reduce Non-Essential Interaction Motion
+
+## Motion Behavior
+
+If opening or closing preview uses non-essential motion, respect a reduced-motion preference or provide an equivalent way to disable it. The reduced-motion state may switch directly to the same sheet, panel, or preview state; it must not remove the preview or its return path.
+
+Use motion only to explain the selected item's relationship to its preview (`UX-004`). Reuse the product's named timing and easing roles; do not introduce a fixed duration or require a particular animation API. Define the following behavior before implementing the transition:
+
+| State or transition | Required outcome |
+| --- | --- |
+| Closed to open | Keep the selected item, filters, and scroll position; show which item the preview belongs to. Define the focus destination for the chosen panel or dialog behavior. |
+| Loading or error | Keep the source usable and show feedback in the preview. Feedback must remain understandable without movement. |
+| Close | Restore the source context. If focus moved into the preview, return it to the invoking control or a logical surviving control if that item was removed. |
+| Interrupted opening or item switch | The latest selection determines the visible item. A delayed transition must not reopen a closed preview or move focus to an old item. |
+| Reduced motion or unsupported animation | Reach the same selected item, information, controls, and focus outcome without non-essential movement. |
+
+## Mobile Behavior
+
+Use a sheet, drawer, or temporary detail view that preserves return state. Avoid resetting filters or scroll on close.
+
+## Desktop Behavior
+
+Prefer side panel, split view, peek, or preview pane when space allows.
+
+## Empty State
+
+Show the source list empty state and avoid opening an empty preview by default.
+
+## Loading State
+
+Keep the source context visible while preview content loads.
+
+## Error State
+
+Show preview-level error and keep the source list usable.
+
+## Required Rules
+
+- `UX-003` Preserve Context During Inspection
+- `IA-002` Define The Object Model Before Screens
+- `IA-001` One Stable Home Surface
+- `A11Y-001` 44x44 Touch Targets
+- `A11Y-004` Reduce Non-Essential Interaction Motion
+- `UX-004` Use Motion To Explain State Continuity
+
+## Related Research
+
+- `research/products/arc.md`
+- `research/products/linear.md`
+- `research/products/telegram.md`
+- `research/ux/motion-as-state-continuity.md`
+
+## Related Patterns
+
+- Parent: none
+- Child: none
+- Alternative: full detail page when editing is the main task
+- Depends on: `object-status-list.md` when previewing structured objects
+
+## Examples
+
+- A consumer task app opens task detail from Today without losing the Today list.
+- An issue tracker opens issue detail beside the filtered issue list.
+
+For a task preview, a brief local transition can connect the selected row to its details. With reduced motion, open those same details immediately. Animating every list row or waiting for a closing animation before accepting the next selection would add motion without preserving useful context.
+
+## Agent Checklist
+
+- Does opening detail preserve source context?
+- Can users inspect several items quickly?
+- Is the return path obvious?
+- Does preview stay smaller than a full workspace?
+- When motion exists, can reduced motion reach the same preview and return state?
+- Are the start state, end state, focus destination, interruption behavior, and fallback recorded?
+- Can a user close or switch items during opening without stale content or focus taking over?
+- Is loading and error feedback still clear with animation disabled?
+
+The motion guidance remains `draft` / `seed`; this revision does not establish rendered or independent validation.

package/patterns/daily-home-surface.md

@@ -0,0 +1,134 @@
+---
+id: PAT-00001
+alias: PAT-001
+slug: daily-home-surface
+title: Daily Home Surface
+object_type: pattern
+status: draft
+version: 0.2.0
+category: product
+tags:
+  - product
+  - home
+maturity: seed
+risk_level: medium
+relationships:
+  - type: requires
+    target: RULE-00001
+  - type: requires
+    target: RULE-00003
+  - type: requires
+    target: RULE-00006
+  - type: requires
+    target: RULE-00009
+  - type: requires
+    target: RULE-00008
+  - type: requires
+    target: RULE-00014
+  - type: related_to
+    target: PAT-00002
+  - type: related_to
+    target: PAT-00003
+---
+
+# Daily Home Surface
+
+## Purpose
+
+Provide one stable starting surface for repeated daily work.
+
+## User Goal
+
+Start the day or session and act on the most relevant current work.
+
+## Product Context
+
+Consumer products with recurring workflows, such as family tasks, reminders, routines, daily planning, and recurring conversations.
+
+## Use When
+
+- Users return frequently to the same product context.
+- One repeated action or current-work view anchors the product.
+- Secondary modes exist but should not replace the starting point.
+
+## Do Not Use When
+
+- The product is primarily exploratory.
+- The user goal changes completely between sessions.
+- Parallel workflows are equally important and cannot share one home.
+
+## UX Rules
+
+- `PRD-001` Daily Actions First
+- `IA-001` One Stable Home Surface
+- `UX-002` Progressively Disclose Power
+
+## Accessibility Rules
+
+- `A11Y-001` 44x44 Touch Targets
+
+## Mobile Behavior
+
+Show the current work and primary daily action in the first 390px-wide viewport. Keep navigation secondary and reachable.
+
+Keep current-work labels readable beside the primary action. Use the same semantic content, action, and supporting-surface roles as desktop; reducing width must not give every row or navigation control the same emphasis as the main action (`VIS-001`, `VIS-002`).
+
+## Desktop Behavior
+
+Use the extra width for supporting context, not competing entry points. Keep the same home concept as mobile.
+
+Identify the content layer (current work), functional layer (navigation and controls), focal emphasis (the repeated daily action), and quiet supporting surfaces. Reuse existing typography, spacing, and color roles. Strong material, shape, or color treatments must clarify that hierarchy; removing decorative effects must leave content order and the primary action understandable (`VIS-001`, `VIS-002`).
+
+## Empty State
+
+Explain what belongs here and provide the primary create or start action.
+
+## Loading State
+
+Keep the home shell and primary action position stable while current work loads.
+
+## Error State
+
+Preserve the home surface and show a recovery action without replacing the whole screen.
+
+## Required Rules
+
+- `PRD-001` Daily Actions First
+- `IA-001` One Stable Home Surface
+- `UX-002` Progressively Disclose Power
+- `A11Y-001` 44x44 Touch Targets
+- `VIS-001` Semantic Tokens Only
+- `VIS-002` Keep Expression Subordinate To Content
+
+## Related Research
+
+- `research/products/things-3.md`
+- `research/products/telegram.md`
+- `research/products/apple-reminders.md`
+- `research/visual/expressive-system-ui-2026.md`
+
+## Related Patterns
+
+- Parent: none
+- Child: `quick-capture.md`, `mobile-primary-action.md`
+- Alternative: none
+- Depends on: none
+
+## Examples
+
+- A consumer task app opens to Today, showing current tasks and the main add action.
+- A reminders app opens to the user's current list instead of settings or analytics.
+
+For a household shopping list, the current items form the content layer, list switching belongs to the functional layer, and Add item is the focal action. Bought items remain readable but quieter. Giving every item, navigation control, and background the same strong accent would obscure this hierarchy. This is an application of `VIS-002`, not a required brand style or a new component system.
+
+## Agent Checklist
+
+- Is there one recognizable home surface?
+- Is the repeated daily action visible without scrolling?
+- Can users return after exploring secondary modes?
+- Are advanced controls quieter than current work?
+- Can the content, functional layer, focal emphasis, and supporting surfaces be identified on both mobile and desktop?
+- Does the hierarchy remain clear without transparency, shadows, or decorative motion?
+- Do repeated visual decisions reuse the project's semantic roles?
+
+The visual guidance remains `draft` / `seed`; this revision adds an application contract, not rendered benchmark validation.

package/patterns/mobile-primary-action.md

@@ -0,0 +1,110 @@
+---
+id: PAT-00003
+alias: PAT-003
+slug: mobile-primary-action
+title: Mobile Primary Action
+object_type: pattern
+status: draft
+version: 0.1.0
+category: mobile
+tags:
+  - mobile
+  - action
+maturity: seed
+risk_level: high
+relationships:
+  - type: requires
+    target: RULE-00005
+  - type: requires
+    target: RULE-00001
+  - type: requires
+    target: RULE-00009
+  - type: related_to
+    target: PAT-00002
+---
+
+# Mobile Primary Action
+
+## Purpose
+
+Make one repeated mobile action physically reachable and safely tappable.
+
+## User Goal
+
+Trigger the main action quickly with one hand.
+
+## Product Context
+
+Touch-first screens with one dominant repeated action, such as add, send, complete, or start.
+
+## Use When
+
+- One action is clearly more frequent than others.
+- The screen is used on mobile.
+- The action is safe enough to make prominent.
+
+## Do Not Use When
+
+- Multiple actions are equally important.
+- The action is destructive or high-risk.
+- The screen is primarily for reading or comparison.
+
+## UX Rules
+
+- `UX-001` Thumb-Zone Primary Actions
+- `PRD-001` Daily Actions First
+
+## Accessibility Rules
+
+- `A11Y-001` 44x44 Touch Targets
+
+## Mobile Behavior
+
+Place the action in a thumb-friendly zone. Keep the clickable area at least 44x44 CSS pixels and separate it from destructive controls.
+
+## Desktop Behavior
+
+Keep the same primary action visible, but position it according to desktop hierarchy and keyboard access instead of thumb reach.
+
+## Empty State
+
+Keep the action available and pair it with concise start guidance.
+
+## Loading State
+
+Keep the action position stable. Disable or show progress only while duplicate actions would be harmful.
+
+## Error State
+
+Show recovery near the action and preserve the user's context.
+
+## Required Rules
+
+- `UX-001` Thumb-Zone Primary Actions
+- `PRD-001` Daily Actions First
+- `A11Y-001` 44x44 Touch Targets
+
+## Related Research
+
+- `research/products/things-3.md`
+- `research/products/apple-reminders.md`
+
+## Related Patterns
+
+- Parent: none
+- Child: none
+- Alternative: none
+- Depends on: none
+- Adjacent: `quick-capture.md` owns the creation flow after tap
+
+## Examples
+
+- A mobile todo app places Add Task in the reachable bottom area.
+- A messaging screen keeps Send reachable without placing Delete nearby.
+
+## Agent Checklist
+
+- Is there one clear primary action?
+- Is it reachable at 390px width?
+- Is the target at least 44x44 CSS pixels?
+- Is the destructive path spatially separate?

package/patterns/object-status-list.md

@@ -0,0 +1,114 @@
+---
+id: PAT-00006
+alias: PAT-006
+slug: object-status-list
+title: Object Status List
+object_type: pattern
+status: draft
+version: 0.1.0
+category: ia
+tags:
+  - ia
+  - status
+maturity: seed
+risk_level: medium
+relationships:
+  - type: requires
+    target: RULE-00004
+  - type: requires
+    target: RULE-00007
+  - type: requires
+    target: RULE-00008
+  - type: requires
+    target: RULE-00009
+  - type: related_to
+    target: PAT-00005
+  - type: related_to
+    target: PAT-00004
+---
+
+# Object Status List
+
+## Purpose
+
+Make structured objects scanable by state, owner, and next action.
+
+## User Goal
+
+Understand what exists, what state it is in, and what needs attention.
+
+## Product Context
+
+Products with stable objects and states, such as issues, projects, shared tasks, requests, or household workflows.
+
+## Use When
+
+- Items have stable states.
+- Users need to scan or filter many objects.
+- Ownership, status, or next action affects decisions.
+
+## Do Not Use When
+
+- Items are mostly unstructured notes or messages.
+- The product does not have stable states.
+- A dense list would make a consumer workflow feel administrative.
+
+## UX Rules
+
+- `IA-002` Define The Object Model Before Screens
+- `UX-003` Preserve Context During Inspection
+
+## Accessibility Rules
+
+- `A11Y-001` 44x44 Touch Targets
+
+## Mobile Behavior
+
+Show object name and most important status first. Move secondary metadata into detail or progressive disclosure.
+
+## Desktop Behavior
+
+Use columns, grouping, filters, or side panels for scanability without duplicating objects.
+
+## Empty State
+
+Explain what object will appear here and provide the relevant create or import action.
+
+## Loading State
+
+Preserve row structure or grouping while loading to avoid scan disruption.
+
+## Error State
+
+Show list-level recovery and preserve filters when possible.
+
+## Required Rules
+
+- `IA-002` Define The Object Model Before Screens
+- `UX-003` Preserve Context During Inspection
+- `VIS-001` Semantic Tokens Only
+- `A11Y-001` 44x44 Touch Targets
+
+## Related Research
+
+- `research/products/linear.md`
+- `research/products/arc.md`
+
+## Related Patterns
+
+- Parent: none
+- Child: `context-preserving-preview.md`
+- Alternative: `progressive-detail.md` when metadata should stay hidden
+- Depends on: none
+
+## Examples
+
+- A household task archetype shows tasks with owner, status, and due cue.
+- A project tool lists issues with status, owner, priority, and next action.
+
+## Agent Checklist
+
+- What object does each row represent?
+- Are statuses stable and consistently named?
+- Is ownership visible when it affects action?
+- Can users change view without duplicating data?