ai-design-context 0.4.0

package/rules/accessibility/A11Y-002.md

@@ -0,0 +1,55 @@
+---
+id: RULE-00010
+alias: A11Y-002
+slug: textual-input-error-recovery
+title: Textual Input Error Recovery
+object_type: rule
+status: draft
+version: 0.1.0
+category: accessibility
+tags:
+  - accessibility
+  - errors
+  - forms
+maturity: seed
+risk_level: high
+relationships:
+  - type: derived_from
+    target: RESEARCH-00006
+---
+
+# A11Y-002 Textual Input Error Recovery
+
+Status: Draft
+Domain: Accessibility
+
+## Source Research
+
+- `research/accessibility/textual-error-recovery.md`
+
+## Why
+
+Users cannot reliably recover when a form only changes color, hides the failed field, or says only that submission failed. Textual, field-specific feedback makes the failure understandable and actionable across visual and assistive-technology contexts.
+
+## Rule
+
+When input validation detects an error, identify the affected input and describe the error in text. Include a correction hint when the valid value or format is known; color and icons may reinforce, but must not be the only signal.
+
+## Good
+
+- “Email: enter an address in the format name@example.com” appears with the invalid email field.
+- A form-level summary names each invalid field and links or moves focus to a recoverable field when appropriate.
+- An error remains understandable after its visual error color is removed.
+
+## Bad
+
+- A field border turns red with no textual explanation.
+- A generic “Something went wrong” message replaces field-specific validation feedback.
+- A message says a value is invalid but provides no correction when the required format is known.
+
+## Review
+
+- Trigger every client-side and server-returned validation state.
+- Verify that each message identifies the input and describes the failed condition in text.
+- Verify that color, position, or animation is not the only error cue.
+- Check that a known correction is explained without exposing sensitive validation details.

package/rules/accessibility/A11Y-003.md

@@ -0,0 +1,54 @@
+---
+id: RULE-00012
+alias: A11Y-003
+slug: visible-keyboard-focus
+title: Visible Keyboard Focus
+object_type: rule
+status: draft
+version: 0.1.0
+category: accessibility
+tags:
+  - accessibility
+  - keyboard
+  - focus
+maturity: seed
+risk_level: high
+relationships:
+  - type: derived_from
+    target: RESEARCH-00008
+---
+
+# A11Y-003 Visible Keyboard Focus
+
+Status: Draft
+Domain: Accessibility
+
+## Source Research
+
+- `research/accessibility/keyboard-focus-and-interaction-motion.md`
+
+## Why
+
+Keyboard users cannot operate a flow reliably when focus disappears or its indicator is visually hidden. Focus must communicate the current interaction target for as long as it remains active.
+
+## Rule
+
+Every keyboard-operable control must retain a visible focus indicator while it has keyboard focus. Do not remove or render the platform focus state invisible without providing an equally visible replacement.
+
+## Good
+
+- A focused input, button, task row, or sheet close control has an indicator that remains visible.
+- A custom control uses a visible `:focus-visible` state or retains the platform default.
+- Keyboard focus remains apparent through validation and recovery states.
+
+## Bad
+
+- A global outline reset leaves keyboard users with no focus indication.
+- Focus appears briefly, then fades while the control remains active.
+- A dialog opens without a visible focused control or an understandable keyboard path.
+
+## Review
+
+- Navigate the primary flow using only a keyboard.
+- Verify each interactive control has a visible focus state and that it persists.
+- Check focus during loading, validation error, detail open, and close actions.

package/rules/accessibility/A11Y-004.md

@@ -0,0 +1,54 @@
+---
+id: RULE-00013
+alias: A11Y-004
+slug: reduce-non-essential-interaction-motion
+title: Reduce Non-Essential Interaction Motion
+object_type: rule
+status: draft
+version: 0.1.0
+category: accessibility
+tags:
+  - accessibility
+  - motion
+  - reduced-motion
+maturity: seed
+risk_level: high
+relationships:
+  - type: derived_from
+    target: RESEARCH-00008
+---
+
+# A11Y-004 Reduce Non-Essential Interaction Motion
+
+Status: Draft
+Domain: Accessibility
+
+## Source Research
+
+- `research/accessibility/keyboard-focus-and-interaction-motion.md`
+
+## Why
+
+Non-essential interaction motion can distract users or cause dizziness, nausea, and headaches. A product must not make that motion a requirement for understanding or operating the flow.
+
+## Rule
+
+When an interaction triggers non-essential motion, respect a reduced-motion preference or provide an equivalent control that disables the motion. Preserve the same information and function in the non-moving state.
+
+## Good
+
+- A sheet opens immediately when reduced motion is enabled while keeping the same focus and close behavior.
+- Decorative parallax or list movement is disabled without hiding content.
+- A transition that explains state also has a static end-state presentation.
+
+## Bad
+
+- A user must watch a sliding or zooming transition to know what opened.
+- Reduced motion removes a required control or information instead of only non-essential movement.
+- Decorative motion is added without a way to avoid it.
+
+## Review
+
+- List interaction-triggered motion separately from essential scrolling and required information.
+- Enable a reduced-motion preference or control and verify the task remains complete.
+- Confirm loading and error feedback remain visible without motion.

