ai-design-context 0.4.0

package/research/GENERATED_INDEX.md

@@ -0,0 +1,18 @@
+# Generated Research Index
+
+This file is generated from registry metadata. Do not edit manually.
+
+| ID | Alias | Title | Category | Status | Maturity | File Path | Derived Or Inspired Rules |
+| --- | --- | --- | --- | --- | --- | --- | --- |
+| RESEARCH-00001 | TELEGRAM | Telegram | product | draft | seed | research/products/telegram.md | derived_from: PRD-001 / RULE-00001 Daily Actions First<br>derived_from: PRD-002 / RULE-00002 Low-Friction Capture Before Organization<br>derived_from: IA-001 / RULE-00003 One Stable Home Surface<br>derived_from: IA-002 / RULE-00004 Define The Object Model Before Screens<br>derived_from: UX-002 / RULE-00006 Progressively Disclose Power<br>derived_from: UX-003 / RULE-00007 Preserve Context During Inspection |
+| RESEARCH-00002 | THINGS-3 | Things 3 | product | draft | seed | research/products/things-3.md | derived_from: PRD-001 / RULE-00001 Daily Actions First<br>derived_from: PRD-002 / RULE-00002 Low-Friction Capture Before Organization<br>derived_from: IA-001 / RULE-00003 One Stable Home Surface<br>derived_from: UX-001 / RULE-00005 Thumb-Zone Primary Actions<br>derived_from: UX-002 / RULE-00006 Progressively Disclose Power<br>derived_from: VIS-001 / RULE-00008 Semantic Tokens Only<br>derived_from: A11Y-001 / RULE-00009 44x44 Touch Targets |
+| RESEARCH-00003 | APPLE-REMINDERS | Apple Reminders | product | draft | seed | research/products/apple-reminders.md | derived_from: PRD-001 / RULE-00001 Daily Actions First<br>derived_from: PRD-002 / RULE-00002 Low-Friction Capture Before Organization<br>derived_from: IA-001 / RULE-00003 One Stable Home Surface<br>derived_from: UX-001 / RULE-00005 Thumb-Zone Primary Actions<br>derived_from: UX-002 / RULE-00006 Progressively Disclose Power<br>derived_from: A11Y-001 / RULE-00009 44x44 Touch Targets |
+| RESEARCH-00004 | LINEAR | Linear | product | draft | seed | research/products/linear.md | derived_from: IA-002 / RULE-00004 Define The Object Model Before Screens<br>derived_from: UX-003 / RULE-00007 Preserve Context During Inspection<br>derived_from: VIS-001 / RULE-00008 Semantic Tokens Only |
+| RESEARCH-00005 | ARC | Arc | product | draft | seed | research/products/arc.md | derived_from: IA-002 / RULE-00004 Define The Object Model Before Screens<br>derived_from: UX-003 / RULE-00007 Preserve Context During Inspection |
+| RESEARCH-00006 | TEXTUAL-ERROR-RECOVERY | Textual Error Recovery | accessibility | draft | seed | research/accessibility/textual-error-recovery.md | derived_from: A11Y-002 / RULE-00010 Textual Input Error Recovery |
+| RESEARCH-00007 | RESERVED-LOADING-SPACE | Reserved Loading Space | performance | draft | seed | research/performance/reserved-loading-space.md | derived_from: PERF-001 / RULE-00011 Reserve Layout Space For Asynchronous Content |
+| RESEARCH-00008 | KEYBOARD-FOCUS-AND-MOTION | Keyboard Focus And Interaction Motion | accessibility | draft | seed | research/accessibility/keyboard-focus-and-interaction-motion.md | derived_from: A11Y-003 / RULE-00012 Visible Keyboard Focus<br>derived_from: A11Y-004 / RULE-00013 Reduce Non-Essential Interaction Motion |
+| RESEARCH-00009 | EXPRESSIVE-SYSTEM-UI-2026 | Expressive System UI In 2026 | visual | draft | seed | research/visual/expressive-system-ui-2026.md | derived_from: VIS-002 / RULE-00014 Keep Expression Subordinate To Content |
+| RESEARCH-00010 | MOTION-AS-STATE-CONTINUITY | Motion As State Continuity | ux | draft | seed | research/ux/motion-as-state-continuity.md | derived_from: UX-004 / RULE-00015 Use Motion To Explain State Continuity |
+| RESEARCH-00011 | CONTEXTUAL-AGENTIC-INTERFACE | Contextual And Observable Agentic Interfaces | ux | draft | seed | research/ux/contextual-agentic-interface.md | derived_from: UX-005 / RULE-00016 Expose Agent Work And Intervention |
+| RESEARCH-00012 | HIGH-RISK-OPERATIONAL-FLOWS | High-Risk Operational Flows | ux | active | validated | research/ux/high-risk-operational-flows.md | derived_from: UX-006 / RULE-00017 Confirm Consequential Actions With Preserved Context |

