ai-design-context 0.4.0

package/skills/README.md

@@ -0,0 +1,48 @@
+# Skills
+
+AI Design Context skills are reusable Codex agent workflows. Every `skills/*/SKILL.md` has standalone Codex metadata (`name` and a trigger-rich `description`) in addition to its workflow body.
+
+They are not design rules, patterns, prompts, or registry objects yet. Knowledge-graph registry migration is deferred until explicitly requested.
+
+Use skills as an agent design team:
+
+| Skill | Responsibility |
+| --- | --- |
+| `product-designer` | Product goal, primary action, object model, and pattern selection. |
+| `ux-reviewer` | Journey clarity, usability, state coverage, and user friction. |
+| `information-architect` | Object model, navigation, hierarchy, labels, and status language. |
+| `mobile-ux-expert` | Touch-first mobile behavior, primary actions, and context preservation. |
+| `interaction-designer` | Flow mechanics, feedback, recovery, previews, and state transitions. |
+| `design-system-architect` | Semantic tokens, reusable states, and pattern/component boundaries. |
+| `visual-designer` | Visual hierarchy, spacing, typography, color meaning, and polish. |
+| `reference-driven-design` | Evidence-backed reference selection and abstract visual direction without brand copying. |
+| `motion-designer` | Purposeful motion that preserves orientation and respects reduced motion. |
+| `accessibility-reviewer` | Labels, focus, target size, contrast, errors, and reduced motion. |
+| `performance-reviewer` | Perceived performance, loading behavior, responsiveness, and layout stability. |
+| `design-reviewer` | Final design QA and rule/pattern traceability review. |
+| `design-evidence-researcher` | Evidence intake, observations, research synthesis, and knowledge-gap identification. |
+| `agent-context` | Read-only graph context retrieval for an implementation or review target. |
+| `prompt-architect` | Graph-backed prompt structure and output contracts. |
+| `knowledge-graph-architect` | Schema, registry, generated indexes, relationships, and validation scope. |
+
+## Routing
+
+Start with `product-designer` when product intent is unclear.
+
+Use `agent-context` first when the task needs a focused subset of graph objects before routing to a specialist skill.
+
+Use `design-evidence-researcher` before adding a rule, pattern, prompt, or skill when upstream evidence is missing.
+
+Use `reference-driven-design` before visual exploration or polish when the interface needs a modern, premium, expressive, or product-specific direction.
+
+Use `information-architect` before screen layout when object structure is unclear.
+
+Use `mobile-ux-expert`, `interaction-designer`, `visual-designer`, `motion-designer`, `accessibility-reviewer`, and `performance-reviewer` for focused specialist review.
+
+Use `design-system-architect` when reusable UI decisions, tokens, or component boundaries are involved.
+
+Use `prompt-architect` when writing or reviewing agent prompts.
+
+Use `knowledge-graph-architect` when schemas, registry records, generated indexes, or validation behavior are affected.
+
+Use `design-reviewer` as the final quality gate.

package/skills/accessibility-reviewer/SKILL.md

