ai-design-context 0.4.0

package/skills/knowledge-graph-architect/SKILL.md

@@ -0,0 +1,96 @@
+---
+name: knowledge-graph-architect
+description: Maintain the AI Design Context knowledge graph. Use when changing schemas, object metadata, registries, typed relationships, generated indexes, validation scope, or DesignLint readiness.
+---
+
+# Knowledge Graph Architect Skill
+
+## Role
+
+Maintain AI Design Context as a schema-first knowledge graph.
+
+## Mission
+
+Keep objects, metadata, generated indexes, relationships, and validation behavior consistent as the repository grows.
+
+## When To Use
+
+- A change affects schemas, registry files, generated indexes, object metadata, or relationship types.
+- A contributor needs to add or migrate a knowledge object type.
+- The graph has orphans, missing targets, duplicate concepts, or stale generated files.
+- DesignLint readiness or validation scope is being changed.
+
+## When Not To Use
+
+- The task is only product UX, visual design, or accessibility review.
+- The request asks for new design advice without source research.
+- The change is a local UI implementation with no repository architecture impact.
+
+## Inputs
+
+- `docs/KNOWLEDGE_ENGINE.md`
+- `schema/*.schema.json`
+- `registry/objects.json`
+- `registry/relationships.json`
+- Generated indexes and graph report.
+- Target files or object type being changed.
+
+## Process
+
+1. Identify affected object types.
+2. Check ID, alias, slug, status, maturity, and relationship conventions.
+3. Verify relationship direction and type.
+4. Check generated indexes and graph diagnostics.
+5. Run or request `npm run check`.
+6. Flag missing schema, registry, or validation coverage.
+7. Avoid changing content meaning while fixing graph structure.
+
+## Output Format
+
+```md
+## Graph Assessment
+- Object types affected:
+- Registry impact:
+- Relationship impact:
+- Generated index impact:
+
+## Findings
+- Issue:
+- File:
+- Suggested fix:
+
+## Validation
+- Command:
+- Result:
+
+## Handoff
+- Next skill:
+- Reason:
+```
+
+## Quality Checklist
+
+- IDs are stable and globally unique.
+- Aliases and slugs are unique where required.
+- Relationship targets resolve.
+- Generated indexes are not edited manually.
+- Manual indexes are treated as transitional.
+- Validation scope is honestly documented.
+
+## Related Rules
+
+- `RULE-00003` / `IA-001` One Stable Home Surface
+- `RULE-00004` / `IA-002` Define The Object Model Before Screens
+- `RULE-00008` / `VIS-001` Semantic Tokens Only
+
+## Related Patterns
+
+- `PAT-00001` / `PAT-001` Daily Home Surface
+- `PAT-00006` / `PAT-006` Object Status List
+
+## Handoff To Other Skills
+
+- Use `prompt-architect` when prompts need graph-backed instructions.
+- Use `design-reviewer` when graph findings affect UX quality.
+- Use `product-designer` when a missing object reflects unclear product intent.
+- Use `accessibility-reviewer` when checklists or validation must cover accessibility.

package/skills/mobile-ux-expert/SKILL.md

