ai-design-context 0.4.0

package/rules/ux/UX-004.md

@@ -0,0 +1,61 @@
+---
+id: RULE-00015
+alias: UX-004
+slug: use-motion-to-explain-state-continuity
+title: Use Motion To Explain State Continuity
+object_type: rule
+status: draft
+version: 0.1.0
+category: ux
+tags:
+  - ux
+  - motion
+  - continuity
+maturity: seed
+risk_level: high
+relationships:
+  - type: derived_from
+    target: RESEARCH-00010
+  - type: related_to
+    target: RULE-00007
+  - type: related_to
+    target: RULE-00013
+---
+
+# UX-004 Use Motion To Explain State Continuity
+
+Status: Draft
+Domain: UX
+
+## Source Research
+
+- `research/ux/motion-as-state-continuity.md`
+
+## Why
+
+Users can lose orientation when objects change state, location, or level of detail. Purposeful motion can connect the before and after states, but generic animation adds delay and accessibility risk.
+
+## Rule
+
+Use motion only when it explains the continuity of an object, state, or navigation context. Define its start state, end state, reusable motion role, reduced-motion behavior, and unsupported-platform fallback.
+
+## Good
+
+- A selected item visibly becomes its detail surface while the source context remains understandable.
+- Insert, remove, reorder, expand, and collapse transitions clarify what changed.
+- Repeated transitions use named timing and easing roles.
+- Reduced motion reaches the same end state with the same focus and information.
+
+## Bad
+
+- Elements animate because the screen should feel more modern.
+- Motion delays a primary action or prevents unrelated interaction.
+- Every component uses unrelated durations or easing.
+- The transition is required to understand success, error, or navigation.
+
+## Review
+
+- State the orientation problem the motion solves.
+- Verify start, end, focus, interruption, and reduced-motion behavior.
+- Confirm loading and error feedback remain available without animation.
+- Check support and progressive fallback for any platform-specific API.

package/rules/ux/UX-005.md

@@ -0,0 +1,62 @@
+---
+id: RULE-00016
+alias: UX-005
+slug: expose-agent-work-and-intervention
+title: Expose Agent Work And Intervention
+object_type: rule
+status: draft
+version: 0.1.0
+category: ux
+tags:
+  - ux
+  - ai
+  - agentic-ui
+  - trust
+maturity: seed
+risk_level: high
+relationships:
+  - type: derived_from
+    target: RESEARCH-00011
+  - type: related_to
+    target: RULE-00004
+  - type: related_to
+    target: RULE-00007
+---
+
+# UX-005 Expose Agent Work And Intervention
+
+Status: Draft
+Domain: UX
+
+## Source Research
+
+- `research/ux/contextual-agentic-interface.md`
+
+## Why
+
+For delegated or long-running work, a prompt thread alone does not reliably communicate progress, scope, required input, or recovery. Users need enough observable state to supervise outcomes without managing every internal step.
+
+## Rule
+
+When an agent performs delegated, long-running, or interruptible work, expose its user-relevant status, scope, result, and intervention points outside transient conversational output.
+
+## Good
+
+- Work distinguishes queued, active, blocked, review-ready, complete, failed, and cancelled states when applicable.
+- The user can inspect sources, scope, output, and the next required decision.
+- Risk-appropriate cancel, retry, edit, or review actions are available.
+- The primary product goal stays more prominent than agent mechanics.
+
+## Bad
+
+- A loading message is the only record of a long-running task.
+- Users cannot tell whether work is active, blocked, complete, or failed.
+- The interface exposes internal reasoning instead of actionable state.
+- Agent controls dominate an otherwise simple instant action.
+
+## Review
+
+- List the actual lifecycle states for the delegated work.
+- Verify that status and next action remain visible after leaving the chat.
+- Test failure, cancellation, retry, and human-input paths.
+- Confirm the interface reveals useful evidence without exposing sensitive or irrelevant internals.

package/rules/ux/UX-006.md