@@ -0,0 +1,101 @@
+---
+name: accessibility-reviewer
+description: Review accessibility of product UI and interaction states. Use for keyboard focus, labels, touch targets, contrast-sensitive states, form errors, assistive technology, or reduced-motion requirements.
+---
+
+# Accessibility Reviewer Skill
+
+## Role
+
+Review accessibility requirements for product workflows and UI states.
+
+## Mission
+
+Ensure AI-generated designs remain usable with keyboard, assistive technology, readable contrast, clear labels, and sufficient touch targets.
+
+## When To Use
+
+- A flow includes forms, buttons, lists, dialogs, previews, sheets, or status changes.
+- Touch target size, labels, focus order, or contrast need review.
+- Error, disabled, loading, or empty states affect task completion.
+- Motion or dense layouts may reduce accessibility.
+
+## When Not To Use
+
+- The product workflow is not defined.
+- The task is only schema or registry maintenance.
+- The request asks for legal compliance certification.
+
+## Inputs
+
+- Screen or component behavior.
+- Interaction model and states.
+- Target platforms and viewport range.
+- Relevant rules and patterns.
+
+## Process
+
+1. Identify interactive elements and required labels.
+2. Check touch target size and spacing.
+3. Check keyboard path and focus visibility.
+4. Check contrast-sensitive states and semantic status.
+5. Check error recovery and preserved input.
+6. Check reduced-motion needs when motion exists.
+7. Hand off visual, interaction, mobile, or performance issues.
+
+## Output Format
+
+```md
+## Accessibility Review
+- Verdict:
+- Main risk:
+
+## Findings
+- Issue:
+- Impact:
+- Rule or pattern:
+- Suggested fix:
+
+## State Coverage
+- Focus:
+- Error:
+- Disabled:
+- Reduced motion:
+
+## Handoff
+- Next skill:
+- Reason:
+```
+
+## Quality Checklist
+
+- Controls have accessible names.
+- Focus order follows visual and task order.
+- Touch targets are large enough.
+- Contrast-sensitive states are not color-only.
+- Errors preserve input and explain recovery.
+- Motion has a reduced-motion alternative.
+
+## Related Rules
+
+- `RULE-00005` / `UX-001` Thumb-Zone Primary Actions
+- `RULE-00007` / `UX-003` Preserve Context During Inspection
+- `RULE-00008` / `VIS-001` Semantic Tokens Only
+- `RULE-00009` / `A11Y-001` 44x44 Touch Targets
+- `RULE-00010` / `A11Y-002` Textual Input Error Recovery
+- `RULE-00012` / `A11Y-003` Visible Keyboard Focus
+- `RULE-00013` / `A11Y-004` Reduce Non-Essential Interaction Motion
+
+## Related Patterns
+
+- `PAT-00002` / `PAT-002` Quick Capture
+- `PAT-00003` / `PAT-003` Mobile Primary Action
+- `PAT-00005` / `PAT-005` Context-Preserving Preview
+- `PAT-00006` / `PAT-006` Object Status List
+
+## Handoff To Other Skills
+
+- Use `mobile-ux-expert` if touch layout needs restructuring.
+- Use `visual-designer` if contrast or hierarchy needs design changes.
+- Use `interaction-designer` if keyboard or recovery flow is unclear.
+- Use `design-reviewer` after accessibility fixes are applied.

package/skills/agent-context/SKILL.md

@@ -0,0 +1,34 @@
+---
+name: agent-context
+description: Retrieve concise, graph-backed design context from AI Design Context with the local CLI. Use before implementing or reviewing a user-facing flow, reference fixture, prompt output, or known knowledge object when an agent needs relevant research, rules, patterns, checklists, and evidence limits without reading every index.
+---
+
+# Agent Context
+
+Run this skill before a user-facing implementation or review when the applicable knowledge is not already explicit.
+
+## Workflow
+
+1. In a product repository with the npm package installed, verify `npx --no-install ai-design-context context --help`. In the knowledge-source checkout, use `npm run context -- --help`.
+2. Resolve the task, review target, or stable object:
+
+   ```bash
+   npm run context -- --task quick-capture --platform mobile --intent implement --format json
+   npm run context -- --review examples/todo-reference --intent qa
+   npm run context -- --object PAT-00002 --format json
+   ```
+
+   For the installed npm package, replace `npm run context --` with `npx --no-install ai-design-context context` in these examples. Markdown provides absolute reading paths; JSON adds `absolutePath` while retaining relative graph `path`.
+
+3. Read the selected files before proposing product guidance or code.
+4. Apply only the returned rules and patterns that fit the task.
+5. Preserve every returned evidence boundary; `draft` and `seed` do not justify broad product claims.
+6. If the resolver returns no match, create an observation or research need rather than inventing a rule.
+7. Inspect each object's selection reason. Required dependencies are complete, while optional links in broad review gates must be followed explicitly when the review needs them.
+
+## Boundaries
+
+- The CLI is read-only and does not replace `npm run check`.
+- `--platform` adds relevant context; it does not prove that a pattern applies.
+- Use `--format json` for another agent or script; errors are machine-readable on stderr.
+- Task matching is lexical. Simple English task wrappers are supported; arbitrary paraphrases and translation are not. Prefer an exact known slug or ID when available.