package/research/INDEX.md

@@ -0,0 +1,40 @@
+# Research Library
+
+Research is the first step in AI Design Context.
+
+Use product research to observe how strong products reduce effort, organize repeated actions, and make complex behavior feel simple. Do not turn research into rules until the observation is stable and reusable.
+
+## Pipeline Position
+
+```text
+observation -> research -> knowledge -> rules -> patterns -> prompts -> reference projects -> reviews
+```
+
+Research files should feed later rules and patterns. They are not final rules.
+
+See `docs/KNOWLEDGE_ENGINE.md` for object metadata and relationship standards.
+
+Manual indexes are transitional. Future indexes should be generated from registry metadata.
+
+## Product Studies
+
+- `products/telegram.md` - speed, optimistic interaction, chat-scale IA.
+- `products/things-3.md` - calm task management, progressive disclosure, tactile list editing.
+- `products/apple-reminders.md` - simple lists, system integration, low-friction capture.
+- `products/linear.md` - perceived performance, workflow structure, operational clarity.
+- `products/arc.md` - workspace organization, context switching, browser interaction model.
+
+## Research Format
+
+Each product note should include:
+
+- why this product is studied;
+- official source signals;
+- observed design behavior;
+- design takeaways for agents;
+- candidate rule directions;
+- what not to copy blindly.
+
+## Contribution Rule
+
+Add research before adding rules. A rule without evidence is likely just taste.

package/research/accessibility/keyboard-focus-and-interaction-motion.md

@@ -0,0 +1,62 @@
+---
+id: RESEARCH-00008
+alias: KEYBOARD-FOCUS-AND-MOTION
+slug: keyboard-focus-and-interaction-motion
+title: Keyboard Focus And Interaction Motion
+object_type: research
+status: draft
+version: 0.1.0
+category: accessibility
+tags:
+  - accessibility
+  - keyboard
+  - focus
+  - motion
+maturity: seed
+risk_level: high
+relationships:
+  - type: derived_from
+    target: observations/accessibility/visible-keyboard-focus.md
+  - type: derived_from
+    target: observations/accessibility/reduced-interaction-motion.md
+---
+
+# Keyboard Focus And Interaction Motion
+
+## Why Study It
+
+Controls, sheets, and transitions are part of task completion. A user must be able to locate keyboard focus and opt out of non-essential interaction motion without losing access to the same product function.
+
+## Source Signals
+
+- WCAG 2.2 SC 2.4.7 requires a mode where each keyboard-operable control has a visible focus indicator.
+- W3C notes that the indicator must remain visible while focus is shown; removing or hiding it is a failure mode.
+- WCAG 2.2 SC 2.3.3 states that interaction-triggered motion can be disabled unless it is essential to the function or information.
+- W3C identifies avoidance, an explicit control, and a reduced-motion preference as valid approaches to non-essential motion.
+
+Sources:
+
+- https://www.w3.org/WAI/WCAG22/Understanding/focus-visible
+- https://www.w3.org/WAI/WCAG22/Understanding/animation-from-interactions
+
+## Observed Design Behavior
+
+- Inputs, buttons, rows, and close controls keep a visible keyboard focus state.
+- Motion is used only to clarify a transition or relationship, never as the only way to understand state.
+- A reduced-motion preference replaces non-essential movement with an immediate or non-moving state change.
+
+## Design Takeaways For Agents
+
+- Specify focus behavior for every keyboard-operable control in a critical flow.
+- Treat reduced motion as a conditional requirement when interaction motion exists.
+- Do not use a motion rule to justify decorative animation.
+
+## Candidate Rule Directions
+
+- Keep keyboard focus visible for keyboard-operable controls.
+- Allow non-essential interaction motion to be reduced or disabled.
+
+## Do Not Copy Blindly
+
+- Do not prescribe one visual focus style across all platforms; preserve a visible platform-appropriate indicator.
+- Do not remove motion that is essential to conveying required information without providing an equivalent static presentation.

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

