ai-design-context 0.4.0

package/docs/PATTERN_SPEC.md

@@ -0,0 +1,113 @@
+# Pattern Specification
+
+Patterns are compositions of rules. They describe reusable product structures that agents can apply across products without copying a specific UI.
+
+Every pattern document must contain exactly these sections, in this order.
+
+## # Pattern Name
+
+Names the reusable solution. The name should describe the product behavior, not a component.
+
+Why it exists: agents need stable names to reference patterns in prompts, reviews, and reference projects.
+
+## Purpose
+
+Explains the design problem the pattern solves.
+
+Why it exists: a pattern should solve one problem only. Purpose prevents overlap with adjacent patterns.
+
+## User Goal
+
+States what the user is trying to accomplish.
+
+Why it exists: agents should start from user intent, not layout or component choice.
+
+## Product Context
+
+Defines the type of product, screen, or workflow where the pattern belongs.
+
+Why it exists: patterns are not universal. Context prevents misuse in products with different constraints.
+
+## Use When
+
+Lists conditions where the pattern is appropriate.
+
+Why it exists: agents need a trigger for selecting the pattern.
+
+## Do Not Use When
+
+Lists conditions where the pattern should be avoided.
+
+Why it exists: good patterns include boundaries, not only positive examples.
+
+## UX Rules
+
+Lists UX-focused rules that shape the interaction.
+
+Why it exists: patterns must remain connected to rules instead of becoming standalone advice.
+
+## Accessibility Rules
+
+Lists accessibility rules or requirements that affect the pattern.
+
+Why it exists: accessibility is part of the pattern contract, not a final polish step.
+
+## Mobile Behavior
+
+Explains how the pattern behaves on touch-first and narrow screens.
+
+Why it exists: AI agents often create desktop-first layouts unless mobile behavior is explicit.
+
+## Desktop Behavior
+
+Explains how the pattern behaves on larger screens, keyboard-heavy workflows, or dense layouts.
+
+Why it exists: desktop behavior should adapt the pattern without changing its core purpose.
+
+## Empty State
+
+Explains what the user sees when there is no content yet.
+
+Why it exists: empty states should help users start the intended workflow.
+
+## Loading State
+
+Explains what remains stable while data or actions are loading.
+
+Why it exists: loading should preserve orientation and avoid layout jumps.
+
+## Error State
+
+Explains how the pattern handles failure and recovery.
+
+Why it exists: errors should preserve user input, context, and trust.
+
+## Required Rules
+
+Lists all rule IDs required by the pattern.
+
+Why it exists: rules are the source of pattern authority and keep the knowledge graph traceable.
+
+## Related Research
+
+Lists research files that influenced the pattern.
+
+Why it exists: patterns must trace back to observed product behavior, not taste.
+
+## Related Patterns
+
+Lists parent, child, alternative, dependent, or adjacent patterns.
+
+Why it exists: related patterns clarify ownership and prevent duplicate responsibilities.
+
+## Examples
+
+Shows concise product situations where the pattern applies.
+
+Why it exists: examples help agents map the abstract pattern to concrete product work.
+
+## Agent Checklist
+
+Provides review questions an agent can run before using or shipping the pattern.
+
+Why it exists: patterns must be actionable and reviewable.

package/docs/PHILOSOPHY.md

@@ -0,0 +1,25 @@
+# Philosophy
+
+AI Design Context exists to help AI coding agents make better product decisions before generating UI.
+
+The baseline is simple: good design reduces user effort.
+
+## What This Means
+
+- Start from the user's real goal, not from a screen layout.
+- Prefer the smallest clear workflow over a feature-heavy interface.
+- Make repeated actions fast and obvious.
+- Treat empty, loading, error, and disabled states as part of the product.
+- Use visual design to clarify priority, not to decorate weak structure.
+
+## What This Does Not Mean
+
+This repository does not replace product judgment, research, accessibility review, or engineering constraints.
+
+It gives agents a structured way to reason from evidence:
+
+```text
+research -> rules -> patterns -> prompts -> evidence
+```
+
+When a rule or pattern cannot be traced to evidence, mark the gap instead of inventing authority.

package/docs/PRODUCT_THINKING.md