@@ -0,0 +1,69 @@
+---
+id: RULE-00017
+alias: UX-006
+slug: confirm-consequential-actions-with-preserved-context
+title: Confirm Consequential Actions With Preserved Context
+object_type: rule
+status: active
+version: 0.1.0
+category: ux
+tags:
+  - ux
+  - finance
+  - ai
+  - confirmation
+  - recovery
+maturity: validated
+risk_level: high
+last_reviewed_at: 2026-08-12
+relationships:
+  - type: derived_from
+    target: RESEARCH-00012
+  - type: related_to
+    target: RULE-00007
+  - type: related_to
+    target: RULE-00010
+  - type: related_to
+    target: RULE-00016
+---
+
+# UX-006 Confirm Consequential Actions With Preserved Context
+
+Status: Draft
+Domain: UX
+
+## Source Research
+
+- `research/ux/high-risk-operational-flows.md`
+
+## Why
+
+When an action can move money, change account access, publish externally, delete durable data, or let an agent act on the user's behalf, users need to verify the exact consequence without losing the context that made the action meaningful.
+
+## Rule
+
+Before executing a consequential action, show a risk-proportional confirmation or challenge state that preserves the acted-on object, critical inputs, side effects, reversibility, and recovery path.
+
+## Good
+
+- The confirmation keeps the object, amount, recipient, destination, scope, or selected records visible.
+- A server-requested challenge adds only the missing confirmation field while preserving entered data.
+- The user can still cancel, edit critical inputs, or understand what happens next.
+- User-facing copy explains the consequence and recovery path without raw backend codes.
+- Agentic actions with real-world side effects require explicit approval and remain interruptible.
+
+## Bad
+
+- A generic modal asks "Are you sure?" while hiding the object and side effects.
+- A failed 2FA, KYC, passkey, or agent approval restarts the entire flow unnecessarily.
+- The UI shows technical backend codes instead of actionable product language.
+- A low-risk reversible action gets the same heavy ceremony as a money movement.
+- The agent proceeds with an external side effect because the user gave a broad initial instruction.
+
+## Review
+
+- Identify the actual consequence, reversibility, and affected object.
+- Verify that critical context remains visible in confirmation, challenge, error, and retry states.
+- Check cancel, edit, retry, and success paths.
+- Confirm the recovery state asks only for the missing information.
+- For agentic work, verify approval, interruption, and audit evidence before execution.

package/rules/visual/VIS-001.md

@@ -0,0 +1,59 @@
+---
+id: RULE-00008
+alias: VIS-001
+slug: semantic-tokens-only
+title: Semantic Tokens Only
+object_type: rule
+status: draft
+version: 0.1.0
+category: visual
+tags:
+  - visual
+  - tokens
+maturity: seed
+risk_level: medium
+relationships:
+  - type: derived_from
+    target: RESEARCH-00004
+  - type: derived_from
+    target: RESEARCH-00002
+---
+
+# VIS-001 Semantic Tokens Only
+
+Status: Draft
+Domain: Visual
+
+## Source Research
+
+- `research/products/linear.md`
+- `research/products/things-3.md`
+
+## Why
+
+Visual consistency becomes fragile when agents choose one-off colors and spacing values. Semantic tokens preserve meaning across states, themes, and repeated surfaces.
+
+## Rule
+
+Use semantic tokens for color, spacing, typography, and state styling instead of raw one-off values.
+
+## Good
+
+- Color names describe purpose, such as text, surface, border, accent, success, warning, danger.
+- Spacing follows existing scale values.
+- Status colors carry the same meaning across screens.
+- New styles reuse existing tokens before adding new ones.
+
+## Bad
+
+- Similar states use unrelated colors.
+- Hex values are added directly to many components.
+- A visual change requires editing unrelated screens one by one.
+- Status colors change meaning by page.
+
+## Review
+
+- Search for raw colors and one-off spacing.
+- Confirm each visual value maps to a semantic purpose.
+- Check light and dark themes if they exist.
+- Check whether status color meaning stays stable across the product.

package/rules/visual/VIS-002.md