@@ -0,0 +1,105 @@
+---
+name: mobile-ux-expert
+description: Design or review touch-first mobile product behavior. Use for reachability, capture flows, primary-action placement, mobile states, gestures, small-screen hierarchy, or context preservation.
+---
+
+# Mobile UX Expert Skill
+
+## Role
+
+Specialize in touch-first product behavior, narrow viewport ergonomics, and mobile workflow review.
+
+## Mission
+
+Ensure consumer workflows remain usable, reachable, and context-preserving on mobile screens.
+
+## When To Use
+
+- A screen or flow must work mobile-first.
+- Primary action placement, capture flow, list behavior, or sheet behavior is being designed.
+- Touch target size, thumb reach, or context preservation needs review.
+- Desktop structure may have been forced onto mobile.
+
+## When Not To Use
+
+- Product direction is still undecided.
+- The task is only token naming or visual styling.
+- The flow is desktop-only operational UI.
+
+## Inputs
+
+- Target viewport range.
+- Primary and secondary actions.
+- Current navigation and interaction model.
+- Relevant rules and patterns.
+- Constraints for keyboard, focus, loading, empty, disabled, and error states.
+
+## Process
+
+1. Identify the mobile primary action.
+2. Check action reachability and content overlap.
+3. Keep capture paths short and defer optional metadata.
+4. Check touch targets and spacing.
+5. Preserve context when opening detail, preview, filters, or settings.
+6. Define mobile behavior separately from desktop behavior.
+7. Flag desktop-only tables, hidden critical actions, and cramped controls.
+8. Hand off unresolved issues to accessibility, interaction, or design review.
+
+## Output Format
+
+```md
+## Mobile UX Assessment
+- Viewport:
+- Primary action:
+- Main risk:
+
+## Required Changes
+- Change:
+- Rule:
+- Pattern:
+
+## Mobile States
+- Empty:
+- Loading:
+- Error:
+- Disabled:
+
+## Verdict
+- PASS or NEEDS WORK:
+
+## Handoff
+- Next skill:
+- Reason:
+```
+
+## Quality Checklist
+
+- Primary action is reachable.
+- Critical controls meet touch target expectations.
+- Capture can happen before advanced organization.
+- Detail views preserve context.
+- Text and controls fit at narrow widths.
+- Loading and error states preserve orientation.
+
+## Related Rules
+
+- `RULE-00001` / `PRD-001` Daily Actions First
+- `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-00009` / `A11Y-001` 44x44 Touch Targets
+
+## 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 `product-designer` if the primary action is unclear.
+- Use `interaction-designer` for detailed gesture, sheet, or transition behavior.
+- Use `accessibility-reviewer` for focus, labels, target size, and assistive technology concerns.
+- Use `performance-reviewer` if mobile responsiveness or loading behavior is weak.

package/skills/motion-designer/SKILL.md

@@ -0,0 +1,100 @@
+---
+name: motion-designer
+description: Design or review purposeful UI motion. Use when animations affect orientation, feedback, transitions, loading, performance, or reduced-motion behavior in product interfaces.
+---
+
+# Motion Designer Skill
+
+## Role
+
+Define purposeful motion and transition behavior for product orientation.
+
+## Mission
+
+Use motion only when it clarifies continuity, preserves context, or explains state change.
+
+## When To Use
+
+- A screen opens detail, preview, sheet, or split context.
+- Users may lose orientation during navigation or state change.
+- Loading, completion, undo, or error feedback needs motion guidance.
+- Existing animation feels decorative, slow, or distracting.
+
+## When Not To Use
+
+- Motion is requested only as decoration.
+- Accessibility or performance constraints make motion unsafe.
+- The interaction model is not defined.
+
+## Inputs
+
+- Interaction flow and affected surfaces.
+- State transitions and user goal.
+- Performance and reduced-motion constraints.
+- Related rules and patterns.
+
+## Process
+
+1. Identify what orientation problem motion must solve.
+2. Define start state, end state, and preserved context.
+3. Select or define a reusable motion role with inspectable timing and easing.
+4. Keep duration short and purpose clear.
+5. Provide reduced-motion and unsupported-platform behavior.
+6. Avoid hiding loading, errors, or state changes behind animation.
+7. Hand off performance and accessibility checks.
+
+## Output Format
+
+```md
+## Motion Decision
+- Transition:
+- Purpose:
+- Start state:
+- End state:
+- Motion role:
+- Timing and easing:
+- Reduced motion:
+- Platform fallback:
+
+## Risks
+- Accessibility:
+- Performance:
+
+## Related Rules And Patterns
+- Rule:
+- Pattern:
+
+## Handoff
+- Next skill:
+- Reason:
+```
+
+## Quality Checklist
+
+- Motion explains a spatial or state relationship.
+- Motion does not delay the primary action.
+- Reduced-motion behavior is defined.
+- Loading and error states remain clear.
+- Motion supports context preservation.
+- Repeated transitions use consistent named roles.
+- Unsupported APIs have a progressive fallback.
+
+## Related Rules
+
+- `RULE-00006` / `UX-002` Progressively Disclose Power
+- `RULE-00007` / `UX-003` Preserve Context During Inspection
+- `RULE-00009` / `A11Y-001` 44x44 Touch Targets
+- `RULE-00013` / `A11Y-004` Reduce Non-Essential Interaction Motion
+- `RULE-00015` / `UX-004` Use Motion To Explain State Continuity
+
+## Related Patterns
+
+- `PAT-00004` / `PAT-004` Progressive Detail
+- `PAT-00005` / `PAT-005` Context-Preserving Preview
+
+## Handoff To Other Skills
+
+- Use `interaction-designer` if flow mechanics are undefined.
+- Use `accessibility-reviewer` for reduced-motion and focus concerns.
+- Use `performance-reviewer` for animation cost and responsiveness.
+- Use `design-reviewer` for final quality gate.

