ai-design-context 0.4.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (288) hide show
  1. package/AGENTS.md +156 -0
  2. package/CHANGELOG.md +71 -0
  3. package/CODE_OF_CONDUCT.md +29 -0
  4. package/CONTRIBUTING.md +128 -0
  5. package/LICENSE +21 -0
  6. package/README.md +283 -0
  7. package/RELEASE_NOTES_v0.1.0.md +45 -0
  8. package/RELEASE_NOTES_v0.3.0.md +47 -0
  9. package/RELEASE_NOTES_v0.4.0.md +29 -0
  10. package/RELEASE_READINESS.md +107 -0
  11. package/ROADMAP.md +60 -0
  12. package/SECURITY.md +40 -0
  13. package/assets/logo.svg +9 -0
  14. package/benchmarks/README.md +19 -0
  15. package/benchmarks/chat.md +37 -0
  16. package/benchmarks/mobile-home-screen.md +38 -0
  17. package/benchmarks/notes-app.md +37 -0
  18. package/benchmarks/settings.md +37 -0
  19. package/benchmarks/shopping-list.md +37 -0
  20. package/benchmarks/todo-app.md +144 -0
  21. package/checklists/DESIGN_QA.md +102 -0
  22. package/checklists/GENERATED_INDEX.md +7 -0
  23. package/docs/AGENT_CONTEXT.md +111 -0
  24. package/docs/BENCHMARK.md +170 -0
  25. package/docs/DESIGNLINT_READINESS.md +110 -0
  26. package/docs/DESIGN_SYSTEM.md +23 -0
  27. package/docs/EVALUATION_RUBRIC.md +154 -0
  28. package/docs/GITHUB_SETUP.md +28 -0
  29. package/docs/GLOSSARY.md +45 -0
  30. package/docs/INDEX.md +109 -0
  31. package/docs/KNOWLEDGE_ENGINE.md +594 -0
  32. package/docs/MOBILE_FIRST.md +18 -0
  33. package/docs/NPM_RELEASE.md +43 -0
  34. package/docs/PATTERN_SPEC.md +113 -0
  35. package/docs/PHILOSOPHY.md +25 -0
  36. package/docs/PRODUCT_THINKING.md +26 -0
  37. package/docs/STYLE_GUIDE.md +49 -0
  38. package/docs/TRACEABILITY.md +45 -0
  39. package/evidence/README.md +64 -0
  40. package/evidence/TEMPLATE.md +46 -0
  41. package/evidence/chat/.gitkeep +1 -0
  42. package/evidence/mobile-home/.gitkeep +1 -0
  43. package/evidence/notes/.gitkeep +1 -0
  44. package/evidence/settings/.gitkeep +1 -0
  45. package/evidence/shopping/.gitkeep +1 -0
  46. package/evidence/todo/.gitkeep +1 -0
  47. package/evidence/todo/2026-06-25-codex-gpt-5/EVALUATION.md +66 -0
  48. package/evidence/todo/2026-06-25-codex-gpt-5/README.md +40 -0
  49. package/evidence/todo/2026-06-25-codex-gpt-5/ai-design-rules/generated-output.md +163 -0
  50. package/evidence/todo/2026-06-25-codex-gpt-5/ai-design-rules/metadata.json +38 -0
  51. package/evidence/todo/2026-06-25-codex-gpt-5/ai-design-rules/notes.md +20 -0
  52. package/evidence/todo/2026-06-25-codex-gpt-5/ai-design-rules/prompt.md +16 -0
  53. package/evidence/todo/2026-06-25-codex-gpt-5/ai-design-rules/scores.md +18 -0
  54. package/evidence/todo/2026-06-25-codex-gpt-5/baseline/generated-output.md +98 -0
  55. package/evidence/todo/2026-06-25-codex-gpt-5/baseline/metadata.json +19 -0
  56. package/evidence/todo/2026-06-25-codex-gpt-5/baseline/notes.md +19 -0
  57. package/evidence/todo/2026-06-25-codex-gpt-5/baseline/prompt.md +9 -0
  58. package/evidence/todo/2026-06-25-codex-gpt-5/baseline/scores.md +18 -0
  59. package/evidence/todo/2026-09-28-codex-paired-todo/EVALUATION.md +70 -0
  60. package/evidence/todo/2026-09-28-codex-paired-todo/README.md +52 -0
  61. package/evidence/todo/2026-09-28-codex-paired-todo/ai-design-rules/GENERATION_NOTES.md +133 -0
  62. package/evidence/todo/2026-09-28-codex-paired-todo/ai-design-rules/app.js +289 -0
  63. package/evidence/todo/2026-09-28-codex-paired-todo/ai-design-rules/context/context-preserving-preview.json +443 -0
  64. package/evidence/todo/2026-09-28-codex-paired-todo/ai-design-rules/context/daily-home-surface.json +373 -0
  65. package/evidence/todo/2026-09-28-codex-paired-todo/ai-design-rules/context/quick-capture.json +301 -0
  66. package/evidence/todo/2026-09-28-codex-paired-todo/ai-design-rules/context/sources-read.txt +36 -0
  67. package/evidence/todo/2026-09-28-codex-paired-todo/ai-design-rules/generated-output.md +11 -0
  68. package/evidence/todo/2026-09-28-codex-paired-todo/ai-design-rules/index.html +64 -0
  69. package/evidence/todo/2026-09-28-codex-paired-todo/ai-design-rules/launch-prompt.md +1 -0
  70. package/evidence/todo/2026-09-28-codex-paired-todo/ai-design-rules/metadata.json +55 -0
  71. package/evidence/todo/2026-09-28-codex-paired-todo/ai-design-rules/notes.md +15 -0
  72. package/evidence/todo/2026-09-28-codex-paired-todo/ai-design-rules/parent-status-message.md +1 -0
  73. package/evidence/todo/2026-09-28-codex-paired-todo/ai-design-rules/prompt.md +49 -0
  74. package/evidence/todo/2026-09-28-codex-paired-todo/ai-design-rules/runtime-checks.json +776 -0
  75. package/evidence/todo/2026-09-28-codex-paired-todo/ai-design-rules/scores.md +20 -0
  76. package/evidence/todo/2026-09-28-codex-paired-todo/ai-design-rules/screenshots/desktop-completed.png +0 -0
  77. package/evidence/todo/2026-09-28-codex-paired-todo/ai-design-rules/screenshots/desktop-default.png +0 -0
  78. package/evidence/todo/2026-09-28-codex-paired-todo/ai-design-rules/screenshots/desktop-detail-reduced-motion.png +0 -0
  79. package/evidence/todo/2026-09-28-codex-paired-todo/ai-design-rules/screenshots/desktop-detail.png +0 -0
  80. package/evidence/todo/2026-09-28-codex-paired-todo/ai-design-rules/screenshots/desktop-empty.png +0 -0
  81. package/evidence/todo/2026-09-28-codex-paired-todo/ai-design-rules/screenshots/desktop-keyboard-focus.png +0 -0
  82. package/evidence/todo/2026-09-28-codex-paired-todo/ai-design-rules/screenshots/desktop-save-error.png +0 -0
  83. package/evidence/todo/2026-09-28-codex-paired-todo/ai-design-rules/screenshots/desktop-saved.png +0 -0
  84. package/evidence/todo/2026-09-28-codex-paired-todo/ai-design-rules/screenshots/desktop-saving.png +0 -0
  85. package/evidence/todo/2026-09-28-codex-paired-todo/ai-design-rules/screenshots/desktop-validation.png +0 -0
  86. package/evidence/todo/2026-09-28-codex-paired-todo/ai-design-rules/screenshots/mobile-completed.png +0 -0
  87. package/evidence/todo/2026-09-28-codex-paired-todo/ai-design-rules/screenshots/mobile-default.png +0 -0
  88. package/evidence/todo/2026-09-28-codex-paired-todo/ai-design-rules/screenshots/mobile-detail-reduced-motion.png +0 -0
  89. package/evidence/todo/2026-09-28-codex-paired-todo/ai-design-rules/screenshots/mobile-detail.png +0 -0
  90. package/evidence/todo/2026-09-28-codex-paired-todo/ai-design-rules/screenshots/mobile-empty.png +0 -0
  91. package/evidence/todo/2026-09-28-codex-paired-todo/ai-design-rules/screenshots/mobile-keyboard-focus.png +0 -0
  92. package/evidence/todo/2026-09-28-codex-paired-todo/ai-design-rules/screenshots/mobile-save-error.png +0 -0
  93. package/evidence/todo/2026-09-28-codex-paired-todo/ai-design-rules/screenshots/mobile-saved.png +0 -0
  94. package/evidence/todo/2026-09-28-codex-paired-todo/ai-design-rules/screenshots/mobile-saving.png +0 -0
  95. package/evidence/todo/2026-09-28-codex-paired-todo/ai-design-rules/screenshots/mobile-validation.png +0 -0
  96. package/evidence/todo/2026-09-28-codex-paired-todo/ai-design-rules/source-hashes.json +5 -0
  97. package/evidence/todo/2026-09-28-codex-paired-todo/ai-design-rules/styles.css +122 -0
  98. package/evidence/todo/2026-09-28-codex-paired-todo/baseline/GENERATION_NOTES.md +86 -0
  99. package/evidence/todo/2026-09-28-codex-paired-todo/baseline/app.js +303 -0
  100. package/evidence/todo/2026-09-28-codex-paired-todo/baseline/generated-output.md +11 -0
  101. package/evidence/todo/2026-09-28-codex-paired-todo/baseline/index.html +71 -0
  102. package/evidence/todo/2026-09-28-codex-paired-todo/baseline/launch-prompt.md +1 -0
  103. package/evidence/todo/2026-09-28-codex-paired-todo/baseline/metadata.json +55 -0
  104. package/evidence/todo/2026-09-28-codex-paired-todo/baseline/notes.md +15 -0
  105. package/evidence/todo/2026-09-28-codex-paired-todo/baseline/parent-status-message.md +1 -0
  106. package/evidence/todo/2026-09-28-codex-paired-todo/baseline/prompt.md +49 -0
  107. package/evidence/todo/2026-09-28-codex-paired-todo/baseline/runtime-checks.json +772 -0
  108. package/evidence/todo/2026-09-28-codex-paired-todo/baseline/scores.md +20 -0
  109. package/evidence/todo/2026-09-28-codex-paired-todo/baseline/screenshots/desktop-completed.png +0 -0
  110. package/evidence/todo/2026-09-28-codex-paired-todo/baseline/screenshots/desktop-default.png +0 -0
  111. package/evidence/todo/2026-09-28-codex-paired-todo/baseline/screenshots/desktop-detail-reduced-motion.png +0 -0
  112. package/evidence/todo/2026-09-28-codex-paired-todo/baseline/screenshots/desktop-detail.png +0 -0
  113. package/evidence/todo/2026-09-28-codex-paired-todo/baseline/screenshots/desktop-empty.png +0 -0
  114. package/evidence/todo/2026-09-28-codex-paired-todo/baseline/screenshots/desktop-keyboard-focus.png +0 -0
  115. package/evidence/todo/2026-09-28-codex-paired-todo/baseline/screenshots/desktop-save-error.png +0 -0
  116. package/evidence/todo/2026-09-28-codex-paired-todo/baseline/screenshots/desktop-saved.png +0 -0
  117. package/evidence/todo/2026-09-28-codex-paired-todo/baseline/screenshots/desktop-saving.png +0 -0
  118. package/evidence/todo/2026-09-28-codex-paired-todo/baseline/screenshots/desktop-validation.png +0 -0
  119. package/evidence/todo/2026-09-28-codex-paired-todo/baseline/screenshots/mobile-completed.png +0 -0
  120. package/evidence/todo/2026-09-28-codex-paired-todo/baseline/screenshots/mobile-default.png +0 -0
  121. package/evidence/todo/2026-09-28-codex-paired-todo/baseline/screenshots/mobile-detail-reduced-motion.png +0 -0
  122. package/evidence/todo/2026-09-28-codex-paired-todo/baseline/screenshots/mobile-detail.png +0 -0
  123. package/evidence/todo/2026-09-28-codex-paired-todo/baseline/screenshots/mobile-empty.png +0 -0
  124. package/evidence/todo/2026-09-28-codex-paired-todo/baseline/screenshots/mobile-keyboard-focus.png +0 -0
  125. package/evidence/todo/2026-09-28-codex-paired-todo/baseline/screenshots/mobile-save-error.png +0 -0
  126. package/evidence/todo/2026-09-28-codex-paired-todo/baseline/screenshots/mobile-saved.png +0 -0
  127. package/evidence/todo/2026-09-28-codex-paired-todo/baseline/screenshots/mobile-saving.png +0 -0
  128. package/evidence/todo/2026-09-28-codex-paired-todo/baseline/screenshots/mobile-validation.png +0 -0
  129. package/evidence/todo/2026-09-28-codex-paired-todo/baseline/source-hashes.json +5 -0
  130. package/evidence/todo/2026-09-28-codex-paired-todo/baseline/styles.css +9 -0
  131. package/evidence/todo/2026-09-28-codex-paired-todo/capture-ai-design-rules.js +60 -0
  132. package/evidence/todo/2026-09-28-codex-paired-todo/capture-baseline.js +60 -0
  133. package/evidence/todo/2026-09-28-codex-paired-todo/common/brief.md +35 -0
  134. package/evidence/todo/2026-09-28-codex-paired-todo/common/knowledge-files.json +127 -0
  135. package/evidence/todo/2026-09-28-codex-paired-todo/common/knowledge.patch +890 -0
  136. package/evidence/todo/2026-09-28-codex-paired-todo/common/review-context.json +550 -0
  137. package/evidence/todo/2026-09-28-codex-paired-todo/common/seed.json +86 -0
  138. package/evidence/todo/2026-09-28-codex-paired-todo/common/setup.json +47 -0
  139. package/evidence/todo/2026-09-28-codex-paired-todo/common/technical-envelope.md +11 -0
  140. package/evidence/todo/2026-09-28-codex-paired-todo/layout-metrics.json +133 -0
  141. package/evidence/todo/2026-09-28-codex-paired-todo/layout-probe.js +15 -0
  142. package/examples/GENERATED_INDEX.md +8 -0
  143. package/examples/INDEX.md +16 -0
  144. package/examples/README.md +15 -0
  145. package/examples/consequential-action-confirmation-reference.md +83 -0
  146. package/examples/todo-app-benchmark.md +117 -0
  147. package/examples/todo-reference/README.md +29 -0
  148. package/examples/todo-reference/app.js +154 -0
  149. package/examples/todo-reference/favicon.svg +4 -0
  150. package/examples/todo-reference/index.html +67 -0
  151. package/examples/todo-reference/review-evidence/2026-07-15/desktop-default.png +0 -0
  152. package/examples/todo-reference/review-evidence/2026-07-15/desktop-detail.png +0 -0
  153. package/examples/todo-reference/review-evidence/2026-07-15/mobile-detail.png +0 -0
  154. package/examples/todo-reference/review-evidence/2026-07-15/mobile-error.png +0 -0
  155. package/examples/todo-reference/styles.css +241 -0
  156. package/graph/GENERATED_GRAPH.md +71 -0
  157. package/observations/README.md +23 -0
  158. package/observations/accessibility/reduced-interaction-motion.md +49 -0
  159. package/observations/accessibility/textual-error-recovery.md +50 -0
  160. package/observations/accessibility/visible-keyboard-focus.md +49 -0
  161. package/observations/ai/agent-consequential-action-controls.md +56 -0
  162. package/observations/ai/agent-work-visibility-and-intervention.md +51 -0
  163. package/observations/ai/figma-agent-context-and-skills.md +52 -0
  164. package/observations/finance/high-risk-wallet-recovery-flows.md +55 -0
  165. package/observations/finance/market-interface-adaptive-trading-surfaces.md +55 -0
  166. package/observations/interaction/chrome-scoped-view-transitions.md +52 -0
  167. package/observations/interaction/figma-motion-as-system-capability.md +53 -0
  168. package/observations/mobile/mobile-bottom-sheet-choice-contracts.md +55 -0
  169. package/observations/performance/reserved-loading-space.md +51 -0
  170. package/observations/product-repos/pinned-ai-design-rules-integration.md +49 -0
  171. package/observations/visual/apple-liquid-glass-functional-layer.md +52 -0
  172. package/observations/visual/chrome-content-first-adaptive-ui.md +51 -0
  173. package/observations/visual/material-3-expressive-system.md +52 -0
  174. package/package.json +65 -0
  175. package/patterns/GENERATED_INDEX.md +13 -0
  176. package/patterns/INDEX.md +41 -0
  177. package/patterns/README.md +5 -0
  178. package/patterns/consequential-action-confirmation.md +127 -0
  179. package/patterns/context-preserving-preview.md +145 -0
  180. package/patterns/daily-home-surface.md +134 -0
  181. package/patterns/mobile-primary-action.md +110 -0
  182. package/patterns/object-status-list.md +114 -0
  183. package/patterns/progressive-detail.md +113 -0
  184. package/patterns/quick-capture.md +132 -0
  185. package/prompts/CONSEQUENTIAL_ACTION_REVIEW.md +100 -0
  186. package/prompts/DESIGN_EVIDENCE_REVIEW.md +49 -0
  187. package/prompts/GENERATED_INDEX.md +11 -0
  188. package/prompts/INDEX.md +24 -0
  189. package/prompts/PROTOTYPE_REVIEW.md +189 -0
  190. package/prompts/QUICK_CAPTURE_STATE_REVIEW.md +74 -0
  191. package/prompts/TODO_APP_BENCHMARK.md +88 -0
  192. package/registry/objects.json +568 -0
  193. package/registry/relationships.json +972 -0
  194. package/research/GENERATED_INDEX.md +18 -0
  195. package/research/INDEX.md +40 -0
  196. package/research/accessibility/keyboard-focus-and-interaction-motion.md +62 -0
  197. package/research/accessibility/textual-error-recovery.md +57 -0
  198. package/research/performance/reserved-loading-space.md +56 -0
  199. package/research/products/apple-reminders.md +59 -0
  200. package/research/products/arc.md +61 -0
  201. package/research/products/linear.md +62 -0
  202. package/research/products/telegram.md +61 -0
  203. package/research/products/things-3.md +60 -0
  204. package/research/ux/contextual-agentic-interface.md +68 -0
  205. package/research/ux/high-risk-operational-flows.md +89 -0
  206. package/research/ux/motion-as-state-continuity.md +71 -0
  207. package/research/visual/expressive-system-ui-2026.md +75 -0
  208. package/reviews/GENERATED_INDEX.md +9 -0
  209. package/reviews/README.md +25 -0
  210. package/reviews/consequential-action-confirmation-review.md +92 -0
  211. package/reviews/todo-app-benchmark-reference-review.md +86 -0
  212. package/reviews/todo-reference-fixture-review.md +77 -0
  213. package/rules/GENERATED_INDEX.md +23 -0
  214. package/rules/INDEX.md +37 -0
  215. package/rules/accessibility/A11Y-001.md +58 -0
  216. package/rules/accessibility/A11Y-002.md +55 -0
  217. package/rules/accessibility/A11Y-003.md +54 -0
  218. package/rules/accessibility/A11Y-004.md +54 -0
  219. package/rules/ia/IA-001.md +60 -0
  220. package/rules/ia/IA-002.md +61 -0
  221. package/rules/performance/PERF-001.md +55 -0
  222. package/rules/product/PRD-001.md +61 -0
  223. package/rules/product/PRD-002.md +61 -0
  224. package/rules/ux/UX-001.md +58 -0
  225. package/rules/ux/UX-002.md +61 -0
  226. package/rules/ux/UX-003.md +60 -0
  227. package/rules/ux/UX-004.md +61 -0
  228. package/rules/ux/UX-005.md +62 -0
  229. package/rules/ux/UX-006.md +69 -0
  230. package/rules/visual/VIS-001.md +59 -0
  231. package/rules/visual/VIS-002.md +59 -0
  232. package/schema/checklist.schema.json +21 -0
  233. package/schema/common.schema.json +178 -0
  234. package/schema/observation.schema.json +21 -0
  235. package/schema/pattern.schema.json +21 -0
  236. package/schema/prompt.schema.json +21 -0
  237. package/schema/reference-project.schema.json +21 -0
  238. package/schema/research.schema.json +21 -0
  239. package/schema/review.schema.json +21 -0
  240. package/schema/rule.schema.json +21 -0
  241. package/skills/README.md +48 -0
  242. package/skills/accessibility-reviewer/SKILL.md +101 -0
  243. package/skills/agent-context/SKILL.md +34 -0
  244. package/skills/agent-context/agents/openai.yaml +4 -0
  245. package/skills/design-evidence-researcher/SKILL.md +47 -0
  246. package/skills/design-evidence-researcher/agents/openai.yaml +4 -0
  247. package/skills/design-reviewer/SKILL.md +113 -0
  248. package/skills/design-system-architect/SKILL.md +101 -0
  249. package/skills/information-architect/SKILL.md +97 -0
  250. package/skills/interaction-designer/SKILL.md +104 -0
  251. package/skills/knowledge-graph-architect/SKILL.md +96 -0
  252. package/skills/mobile-ux-expert/SKILL.md +105 -0
  253. package/skills/motion-designer/SKILL.md +100 -0
  254. package/skills/performance-reviewer/SKILL.md +97 -0
  255. package/skills/product-designer/SKILL.md +104 -0
  256. package/skills/prompt-architect/SKILL.md +105 -0
  257. package/skills/reference-driven-design/SKILL.md +119 -0
  258. package/skills/ux-reviewer/SKILL.md +99 -0
  259. package/skills/visual-designer/SKILL.md +107 -0
  260. package/starter-kit/AGENTS.md +37 -0
  261. package/starter-kit/BOOTSTRAP.md +13 -0
  262. package/starter-kit/INSTALL_WITH_AGENT.md +133 -0
  263. package/starter-kit/PROJECT_INTEGRATION.md +60 -0
  264. package/starter-kit/README.md +41 -0
  265. package/starter-kit/benchmarks/BENCHMARK_CHECKLIST.md +10 -0
  266. package/starter-kit/docs/DESIGN_DECISIONS.md +22 -0
  267. package/starter-kit/docs/INFORMATION_ARCHITECTURE.md +25 -0
  268. package/starter-kit/docs/PERSONAS.md +14 -0
  269. package/starter-kit/docs/PRD.md +32 -0
  270. package/starter-kit/docs/USER_FLOWS.md +19 -0
  271. package/starter-kit/reviews/DESIGN_REVIEW.md +49 -0
  272. package/starter-kit/templates/FEATURE_TEMPLATE.md +36 -0
  273. package/starter-kit/templates/TASK_TEMPLATE.md +22 -0
  274. package/templates/CHECKLIST_TEMPLATE.md +43 -0
  275. package/templates/OBSERVATION_TEMPLATE.md +41 -0
  276. package/templates/PATTERN_TEMPLATE.md +100 -0
  277. package/templates/PROMPT_TEMPLATE.md +46 -0
  278. package/templates/PROTOTYPE_REVIEW.md +50 -0
  279. package/templates/REFERENCE_PROJECT_TEMPLATE.md +49 -0
  280. package/templates/REVIEW_TEMPLATE.md +55 -0
  281. package/templates/RULE_TEMPLATE.md +57 -0
  282. package/tools/cli.mjs +46 -0
  283. package/tools/context.mjs +342 -0
  284. package/tools/designlint.mjs +77 -0
  285. package/tools/generate-indexes.mjs +621 -0
  286. package/tools/init.mjs +99 -0
  287. package/tools/validate-benchmark-evidence.mjs +248 -0
  288. package/tools/validate-knowledge.mjs +481 -0