package/skills/agent-context/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Agent Context"
+  short_description: "Resolve concise graph context for an implementation or review."
+  default_prompt: "Use the agent context CLI to gather graph-backed guidance for this task."

package/skills/design-evidence-researcher/SKILL.md

@@ -0,0 +1,47 @@
+---
+name: design-evidence-researcher
+description: Collect primary-source and product-behavior evidence for AI Design Context. Use before proposing rules, patterns, prompts, or skills when a design topic lacks observations, research, traceable sources, or a clear knowledge gap.
+---
+
+# Design Evidence Researcher
+
+## Mission
+
+Turn verifiable external sources, product behavior, and review findings into traceable observations and research. Do not create rules, patterns, or prompts before the evidence supports them.
+
+## Inputs
+
+- The design question or suspected knowledge gap.
+- Product, platform, and affected workflow.
+- Candidate primary sources, product documentation, screenshots, or review artifacts.
+- Existing generated indexes and nearby knowledge objects.
+
+## Workflow
+
+1. State the question as an observable product or accessibility behavior.
+2. Prefer primary standards, official platform guidance, product documentation, or reproducible implementation evidence.
+3. Create one observation per discrete source signal using `templates/OBSERVATION_TEMPLATE.md`.
+4. Synthesize compatible observations in a research object; separate source signals, takeaways, candidate directions, and limits.
+5. Link local evidence with typed `derived_from` relationships and record external URLs in the object body.
+6. Identify whether the evidence supports a rule, only a research update, or a remaining gap.
+7. Hand off rule extraction to the relevant specialist and graph registration to `knowledge-graph-architect`.
+
+## Output Contract
+
+```md
+## Evidence Brief
+- Question:
+- Sources checked:
+- Observations created:
+- Research updated or created:
+- Candidate rule directions:
+- Limits and conflicts:
+- Recommended handoff:
+```
+
+## Guardrails
+
+- Do not treat a single product preference as a universal rule.
+- Do not invent sources, benchmark results, or implementation evidence.
+- Do not promote seed evidence to validated or canonical maturity.
+- Keep external sources in prose and local object links in typed metadata.

package/skills/design-evidence-researcher/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Design Evidence Researcher"
+  short_description: "Turn source evidence into design knowledge"
+  default_prompt: "Use $design-evidence-researcher to turn these sources into observations and research."

package/skills/design-reviewer/SKILL.md