@@ -0,0 +1,59 @@
+---
+id: RULE-00014
+alias: VIS-002
+slug: keep-expression-subordinate-to-content
+title: Keep Expression Subordinate To Content
+object_type: rule
+status: draft
+version: 0.1.0
+category: visual
+tags:
+  - visual
+  - hierarchy
+  - expressive-design
+maturity: seed
+risk_level: medium
+relationships:
+  - type: derived_from
+    target: RESEARCH-00009
+  - type: related_to
+    target: RULE-00008
+---
+
+# VIS-002 Keep Expression Subordinate To Content
+
+Status: Draft
+Domain: Visual
+
+## Source Research
+
+- `research/visual/expressive-system-ui-2026.md`
+
+## Why
+
+Materials, strong shapes, color, typography, and depth can create product identity, but equal or excessive emphasis obscures content and primary actions. Modern platform systems use expression selectively and preserve semantic hierarchy.
+
+## Rule
+
+Use the strongest expressive treatment only where it clarifies functional hierarchy, primary emphasis, or product identity. Keep core content readable and dominant, and encode repeated expression through semantic system roles.
+
+## Good
+
+- Navigation and controls are visually distinct from the content they operate on.
+- One focal treatment identifies the primary action or important state.
+- Typography, shape, material, color, and depth use reusable semantic roles.
+- The interface remains understandable when transparency, motion, or decorative effects are reduced.
+
+## Bad
+
+- Every card, control, and background uses the same strong material or effect.
+- Glass, gradients, shadows, or unusual shapes compete with reading and task completion.
+- A platform-specific effect is copied to unrelated platforms without fallback.
+- Removing decorative effects collapses hierarchy or hides the primary action.
+
+## Review
+
+- Identify the content layer, functional layer, focal accent, and quiet supporting surfaces.
+- Temporarily remove decorative effects and confirm content order and primary action remain clear.
+- Check high contrast, reduced transparency, and reduced motion where relevant.
+- Confirm repeated visual decisions map to semantic tokens or component roles.

package/schema/checklist.schema.json

@@ -0,0 +1,21 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://ai-design-rules.dev/schema/checklist.schema.json",
+  "title": "Checklist",
+  "allOf": [
+    {
+      "$ref": "./common.schema.json"
+    },
+    {
+      "type": "object",
+      "properties": {
+        "id": {
+          "pattern": "^CHECK-[0-9]{5}$"
+        },
+        "object_type": {
+          "const": "checklist"
+        }
+      }
+    }
+  ]
+}

package/schema/common.schema.json

@@ -0,0 +1,178 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://ai-design-rules.dev/schema/common.schema.json",
+  "title": "AI Design Context Common Metadata",
+  "type": "object",
+  "additionalProperties": true,
+  "properties": {
+    "id": {
+      "type": "string",
+      "pattern": "^(OBS|RESEARCH|RULE|PAT|PROMPT|SKILL|REVIEW|CHECK|REF)-[0-9]{5}$"
+    },
+    "alias": {
+      "type": "string"
+    },
+    "slug": {
+      "type": "string",
+      "pattern": "^[a-z0-9]+(?:-[a-z0-9]+)*$"
+    },
+    "title": {
+      "type": "string",
+      "minLength": 1
+    },
+    "object_type": {
+      "type": "string",
+      "enum": [
+        "observation",
+        "research",
+        "rule",
+        "pattern",
+        "prompt",
+        "skill",
+        "review",
+        "checklist",
+        "reference_project"
+      ]
+    },
+    "status": {
+      "type": "string",
+      "enum": [
+        "draft",
+        "active",
+        "deprecated",
+        "superseded"
+      ]
+    },
+    "version": {
+      "type": "string",
+      "pattern": "^[0-9]+\\.[0-9]+\\.[0-9]+$"
+    },
+    "category": {
+      "type": "string"
+    },
+    "tags": {
+      "type": "array",
+      "items": {
+        "type": "string"
+      },
+      "uniqueItems": true
+    },
+    "created_at": {
+      "type": "string",
+      "format": "date"
+    },
+    "updated_at": {
+      "type": "string",
+      "format": "date"
+    },
+    "last_reviewed_at": {
+      "type": "string",
+      "format": "date"
+    },
+    "owner": {
+      "type": "string"
+    },
+    "maturity": {
+      "type": "string",
+      "enum": [
+        "seed",
+        "reviewed",
+        "validated",
+        "canonical"
+      ]
+    },
+    "risk_level": {
+      "type": "string",
+      "enum": [
+        "low",
+        "medium",
+        "high",
+        "critical"
+      ]
+    },
+    "platform": {
+      "type": "array",
+      "items": {
+        "type": "string"
+      },
+      "uniqueItems": true
+    },
+    "product_type": {
+      "type": "array",
+      "items": {
+        "type": "string"
+      },
+      "uniqueItems": true
+    },
+    "surface": {
+      "type": "array",
+      "items": {
+        "type": "string"
+      },
+      "uniqueItems": true
+    },
+    "applies_to": {
+      "type": "array",
+      "items": {
+        "type": "string"
+      },
+      "uniqueItems": true
+    },
+    "does_not_apply_to": {
+      "type": "array",
+      "items": {
+        "type": "string"
+      },
+      "uniqueItems": true
+    },
+    "relationships": {
+      "type": "array",
+      "items": {
+        "$ref": "#/$defs/relationship"
+      }
+    }
+  },
+  "required": [
+    "id",
+    "slug",
+    "title",
+    "object_type",
+    "status",
+    "version",
+    "category",
+    "relationships"
+  ],
+  "$defs": {
+    "relationship": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "type": {
+          "type": "string",
+          "enum": [
+            "derived_from",
+            "cites",
+            "inspired_by",
+            "requires",
+            "validates",
+            "implements",
+            "related_to",
+            "supersedes",
+            "deprecated_by",
+            "replaced_by"
+          ]
+        },
+        "target": {
+          "type": "string"
+        },
+        "note": {
+          "type": "string"
+        }
+      },
+      "required": [
+        "type",
+        "target"
+      ]
+    }
+  }
+}