package/rules/ia/IA-001.md

@@ -0,0 +1,60 @@
+---
+id: RULE-00003
+alias: IA-001
+slug: one-stable-home-surface
+title: One Stable Home Surface
+object_type: rule
+status: draft
+version: 0.1.0
+category: ia
+tags:
+  - ia
+  - home-surface
+maturity: seed
+risk_level: medium
+relationships:
+  - type: derived_from
+    target: RESEARCH-00001
+  - type: derived_from
+    target: RESEARCH-00002
+  - type: derived_from
+    target: RESEARCH-00003
+---
+
+# IA-001 One Stable Home Surface
+
+Status: Draft
+Domain: IA
+
+## Source Research
+
+- `research/products/telegram.md`
+- `research/products/things-3.md`
+- `research/products/apple-reminders.md`
+
+## Why
+
+Products with many modes become understandable when users can return to one stable home surface. The home surface anchors memory and reduces the cost of switching tasks.
+
+## Rule
+
+Give the product one primary home surface that stays recognizable as features, modes, and organization layers grow.
+
+## Good
+
+- Users can name where they return after finishing a task.
+- New modes extend the home model instead of replacing it.
+- Navigation supports fast exit and fast return.
+- Advanced grouping is optional.
+
+## Bad
+
+- Each feature introduces a new top-level destination with a different mental model.
+- The product has several competing "home" screens.
+- Users must remember which mode they were in to find basic work.
+
+## Review
+
+- Identify the product's home surface in one sentence.
+- Check whether each major mode returns to that surface.
+- Check whether new organization adds clarity or creates another product inside the product.

package/rules/ia/IA-002.md

@@ -0,0 +1,61 @@
+---
+id: RULE-00004
+alias: IA-002
+slug: define-the-object-model-before-screens
+title: Define The Object Model Before Screens
+object_type: rule
+status: draft
+version: 0.1.0
+category: ia
+tags:
+  - ia
+  - object-model
+maturity: seed
+risk_level: medium
+relationships:
+  - type: derived_from
+    target: RESEARCH-00004
+  - type: derived_from
+    target: RESEARCH-00001
+  - type: derived_from
+    target: RESEARCH-00005
+---
+
+# IA-002 Define The Object Model Before Screens
+
+Status: Draft
+Domain: IA
+
+## Source Research
+
+- `research/products/linear.md`
+- `research/products/telegram.md`
+- `research/products/arc.md`
+
+## Why
+
+Agents often jump into screen layout before defining what the product objects are. This creates navigation, naming, and state inconsistencies.
+
+## Rule
+
+Before designing screens, define the core objects, their states, and how users move between them.
+
+## Good
+
+- Core objects have clear names and stable relationships.
+- Screens expose the same object model from different views.
+- Statuses and ownership labels mean the same thing everywhere.
+- Navigation mirrors how users think about the work.
+
+## Bad
+
+- Similar concepts use different names across screens.
+- A view creates duplicate data instead of another perspective on the same object.
+- Status, ownership, and grouping change meaning by screen.
+
+## Review
+
+- List the product's core objects.
+- List the states each object can enter.
+- Check whether every screen maps to those objects and states.
+- Check whether users can switch views without losing the underlying data.

package/rules/performance/PERF-001.md