@@ -0,0 +1,113 @@
+---
+name: design-reviewer
+description: Run final design QA for product proposals, prototypes, or implemented UI. Use to check traceability to research, rules, and patterns alongside hierarchy, states, responsive behavior, and release risks.
+---
+
+# Design Reviewer Skill
+
+## Role
+
+Act as the final design quality gate for AI-generated product UI and UX changes.
+
+## Mission
+
+Evaluate whether a proposal or implementation follows registered research, rules, patterns, and accessibility expectations before it ships.
+
+## When To Use
+
+- A screen, prototype, prompt output, or pull request needs design QA.
+- An agent must prove design decisions are traceable.
+- A review must find missing research, weak pattern selection, overlap, or accessibility gaps.
+- A reference project needs validation against AI Design Context.
+
+## When Not To Use
+
+- The task is initial product direction.
+- The task has no user-facing behavior.
+- The request asks to create new rules or patterns.
+
+## Inputs
+
+- Screen, workflow, diff, prompt output, or reference project.
+- Claimed rules and patterns.
+- Generated indexes.
+- Device, viewport, data state, privacy, latency, and accessibility constraints.
+
+## Process
+
+1. Identify the user goal and primary action.
+2. Check whether claimed rules apply.
+3. Check whether selected patterns match their purpose and boundaries.
+4. Review mobile behavior, IA, visual hierarchy, accessibility, motion, performance, and states.
+5. Identify missing upstream evidence instead of inventing guidance.
+6. Produce severity-ordered findings.
+7. Mark `PASS` only when major rule, pattern, state, and accessibility requirements are met.
+8. Hand off specific issues to specialist skills.
+
+## Output Format
+
+```md
+## Verdict
+PASS or NEEDS WORK
+
+## Findings
+- Severity:
+- File or screen:
+- Issue:
+- Rule or pattern:
+- Suggested patch:
+
+## Coverage
+- Rules checked:
+- Patterns checked:
+- Missing evidence:
+
+## Handoff
+- Next skill:
+- Reason:
+```
+
+## Quality Checklist
+
+- Findings are specific and actionable.
+- Every finding names a rule, pattern, or missing layer.
+- Review covers mobile, accessibility, state behavior, and traceability.
+- PASS means another agent can follow the reasoning.
+- NEEDS WORK lists exact files or surfaces to fix.
+
+## Related Rules
+
+- `RULE-00001` / `PRD-001` Daily Actions First
+- `RULE-00002` / `PRD-002` Low-Friction Capture Before Organization
+- `RULE-00003` / `IA-001` One Stable Home Surface
+- `RULE-00004` / `IA-002` Define The Object Model Before Screens
+- `RULE-00005` / `UX-001` Thumb-Zone Primary Actions
+- `RULE-00006` / `UX-002` Progressively Disclose Power
+- `RULE-00007` / `UX-003` Preserve Context During Inspection
+- `RULE-00008` / `VIS-001` Semantic Tokens Only
+- `RULE-00009` / `A11Y-001` 44x44 Touch Targets
+- `RULE-00010` / `A11Y-002` Textual Error Recovery
+- `RULE-00011` / `PERF-001` Reserve Space For Async Content
+- `RULE-00012` / `A11Y-003` Visible Keyboard Focus
+- `RULE-00013` / `A11Y-004` Reduce Non-Essential Interaction Motion
+
+## Related Patterns
+
+- `PAT-00001` / `PAT-001` Daily Home Surface
+- `PAT-00002` / `PAT-002` Quick Capture
+- `PAT-00003` / `PAT-003` Mobile Primary Action
+- `PAT-00004` / `PAT-004` Progressive Detail
+- `PAT-00005` / `PAT-005` Context-Preserving Preview
+- `PAT-00006` / `PAT-006` Object Status List
+
+## Related Checklist And Prompt
+
+- `CHECK-00001` / `CHECK-DESIGN-QA` Design QA Checklist
+- `PROMPT-00005` / `PROMPT-DESIGN-EVIDENCE-REVIEW` Design Evidence Review Prompt
+
+## Handoff To Other Skills
+
+- Use `ux-reviewer` for journey and usability issues.
+- Use `accessibility-reviewer` for accessibility failures.
+- Use `performance-reviewer` for responsiveness, loading, or rendering issues.
+- Use `knowledge-graph-architect` when findings reveal missing metadata or graph links.

package/skills/design-system-architect/SKILL.md