@@ -0,0 +1,26 @@
+# Product Thinking
+
+Product thinking comes before interface generation.
+
+Before an agent proposes UI, it should understand:
+
+- who the user is;
+- what job they are trying to complete;
+- what they repeat often;
+- what must be fast, calm, or trustworthy;
+- what can wait until later.
+
+## Agent Questions
+
+- What is the user's primary goal in this product?
+- What action happens every day or every session?
+- What object is the product built around?
+- What must be visible immediately?
+- What should be progressively disclosed?
+- What state can block user progress?
+
+## Output Standard
+
+A product decision should be specific enough to become a rule, pattern, prompt, benchmark criterion, or review finding.
+
+Avoid vague claims such as "make it clean" or "make it modern" unless they are translated into concrete behavior.

package/docs/STYLE_GUIDE.md

@@ -0,0 +1,49 @@
+# Documentation Style Guide
+
+AI Design Context documentation must help agents act. Write for practical use inside real product codebases.
+
+## Tone
+
+- Concise.
+- Practical.
+- Rule-based.
+- Direct.
+- Specific enough to review.
+
+## Content Rules
+
+- Explain why, not only what.
+- Prefer short sections over long essays.
+- Use examples only when they clarify a decision.
+- Keep advice tied to product behavior.
+- Separate evidence, rules, patterns, prompts, and reviews.
+
+## Avoid
+
+- Filler paragraphs.
+- Generic design slogans.
+- Unreviewable taste claims.
+- Long prompt dumps.
+- Duplicating the same concept under new names.
+- Inventing rules without research.
+
+## Good Documentation Answers
+
+Every substantial document should make these clear:
+
+- What problem does this solve?
+- Who uses it?
+- When should it be applied?
+- What should an agent do with it?
+- How can the result be reviewed?
+
+## Naming
+
+- Use lowercase plural folder names: `research/`, `rules/`, `patterns/`, `prompts/`, `skills/`.
+- Use uppercase topic files in `docs/`: `PRODUCT_THINKING.md`, `MOBILE_FIRST.md`.
+- Use stable rule IDs in `rules/`: `UX-001.md`, `A11Y-001.md`.
+- Do not create a new folder when an existing folder already owns the concept.
+
+## TODO Placeholders
+
+Use TODO placeholders only when they mark a real missing artifact. Keep them specific and easy to remove.

package/docs/TRACEABILITY.md

@@ -0,0 +1,45 @@
+# Traceability
+
+Traceability proves that a design decision is connected to the knowledge graph.
+
+Use this chain:
+
+```text
+feature -> observation -> research -> rule -> pattern -> prompt -> reference implementation -> review
+```
+
+## Purpose
+
+Traceability prevents agents from designing from taste. If a decision cannot be traced, the missing layer should be named instead of inventing new guidance.
+
+## Traceability Fields
+
+- Feature: product area being validated.
+- Observation: concrete product or reference-project behavior.
+- Research: source research that supports the observation.
+- Rule: reviewable instruction derived from research.
+- Pattern: reusable composition of rules.
+- Prompt: agent instruction that applies the pattern.
+- Reference implementation: reference project surface or workflow.
+- Review: checklist or review question used to validate the result.
+- Gap: missing layer, if any.
+
+## Coverage Levels
+
+- Covered: every layer exists and links to the next layer.
+- Partial: some layers exist, but one or more links are weak or missing.
+- Missing: the feature cannot be supported by the current graph.
+
+## Validation Rule
+
+Do not create new rules, patterns, or prompts during traceability review. Record missing layers and decide later whether the architecture needs new objects.
+
+## DesignLint Relevance
+
+Future DesignLint should use traceability to detect:
+
+- orphan rules;
+- patterns without rules;
+- prompts without patterns;
+- reference projects without validation links;
+- feature decisions without source research.

package/evidence/README.md