@@ -0,0 +1,55 @@
+---
+id: RULE-00011
+alias: PERF-001
+slug: reserve-layout-space-for-asynchronous-content
+title: Reserve Layout Space For Asynchronous Content
+object_type: rule
+status: draft
+version: 0.1.0
+category: performance
+tags:
+  - performance
+  - loading
+  - layout-stability
+maturity: seed
+risk_level: medium
+relationships:
+  - type: derived_from
+    target: RESEARCH-00007
+---
+
+# PERF-001 Reserve Layout Space For Asynchronous Content
+
+Status: Draft
+Domain: Performance
+
+## Source Research
+
+- `research/performance/reserved-loading-space.md`
+
+## Why
+
+When loading media, embeds, or delayed content unexpectedly moves controls and text, users lose orientation and may act on the wrong target. Stable loading geometry makes waiting predictable.
+
+## Rule
+
+Reserve the expected layout space for asynchronous content before it arrives. Loading placeholders must preserve the structure and approximate dimensions of the resolved content whenever those dimensions are known.
+
+## Good
+
+- An image card declares or derives its aspect ratio before the image is painted.
+- A list row skeleton has the same height and action placement as the loaded row.
+- An embed or dynamic slot reserves a bounded, expected region instead of pushing active content down on arrival.
+
+## Bad
+
+- A spinner occupies a smaller region than the content that will replace it, shifting nearby controls after load.
+- Lazy-loaded media appears above an active form or list item without reserved space.
+- A placeholder reserves an arbitrary large area that collapses dramatically when content loads.
+
+## Review
+
+- Test slow-network and cache-cold loading states.
+- Compare the loading and resolved layout around primary actions and visible controls.
+- Check media, embeds, list rows, and late-loaded status blocks for unexpected movement.
+- Exclude deliberate user-initiated expansion or reordering from layout-shift findings.

package/rules/product/PRD-001.md

@@ -0,0 +1,61 @@
+---
+id: RULE-00001
+alias: PRD-001
+slug: daily-actions-first
+title: Daily Actions First
+object_type: rule
+status: draft
+version: 0.1.0
+category: product
+tags:
+  - product
+  - daily-work
+maturity: seed
+risk_level: medium
+relationships:
+  - type: derived_from
+    target: RESEARCH-00002
+  - type: derived_from
+    target: RESEARCH-00001
+  - type: derived_from
+    target: RESEARCH-00003
+---
+
+# PRD-001 Daily Actions First
+
+Status: Draft
+Domain: Product
+
+## Source Research
+
+- `research/products/things-3.md`
+- `research/products/telegram.md`
+- `research/products/apple-reminders.md`
+
+## Why
+
+Consumer products earn trust through repeated daily actions. If the most common action is buried under structure, decoration, or setup, the product feels heavier than the job it solves.
+
+## Rule
+
+Design the main screen around the user's most repeated action before adding secondary navigation, advanced metadata, or decorative sections.
+
+## Good
+
+- The primary repeated action is visible without scrolling.
+- The action can be completed without opening a configuration flow.
+- Supporting state is quiet and does not compete with the action.
+- Secondary tools are available but not placed ahead of the daily job.
+
+## Bad
+
+- The screen starts with analytics, cards, onboarding copy, or branding while the daily action is hidden.
+- A simple action requires choosing categories, filters, or settings first.
+- The interface optimizes for edge cases before the repeated behavior.
+
+## Review
+
+- Name the most repeated action for this product.
+- Confirm the action is reachable in the first viewport.
+- Confirm secondary actions do not visually dominate it.
+- Confirm the rule still fits products where the primary job is review, not creation.

package/rules/product/PRD-002.md

@@ -0,0 +1,61 @@
+---
+id: RULE-00002
+alias: PRD-002
+slug: low-friction-capture-before-organization
+title: Low-Friction Capture Before Organization
+object_type: rule
+status: draft
+version: 0.1.0
+category: product
+tags:
+  - product
+  - capture
+maturity: seed
+risk_level: medium
+relationships:
+  - type: derived_from
+    target: RESEARCH-00003
+  - type: derived_from
+    target: RESEARCH-00002
+  - type: derived_from
+    target: RESEARCH-00001
+---
+
+# PRD-002 Low-Friction Capture Before Organization
+
+Status: Draft
+Domain: Product
+
+## Source Research
+
+- `research/products/apple-reminders.md`
+- `research/products/things-3.md`
+- `research/products/telegram.md`
+
+## Why
+
+Everyday products often fail when they ask users to organize information before capturing it. Capture should be fast; organization can happen after the user has recorded the intent.
+
+## Rule
+
+Let users add the basic item first, then offer categorization, scheduling, metadata, or smart organization as follow-up actions.
+
+## Good
+
+- A user can create the core item with one clear action.
+- Optional fields do not block capture.
+- Smart suggestions are correctable and do not replace user control.
+- Organization improves retrieval without changing the basic model.
+
+## Bad
+
+- The creation flow requires category, priority, project, tags, and dates before saving.
+- Smart categorization silently changes user intent.
+- Empty states explain the system instead of helping the user add the first item.
+
+## Review
+
+- Try creating the simplest possible item.
+- Count how many required decisions happen before save.
+- Check whether optional metadata can be added later.
+- Check whether automation is reversible.

package/rules/ux/UX-001.md