@@ -0,0 +1,57 @@
+---
+id: RESEARCH-00006
+alias: TEXTUAL-ERROR-RECOVERY
+slug: textual-error-recovery
+title: Textual Error Recovery
+object_type: research
+status: draft
+version: 0.1.0
+category: accessibility
+tags:
+  - accessibility
+  - errors
+  - forms
+maturity: seed
+risk_level: high
+relationships:
+  - type: derived_from
+    target: observations/accessibility/textual-error-recovery.md
+---
+
+# Textual Error Recovery
+
+## Why Study It
+
+Forms and capture flows fail when a user cannot tell which value was rejected or how to recover. This is both an accessibility and task-completion risk.
+
+## Source Signals
+
+- W3C WCAG 2.2 Success Criterion 3.3.1 requires an automatically detected input error to identify the affected item and describe the error in text.
+- W3C notes that color or visual styling may supplement, but cannot replace, the textual description.
+- W3C distinguishes identifying an error from suggesting how to correct it; a clear message can serve both purposes.
+
+Sources:
+
+- https://www.w3.org/WAI/WCAG22/Understanding/error-identification
+
+## Observed Design Behavior
+
+- An error message names the field and the invalid condition.
+- The error remains available in the flow instead of being conveyed only by a transient color change.
+- When the correction is known, the message explains the required next input.
+
+## Design Takeaways For Agents
+
+- Treat validation as a recovery state, not a decorative red state.
+- Keep the message specific to the affected input and understandable without color.
+- Do not prescribe one display location for every form; inline, summary, alert, and dialog patterns depend on context.
+
+## Candidate Rule Directions
+
+- Describe detected input errors in text and identify the affected input.
+- Give a correction hint when the valid value or format is known.
+
+## Do Not Copy Blindly
+
+- Do not expose private validation or server details in an error message.
+- Do not force every error into a modal; choose the recovery mechanism for the task and platform.

package/research/performance/reserved-loading-space.md

@@ -0,0 +1,56 @@
+---
+id: RESEARCH-00007
+alias: RESERVED-LOADING-SPACE
+slug: reserved-loading-space
+title: Reserved Loading Space
+object_type: research
+status: draft
+version: 0.1.0
+category: performance
+tags:
+  - performance
+  - loading
+  - layout-stability
+maturity: seed
+risk_level: medium
+relationships:
+  - type: derived_from
+    target: observations/performance/reserved-loading-space.md
+---
+
+# Reserved Loading Space
+
+## Why Study It
+
+Slow or asynchronous content should not move the surrounding interface after users have begun reading or acting. This is a perceived-performance and interaction-safety concern.
+
+## Source Signals
+
+- web.dev defines Cumulative Layout Shift as a measure of visible-content instability.
+- The guidance identifies media and late content with unknown dimensions as common sources of unexpected movement.
+- Reserving the expected space lets the browser and interface keep nearby content in place while the content loads.
+
+Sources:
+
+- https://web.dev/articles/optimize-cls
+
+## Observed Design Behavior
+
+- Media and embeds reserve dimensions before their content arrives.
+- Loading placeholders occupy the same structural space as the resolved content.
+- Late content does not insert above a user’s current task unless it follows an explicit user action.
+
+## Design Takeaways For Agents
+
+- Specify loading-state geometry together with the resolved layout.
+- Prefer stable placeholders over spinners that cause the final content to reflow the screen.
+- Treat layout stability as part of the primary action’s feedback loop.
+
+## Candidate Rule Directions
+
+- Reserve layout space for asynchronous content and loading placeholders.
+
+## Do Not Copy Blindly
+
+- Do not hold a large empty region when the eventual content has no predictable size; choose a stable, bounded fallback instead.
+- Do not suppress user-initiated expansion or reordering solely to avoid movement.

package/research/products/apple-reminders.md