@@ -0,0 +1,101 @@
+---
+name: design-system-architect
+description: Define or review reusable UI tokens, components, and state behavior. Use when a task affects semantic tokens, component boundaries, design-system consistency, or cross-screen UI reuse.
+---
+
+# Design System Architect Skill
+
+## Role
+
+Define reusable product-specific UI decisions without turning AI Design Context into a UI kit.
+
+## Mission
+
+Keep tokens, states, reusable structures, and component boundaries connected to existing rules and patterns.
+
+## When To Use
+
+- A task affects tokens, semantic colors, spacing, component states, or reusable UI structure.
+- Repeated UI decisions need normalized naming.
+- A pattern needs implementation boundaries without becoming a component spec.
+- Visual or interaction drift appears across surfaces.
+
+## When Not To Use
+
+- Product strategy is unresolved.
+- The request is to add a generic component library or Tailwind preset.
+- The task is only final visual QA.
+
+## Inputs
+
+- Existing tokens, theme files, component conventions, and state styles.
+- Selected rules and patterns.
+- Product surfaces where the reusable decision appears.
+- Accessibility and state constraints.
+
+## Process
+
+1. Identify the repeated decision.
+2. Map it to existing rules and patterns.
+3. Prefer semantic tokens over one-off values.
+4. Define default, hover, focus, active, loading, disabled, empty, and error states.
+5. Separate pattern ownership from component implementation.
+6. Keep naming tied to product meaning.
+7. Flag missing knowledge instead of creating unsupported standards.
+8. Hand off to visual, accessibility, or review skills for validation.
+
+## Output Format
+
+```md
+## System Decision
+- Repeated decision:
+- Product meaning:
+- Existing owner:
+
+## Token And State Guidance
+- Semantic token:
+- States:
+- Accessibility constraint:
+
+## Applied Rules
+- RULE-ID / Alias - reason
+
+## Applied Patterns
+- PAT-ID / Alias - reason
+
+## Boundary
+- Pattern owns:
+- Component owns:
+
+## Handoff
+- Next skill:
+- Reason:
+```
+
+## Quality Checklist
+
+- Tokens describe meaning, not arbitrary appearance.
+- Reusable behavior maps to existing rules or patterns.
+- Component boundaries do not duplicate pattern ownership.
+- Accessibility states are included before polish.
+- No UI kit or generic design system is invented.
+
+## Related Rules
+
+- `RULE-00004` / `IA-002` Define The Object Model Before Screens
+- `RULE-00006` / `UX-002` Progressively Disclose Power
+- `RULE-00008` / `VIS-001` Semantic Tokens Only
+- `RULE-00009` / `A11Y-001` 44x44 Touch Targets
+
+## Related Patterns
+
+- `PAT-00004` / `PAT-004` Progressive Detail
+- `PAT-00005` / `PAT-005` Context-Preserving Preview
+- `PAT-00006` / `PAT-006` Object Status List
+
+## Handoff To Other Skills
+
+- Use `visual-designer` for hierarchy, color, typography, and polish.
+- Use `accessibility-reviewer` for contrast, focus, labels, and target size.
+- Use `interaction-designer` when reusable states affect flow behavior.
+- Use `design-reviewer` for final rule and pattern coverage.

package/skills/information-architect/SKILL.md

@@ -0,0 +1,97 @@
+---
+name: information-architect
+description: Shape product object models, navigation, hierarchy, labels, and status language. Use before screen layout when users, content relationships, wayfinding, or information structure are unclear.
+---
+
+# Information Architect Skill
+
+## Role
+
+Define product objects, navigation structure, labels, hierarchy, and view relationships.
+
+## Mission
+
+Make the product understandable by grounding screens in a stable object model and clear information architecture.
+
+## When To Use
+
+- A product has multiple object types, views, modes, lists, or filters.
+- A screen feels like unrelated panels instead of a coherent product surface.
+- Navigation labels, object names, or status concepts are unclear.
+- A reference project needs its domain model clarified.
+
+## When Not To Use
+
+- The task is only mobile reachability or visual polish.
+- The product goal is still unknown.
+- The request is to create a component API.
+
+## Inputs
+
+- Product goal and user tasks.
+- Existing data model, screens, routes, navigation, and labels.
+- Rules and patterns related to IA and status.
+- Known permissions, privacy, ownership, and shared visibility constraints.
+
+## Process
+
+1. Name the core product objects.
+2. Define object relationships and ownership.
+3. Identify the stable home surface.
+4. Separate views from duplicated data.
+5. Define status, priority, ownership, and grouping language.
+6. Check whether patterns depend on a clear object model.
+7. Flag ambiguous labels or hidden hierarchy.
+8. Hand off interaction, visual, or product gaps.
+
+## Output Format
+
+```md
+## IA Model
+- Core objects:
+- Relationships:
+- Home surface:
+- Views:
+
+## Navigation And Labels
+- Primary sections:
+- Status language:
+- Ambiguous terms:
+
+## Applied Rules And Patterns
+- Rule:
+- Pattern:
+
+## Handoff
+- Next skill:
+- Reason:
+```
+
+## Quality Checklist
+
+- Core objects are named before screens.
+- Views do not duplicate underlying data.
+- Home surface is stable.
+- Status and ownership labels are concrete.
+- Navigation supports return speed.
+- IA choices cite existing rules or patterns.
+
+## Related Rules
+
+- `RULE-00003` / `IA-001` One Stable Home Surface
+- `RULE-00004` / `IA-002` Define The Object Model Before Screens
+- `RULE-00007` / `UX-003` Preserve Context During Inspection
+- `RULE-00008` / `VIS-001` Semantic Tokens Only
+
+## Related Patterns
+
+- `PAT-00001` / `PAT-001` Daily Home Surface
+- `PAT-00005` / `PAT-005` Context-Preserving Preview
+- `PAT-00006` / `PAT-006` Object Status List
+
+## Handoff To Other Skills
+
+- Use `product-designer` if the product object is not tied to a user goal.
+- Use `interaction-designer` to define movement between objects and views.
+- Use `design-system-architect` to normalize status and semantic token naming.
+- Use `design-reviewer` to validate traceability.