@@ -0,0 +1,64 @@
+# Evidence
+
+Benchmark results are stored here.
+
+- [2026-06-25 Todo run](todo/2026-06-25-codex-gpt-5/README.md): directional evidence.
+- [2026-09-28 paired rendered Todo run](todo/2026-09-28-codex-paired-todo/README.md): frozen source, forty screenshots, runtime checks, and an internal unblinded comparison with mixed results.
+
+Do not add fabricated scores.
+
+Every benchmark result should include:
+
+- scenario name;
+- run date;
+- model and provider;
+- generation surface;
+- temperature or sampling settings;
+- tool access;
+- baseline prompt;
+- AI Design Rules prompt;
+- baseline output;
+- AI Design Rules output;
+- screenshots or preview links;
+- completed evaluation rubric;
+- evaluator notes.
+
+Validate all stored runs with:
+
+```bash
+npm run benchmark:validate
+```
+
+## Evidence Levels
+
+- `directional`: raw prompts, outputs, scorecards, and evaluator notes are present, but the implementation is not rendered or has no local visual evidence. It must not be described as proof of product quality.
+- `rendered`: both comparison outputs are runnable or rendered, and each run stores at least one local screenshot path. The harness verifies that every declared screenshot stays inside its matching run directory and is a regular file with a supported image signature; it does not score pixels or certify a result as production-ready.
+
+Suggested structure:
+
+```text
+evidence/
+  todo/
+  notes/
+  chat/
+  settings/
+  shopping/
+  mobile-home/
+```
+
+Each scenario folder should contain one folder per run.
+
+Example:
+
+```text
+evidence/todo/2026-06-25-model-name/
+  baseline-prompt.md
+  rules-prompt.md
+  baseline-output/
+  rules-output/
+  screenshots/
+  evaluation.md
+  metadata.json
+```
+
+Results are evidence only when raw outputs and scoring notes are included.

package/evidence/TEMPLATE.md

@@ -0,0 +1,46 @@
+# Benchmark Evidence Run Template
+
+Create one directory per scenario and run, then validate it with `npm run benchmark:validate`.
+
+```text
+evidence/<scenario>/<yyyy-mm-dd-model>/
+  README.md
+  EVALUATION.md
+  baseline/
+    metadata.json
+    prompt.md
+    generated-output.md
+    notes.md
+    scores.md
+    screenshots/                 # required when evidence_level is rendered
+  ai-design-rules/
+    metadata.json
+    prompt.md
+    generated-output.md
+    notes.md
+    scores.md
+    screenshots/                 # required when evidence_level is rendered
+```
+
+Both `metadata.json` files must contain the same benchmark setup and differ only in `run_type` (`baseline` or `ai-design-rules`) and run-specific limitations.
+
+```json
+{
+  "scenario": "Todo App",
+  "run_type": "baseline",
+  "date": "2026-07-14",
+  "model": "Model name",
+  "provider": "Provider",
+  "generation_surface": "CLI or product surface",
+  "temperature": "0.2",
+  "tool_access": ["filesystem write"],
+  "implementation_target": "Rendered responsive web app",
+  "evaluator": "Evaluator name or handle",
+  "rubric_version": "docs/EVALUATION_RUBRIC.md@v0.1.0",
+  "evidence_level": "rendered",
+  "screenshots": ["baseline/screenshots/mobile.png", "baseline/screenshots/desktop.png"],
+  "limitation": "Any remaining comparability limit"
+}
+```
+
+Use `directional` only when rendered, local visual evidence does not exist. Do not upgrade the level based on a score alone.

package/evidence/chat/.gitkeep

@@ -0,0 +1 @@
+

package/evidence/mobile-home/.gitkeep

@@ -0,0 +1 @@
+

package/evidence/notes/.gitkeep

@@ -0,0 +1 @@
+

package/evidence/settings/.gitkeep

@@ -0,0 +1 @@
+

package/evidence/shopping/.gitkeep

@@ -0,0 +1 @@
+

package/evidence/todo/.gitkeep

@@ -0,0 +1 @@
+

package/evidence/todo/2026-06-25-codex-gpt-5/EVALUATION.md