@@ -0,0 +1,58 @@
+---
+id: RULE-00005
+alias: UX-001
+slug: thumb-zone-primary-actions
+title: Thumb-Zone Primary Actions
+object_type: rule
+status: draft
+version: 0.1.0
+category: ux
+tags:
+  - ux
+  - mobile
+  - touch
+maturity: seed
+risk_level: high
+relationships:
+  - type: derived_from
+    target: RESEARCH-00002
+  - type: derived_from
+    target: RESEARCH-00003
+---
+
+# UX-001 Thumb-Zone Primary Actions
+
+Status: Draft
+Domain: UX
+
+## Source Research
+
+- `research/products/things-3.md`
+- `research/products/apple-reminders.md`
+
+## Why
+
+Mobile consumer workflows depend on fast repeated actions. If the main action sits outside comfortable reach, the product feels slower even when the feature set is correct.
+
+## Rule
+
+Place the primary mobile action where it is reachable by thumb and keep destructive or secondary actions away from accidental taps.
+
+## Good
+
+- The main action is reachable near the bottom or another established thumb-friendly control area.
+- Secondary actions are visually and spatially distinct.
+- Repeated list actions support quick insertion, completion, and reordering.
+
+## Bad
+
+- The primary action is only in a top bar on a tall mobile viewport.
+- Multiple actions compete in the same touch area.
+- Destructive actions sit next to frequent positive actions.
+
+## Review
+
+- Test the screen at 390px width.
+- Confirm the primary action is reachable without hand repositioning.
+- Confirm touch targets meet `A11Y-001`.
+- Confirm the layout still works when the list is empty and when it is long.

package/rules/ux/UX-002.md

@@ -0,0 +1,61 @@
+---
+id: RULE-00006
+alias: UX-002
+slug: progressively-disclose-power
+title: Progressively Disclose Power
+object_type: rule
+status: draft
+version: 0.1.0
+category: ux
+tags:
+  - ux
+  - progressive-disclosure
+maturity: seed
+risk_level: medium
+relationships:
+  - type: derived_from
+    target: RESEARCH-00002
+  - type: derived_from
+    target: RESEARCH-00003
+  - type: derived_from
+    target: RESEARCH-00001
+---
+
+# UX-002 Progressively Disclose Power
+
+Status: Draft
+Domain: UX
+
+## Source Research
+
+- `research/products/things-3.md`
+- `research/products/apple-reminders.md`
+- `research/products/telegram.md`
+
+## Why
+
+Power features help advanced users but can slow down first use. Progressive disclosure keeps the default path simple while preserving depth.
+
+## Rule
+
+Show the minimum controls needed for the current task, and reveal advanced fields, filters, or modes only when they become relevant.
+
+## Good
+
+- The default state supports basic completion without explanation.
+- Advanced metadata is discoverable but not visually dominant.
+- Users can add detail after capture.
+- The interface remains usable without learning every feature.
+
+## Bad
+
+- Every possible field appears in the first form.
+- Advanced filters are required before the first useful result.
+- The UI hides essential status that users need for comparison or audit.
+
+## Review
+
+- Identify which fields are required for the first useful action.
+- Move non-required metadata behind edit, details, filter, or secondary controls.
+- Check that hidden controls are still discoverable.
+- Check that hiding information does not harm collaboration or accountability.

package/rules/ux/UX-003.md

@@ -0,0 +1,60 @@
+---
+id: RULE-00007
+alias: UX-003
+slug: preserve-context-during-inspection
+title: Preserve Context During Inspection
+object_type: rule
+status: draft
+version: 0.1.0
+category: ux
+tags:
+  - ux
+  - context
+maturity: seed
+risk_level: medium
+relationships:
+  - type: derived_from
+    target: RESEARCH-00005
+  - type: derived_from
+    target: RESEARCH-00004
+  - type: derived_from
+    target: RESEARCH-00001
+---
+
+# UX-003 Preserve Context During Inspection
+
+Status: Draft
+Domain: UX
+
+## Source Research
+
+- `research/products/arc.md`
+- `research/products/linear.md`
+- `research/products/telegram.md`
+
+## Why
+
+Users lose momentum when every inspection forces a full navigation change. Preview, split, and side-panel patterns reduce context switching when users need to inspect without committing.
+
+## Rule
+
+When users need to compare, inspect, or triage items, provide a way to view detail without losing the original context.
+
+## Good
+
+- Detail can open in a preview, side panel, split view, or temporary surface.
+- Returning to the list or workspace preserves scroll, filters, and selection.
+- Motion or placement makes it clear where the detail came from.
+
+## Bad
+
+- Opening detail resets the list, filters, or scroll position.
+- Users must navigate back and rebuild context after every inspection.
+- Preview surfaces become full editors with too many actions.
+
+## Review
+
+- Identify inspection-heavy workflows.
+- Open and close item detail repeatedly.
+- Confirm the source context remains intact.
+- Confirm the preview does not hide essential primary actions.