@@ -0,0 +1,59 @@
+---
+id: RESEARCH-00003
+alias: APPLE-REMINDERS
+slug: apple-reminders
+title: Apple Reminders
+object_type: research
+status: draft
+version: 0.1.0
+category: product
+tags:
+  - product-research
+  - reminders
+  - task-management
+maturity: seed
+risk_level: medium
+relationships:
+---
+
+# Apple Reminders
+
+## Why Study It
+
+Apple Reminders is useful for studying simple lists, system integration, and low-friction task capture for everyday users.
+
+## Source Signals
+
+- Reminders helps users track and organize to-dos.
+- Reminders integrates scheduled reminders into Calendar.
+- It supports grocery categories, list and column views, smart lists, pinned lists, subtasks, tags, dates, locations, shared lists, templates, and widgets.
+
+Sources:
+
+- https://support.apple.com/guide/reminders/welcome/mac
+
+## Observed Design Behavior
+
+- The basic model stays simple: list, reminder, complete.
+- Power features exist around the list instead of replacing it.
+- Smart lists and pinned lists improve retrieval without changing capture.
+- Grocery categorization shows automation only where the domain is predictable.
+- System integration matters: reminders can appear in Calendar, widgets, notifications, and shared contexts.
+
+## Design Takeaways For Agents
+
+- Keep the default path obvious for casual users.
+- Add intelligence only where it reduces manual sorting.
+- Prefer platform integration over custom surfaces when the platform already owns the moment.
+- Let simple lists remain simple.
+
+## Candidate Rule Directions
+
+- Everyday tools need a low-friction capture path before advanced organization.
+- Smart organization should preserve user control.
+- Platform-native moments can be better than another in-app screen.
+
+## Do Not Copy Blindly
+
+- Do not use Apple's simplicity as an excuse to omit needed hierarchy.
+- Do not add smart categorization unless the categories are predictable and correctable.

package/research/products/arc.md

@@ -0,0 +1,61 @@
+---
+id: RESEARCH-00005
+alias: ARC
+slug: arc
+title: Arc
+object_type: research
+status: draft
+version: 0.1.0
+category: product
+tags:
+  - product-research
+  - workspace
+  - context
+maturity: seed
+risk_level: medium
+relationships:
+---
+
+# Arc
+
+## Why Study It
+
+Arc is useful for studying workspace organization, context switching, browser interaction models, and motion-led product feel.
+
+## Source Signals
+
+- Arc positions itself as a browser that organizes work, study, hobbies, and other contexts in one window.
+- Arc uses Spaces and Profiles for context separation.
+- Arc includes Split View, Themes, Pinned Tabs, Favorites, Peek, Little Arc, Mini Player, Boosts, Easels, and sharing for spaces, folders, and splits.
+- Arc's site notes that Arc now receives Chromium updates only and points users who need active security patches to Dia.
+
+Sources:
+
+- https://arc.net/
+- https://resources.arc.net/hc/en-us/categories/16435255982103-Features
+
+## Observed Design Behavior
+
+- The browser is treated as a workspace, not only a page viewer.
+- Context is organized spatially through Spaces, Profiles, pinned tabs, favorites, and split views.
+- Lightweight preview patterns reduce full context switching.
+- Creation tools sit inside browsing instead of requiring a separate app.
+- Motion and interaction polish communicate that the product is meant to feel different from a default browser.
+
+## Design Takeaways For Agents
+
+- For products with many contexts, make the context model visible and navigable.
+- Reduce context switches with previews, split surfaces, and temporary windows.
+- Use motion to preserve orientation, not to decorate.
+- Workspace products need opinionated organization defaults.
+
+## Candidate Rule Directions
+
+- Context-heavy products should expose context boundaries clearly.
+- Preview interactions should help users inspect without committing to navigation.
+- Motion should explain where objects came from and where they went.
+
+## Do Not Copy Blindly
+
+- Do not copy Arc's novelty if the product's value depends on predictability.
+- Do not use motion-heavy interactions without accessibility and performance review.

package/research/products/linear.md