@@ -0,0 +1,66 @@
+# Todo App Evaluation
+
+Scenario: Todo App
+Run: 2026-06-25-codex-gpt-5
+Model: Codex GPT-5
+Evaluator: Codex GPT-5, single evaluator
+Date: 2026-06-25
+
+## Score Table
+
+| Category | Baseline | AI Design Rules | Difference | Notes |
+| --- | ---: | ---: | ---: | --- |
+| Product Thinking | 6 | 8 | +2 | AI Design Rules output centers the daily surface and primary action more clearly. |
+| UX | 6 | 8 | +2 | AI Design Rules output reduces capture friction and improves recovery. |
+| Information Architecture | 6 | 8 | +2 | AI Design Rules output names the task object and separates required from optional fields. |
+| Navigation | 6 | 7 | +1 | AI Design Rules output keeps Today stable and uses context-preserving detail. |
+| Accessibility | 5 | 7 | +2 | AI Design Rules output specifies labels, target size, keyboard order, and text errors. |
+| Mobile-first | 5 | 8 | +3 | AI Design Rules output defines mobile bottom sheet and reachable primary action behavior. |
+| Visual Hierarchy | 6 | 7 | +1 | AI Design Rules output is clearer but not visually rendered. |
+| State Design | 5 | 8 | +3 | AI Design Rules output gives specific empty, loading, failed save, and retry behavior. |
+| Consistency | 6 | 8 | +2 | AI Design Rules output keeps one product model across mobile and desktop. |
+| Performance Awareness | 5 | 7 | +2 | AI Design Rules output preserves the shell during loading; no measured performance data. |
+| Simplicity | 5 | 8 | +3 | AI Design Rules output avoids dashboard cards and keeps metadata secondary. |
+| Overall Product Quality | 6 | 8 | +2 | AI Design Rules output is more coherent as a consumer todo product. |
+
+Baseline average: 5.58
+AI Design Rules average: 7.67
+Difference: +2.09
+
+## Evidence Links
+
+- Baseline prompt: `baseline/prompt.md`
+- Baseline output: `baseline/generated-output.md`
+- Baseline metadata: `baseline/metadata.json`
+- Baseline notes: `baseline/notes.md`
+- Baseline scores: `baseline/scores.md`
+- AI Design Rules prompt: `ai-design-rules/prompt.md`
+- AI Design Rules output: `ai-design-rules/generated-output.md`
+- AI Design Rules metadata: `ai-design-rules/metadata.json`
+- AI Design Rules notes: `ai-design-rules/notes.md`
+- AI Design Rules scores: `ai-design-rules/scores.md`
+
+## Strongest Improvements
+
+- Mobile-first behavior improved from generic responsive stacking to explicit reachable actions and bottom-sheet detail.
+- State design improved from generic empty/loading/error states to input-preserving failed-save recovery.
+- Simplicity improved by removing dashboard summary cards and keeping optional metadata secondary.
+- Product thinking improved by centering the Today surface and low-friction capture.
+
+## Weaknesses
+
+- This run produced Markdown UI artifacts, not rendered implementations.
+- No screenshots were captured.
+- The same model and evaluator generated and scored both outputs.
+- The conversation already contained repository context, so the baseline is not perfectly isolated.
+- Performance was judged from described behavior, not measured runtime data.
+
+## Does This Support The Project Claim?
+
+This benchmark provides directional support, not proof.
+
+The AI Design Rules output scored higher in every category in this single run, especially mobile-first behavior, state design, simplicity, and product thinking.
+
+However, the evidence is not strong enough for broad claims because it uses one model, one evaluator, no screenshots, no rendered implementation, and an imperfectly isolated baseline.
+
+The next experiment should use a clean session, produce rendered implementations, capture screenshots, and include at least one independent evaluator.

package/evidence/todo/2026-06-25-codex-gpt-5/README.md

@@ -0,0 +1,40 @@
+# Todo App Benchmark Run
+
+Date: 2026-06-25
+
+Model: Codex GPT-5
+
+Scenario: `benchmarks/todo-app.md`
+
+## Contents
+
+- `baseline/` - baseline AI run using only the raw benchmark prompt.
+- `ai-design-rules/` - run using the AI Design Rules prompt.
+- `EVALUATION.md` - comparative rubric scoring and notes.
+
+## Result Summary
+
+| Run | Average Score |
+| --- | ---: |
+| Baseline AI | 5.58 |
+| AI + AI Design Rules | 7.67 |
+
+Difference: +2.09
+
+## Interpretation
+
+This run gives directional evidence that AI Design Rules improved the generated Todo App artifact in this setting.
+
+It does not prove general improvement.
+
+The main limitations are:
+
+- same model generated both outputs;
+- same evaluator scored both outputs;
+- baseline was generated in a repository-aware conversation;
+- outputs are Markdown UI artifacts, not rendered implementations;
+- no screenshots were captured.
+
+## Next Run Recommendation
+
+Repeat this benchmark in a clean session with rendered implementations, screenshots, and at least one independent evaluator.