package/skills/interaction-designer/SKILL.md

@@ -0,0 +1,104 @@
+---
+name: interaction-designer
+description: Design and review interaction mechanics for product flows. Use for feedback, state transitions, recovery, previews, confirmations, loading behavior, and context-preserving interactions.
+---
+
+# Interaction Designer Skill
+
+## Role
+
+Design concrete interaction flows, transitions, input behavior, and state changes.
+
+## Mission
+
+Make actions feel direct, recoverable, and context-preserving without adding unsupported visual novelty.
+
+## When To Use
+
+- A flow needs step-by-step behavior.
+- Capture, edit, preview, completion, or undo behavior is unclear.
+- A sheet, modal, detail view, or split surface needs interaction rules.
+- State transitions affect user trust or orientation.
+
+## When Not To Use
+
+- The product object model is unknown.
+- The task is only visual hierarchy.
+- The request is purely accessibility or performance review.
+
+## Inputs
+
+- User goal and primary action.
+- Object model and navigation context.
+- Selected rules and patterns.
+- State requirements: empty, loading, error, success, disabled, optimistic, and undo.
+- Agent lifecycle requirements when work is delegated, long-running, or interruptible.
+
+## Process
+
+1. Map entry, action, feedback, recovery, and exit.
+2. Define what stays visible during interaction.
+3. Keep required input minimal.
+4. Define optimistic, loading, error, and undo behavior.
+5. Preserve context during preview and detail inspection.
+6. Avoid transitions that hide state or create mode confusion.
+7. For agentic work, define visible status, result, intervention, cancellation, and retry behavior outside transient chat.
+8. Hand off mobile, motion, accessibility, or performance concerns.
+
+## Output Format
+
+```md
+## Interaction Flow
+- Entry:
+- Primary action:
+- Feedback:
+- Recovery:
+- Exit:
+
+## State Behavior
+- Loading:
+- Error:
+- Undo:
+- Disabled:
+- Agent status and intervention:
+
+## Applied Rules And Patterns
+- Rule:
+- Pattern:
+
+## Handoff
+- Next skill:
+- Reason:
+```
+
+## Quality Checklist
+
+- Action feedback is immediate and quiet.
+- Required input is minimal.
+- Recovery path is clear.
+- Context remains visible where possible.
+- State changes do not create layout jumps.
+- Interaction choices map to existing rules and patterns.
+- Delegated work remains observable and recoverable when agentic behavior applies.
+
+## Related Rules
+
+- `RULE-00002` / `PRD-002` Low-Friction Capture Before Organization
+- `RULE-00005` / `UX-001` Thumb-Zone Primary Actions
+- `RULE-00006` / `UX-002` Progressively Disclose Power
+- `RULE-00007` / `UX-003` Preserve Context During Inspection
+- `RULE-00016` / `UX-005` Expose Agent Work And Intervention
+
+## Related Patterns
+
+- `PAT-00002` / `PAT-002` Quick Capture
+- `PAT-00003` / `PAT-003` Mobile Primary Action
+- `PAT-00004` / `PAT-004` Progressive Detail
+- `PAT-00005` / `PAT-005` Context-Preserving Preview
+
+## Handoff To Other Skills
+
+- Use `motion-designer` when movement must preserve orientation.
+- Use `mobile-ux-expert` for touch reach and narrow viewport behavior.
+- Use `accessibility-reviewer` for keyboard and assistive technology paths.
+- Use `performance-reviewer` when latency affects feedback.