@@ -0,0 +1,62 @@
+---
+id: RESEARCH-00004
+alias: LINEAR
+slug: linear
+title: Linear
+object_type: research
+status: draft
+version: 0.1.0
+category: product
+tags:
+  - product-research
+  - workflow
+  - operational-ui
+maturity: seed
+risk_level: medium
+relationships:
+---
+
+# Linear
+
+## Why Study It
+
+Linear is useful for studying perceived performance, dense operational UI, issue workflow structure, and how professional tools can feel fast without becoming visually noisy.
+
+## Source Signals
+
+- Linear organizes work around teams, issues, projects, initiatives, cycles, views, filtering, integrations, and analytics.
+- Projects are units of work with clear outcomes or planned completion dates.
+- Issue workflows are team-specific and commonly move through Backlog, Todo, In Progress, Done, and Canceled.
+- Triage acts as an inbox for incoming work from integrations and other teams.
+
+Sources:
+
+- https://linear.app/docs
+- https://linear.app/docs/projects
+- https://linear.app/docs/configuring-workflows
+
+## Observed Design Behavior
+
+- The product gives every work item a strong place in the system: issue, project, cycle, team, view.
+- Navigation and filtering are treated as core product actions, not secondary utilities.
+- Dense data is made scannable through consistent status, priority, ownership, and grouping.
+- Workflow language stays operational and concrete.
+- Views let different users inspect the same work from different angles without duplicating data.
+
+## Design Takeaways For Agents
+
+- Operational products need speed and structure before decoration.
+- Clear object models reduce UI complexity.
+- Dense screens can still feel calm when hierarchy, grouping, and actions are predictable.
+- Inbox-style triage is useful when work enters from many sources.
+
+## Candidate Rule Directions
+
+- Define the product object model before designing screens.
+- Give recurring work states stable names and positions.
+- Let users switch views without changing the underlying data.
+
+## Do Not Copy Blindly
+
+- Do not apply Linear's density to consumer workflows where emotional clarity matters more than throughput.
+- Do not introduce projects, cycles, or triage unless the product has real operational complexity.

package/research/products/telegram.md

@@ -0,0 +1,61 @@
+---
+id: RESEARCH-00001
+alias: TELEGRAM
+slug: telegram
+title: Telegram
+object_type: research
+status: draft
+version: 0.1.0
+category: product
+tags:
+  - product-research
+  - messaging
+  - information-architecture
+maturity: seed
+risk_level: medium
+relationships:
+---
+
+# Telegram
+
+## Why Study It
+
+Telegram is useful for studying speed, optimistic interaction, and information architecture that scales from private chats to large public communities.
+
+## Source Signals
+
+- Telegram describes itself as a cloud-based mobile and desktop messaging app focused on security and speed.
+- Telegram supports private chats, groups, channels, bots, stories, and chat folders.
+- Telegram groups can support very large communities, while channels are optimized for broadcast.
+
+Sources:
+
+- https://telegram.org/tour
+- https://telegram.org/blog/groups-and-channels
+- https://telegram.org/blog/shareable-folders-custom-wallpapers
+
+## Observed Design Behavior
+
+- The chat list is the primary home surface.
+- Sending a message feels immediate; delivery state is secondary to the action.
+- The same base object, a conversation, supports private, group, broadcast, bot, and folder contexts.
+- Advanced features are available, but they do not block basic messaging.
+- Navigation favors return speed: users can leave and re-enter a thread quickly.
+
+## Design Takeaways For Agents
+
+- Optimize the repeated action first.
+- Keep the core surface stable even when the product supports many modes.
+- Make advanced organization optional, not mandatory.
+- Treat status and delivery feedback as quiet confirmation, not the center of the UI.
+
+## Candidate Rule Directions
+
+- Primary repeated actions should complete with minimal visual interruption.
+- Products with many modes need one stable home surface.
+- Large-scale IA should grow from the same mental model as small-scale usage.
+
+## Do Not Copy Blindly
+
+- Do not copy Telegram's density into products where users need reflection or structured decision-making.
+- Do not add channels, folders, or bots unless the product has a real scale problem.

package/research/products/things-3.md