package/schema/observation.schema.json

@@ -0,0 +1,21 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://ai-design-rules.dev/schema/observation.schema.json",
+  "title": "Observation",
+  "allOf": [
+    {
+      "$ref": "./common.schema.json"
+    },
+    {
+      "type": "object",
+      "properties": {
+        "id": {
+          "pattern": "^OBS-[0-9]{5}$"
+        },
+        "object_type": {
+          "const": "observation"
+        }
+      }
+    }
+  ]
+}

package/schema/pattern.schema.json

@@ -0,0 +1,21 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://ai-design-rules.dev/schema/pattern.schema.json",
+  "title": "Pattern",
+  "allOf": [
+    {
+      "$ref": "./common.schema.json"
+    },
+    {
+      "type": "object",
+      "properties": {
+        "id": {
+          "pattern": "^PAT-[0-9]{5}$"
+        },
+        "object_type": {
+          "const": "pattern"
+        }
+      }
+    }
+  ]
+}

package/schema/prompt.schema.json

@@ -0,0 +1,21 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://ai-design-rules.dev/schema/prompt.schema.json",
+  "title": "Prompt",
+  "allOf": [
+    {
+      "$ref": "./common.schema.json"
+    },
+    {
+      "type": "object",
+      "properties": {
+        "id": {
+          "pattern": "^PROMPT-[0-9]{5}$"
+        },
+        "object_type": {
+          "const": "prompt"
+        }
+      }
+    }
+  ]
+}

package/schema/reference-project.schema.json

@@ -0,0 +1,21 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://ai-design-rules.dev/schema/reference-project.schema.json",
+  "title": "Reference Project",
+  "allOf": [
+    {
+      "$ref": "./common.schema.json"
+    },
+    {
+      "type": "object",
+      "properties": {
+        "id": {
+          "pattern": "^REF-[0-9]{5}$"
+        },
+        "object_type": {
+          "const": "reference_project"
+        }
+      }
+    }
+  ]
+}

package/schema/research.schema.json

@@ -0,0 +1,21 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://ai-design-rules.dev/schema/research.schema.json",
+  "title": "Research",
+  "allOf": [
+    {
+      "$ref": "./common.schema.json"
+    },
+    {
+      "type": "object",
+      "properties": {
+        "id": {
+          "pattern": "^RESEARCH-[0-9]{5}$"
+        },
+        "object_type": {
+          "const": "research"
+        }
+      }
+    }
+  ]
+}

package/schema/review.schema.json

@@ -0,0 +1,21 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://ai-design-rules.dev/schema/review.schema.json",
+  "title": "Review",
+  "allOf": [
+    {
+      "$ref": "./common.schema.json"
+    },
+    {
+      "type": "object",
+      "properties": {
+        "id": {
+          "pattern": "^REVIEW-[0-9]{5}$"
+        },
+        "object_type": {
+          "const": "review"
+        }
+      }
+    }
+  ]
+}

package/schema/rule.schema.json

@@ -0,0 +1,21 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://ai-design-rules.dev/schema/rule.schema.json",
+  "title": "Rule",
+  "allOf": [
+    {
+      "$ref": "./common.schema.json"
+    },
+    {
+      "type": "object",
+      "properties": {
+        "id": {
+          "pattern": "^RULE-[0-9]{5}$"
+        },
+        "object_type": {
+          "const": "rule"
+        }
+      }
+    }
+  ]
+}