@@ -0,0 +1,119 @@
1
+ ---
2
+ name: reference-driven-design
3
+ description: Build an evidence-backed visual reference brief before UI concept or polish work. Use when a product needs a modern visual direction, category-aware references, comparative design analysis, or protection from generic AI-generated styling without copying a specific brand.
4
+ ---
5
+
6
+ # Reference-Driven Design Skill
7
+
8
+ ## Role
9
+
10
+ Translate current product and platform references into an abstract, traceable visual direction.
11
+
12
+ ## Mission
13
+
14
+ Improve visual judgment without turning taste, trends, or one admired product into unsupported design rules.
15
+
16
+ ## When To Use
17
+
18
+ - A user asks for a more modern, polished, premium, expressive, or product-specific interface.
19
+ - A new surface needs a visual direction before implementation.
20
+ - Existing UI feels generic but the workflow and object model are already clear.
21
+ - A prompt needs reference categories and explicit anti-copy constraints.
22
+
23
+ ## When Not To Use
24
+
25
+ - Product direction, user goal, or object model is unresolved.
26
+ - The task is a narrow visual bug with an existing token and component answer.
27
+ - No source, screenshot, product behavior, or graph context is available; record a research gap first.
28
+
29
+ ## Inputs
30
+
31
+ - Product goal, primary action, audience, and platform.
32
+ - Current UI or implementation.
33
+ - Existing components, tokens, and product design direction.
34
+ - Focused graph context from `npm run context`.
35
+ - Supplied references or traceable current product and platform evidence.
36
+
37
+ ## Process
38
+
39
+ 1. Resolve graph context for the target task.
40
+ 2. Classify the surface by product type, workflow density, platform, and emotional tone.
41
+ 3. Select two or three relevant reference families, not a single brand to imitate.
42
+ 4. For each source, separate observed behavior from interpretation.
43
+ 5. Extract reusable abstractions:
44
+ - content and functional layers;
45
+ - hierarchy and density;
46
+ - typography and shape roles;
47
+ - material and color meaning;
48
+ - state and motion behavior;
49
+ - responsive and input adaptation.
50
+ 6. Map recommendations to existing research, rules, patterns, and tokens.
51
+ 7. Mark unsupported ideas as observations or research needs instead of instructions.
52
+ 8. Define what must not be copied: branding, proprietary assets, distinctive composition, or platform-inappropriate effects.
53
+ 9. Hand the brief to `visual-designer`, `motion-designer`, or `prompt-architect`.
54
+
55
+ ## Output Format
56
+
57
+ ```md
58
+ ## Reference Brief
59
+ - Product category:
60
+ - User goal:
61
+ - Platform and density:
62
+ - Evidence date:
63
+
64
+ ## Reference Matrix
65
+ | Source | Observed behavior | Reusable abstraction | Limit |
66
+ | --- | --- | --- | --- |
67
+
68
+ ## Visual Direction
69
+ - Content layer:
70
+ - Functional layer:
71
+ - Focal emphasis:
72
+ - Typography and shape:
73
+ - State and motion:
74
+ - Responsive adaptation:
75
+
76
+ ## Graph Traceability
77
+ - Research:
78
+ - Rules:
79
+ - Patterns:
80
+ - Missing evidence:
81
+
82
+ ## Anti-Copy Boundary
83
+ - Do not copy:
84
+ - Platform constraints:
85
+
86
+ ## Handoff
87
+ - Next skill:
88
+ - Reason:
89
+ ```
90
+
91
+ ## Quality Checklist
92
+
93
+ - Recommendations come from observable source behavior.
94
+ - At least two reference families are compared when the task is exploratory.
95
+ - Product purpose determines expression level and density.
96
+ - Content and primary action remain dominant.
97
+ - Platform-specific materials have fallbacks.
98
+ - The brief names unsupported ideas as gaps.
99
+ - No specific brand composition or proprietary asset is copied.
100
+
101
+ ## Related Research
102
+
103
+ - `RESEARCH-00009` Expressive System UI In 2026
104
+ - `RESEARCH-00010` Motion As State Continuity
105
+ - `RESEARCH-00011` Contextual And Observable Agentic Interfaces
106
+
107
+ ## Related Rules
108
+
109
+ - `RULE-00008` / `VIS-001` Semantic Tokens Only
110
+ - `RULE-00014` / `VIS-002` Keep Expression Subordinate To Content
111
+ - `RULE-00015` / `UX-004` Use Motion To Explain State Continuity
112
+
113
+ ## Handoff To Other Skills
114
+
115
+ - Use `product-designer` if product direction or the primary action is unclear.
116
+ - Use `design-evidence-researcher` when current evidence is missing.
117
+ - Use `visual-designer` to convert the brief into hierarchy and token decisions.
118
+ - Use `motion-designer` when continuity or interaction feedback needs movement.
119
+ - Use `prompt-architect` to encode the direction into a graph-backed prompt.
@@ -0,0 +1,99 @@
1
+ ---
2
+ name: ux-reviewer
3
+ description: Review product journeys for usability and friction. Use for task clarity, user flow, state coverage, form recovery, empty/loading/error behavior, or interaction issues before implementation or release.
4
+ ---
5
+
6
+ # UX Reviewer Skill
7
+
8
+ ## Role
9
+
10
+ Review user journeys, usability, flow clarity, and state behavior.
11
+
12
+ ## Mission
13
+
14
+ Find where a product workflow makes users think, wait, repeat work, lose context, or miss the next action.
15
+
16
+ ## When To Use
17
+
18
+ - A feature flow needs usability review.
19
+ - Empty, loading, error, or success states are unclear.
20
+ - A design may be too dashboard-like for a consumer workflow.
21
+ - Pattern selection needs UX validation.
22
+
23
+ ## When Not To Use
24
+
25
+ - The product goal is not defined.
26
+ - The task is only visual token cleanup.
27
+ - The request is purely schema or registry architecture.
28
+
29
+ ## Inputs
30
+
31
+ - User goal, workflow, screen sequence, or prototype.
32
+ - Claimed rules and patterns.
33
+ - State requirements and constraints.
34
+ - Generated rule and pattern indexes.
35
+
36
+ ## Process
37
+
38
+ 1. Identify the user goal and expected next action.
39
+ 2. Trace the default path from entry to completion.
40
+ 3. Check whether capture, inspection, and completion preserve context.
41
+ 4. Review empty, loading, error, disabled, and success states.
42
+ 5. Flag friction, ambiguity, unnecessary metadata, and mode confusion.
43
+ 6. Tie each issue to an existing rule, pattern, or missing knowledge layer.
44
+ 7. Hand off visual, mobile, accessibility, or interaction issues as needed.
45
+
46
+ ## Output Format
47
+
48
+ ```md
49
+ ## UX Review
50
+ - User goal:
51
+ - Flow reviewed:
52
+ - Verdict:
53
+
54
+ ## Findings
55
+ - Issue:
56
+ - Impact:
57
+ - Rule or pattern:
58
+ - Suggested fix:
59
+
60
+ ## State Coverage
61
+ - Empty:
62
+ - Loading:
63
+ - Error:
64
+ - Success:
65
+
66
+ ## Handoff
67
+ - Next skill:
68
+ - Reason:
69
+ ```
70
+
71
+ ## Quality Checklist
72
+
73
+ - The main user path is understandable.
74
+ - The next action is visible.
75
+ - Optional metadata does not block capture.
76
+ - Detail views preserve context.
77
+ - States are designed, not left implicit.
78
+ - Findings are grounded in rules and patterns.
79
+
80
+ ## Related Rules
81
+
82
+ - `RULE-00001` / `PRD-001` Daily Actions First
83
+ - `RULE-00002` / `PRD-002` Low-Friction Capture Before Organization
84
+ - `RULE-00006` / `UX-002` Progressively Disclose Power
85
+ - `RULE-00007` / `UX-003` Preserve Context During Inspection
86
+
87
+ ## Related Patterns
88
+
89
+ - `PAT-00001` / `PAT-001` Daily Home Surface
90
+ - `PAT-00002` / `PAT-002` Quick Capture
91
+ - `PAT-00004` / `PAT-004` Progressive Detail
92
+ - `PAT-00005` / `PAT-005` Context-Preserving Preview
93
+
94
+ ## Handoff To Other Skills
95
+
96
+ - Use `product-designer` when the user goal or primary action is unclear.
97
+ - Use `interaction-designer` for detailed flow mechanics.
98
+ - Use `mobile-ux-expert` for touch-first layout issues.
99
+ - Use `design-reviewer` for final quality gate.
@@ -0,0 +1,107 @@
1
+ ---
2
+ name: visual-designer
3
+ description: Review or refine visual hierarchy in product UI. Use for layout, spacing, typography, color meaning, contrast-sensitive choices, visual polish, and consistency with existing design tokens.
4
+ ---
5
+
6
+ # Visual Designer Skill
7
+
8
+ ## Role
9
+
10
+ Review visual hierarchy, typography, spacing, color meaning, and product polish.
11
+
12
+ ## Mission
13
+
14
+ Make the interface feel modern, legible, and product-specific while preserving rule and pattern intent.
15
+
16
+ ## When To Use
17
+
18
+ - A screen is structurally correct but visually unclear or generic.
19
+ - Hierarchy, spacing, contrast, density, or status styling needs review.
20
+ - A product surface needs polish without redesigning the workflow.
21
+ - Semantic token use needs visual validation.
22
+
23
+ ## When Not To Use
24
+
25
+ - Product direction or IA is unresolved.
26
+ - The task asks for a new design system or component library.
27
+ - The issue is primarily accessibility, motion, or performance.
28
+
29
+ ## Inputs
30
+
31
+ - Current screen or implementation.
32
+ - Product goal and selected patterns.
33
+ - Evidence-backed reference brief when visual direction or polish is requested.
34
+ - Existing tokens, theme values, and component styles.
35
+ - Accessibility constraints and viewport requirements.
36
+
37
+ ## Process
38
+
39
+ 1. Identify the primary content and action.
40
+ 2. Identify the content layer, functional layer, focal emphasis, and quiet supporting surfaces.
41
+ 3. Check typography scale, spacing, density, and hierarchy.
42
+ 4. Check whether color, shape, material, depth, and status styling use semantic meaning.
43
+ 5. Keep expressive treatment subordinate to content and primary action.
44
+ 6. Ensure repeated items scan cleanly.
45
+ 7. Preserve platform, mobile, and accessibility constraints.
46
+ 8. Hand off reference, token, accessibility, or final review concerns.
47
+
48
+ ## Output Format
49
+
50
+ ```md
51
+ ## Visual Review
52
+ - Primary visual issue:
53
+ - Product impact:
54
+ - Recommended change:
55
+ - Evidence or reference:
56
+
57
+ ## Hierarchy
58
+ - Primary:
59
+ - Secondary:
60
+ - Supporting:
61
+
62
+ ## Surface Roles
63
+ - Content layer:
64
+ - Functional layer:
65
+ - Focal emphasis:
66
+ - Quiet surfaces:
67
+
68
+ ## Token And Pattern Links
69
+ - Rule:
70
+ - Pattern:
71
+
72
+ ## Handoff
73
+ - Next skill:
74
+ - Reason:
75
+ ```
76
+
77
+ ## Quality Checklist
78
+
79
+ - Primary action and content are visually dominant.
80
+ - Typography fits the surface.
81
+ - Spacing supports scanning.
82
+ - Color communicates meaning, not decoration alone.
83
+ - Expressive materials preserve content priority and platform behavior.
84
+ - Visual polish does not change product logic.
85
+ - The recommendation uses existing rules and patterns.
86
+
87
+ ## Related Rules
88
+
89
+ - `RULE-00001` / `PRD-001` Daily Actions First
90
+ - `RULE-00003` / `IA-001` One Stable Home Surface
91
+ - `RULE-00008` / `VIS-001` Semantic Tokens Only
92
+ - `RULE-00009` / `A11Y-001` 44x44 Touch Targets
93
+ - `RULE-00014` / `VIS-002` Keep Expression Subordinate To Content
94
+
95
+ ## Related Patterns
96
+
97
+ - `PAT-00001` / `PAT-001` Daily Home Surface
98
+ - `PAT-00004` / `PAT-004` Progressive Detail
99
+ - `PAT-00006` / `PAT-006` Object Status List
100
+
101
+ ## Handoff To Other Skills
102
+
103
+ - Use `design-system-architect` when token or reusable state naming is needed.
104
+ - Use `reference-driven-design` when the visual direction lacks traceable references.
105
+ - Use `accessibility-reviewer` for contrast, focus, and target checks.
106
+ - Use `mobile-ux-expert` when visual density breaks on narrow screens.
107
+ - Use `design-reviewer` for final signoff.
@@ -0,0 +1,37 @@
1
+ # Project AGENTS
2
+
3
+ This repository follows AI Design Context.
4
+
5
+ ## Agent Workflow
6
+
7
+ For every feature:
8
+
9
+ 1. Read `docs/PRD.md`.
10
+ 2. Read `docs/PERSONAS.md`.
11
+ 3. Read `docs/USER_FLOWS.md`.
12
+ 4. Read `docs/INFORMATION_ARCHITECTURE.md`.
13
+ 5. Select applicable rules from AI Design Context.
14
+ 6. Select applicable patterns from AI Design Context.
15
+ 7. Explain the design reasoning before implementation.
16
+ 8. Prototype or implement the smallest useful change.
17
+ 9. Review with `reviews/DESIGN_REVIEW.md`.
18
+ 10. Benchmark meaningful product changes.
19
+
20
+ ## Do Not
21
+
22
+ - Do not jump directly from a feature request to code.
23
+ - Do not invent new design rules inside the product repo.
24
+ - Do not add UI complexity without a user goal.
25
+ - Do not skip empty, loading, error, disabled, and success states.
26
+ - Do not claim benchmark improvement without stored evidence.
27
+
28
+ ## Output
29
+
30
+ When completing UI or product work, report:
31
+
32
+ - rules used;
33
+ - patterns used;
34
+ - states covered;
35
+ - mobile assumptions;
36
+ - accessibility checks;
37
+ - validation result.
@@ -0,0 +1,13 @@
1
+ # Bootstrap Checklist
2
+
3
+ - [ ] Create `docs/PRD.md`.
4
+ - [ ] Define personas and jobs in `docs/PERSONAS.md`.
5
+ - [ ] Map primary user flows in `docs/USER_FLOWS.md`.
6
+ - [ ] Define screens, navigation, and object model in `docs/INFORMATION_ARCHITECTURE.md`.
7
+ - [ ] Record product and UX decisions in `docs/DESIGN_DECISIONS.md`.
8
+ - [ ] Select applicable AI Design Context.
9
+ - [ ] Select applicable patterns.
10
+ - [ ] Prototype or implement the smallest useful version.
11
+ - [ ] Run `reviews/DESIGN_REVIEW.md`.
12
+ - [ ] Benchmark meaningful product changes.
13
+ - [ ] Store evidence before claiming improvement.
@@ -0,0 +1,133 @@
1
+ # Install with a Coding Agent
2
+
3
+ Use this guide to connect AI Design Context to an existing product repository without replacing its application code, UI library, or current agent instructions.
4
+
5
+ After setup, the product repository has:
6
+
7
+ - a pinned AI Design Context knowledge source;
8
+ - project-local agent instructions;
9
+ - product context and review templates where they are missing;
10
+ - a repeatable command for retrieving task-specific graph context.
11
+
12
+ ## Choose a Connection
13
+
14
+ | Connection | Use when | Trade-off |
15
+ | --- | --- | --- |
16
+ | npm dev dependency `ai-design-context` | A Node.js project wants CLI access and lockfile-pinned guidance. | Requires Node.js 20+; upgrades are explicit dependency updates. |
17
+ | Git submodule at `.ai-design-rules/` | A team needs a reviewable, reproducible version. | The parent repository must update the pinned commit deliberately. |
18
+ | Sibling checkout | One developer wants to evaluate the workflow locally. | The path is machine-specific and is not shared with the team. |
19
+ | Starter kit only | The project needs the workflow and templates but not live graph retrieval. | The agent cannot resolve current research, rules, or patterns automatically. |
20
+
21
+ ## npm Installation
22
+
23
+ The package is implemented in this checkout; registry installation requires its first npm publication. After publication, run these commands from the product repository:
24
+
25
+ ```bash
26
+ npm install --save-dev --save-exact ai-design-context
27
+ npx ai-design-context init
28
+ npx ai-design-context context --task quick-capture --platform mobile --intent implement
29
+ ```
30
+
31
+ Before publication, run `npm pack` in the knowledge-source checkout, then install that generated `.tgz` with `npm install --save-dev /path/to/ai-design-context-0.4.0.tgz` in the product repository. The same `init` and `context` commands work with the local tarball.
32
+
33
+ `init` appends an optional, marked section to the existing `AGENTS.md` and creates only missing files under `docs/`, `templates/`, `reviews/`, and `benchmarks/`. It preserves existing project-specific instructions, populated documents, and edited integration blocks. Repeat it safely to create newly missing templates; it does not refresh an existing block. Review any newly created placeholders and fill them with actual product context. There are no install hooks and no runtime dependencies.
34
+
35
+ Ask the agent to use the returned absolute reading paths, read research and rules, and preserve evidence limits. JSON output includes `knowledgeRoot`, relative `path`, and `absolutePath`. `--review` matches graph identifiers or phrases rather than analyzing arbitrary product files.
36
+
37
+ Commit the package manifest and lockfile. Adopt future guidance deliberately with `npm install --save-dev --save-exact ai-design-context@<version>` after reviewing its changes.
38
+
39
+ The GitHub URL remains `https://github.com/dev-ik/ai-design-rules`. The instructions below describe the Git submodule alternative; its existing `.ai-design-rules/` path remains valid.
40
+
41
+ ## Give the Agent This Task
42
+
43
+ Run the agent from the root of the product repository and give it this prompt:
44
+
45
+ ```text
46
+ Connect AI Design Context to this repository.
47
+
48
+ Knowledge source:
49
+ https://github.com/dev-ik/ai-design-rules.git
50
+
51
+ Use the repository's existing conventions and make only integration changes.
52
+
53
+ 1. Inspect the repository instructions, documentation structure, package manager,
54
+ and current git status before changing files.
55
+ 2. If `.ai-design-rules` is absent, add the knowledge source there as a Git
56
+ submodule. If that path already exists, inspect and reuse it; do not replace it.
57
+ 3. Read `.ai-design-rules/starter-kit/README.md`,
58
+ `.ai-design-rules/starter-kit/PROJECT_INTEGRATION.md`, and
59
+ `.ai-design-rules/starter-kit/AGENTS.md`.
60
+ 4. Merge the relevant starter-kit instructions into the repository's existing
61
+ `AGENTS.md`. Preserve all existing project-specific and higher-priority rules.
62
+ If the repository uses another instruction file, adapt the integration to it
63
+ and explain the choice.
64
+ 5. Reuse existing product documentation. Create only missing PRD, persona,
65
+ user-flow, information-architecture, design-decision, feature-template,
66
+ design-review, and benchmark files. Never overwrite populated files with
67
+ starter-kit placeholders.
68
+ 6. Add these commands to the project instructions for user-facing product, UX,
69
+ UI, accessibility, motion, and design-prompt work:
70
+
71
+ npm --prefix .ai-design-rules run context -- --task "<task phrase>" --intent implement
72
+ npm --prefix .ai-design-rules run context -- --task "<task phrase>" --platform mobile --intent implement
73
+ npm --prefix .ai-design-rules run context -- --review "<path>" --intent qa
74
+
75
+ Tell agents to read the returned research and rules before making product
76
+ decisions. If no context resolves, they must record a knowledge gap instead of
77
+ inventing a rule. Skip graph retrieval for backend-only, infrastructure-only,
78
+ or unrelated maintenance work.
79
+ 7. Verify the knowledge source and run:
80
+
81
+ npm --prefix .ai-design-rules run check
82
+ npm --prefix .ai-design-rules run context -- --task quick-capture --platform mobile --intent implement
83
+
84
+ 8. Report the files created or merged, checks run, unresolved conflicts, and the
85
+ pinned AI Design Context commit.
86
+
87
+ Do not change application behavior, dependencies, or product code as part of this
88
+ integration.
89
+ ```
90
+
91
+ The prompt intentionally tells the agent to merge rather than copy. Existing product context is more authoritative than starter-kit placeholders.
92
+
93
+ ## Verify the Connection
94
+
95
+ From the product repository root, run:
96
+
97
+ ```bash
98
+ git submodule status .ai-design-rules
99
+ npm --prefix .ai-design-rules run check
100
+ npm --prefix .ai-design-rules run context -- --task quick-capture --platform mobile --intent implement
101
+ git status --short
102
+ ```
103
+
104
+ The context command should return matched anchors, research, rules, and a recommended reading order. Review `git status` before committing: the integration should change only `.gitmodules`, the pinned submodule, agent instructions, and explicitly selected project documentation.
105
+
106
+ ## Use It on Product Work
107
+
108
+ Before implementing a user-facing task:
109
+
110
+ ```bash
111
+ npm --prefix .ai-design-rules run context -- --task "describe the task" --intent implement
112
+ ```
113
+
114
+ Add `--platform mobile` when narrow-screen or touch behavior matters.
115
+
116
+ Before reviewing an implementation or reference fixture:
117
+
118
+ ```bash
119
+ npm --prefix .ai-design-rules run context -- --review "path/to/implementation" --intent qa
120
+ ```
121
+
122
+ The agent should use the returned objects as bounded evidence, preserve the product's existing logic and design system, and report which rules and patterns influenced the result.
123
+
124
+ ## Update the Pinned Knowledge Source
125
+
126
+ Update intentionally, then validate before committing the new submodule pointer:
127
+
128
+ ```bash
129
+ git submodule update --remote .ai-design-rules
130
+ npm --prefix .ai-design-rules run check
131
+ ```
132
+
133
+ Review upstream changes before adopting them. A knowledge-source update can change the guidance an agent retrieves even when product code is unchanged.
@@ -0,0 +1,60 @@
1
+ # Project Integration
2
+
3
+ Integrate AI Design Context before implementation.
4
+
5
+ ## Workflow
6
+
7
+ 1. Understand the product problem.
8
+ 2. Capture relevant research or product context.
9
+ 3. Select applicable rules.
10
+ 4. Select applicable patterns.
11
+ 5. Explain design decisions.
12
+ 6. Prototype the smallest useful solution.
13
+ 7. Review UX, IA, accessibility, mobile behavior, states, and consistency.
14
+ 8. Implement after review.
15
+ 9. Benchmark meaningful product changes.
16
+ 10. Feed learnings back into project docs.
17
+
18
+ ## Design Options Checkpoint
19
+
20
+ Before broad visual design, new screen direction, visual exploration, or product polish, ask whether the user wants:
21
+
22
+ - multiple design options for comparison; or
23
+ - one conservative implementation path that fits the existing product system.
24
+
25
+ Skip this checkpoint for narrow bug fixes, already approved designs, small accessibility fixes, copy-only changes, or tasks where the user explicitly asked for immediate implementation.
26
+
27
+ ## Integration Modes
28
+
29
+ Choose the lightest integration mode that gives agents enough context without weakening local project rules.
30
+
31
+ - npm package: install `ai-design-context` as a dev dependency, run `npx ai-design-context init`, and use `npx ai-design-context context` for lockfile-pinned graph retrieval. See `INSTALL_WITH_AGENT.md` for publication status and local tarball installation.
32
+ - Direct graph: use this repository directly when the product repo is the same workspace or can run the local context CLI.
33
+ - Pinned snapshot: copy a reviewed snapshot into the product repo when agents need reproducible offline guidance.
34
+ - Bridge skill: create a small local skill that points agents at the snapshot, local design docs, and applicable AI Design Context skills.
35
+ - Optional reasoning layer: reference AI Design Context only for UI, UX, accessibility, responsive behavior, design review, or visual polish while keeping local architecture, API, security, routing, and test rules higher priority.
36
+
37
+ Do not copy the starter kit wholesale into mature product repositories. Adapt only the parts that improve design reasoning and keep local product constraints authoritative.
38
+
39
+ ## Required Project Files
40
+
41
+ For broad product work, prefer:
42
+
43
+ - `docs/PRD.md`
44
+ - `docs/PERSONAS.md`
45
+ - `docs/USER_FLOWS.md`
46
+ - `docs/INFORMATION_ARCHITECTURE.md`
47
+ - `docs/DESIGN_DECISIONS.md`
48
+
49
+ For narrow UI fixes, do not require a full document set. Capture the user goal, affected state, applicable rule or pattern, responsive assumption, accessibility check, and visual QA result in the task or review.
50
+
51
+ ## Contributor Expectation
52
+
53
+ Every UI or UX change should state:
54
+
55
+ - user goal;
56
+ - applicable AI Design Context;
57
+ - applicable patterns;
58
+ - states handled;
59
+ - review result;
60
+ - validation or benchmark evidence when relevant.
@@ -0,0 +1,41 @@
1
+ # AI Design Context Starter Kit
2
+
3
+ This starter kit bootstraps a product repository that wants to use AI Design Context.
4
+
5
+ Use the npm CLI's `init` command to append agent instructions and create only missing templates, or selectively copy these files into a target project. Adapt placeholders to that product. See `INSTALL_WITH_AGENT.md` for registry and local tarball installation.
6
+
7
+ It does not include a UI kit, components, or generated rules. It gives agents a working structure for applying research, rules, patterns, prompts, reviews, benchmarks, and evidence.
8
+
9
+ ## Included
10
+
11
+ - `INSTALL_WITH_AGENT.md` - safe, agent-driven installation for an existing repository.
12
+ - `PROJECT_INTEGRATION.md` - how the project should adopt AI Design Context.
13
+ - `AGENTS.md` - local agent instructions for feature work.
14
+ - `BOOTSTRAP.md` - first setup checklist.
15
+ - `docs/` - product context documents.
16
+ - `templates/` - feature and task templates.
17
+ - `reviews/` - design review checklist.
18
+ - `benchmarks/` - benchmark checklist.
19
+
20
+ ## Recommended Workflow
21
+
22
+ ```text
23
+ research -> rules -> patterns -> prompts -> prototype -> review -> code -> benchmark -> evidence
24
+ ```
25
+
26
+ ## How To Use
27
+
28
+ For an existing repository, start with `INSTALL_WITH_AGENT.md`. It tells an agent how to preserve current instructions and populated project documents.
29
+
30
+ 1. Fill `docs/PRD.md`.
31
+ 2. Define users in `docs/PERSONAS.md`.
32
+ 3. Map the core journey in `docs/USER_FLOWS.md`.
33
+ 4. Define objects, screens, and navigation in `docs/INFORMATION_ARCHITECTURE.md`.
34
+ 5. Record key decisions in `docs/DESIGN_DECISIONS.md`.
35
+ 6. Use `templates/FEATURE_TEMPLATE.md` before implementing a feature.
36
+ 7. Run `reviews/DESIGN_REVIEW.md` before merging UI work.
37
+ 8. Store benchmark evidence for meaningful product changes.
38
+
39
+ ## Agent Rule
40
+
41
+ Agents should not jump from a feature request directly to code. They should identify the user goal, select applicable AI Design Context, compose patterns, review states, and validate the result.
@@ -0,0 +1,10 @@
1
+ # Benchmark Checklist
2
+
3
+ - [ ] Product brief is fixed.
4
+ - [ ] Same model/tooling is used for both runs.
5
+ - [ ] Baseline output is stored.
6
+ - [ ] AI Design Context output is stored.
7
+ - [ ] Evaluation rubric is applied.
8
+ - [ ] Scores include written evidence.
9
+ - [ ] Difference is described without overclaiming.
10
+ - [ ] Evidence is stored in the project.
@@ -0,0 +1,22 @@
1
+ # Design Decisions
2
+
3
+ Record important UX and product decisions.
4
+
5
+ ## Decision Template
6
+
7
+ ### Decision
8
+
9
+ What was decided?
10
+
11
+ ### Why
12
+
13
+ What user goal, rule, pattern, research, or constraint supports it?
14
+
15
+ ### Alternatives Considered
16
+
17
+ - Alternative:
18
+ - Reason rejected:
19
+
20
+ ### Evidence
21
+
22
+ - Link to benchmark, review, issue, or product note:
@@ -0,0 +1,25 @@
1
+ # Information Architecture
2
+
3
+ Define screens, navigation and object model.
4
+
5
+ ## Objects
6
+
7
+ - Object:
8
+ - Key fields:
9
+ - Status values:
10
+
11
+ ## Screens
12
+
13
+ - Screen:
14
+ - Purpose:
15
+ - Primary action:
16
+
17
+ ## Navigation
18
+
19
+ - Home surface:
20
+ - Primary navigation:
21
+ - Secondary navigation:
22
+
23
+ ## Relationships
24
+
25
+ - Object A relates to Object B because...
@@ -0,0 +1,14 @@
1
+ # Personas
2
+
3
+ ## Primary User
4
+
5
+ - Context:
6
+ - Motivation:
7
+ - Constraints:
8
+ - Repeated action:
9
+
10
+ ## Jobs To Be Done
11
+
12
+ - When...
13
+ - I want...
14
+ - So I can...