@@ -0,0 +1,60 @@
+---
+id: RESEARCH-00002
+alias: THINGS-3
+slug: things-3
+title: Things 3
+object_type: research
+status: draft
+version: 0.1.0
+category: product
+tags:
+  - product-research
+  - productivity
+  - task-management
+maturity: seed
+risk_level: medium
+relationships:
+---
+
+# Things 3
+
+## Why Study It
+
+Things 3 is useful for studying calm productivity UX, typography, spacing, progressive disclosure, and list editing that feels lightweight on mobile and desktop.
+
+## Source Signals
+
+- Things is a personal task manager for planning the day, managing projects, and making progress.
+- The product uses Today, This Evening, Upcoming, headings, checklists, reminders, Quick Find, and direct manipulation.
+- Things emphasizes hiding extra task fields until they are needed.
+
+Sources:
+
+- https://culturedcode.com/things/
+- https://culturedcode.com/things/features/
+
+## Observed Design Behavior
+
+- The Today view turns a large task database into a daily plan.
+- Extra fields such as tags, checklist, start date, and deadline are available without dominating the to-do.
+- This Evening separates later tasks from the main day without creating a new system.
+- Upcoming combines scheduled tasks, repeating tasks, deadlines, and calendar events.
+- Direct manipulation is central: drag to insert, reorder, move, and structure.
+
+## Design Takeaways For Agents
+
+- Separate capture, planning, and doing.
+- Hide power until the user needs it.
+- Use time language that matches user intent: today, evening, upcoming, someday.
+- Make list editing feel tactile, not like form administration.
+
+## Candidate Rule Directions
+
+- Daily planning screens should reduce the total system into today's useful subset.
+- Advanced metadata should be progressively disclosed.
+- Mobile list editing should support fast insertion, selection, and reordering.
+
+## Do Not Copy Blindly
+
+- Do not copy Things' minimalism into collaboration-heavy products that need visible ownership and status.
+- Do not hide metadata if users must compare or audit items quickly.

package/research/ux/contextual-agentic-interface.md

@@ -0,0 +1,68 @@
+---
+id: RESEARCH-00011
+alias: CONTEXTUAL-AGENTIC-INTERFACE
+slug: contextual-agentic-interface
+title: Contextual And Observable Agentic Interfaces
+object_type: research
+status: draft
+version: 0.1.0
+category: ux
+tags:
+  - ai
+  - agentic-ui
+  - context
+  - trust
+maturity: seed
+risk_level: high
+relationships:
+  - type: derived_from
+    target: observations/ai/figma-agent-context-and-skills.md
+  - type: derived_from
+    target: observations/ai/agent-work-visibility-and-intervention.md
+  - type: related_to
+    target: RESEARCH-00004
+---
+
+# Contextual And Observable Agentic Interfaces
+
+## Why Study It
+
+AI product surfaces increasingly coordinate tools, long-running tasks, and shared work. A prompt box alone does not expose enough context, progress, or control for these workflows.
+
+## Source Signals
+
+- Figma's agent uses structured files, components, tokens, attachments, connectors, shared prompt history, and reusable skills.
+- Figma's agentic-work case study shows active, completed, review-ready, and intervention-required work outside the chat thread.
+- Existing Linear research supports visible state and calm handling of high information density.
+
+Sources:
+
+- https://www.figma.com/blog/agent-custom-tools-context-skills/
+- https://www.figma.com/blog/the-figma-canvas-is-now-open-to-agents/
+- https://www.figma.com/blog/how-to-design-agentic-tools-for-work/
+
+## Observed Design Behavior
+
+- The agent is grounded in product and system context instead of only prompt text.
+- Delegated work exposes status, scope, result, and whether human input is required.
+- Users can inspect and intervene without managing every internal agent step.
+- Shared history makes decisions and iterations available to collaborators.
+
+## Design Takeaways For Agents
+
+- Identify the user's goal before exposing agent mechanics.
+- Show stable states for queued, active, blocked, review-ready, complete, failed, and cancelled work when those states exist.
+- Make scope, source context, result, and intervention points inspectable.
+- Keep recovery and cancellation proportional to the risk and duration of the work.
+- Do not make chat the only place where users can understand ongoing work.
+
+## Candidate Rule Directions
+
+- Expose agent work state and intervention points for delegated or long-running work.
+- Ground agent output in inspectable product and design-system context.
+
+## Do Not Copy Blindly
+
+- Do not add an operations dashboard for an instant deterministic action.
+- Do not expose internal chain-of-thought or irrelevant implementation detail.
+- Do not imply that visibility alone makes an unsafe agent action trustworthy.