package/skills/performance-reviewer/SKILL.md

@@ -0,0 +1,97 @@
+---
+name: performance-reviewer
+description: Review perceived performance in product UI. Use for loading, optimistic updates, responsiveness, layout stability, rendering risks, network delay, animations, or performance-related recovery states.
+---
+
+# Performance Reviewer Skill
+
+## Role
+
+Review perceived performance, loading behavior, responsiveness, and rendering risk in product UI.
+
+## Mission
+
+Keep product workflows fast enough that users can act, recover, and stay oriented without waiting through avoidable UI delay.
+
+## When To Use
+
+- Loading, optimistic updates, list rendering, animation, or network delay affects UX.
+- A product surface feels slow or unstable.
+- Generated UI introduces heavy visuals, layout shifts, or blocking states.
+- A review needs performance risk called out before release.
+
+## When Not To Use
+
+- The task is purely backend performance without user-facing UI.
+- The workflow and interaction model are not defined.
+- The request is only visual polish.
+
+## Inputs
+
+- User action and expected feedback time.
+- Loading, empty, error, and optimistic states.
+- Device and network constraints.
+- UI implementation details when available.
+
+## Process
+
+1. Identify latency-sensitive actions.
+2. Check whether feedback appears immediately.
+3. Check whether loading preserves layout and context.
+4. Flag expensive animation, media, rendering, and list behavior.
+5. Ensure errors are recoverable without losing input.
+6. Recommend measurement or implementation checks when needed.
+7. Hand off motion, interaction, or review issues.
+
+## Output Format
+
+```md
+## Performance UX Review
+- Latency-sensitive action:
+- Main risk:
+- Verdict:
+
+## Findings
+- Issue:
+- User impact:
+- Suggested fix:
+
+## State Behavior
+- Loading:
+- Optimistic:
+- Error:
+
+## Handoff
+- Next skill:
+- Reason:
+```
+
+## Quality Checklist
+
+- Primary action gets immediate feedback.
+- Loading avoids layout jumps.
+- Long work does not block unrelated actions.
+- Error recovery preserves user input.
+- Motion and media do not harm responsiveness.
+- Findings distinguish UX risk from implementation detail.
+
+## Related Rules
+
+- `RULE-00001` / `PRD-001` Daily Actions First
+- `RULE-00002` / `PRD-002` Low-Friction Capture Before Organization
+- `RULE-00007` / `UX-003` Preserve Context During Inspection
+- `RULE-00011` / `PERF-001` Reserve Layout Space For Asynchronous Content
+
+## Related Patterns
+
+- `PAT-00001` / `PAT-001` Daily Home Surface
+- `PAT-00002` / `PAT-002` Quick Capture
+- `PAT-00005` / `PAT-005` Context-Preserving Preview
+- `PAT-00006` / `PAT-006` Object Status List
+
+## Handoff To Other Skills
+
+- Use `interaction-designer` if feedback or recovery flow is unclear.
+- Use `motion-designer` if animation affects responsiveness.
+- Use `mobile-ux-expert` if mobile rendering or reachability is affected.
+- Use `design-reviewer` for final release review.

package/skills/product-designer/SKILL.md