package/evidence/todo/2026-06-25-codex-gpt-5/ai-design-rules/generated-output.md

@@ -0,0 +1,163 @@
+# Generated Output: AI Design Rules Todo App
+
+## Product
+
+Name: Today List
+
+Today List is a mobile-first consumer todo app centered on one stable daily surface. The app helps a busy person capture a task before organizing it, see today's useful work, complete tasks, and inspect details without losing the list.
+
+## Main Surface
+
+Primary screen: `Today`
+
+The first screen shows:
+
+- current date;
+- quick capture input;
+- today's active tasks;
+- completed tasks collapsed below active tasks;
+- quiet status feedback for saved, saving, and failed tasks.
+
+No dashboard cards are shown. The first viewport is reserved for the current tasks and the add action.
+
+## Core Object
+
+Object: `Task`
+
+Required fields:
+
+- title;
+- completion state.
+
+Optional fields:
+
+- note;
+- due time;
+- repeat;
+- list;
+- priority.
+
+Optional fields are hidden until the user opens detail.
+
+## Core Interactions
+
+### Quick Capture
+
+The user types a task into a single input and presses `Add`.
+
+The task appears immediately in Today with a quiet `Saving` status.
+
+If saving fails, the task remains in place with:
+
+- visible failed state;
+- `Retry`;
+- `Edit`;
+- preserved text.
+
+### Complete Task
+
+The user taps a 44px checkbox row target.
+
+The task moves to completed state in place first, then collapses under `Completed today`.
+
+### Inspect Details
+
+The user selects a task row.
+
+Desktop:
+
+- a side panel opens beside the Today list.
+- the Today list remains visible.
+
+Mobile:
+
+- a bottom sheet opens over the Today list.
+- the sheet has a clear close control.
+- the task title remains visible at the top.
+
+### Edit Optional Details
+
+Inside detail, the user can add note, due time, repeat, list, or priority.
+
+These fields do not block capture.
+
+## Empty State
+
+Title: `Nothing for today`
+
+Text: `Add one thing to get it out of your head.`
+
+Primary action: focused quick capture input.
+
+## Loading State
+
+Keep the Today header and quick capture input visible.
+
+Show two quiet task row skeletons below. Do not replace the whole screen with a spinner.
+
+## Error State
+
+Task save failure appears on the affected task row.
+
+Message: `Not saved. Retry?`
+
+Actions:
+
+- `Retry`;
+- `Edit`.
+
+The task text is preserved.
+
+## Accessibility Notes
+
+- Primary input has label `New task`.
+- Add button has label `Add task`.
+- Task rows have accessible names using task title and completion state.
+- Checkbox row target is at least 44px high.
+- Detail sheet close control is labeled.
+- Error state uses text, not color alone.
+- Keyboard order: quick add -> task rows -> detail fields -> close.
+
+## Responsive Behavior
+
+Mobile:
+
+- quick capture stays near the bottom action zone or immediately above the task list depending on viewport.
+- primary add action remains reachable.
+- detail opens as a bottom sheet.
+- no multi-column dashboard layout.
+
+Desktop:
+
+- Today list remains primary.
+- detail can open as a side panel.
+- additional width improves inspection without changing the product model.
+
+## Applied Rules
+
+- `PRD-001` Daily Actions First
+- `PRD-002` Low-Friction Capture Before Organization
+- `IA-001` One Stable Home Surface
+- `IA-002` Define The Object Model Before Screens
+- `UX-001` Thumb-Zone Primary Actions
+- `UX-002` Progressively Disclose Power
+- `UX-003` Preserve Context During Inspection
+- `VIS-001` Semantic Tokens Only
+- `A11Y-001` 44x44 Touch Targets
+
+## Applied Patterns
+
+- `PAT-001` Daily Home Surface
+- `PAT-002` Quick Capture
+- `PAT-003` Mobile Primary Action
+- `PAT-004` Progressive Detail
+- `PAT-005` Context-Preserving Preview
+- `PAT-006` Object Status List
+
+## Known Output Characteristics
+
+- The output is more focused on the daily task surface.
+- Optional details are secondary.
+- Mobile and desktop share the same product model.
+- State behavior preserves user input and orientation.
+- The artifact is a design specification, not a rendered implementation.