ai-design-context 0.4.0

package/examples/todo-reference/styles.css

@@ -0,0 +1,241 @@
+:root {
+  --surface-page: #f5f5f2;
+  --surface-raised: #ffffff;
+  --surface-muted: #ecece7;
+  --text-primary: #20211d;
+  --text-secondary: #62655b;
+  --border-subtle: #d8d9d2;
+  --action-primary: #286248;
+  --action-primary-hover: #1d5039;
+  --action-on-primary: #ffffff;
+  --status-complete: #718071;
+  --status-error: #a13c2f;
+  --focus-ring: #0b75d1;
+  --radius-card: 18px;
+  --radius-control: 12px;
+  --shadow-panel: 0 18px 50px rgb(31 34 27 / 14%);
+}
+
+* { box-sizing: border-box; }
+
+body {
+  margin: 0;
+  min-width: 320px;
+  color: var(--text-primary);
+  background: var(--surface-page);
+  font: 16px/1.45 Inter, ui-sans-serif, system-ui, -apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif;
+}
+
+button, input { font: inherit; }
+
+button {
+  min-height: 44px;
+  border: 0;
+  border-radius: var(--radius-control);
+  padding: 0 16px;
+  color: var(--action-on-primary);
+  background: var(--action-primary);
+  cursor: pointer;
+}
+
+button:hover { background: var(--action-primary-hover); }
+button:disabled { cursor: wait; opacity: .65; }
+
+button:focus-visible, input:focus-visible {
+  outline: 3px solid var(--focus-ring);
+  outline-offset: 3px;
+}
+
+.app-shell {
+  display: grid;
+  grid-template-columns: minmax(0, 680px) minmax(280px, 360px);
+  gap: 32px;
+  width: min(100% - 48px, 1120px);
+  min-height: 100vh;
+  margin: 0 auto;
+  padding: 56px 0;
+  align-content: start;
+}
+
+.app-header, .section-heading, .detail-header, .task-row, .task-main { display: flex; align-items: center; }
+.app-header, .section-heading, .detail-header { justify-content: space-between; gap: 16px; }
+.content-column { min-width: 0; }
+
+h1, h2, p { margin: 0; }
+h1 { font-size: clamp(2rem, 5vw, 3rem); letter-spacing: -.045em; line-height: 1; }
+h2 { font-size: 1rem; letter-spacing: -.01em; }
+
+.eyebrow {
+  margin-bottom: 7px;
+  color: var(--text-secondary);
+  font-size: .79rem;
+  font-weight: 700;
+  letter-spacing: .08em;
+  text-transform: uppercase;
+}
+
+.icon-button {
+  display: grid;
+  width: 44px;
+  min-width: 44px;
+  place-items: center;
+  padding: 0;
+  color: var(--text-primary);
+  background: var(--surface-raised);
+  border: 1px solid var(--border-subtle);
+  font-size: 1.45rem;
+}
+
+.icon-button:hover { background: var(--surface-muted); }
+
+.summary {
+  display: flex;
+  justify-content: space-between;
+  gap: 16px;
+  margin: 28px 0 16px;
+  color: var(--text-secondary);
+}
+
+.summary strong { color: var(--text-primary); }
+
+.quick-capture {
+  display: grid;
+  grid-template-columns: 1fr auto;
+  gap: 10px;
+  position: relative;
+  padding: 10px;
+  background: var(--surface-raised);
+  border: 1px solid var(--border-subtle);
+  border-radius: var(--radius-card);
+  box-shadow: 0 8px 24px rgb(31 34 27 / 5%);
+}
+
+.quick-capture input {
+  min-width: 0;
+  min-height: 44px;
+  padding: 0 8px;
+  color: var(--text-primary);
+  background: transparent;
+  border: 1px solid transparent;
+  border-radius: 8px;
+}
+
+.quick-capture input::placeholder { color: #85887d; }
+.quick-capture input[aria-invalid="true"] { border-color: var(--status-error); }
+
+.form-error {
+  grid-column: 1 / -1;
+  padding: 0 8px 4px;
+  color: var(--status-error);
+  font-size: .9rem;
+}
+
+.task-surface { min-height: 320px; margin-top: 28px; }
+.section-heading { margin: 0 4px 12px; }
+.save-status { color: var(--text-secondary); font-size: .875rem; }
+
+.task-list { display: grid; gap: 8px; margin: 0; padding: 0; list-style: none; }
+
+.task-row {
+  justify-content: space-between;
+  gap: 12px;
+  min-height: 68px;
+  padding: 12px;
+  background: var(--surface-raised);
+  border: 1px solid var(--border-subtle);
+  border-radius: var(--radius-control);
+}
+
+.task-main { min-width: 0; gap: 12px; }
+
+.complete-toggle {
+  width: 44px;
+  min-width: 44px;
+  padding: 0;
+  color: transparent;
+  background: transparent;
+  border: 2px solid var(--status-complete);
+  border-radius: 50%;
+}
+
+.complete-toggle[aria-pressed="true"] { color: var(--action-on-primary); background: var(--status-complete); }
+.task-row.is-complete .task-title { color: var(--text-secondary); text-decoration: line-through; }
+
+.task-open {
+  min-width: 0;
+  min-height: 44px;
+  padding: 0;
+  color: var(--text-primary);
+  background: transparent;
+  border-radius: 8px;
+  text-align: left;
+}
+
+.task-open:hover { color: var(--action-primary-hover); background: transparent; }
+.task-meta { display: block; color: var(--text-secondary); font-size: .8rem; }
+
+.empty-state {
+  display: grid;
+  min-height: 270px;
+  place-content: center;
+  justify-items: center;
+  gap: 10px;
+  padding: 32px;
+  text-align: center;
+  background: var(--surface-raised);
+  border: 1px dashed var(--border-subtle);
+  border-radius: var(--radius-card);
+}
+
+.empty-state[hidden], .detail-panel[hidden] { display: none; }
+
+.empty-state p { color: var(--text-secondary); }
+.empty-icon { font-size: 2rem; color: var(--action-primary); }
+
+.detail-panel {
+  position: sticky;
+  top: 32px;
+  min-height: 382px;
+  padding: 24px;
+  background: var(--surface-raised);
+  border: 1px solid var(--border-subtle);
+  border-radius: var(--radius-card);
+  box-shadow: var(--shadow-panel);
+}
+
+.detail-panel h2 { margin: 24px 0; font-size: 1.35rem; }
+.detail-list { display: grid; gap: 20px; margin: 0; }
+.detail-list div { display: grid; gap: 3px; }
+.detail-list dt { color: var(--text-secondary); font-size: .8rem; }
+.detail-list dd { margin: 0; }
+.secondary-button { width: 100%; margin-top: 32px; color: var(--action-primary); background: var(--surface-muted); }
+.secondary-button:hover { background: #dde1d8; }
+
+.sr-only { position: absolute; width: 1px; height: 1px; overflow: hidden; clip: rect(0 0 0 0); white-space: nowrap; }
+
+@media (max-width: 820px) {
+  .app-shell { display: block; width: min(100% - 32px, 680px); padding: 32px 0 108px; }
+  .detail-panel {
+    position: fixed;
+    z-index: 2;
+    right: 0;
+    bottom: 0;
+    left: 0;
+    min-height: 0;
+    width: 100%;
+    max-height: 60vh;
+    overflow: auto;
+    border-radius: 24px 24px 0 0;
+  }
+  .summary { align-items: flex-start; flex-direction: column; gap: 4px; }
+}
+
+@media (max-width: 460px) {
+  .quick-capture { grid-template-columns: 1fr; }
+  .quick-capture button { width: 100%; }
+  .summary { margin-top: 24px; }
+}
+
+@media (prefers-reduced-motion: reduce) {
+  *, *::before, *::after { scroll-behavior: auto !important; transition-duration: .01ms !important; animation-duration: .01ms !important; }
+}

package/graph/GENERATED_GRAPH.md

@@ -0,0 +1,71 @@
+# Generated Graph Report
+
+This file is generated from registry metadata. Do not edit manually.
+
+## Object Counts By Type
+
+| Object Type | Count |
+| --- | --- |
+| checklist | 1 |
+| pattern | 7 |
+| prompt | 5 |
+| reference_project | 2 |
+| research | 12 |
+| review | 3 |
+| rule | 17 |
+
+## Relationship Counts By Type
+
+| Relationship Type | Count |
+| --- | --- |
+| cites | 1 |
+| derived_from | 32 |
+| implements | 12 |
+| related_to | 65 |
+| requires | 64 |
+| validates | 18 |
+
+## Orphan Objects
+
+None
+
+## Missing Targets
+
+None
+
+## Research Without Derived Or Inspired Rules
+
+None
+
+## Rules Without Research
+
+None
+
+## Prompts Without Knowledge References
+
+None
+
+## Reference Projects Without Validates Relationships
+
+None
+
+## Most Connected Objects
+
+- PROMPT-PROTOTYPE-REVIEW / PROMPT-00002 Prototype Review Prompt: 25
+- CHECK-DESIGN-QA / CHECK-00001 Design QA Checklist: 22
+- PROMPT-TODO-BENCHMARK / PROMPT-00003 Todo App Benchmark Prompt: 18
+- REF-TODO-BENCHMARK / REF-00001 Todo App Benchmark Reference Project: 16
+- PAT-002 / PAT-00002 Quick Capture: 15
+- PAT-005 / PAT-00005 Context-Preserving Preview: 13
+- PAT-006 / PAT-00006 Object Status List: 13
+- UX-003 / RULE-00007 Preserve Context During Inspection: 13
+- PAT-001 / PAT-00001 Daily Home Surface: 12
+- A11Y-001 / RULE-00009 44x44 Touch Targets: 12
+
+## Patterns Without Required Rules
+
+None
+
+## Rules Not Used By Any Pattern
+
+None

package/observations/README.md

@@ -0,0 +1,23 @@
+# Observations
+
+Observations are raw evidence before synthesis.
+
+Use observations to capture product behavior, review findings, screenshots, implementation outcomes, or failure modes before they become research.
+
+## Object Format
+
+Observation objects should follow `schema/observation.schema.json`.
+
+Use `templates/OBSERVATION_TEMPLATE.md` for new observations.
+
+## Graph Role
+
+```text
+observation -> research -> knowledge -> rules -> patterns -> prompts -> reference projects -> reviews
+```
+
+Observations are usually connected with `derived_from` relationships when research absorbs them.
+
+## Contribution Rule
+
+Do not turn an observation into a rule until it has been grouped into research and reviewed for reuse.

package/observations/accessibility/reduced-interaction-motion.md

@@ -0,0 +1,49 @@
+---
+id: OBS-00004
+alias: OBS-A11Y-REDUCED-MOTION
+slug: wcag-reduced-interaction-motion
+title: Reduced Interaction Motion
+object_type: observation
+status: draft
+version: 0.1.0
+category: accessibility
+tags:
+  - accessibility
+  - motion
+  - reduced-motion
+created_at: 2026-07-14
+updated_at: 2026-07-14
+last_reviewed_at: 2026-07-14
+owner: ai-design-rules
+maturity: seed
+risk_level: high
+platform:
+  - web
+product_type:
+  - consumer
+surface:
+  - interaction-transition
+applies_to:
+  - non-essential-motion
+does_not_apply_to:
+  - essential-motion-that-conveys-required-information
+relationships: []
+---
+
+# Reduced Interaction Motion
+
+## Source
+
+W3C WCAG 2.2, Understanding Success Criterion 2.3.3: Animation from Interactions.
+
+## Observed Behavior
+
+Non-essential motion initiated by an interaction can distract or make people ill. Interfaces can avoid it, offer a control, or respect a reduced-motion preference; movement essential to the information or function is an exception.
+
+## Why It May Matter
+
+Motion should never be an undisclosed dependency for using a product. Treating reduced motion as an explicit state preserves orientation without forcing decorative animation into interfaces that do not need it.
+
+## Evidence
+
+- https://www.w3.org/WAI/WCAG22/Understanding/animation-from-interactions

package/observations/accessibility/textual-error-recovery.md

@@ -0,0 +1,50 @@
+---
+id: OBS-00001
+alias: OBS-A11Y-ERROR-RECOVERY
+slug: wcag-textual-error-recovery
+title: Textual Error Recovery
+object_type: observation
+status: draft
+version: 0.1.0
+category: accessibility
+tags:
+  - accessibility
+  - errors
+  - forms
+created_at: 2026-07-14
+updated_at: 2026-07-14
+last_reviewed_at: 2026-07-14
+owner: ai-design-rules
+maturity: seed
+risk_level: high
+platform:
+  - web
+product_type:
+  - consumer
+surface:
+  - form
+applies_to:
+  - input-validation
+  - submission-errors
+does_not_apply_to:
+  - server-error-details-that-expose-sensitive-data
+relationships: []
+---
+
+# Textual Error Recovery
+
+## Source
+
+W3C WCAG 2.2, Understanding Success Criterion 3.3.1: Error Identification.
+
+## Observed Behavior
+
+When an input error is detected, the affected input and the nature of the error are described in text. Color, icons, or styling may reinforce the message but do not replace it. A useful message can also state how to correct the value.
+
+## Why It May Matter
+
+Users need to know what failed and what to change without relying on color perception or visual scanning. Field-specific text enables recovery for assistive-technology users and reduces repeated, blind resubmission.
+
+## Evidence
+
+- https://www.w3.org/WAI/WCAG22/Understanding/error-identification

package/observations/accessibility/visible-keyboard-focus.md

@@ -0,0 +1,49 @@
+---
+id: OBS-00003
+alias: OBS-A11Y-FOCUS-VISIBLE
+slug: wcag-visible-keyboard-focus
+title: Visible Keyboard Focus
+object_type: observation
+status: draft
+version: 0.1.0
+category: accessibility
+tags:
+  - accessibility
+  - keyboard
+  - focus
+created_at: 2026-07-14
+updated_at: 2026-07-14
+last_reviewed_at: 2026-07-14
+owner: ai-design-rules
+maturity: seed
+risk_level: high
+platform:
+  - web
+product_type:
+  - consumer
+surface:
+  - interactive-controls
+applies_to:
+  - keyboard-operable-controls
+does_not_apply_to:
+  - non-interactive-content
+relationships: []
+---
+
+# Visible Keyboard Focus
+
+## Source
+
+W3C WCAG 2.2, Understanding Success Criterion 2.4.7: Focus Visible.
+
+## Observed Behavior
+
+Keyboard-operable controls retain a visible focus indicator while focused. Removing or visually hiding browser focus leaves keyboard users unable to determine where their next action will apply.
+
+## Why It May Matter
+
+Focus is a state in the user journey, not a decoration. A visible, persistent indicator lets keyboard users complete capture and recovery flows without guessing which control is active.
+
+## Evidence
+
+- https://www.w3.org/WAI/WCAG22/Understanding/focus-visible

package/observations/ai/agent-consequential-action-controls.md

@@ -0,0 +1,56 @@
+---
+id: OBS-00015
+alias: OBS-AGENT-CONSEQUENTIAL-CONTROLS
+slug: agent-consequential-action-controls
+title: Agentic Systems Gate Consequential Actions With Control And Auditability
+object_type: observation
+status: draft
+version: 0.1.0
+category: ux
+tags:
+  - ai
+  - agentic-ui
+  - confirmation
+  - audit
+created_at: 2026-08-12
+updated_at: 2026-08-12
+last_reviewed_at: 2026-08-12
+owner: ai-design-rules
+maturity: seed
+risk_level: high
+platform:
+  - web
+product_type:
+  - ai-tool
+  - productivity
+surface:
+  - agent-workflow
+  - permissions
+applies_to:
+  - delegated-consequential-actions
+does_not_apply_to:
+  - read-only-summaries
+relationships: []
+---
+
+# Agentic Systems Gate Consequential Actions With Control And Auditability
+
+## Source
+
+OpenAI ChatGPT agent, OpenAI Codex safety, Microsoft agent design guidance, Microsoft HAX, and Google PAIR guidance.
+
+## Observed Behavior
+
+Current agentic systems make higher-risk actions explicit through permission prompts, interruption, takeover, sandbox boundaries, approval policies, observable progress, and logs. Human-centered AI guidance also emphasizes lifecycle design, user ownership, correction paths, expectation setting, and recovery when AI output is wrong.
+
+## Why It May Matter
+
+As agents move from advice to action, design systems need rules for consequence-aware control. A generic confirm dialog is not enough when the user must understand scope, source context, side effects, reversibility, and audit trail.
+
+## Evidence
+
+- https://openai.com/index/introducing-chatgpt-agent/
+- https://openai.com/index/running-codex-safely/
+- https://learn.microsoft.com/en-us/agents/design-guidelines/human-centered-design
+- https://www.microsoft.com/en-us/haxtoolkit/ai-guidelines/
+- https://pair.withgoogle.com/guidebook-v2/

package/observations/ai/agent-work-visibility-and-intervention.md

@@ -0,0 +1,51 @@
+---
+id: OBS-00011
+alias: OBS-AGENT-WORK-VISIBILITY
+slug: agent-work-visibility-and-intervention
+title: Agentic Workflows Need Visible Status And Intervention
+object_type: observation
+status: draft
+version: 0.1.0
+category: ux
+tags:
+  - ai
+  - agentic-ui
+  - status
+  - trust
+created_at: 2026-07-24
+updated_at: 2026-07-24
+last_reviewed_at: 2026-07-24
+owner: ai-design-rules
+maturity: seed
+risk_level: high
+platform:
+  - web
+product_type:
+  - ai-tool
+  - productivity
+surface:
+  - agent-workflow
+applies_to:
+  - delegated-and-long-running-work
+does_not_apply_to:
+  - instant-deterministic-actions
+relationships: []
+---
+
+# Agentic Workflows Need Visible Status And Intervention
+
+## Source
+
+Figma's 2026 case study on the design of agentic work tools.
+
+## Observed Behavior
+
+The studied workflow moves beyond a prompt thread to a dashboard of active, completed, review-ready, and intervention-required work. It keeps the user's goal primary while making it clear where people can inspect or interrupt agent activity.
+
+## Why It May Matter
+
+Delegated work becomes difficult to trust when progress, scope, and intervention points are hidden. Agentic interfaces need observable state and recovery behavior, not only conversational output.
+
+## Evidence
+
+- https://www.figma.com/blog/how-to-design-agentic-tools-for-work/

package/observations/ai/figma-agent-context-and-skills.md

@@ -0,0 +1,52 @@
+---
+id: OBS-00010
+alias: OBS-FIGMA-AGENT-CONTEXT
+slug: figma-agent-context-and-skills
+title: Design Agents Improve Through Real Context And Reusable Skills
+object_type: observation
+status: draft
+version: 0.1.0
+category: product
+tags:
+  - ai
+  - agent
+  - context
+  - skills
+created_at: 2026-07-24
+updated_at: 2026-07-24
+last_reviewed_at: 2026-07-24
+owner: ai-design-rules
+maturity: seed
+risk_level: medium
+platform:
+  - web
+product_type:
+  - ai-tool
+  - productivity
+surface:
+  - agent-workflow
+applies_to:
+  - design-agent-context
+does_not_apply_to:
+  - context-free-style-generation
+relationships: []
+---
+
+# Design Agents Improve Through Real Context And Reusable Skills
+
+## Source
+
+Figma's 2026 design agent and Config announcements.
+
+## Observed Behavior
+
+Figma lets the design agent use file structure, components, tokens, attachments, web research, connectors, and reusable team skills. Prompt history is also treated as shared process context rather than only disposable chat.
+
+## Why It May Matter
+
+Prompt wording alone cannot reliably carry product identity. Agents need scoped project evidence, reusable design decisions, and direct access to the system they are expected to apply.
+
+## Evidence
+
+- https://www.figma.com/blog/agent-custom-tools-context-skills/
+- https://www.figma.com/blog/the-figma-canvas-is-now-open-to-agents/

package/observations/finance/high-risk-wallet-recovery-flows.md

@@ -0,0 +1,55 @@
+---
+id: OBS-00013
+alias: OBS-WALLET-RISK-RECOVERY
+slug: high-risk-wallet-recovery-flows
+title: Wallet Flows Preserve Context Through Risk Gates
+object_type: observation
+status: draft
+version: 0.1.0
+category: ux
+tags:
+  - finance
+  - wallet
+  - recovery
+  - confirmation
+created_at: 2026-08-12
+updated_at: 2026-08-12
+last_reviewed_at: 2026-08-12
+owner: ai-design-rules
+maturity: seed
+risk_level: high
+platform:
+  - web
+product_type:
+  - fintech
+  - wallet
+surface:
+  - withdrawal
+  - authentication
+  - recovery
+applies_to:
+  - consequential-user-actions
+does_not_apply_to:
+  - low-risk-preference-changes
+relationships: []
+---
+
+# Wallet Flows Preserve Context Through Risk Gates
+
+## Source
+
+Wallet product design review note captured on 2026-08-12.
+
+## Observed Behavior
+
+The wallet design guidance treats withdrawal, KYC, 2FA, passkey, activation, and backend error states as separate recoverable flows. Challenged withdrawals keep provider, amount, and requisites visible and unchanged, then retry with only the server-requested confirmation field added. Backend error codes are stripped from user copy, but useful backend-provided recovery messages are preserved.
+
+## Why It May Matter
+
+High-risk flows become less safe when confirmations erase context, hide the object being acted on, or collapse distinct risk gates into generic error UI. Users need to verify exactly what will happen and recover without re-entering unrelated data.
+
+## Evidence
+
+- Wallet design-decision note captured on 2026-08-12.
+- Wallet product-requirement note captured on 2026-08-12.
+- Wallet implementation-planning note captured on 2026-08-12.