@@ -0,0 +1,104 @@
+---
+name: product-designer
+description: Frame product direction for consumer workflows. Use when a feature needs a user goal, primary action, core object model, state coverage, or research-backed pattern selection before UI design.
+---
+
+# Product Designer Skill
+
+## Role
+
+Lead product direction for consumer workflows before interface structure or visual treatment is chosen.
+
+## Mission
+
+Turn user goals, product context, and research-backed rules into a focused workflow direction that agents can implement or review.
+
+## When To Use
+
+- A feature needs product framing before UX or UI work.
+- The primary user action is unclear.
+- A reference project flow needs scope, states, and pattern selection.
+- An agent must decide which existing rules and patterns apply.
+
+## When Not To Use
+
+- The task is only visual polish, token cleanup, code refactoring, or CI.
+- The product direction is already approved and the task is review-only.
+- The request requires inventing a new rule or pattern.
+
+## Inputs
+
+- Product goal, target user, and user context.
+- Existing screen, brief, issue, prototype, or code context.
+- Relevant research and generated indexes.
+- Constraints: platform, viewport, data model, privacy, latency, empty state, loading state, and error state.
+
+## Process
+
+1. State the user goal in one sentence.
+2. Identify the primary repeated action.
+3. Name the core product object before naming screens.
+4. Select only directly relevant rules.
+5. Select patterns that compose those rules.
+6. Define default, empty, loading, and error behavior.
+7. Identify missing upstream knowledge instead of inventing guidance.
+8. Hand off to UX, IA, mobile, or review skills as needed.
+
+## Output Format
+
+```md
+## Product Direction
+- User goal:
+- Primary action:
+- Core object:
+- Screen priority:
+
+## Applied Rules
+- RULE-ID / Alias - reason
+
+## Applied Patterns
+- PAT-ID / Alias - reason
+
+## States
+- Empty:
+- Loading:
+- Error:
+
+## Gaps
+- Missing evidence, rule, or pattern:
+
+## Handoff
+- Next skill:
+- Reason:
+```
+
+## Quality Checklist
+
+- User intent is explicit.
+- Primary action is clear and low friction.
+- Object model is named before layout.
+- Pattern selection is traceable to existing rules.
+- State behavior is included.
+- No new rule or pattern is invented.
+
+## 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-00006` / `UX-002` Progressively Disclose Power
+
+## Related Patterns
+
+- `PAT-00001` / `PAT-001` Daily Home Surface
+- `PAT-00002` / `PAT-002` Quick Capture
+- `PAT-00004` / `PAT-004` Progressive Detail
+- `PAT-00006` / `PAT-006` Object Status List
+
+## Handoff To Other Skills
+
+- Use `information-architect` after the product object model is known.
+- Use `interaction-designer` when flow mechanics or state transitions need definition.
+- Use `mobile-ux-expert` for touch-first layout and primary action placement.
+- Use `design-reviewer` after a proposal, prototype, or implementation exists.

package/skills/prompt-architect/SKILL.md

@@ -0,0 +1,105 @@
+---
+name: prompt-architect
+description: Create or review graph-backed prompts for design agents. Use when prompts need explicit rules, patterns, output contracts, scope constraints, review expectations, or traceable knowledge references.
+---
+
+# Prompt Architect Skill
+
+## Role
+
+Design and review prompts that apply existing AI Design Context knowledge without inventing new design advice.
+
+## Mission
+
+Turn rules, patterns, reference projects, and review expectations into agent instructions that are specific, traceable, and safe to execute.
+
+## When To Use
+
+- A prompt needs to guide agents through product design or review.
+- A prompt must reference existing rules and patterns.
+- Prompt output is vague, too broad, or disconnected from the graph.
+- A reference project prompt needs maintenance.
+
+## When Not To Use
+
+- A new rule, pattern, or research object is needed first.
+- The task is direct UI implementation.
+- The request is only final design QA.
+
+## Inputs
+
+- Target task and agent audience.
+- Required rules and patterns.
+- Reference project context if applicable.
+- Evidence-backed visual direction or agent lifecycle requirements when applicable.
+- Known constraints and expected output format.
+
+## Process
+
+1. Define the prompt objective.
+2. List required rules and patterns by ID.
+3. State what the agent must not invent.
+4. Define input requirements.
+5. Require source or artifact evidence for visual-reference claims.
+6. Define output format, states, responsive assumptions, and review criteria.
+7. Add traceability expectations and explicit knowledge gaps.
+8. Hand off to design review or knowledge graph review.
+
+## Output Format
+
+```md
+## Prompt Architecture
+- Objective:
+- Agent audience:
+- Required inputs:
+
+## Required Knowledge
+- Rules:
+- Patterns:
+- Reference project:
+- Reference evidence:
+
+## Output Contract
+- Sections:
+- Validation:
+- Forbidden output:
+- Evidence gaps:
+
+## Handoff
+- Next skill:
+- Reason:
+```
+
+## Quality Checklist
+
+- Prompt has one clear job.
+- Prompt references existing rules and patterns.
+- Prompt tells agents what not to invent.
+- Output format is explicit.
+- Review criteria are included.
+- Reference project usage is traceable.
+- Visual direction and agentic lifecycle claims are grounded in applicable research and rules.
+
+## 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-00006` / `UX-002` Progressively Disclose Power
+
+## 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
+
+## Handoff To Other Skills
+
+- Use `product-designer` to clarify product intent before prompt writing.
+- Use `design-reviewer` to test prompt output quality.
+- Use `knowledge-graph-architect` to validate metadata and relationships.
+- Use `accessibility-reviewer` if prompt output includes UI review obligations.