ai-design-context 0.4.0

package/RELEASE_NOTES_v0.1.0.md

@@ -0,0 +1,45 @@
+# AI Design Rules v0.1.0
+
+AI Design Rules is an AI-first knowledge base for helping coding agents build products, not dashboards.
+
+This first release establishes the foundation: schema-backed knowledge objects, typed relationships, generated navigation, validation tooling, and an evidence workflow for measuring whether the rules improve AI-generated products.
+
+## Included
+
+- Schema-first metadata model for knowledge objects.
+- Registry-backed research, rules, patterns, and prompts.
+- Generated indexes and graph report.
+- Validation script and `npm run check`.
+- Benchmark methodology and evaluation rubric.
+- First Todo App benchmark evidence.
+- OSS cleanup with personal reference projects removed.
+
+## Intentionally Not Included
+
+- A UI kit or component library.
+- A Tailwind preset or design token package.
+- DesignLint implementation.
+- A large rule or pattern catalog.
+- Public reference projects.
+
+## Current Limitations
+
+- The knowledge graph is still small.
+- Manual registry updates are still required.
+- Generated indexes are transitional until more metadata is migrated.
+- Skills are documented but not yet schema-migrated.
+- Reference projects are omitted from the first OSS release.
+
+## Benchmark Caveat
+
+The first benchmark run is directional, not conclusive. It proves the evidence workflow can be used, not that AI Design Rules has statistically validated product-quality gains.
+
+Future claims should be based on repeated benchmark runs across scenarios, agents, and reviewers.
+
+## Next Roadmap
+
+- Expand benchmark coverage and independent evidence.
+- Migrate skills and checklists into the schema-first graph.
+- Improve registry automation.
+- Add generated contribution reports.
+- Prepare DesignLint requirements without implementing it prematurely.

package/RELEASE_NOTES_v0.3.0.md

@@ -0,0 +1,47 @@
+# AI Design Rules v0.3.0
+
+## Expressive Systems And Agent Context
+
+This release expands AI Design Rules from foundational product structure into evidence-backed visual direction, systematic motion, and observable agentic workflows.
+
+## Included
+
+- Seven dated observations drawn from current Apple, Google, Chrome, and Figma guidance.
+- Three research objects:
+  - Expressive System UI In 2026;
+  - Motion As State Continuity;
+  - Contextual And Observable Agentic Interfaces.
+- Three seed rules:
+  - `VIS-002` Keep Expression Subordinate To Content;
+  - `UX-004` Use Motion To Explain State Continuity;
+  - `UX-005` Expose Agent Work And Intervention.
+- A `reference-driven-design` skill for comparative, traceable visual reference briefs without copying brands.
+- Expanded visual, motion, interaction, and prompt-architecture skills.
+- Prototype Review `0.2.0` with explicit state, responsive, accessibility, motion, and agent lifecycle coverage.
+- Design QA `0.2.0` with the new rule coverage and platform fallback checks.
+- Research-led context resolution that includes downstream rules, prompts, and review gates.
+
+## Validation
+
+- Knowledge metadata and registry relationships are validated.
+- Generated indexes and graph diagnostics are synchronized.
+- DesignLint v0 reports no missing evidence-chain relationships.
+- Automated context and validation regression tests pass.
+
+## Evidence Boundary
+
+The new research and rules are `draft` and `seed`.
+
+They are supported by traceable primary-source observations, but have not yet been validated by paired rendered benchmark runs or independent evaluation. The release improves what agents can retrieve, apply, and review; it does not claim measured visual-quality improvement.
+
+The existing Todo benchmark remains directional.
+
+## Recommended Next Validation
+
+1. Add rendered benchmark scenarios for:
+   - consumer utility;
+   - dense operations or fintech;
+   - agentic workspace.
+2. Capture baseline and graph-backed outputs at desktop and mobile viewports.
+3. Store screenshots, raw prompts, evaluator identity, and review notes.
+4. Promote rules beyond `seed` only after evidence-backed review.

package/RELEASE_NOTES_v0.4.0.md

@@ -0,0 +1,29 @@
+# AI Design Rules v0.4.0
+
+## Focused Context And Applied Patterns
+
+This release makes task context more focused and explainable, applies visual and motion guidance in existing patterns, and adds the first paired rendered Todo benchmark with inspectable evidence.
+
+## Included
+
+- Context retrieval prioritizes exact identifiers and focused titles, matches whole Unicode words, and handles simple English task phrasing.
+- Required and upstream dependencies are fully resolved, optional graph expansion is bounded, and each selected object includes a selection reason. Existing JSON fields are preserved.
+- Daily Home Surface applies `VIS-001` / `VIS-002` through concrete hierarchy contracts; Context-Preserving Preview applies `UX-004` through motion, interruption, focus-return, and fallback contracts.
+- A paired Todo run stores frozen source, prompts, context bundles, forty screenshots, runtime checks, and an internal evaluation.
+- Quick Capture State Review checks keyboard access with realistic list lengths and layout geometry across saving, error, retry, and success states.
+- Consequential-action guidance connects observations and research to `UX-006`, a confirmation pattern, a review prompt, and a reference specification with specification-level validation.
+- An agent-led installation guide explains pinned integration into existing repositories while preserving project instructions and application behavior.
+
+## Validation
+
+- `npm run check` passes metadata, registry, generated-index, DesignLint, and benchmark-evidence checks.
+- All 32 automated tests pass, including context matching, dependency closure, cycle handling, platform selection, and malformed evidence cases.
+- Both Todo outputs were exercised at 390×844 and 1440×900. Capture retry, completion, detail return, edit recovery, persistence, and reduced-motion behavior were checked.
+
+## Evidence Boundary
+
+The paired run scored **7.42/10 for baseline and 7.67/10 with AI Design Rules** in an internal, unblinded evaluation. Touch targets and error-state layout improved, visual hierarchy tied, and sequential keyboard access to capture worsened from 4 to 29 Tab presses. Both prototypes remain **NEEDS WORK**.
+
+This single pair does not establish a general quality gain or compare the previous release against this one. Physical mobile keyboard behavior, independent evaluation, and a new paired run of the revised review prompt remain outstanding. Updated patterns and the review prompt retain their draft/seed maturity. Consequential-action validation remains specification-level and does not validate production domain policy or security controls.
+
+Read the [paired Todo evaluation](https://github.com/dev-ik/ai-design-rules/blob/v0.4.0/evidence/todo/2026-09-28-codex-paired-todo/EVALUATION.md) and [installation guide](https://github.com/dev-ik/ai-design-rules/blob/v0.4.0/starter-kit/INSTALL_WITH_AGENT.md).

package/RELEASE_READINESS.md

@@ -0,0 +1,107 @@
+# Release Readiness
+
+Target: `v0.4.0 — Focused Context And Applied Patterns`
+
+Verdict: PASS
+
+AI Design Rules is ready to release focused context retrieval, applied visual and motion patterns, a paired rendered Todo benchmark, and evidence-informed review checks. This release also includes the agent installation guide and consequential-action guidance added since v0.3.0.
+
+## Blockers
+
+None.
+
+## Evidence Boundary
+
+- The updated visual/motion patterns and Quick Capture review prompt remain `draft` / `seed`.
+- The first paired rendered Todo run includes frozen source, forty screenshots, context bundles, and runtime measurements. The earlier directional run remains explicitly directional.
+- The internal, unblinded evaluation scored 7.42 versus 7.67, with equal visual-hierarchy scores and a worse sequential keyboard capture path in the rules-assisted output.
+- One pair does not establish a general quality gain, independent validation, or improvement over the previous release. The revised review prompt was written after the run and still needs a new paired run.
+- Consequential-action guidance is `active` / `validated` at specification level only; it does not validate production security, financial policy, or a rendered implementation.
+- Release messaging must describe stronger retrieval, applied guidance, and review evidence without claiming broadly proven output-quality gains.
+
+## Non-Blocking Improvements
+
+- Repeat the paired Todo run with the revised review prompt and test physical mobile keyboard behavior.
+- Add rendered scenarios for dense operations, consequential actions, and agentic workspace surfaces.
+- Independently or blindly evaluate repeated rendered runs before making broader quality claims or promoting seed guidance.
+- Expand `CODE_OF_CONDUCT.md` and `SECURITY.md`; both exist but remain minimal.
+- Decide when observation intake volume justifies registry migration.
+- Keep skills outside the registry until skill metadata migration is explicitly scoped.
+
+## Branding And Scope
+
+Status: PASS
+
+- Project name remains `AI Design Rules`.
+- Tagline remains `Build products. Not dashboards.`
+- The knowledge remains vendor-neutral at the rule level and traceable to upstream evidence.
+- Reference guidance explicitly prohibits copying brand composition or proprietary assets.
+- The directional Todo reference and paired rendered evidence remain distinguishable; neither is presented as universal proof of visual quality.
+
+## Repository Hygiene
+
+Status: PASS
+
+- No local home-directory paths are stored in repository content.
+- No private product names or private roadmap references are introduced.
+- Generated indexes are updated through repository tooling.
+- Reusable skills remain intentionally outside the registry.
+- Rendered benchmark source is frozen and stored with hashes; local browser output stays ignored.
+
+## Schema And Registry
+
+Status: PASS
+
+- `npm run check` passes.
+- `npm test` passes.
+- Generated indexes are synchronized with registry metadata.
+- The graph reports no orphan objects and no missing relationship targets.
+
+Current graph counts:
+
+- Observations: 16, validated but not registry-backed.
+- Research: 12.
+- Rules: 17.
+- Patterns: 7.
+- Prompts: 5.
+- Checklists: 1.
+- Reviews: 3.
+- Reference projects: 2.
+- Skills: 16, validated but not registry-backed.
+- Registered objects: 47.
+- Relationships: 192.
+
+## Documentation Quality
+
+Status: PASS
+
+- `README.md` remains public-facing and does not overstate benchmark evidence.
+- `CHANGELOG.md` includes the full `v0.4.0` scope and evidence boundary.
+- `RELEASE_NOTES_v0.4.0.md` explains included changes and limitations.
+- `docs/AGENT_CONTEXT.md` explains lexical matching, selection reasons, and dependency expansion.
+- `docs/BENCHMARK.md` and the saved evaluation describe reproducible inputs, measured findings, and limits.
+- `docs/KNOWLEDGE_ENGINE.md` remains the architecture source of truth.
+- `docs/DESIGNLINT_READINESS.md` documents the current DesignLint v0 boundary and future scope.
+
+## GitHub Readiness
+
+Status: PASS
+
+- `.github/workflows/validate.yml` runs `npm run check` and `npm test` on pull requests and pushes to `main`.
+- Pull request and issue templates exist.
+- `LICENSE`, `CODE_OF_CONDUCT.md`, and `SECURITY.md` exist.
+
+## Recommended Release Positioning
+
+Ship as `v0.4.0 — Focused Context And Applied Patterns`.
+
+Include:
+
+- focused, explainable context retrieval with complete required dependencies;
+- concrete visual hierarchy and motion contracts in existing patterns;
+- the first paired rendered Todo evidence with explicit mixed findings;
+- keyboard-path and state-geometry review checks;
+- a bounded consequential-action guidance chain;
+- an agent-led installation guide.
+
+Position the release as a stronger retrieval and review workflow with inspectable rendered evidence. Do not claim statistically validated improvements to generated UI or production readiness of the benchmark prototypes.

package/ROADMAP.md

@@ -0,0 +1,60 @@
+# Roadmap
+
+AI Design Context grows from research-backed foundations into rules, patterns, prompts, skills, and review tooling. Each phase should produce usable artifacts without generating filler content.
+
+## v0.1 Foundation
+
+- Clarify repository structure and naming conventions.
+- Define the documentation reading order.
+- Document the agent pipeline: `research -> knowledge -> rules -> patterns -> prompts -> examples -> review`.
+- Establish contribution style and review expectations.
+
+## v0.2 Research
+
+- Expand product research under `research/products/`.
+- Capture observations from strong consumer products.
+- Separate evidence from opinion.
+- Identify which observations can become rules.
+
+## v0.3 Rules
+
+- Normalize rule format using `templates/RULE_TEMPLATE.md`.
+- Add only research-backed rules.
+- Keep rules practical, reviewable, and product-oriented.
+- Cover product, UX, IA, mobile, visual, accessibility, and performance domains.
+
+## v0.4 Patterns
+
+- Derive reusable patterns from validated rules.
+- Keep patterns product-facing, not component-library documentation.
+- Document when a pattern should and should not be used.
+
+## v0.5 Prompts
+
+- Create prompts that help agents apply the rules to real product tasks.
+- Keep prompts concise and task-specific.
+- Use benchmark scenarios as the first validation target.
+
+## v0.6 Skills
+
+- Package stable workflows into agent skills.
+- Keep skills aligned with the repository pipeline.
+- Avoid skills that bypass research, rules, or review.
+
+## v0.7 Reviews
+
+- Improve design QA checklists and review templates.
+- Add review criteria for product fit, UX, mobile, accessibility, and rule coverage.
+- Validate output against benchmark scenarios and future public reference archetypes.
+
+## v1.0 Public Release
+
+- Publish a coherent public knowledge base.
+- Provide a stable contribution workflow.
+- Include enough benchmarks, generated indexes, and skills for agents to use the system without guessing.
+
+## v2.0 DesignLint
+
+- Explore automated checks for rule coverage and design QA.
+- Detect common agent-generated design failures.
+- Keep automation explainable and tied to documented rules.

package/SECURITY.md

@@ -0,0 +1,40 @@
+# Security Policy
+
+AI Design Context ships a local npm CLI, documentation, schemas, a knowledge graph, and validation tools including DesignLint. It does not run a hosted service. Graph retrieval is read-only and offline; `init` explicitly writes agent instructions and missing templates into the current project. Installation has no initialization hooks. Review repository guidance as input to your agent, with project-specific instructions remaining authoritative.
+
+## Supported Versions
+
+Security review applies to the current `main` branch.
+
+## Reporting A Vulnerability
+
+If you find a security issue, do not open a public issue with exploit details.
+
+Use GitHub Security Advisories when available, or contact the maintainers privately through the repository owner profile.
+
+Include:
+
+- affected file or workflow;
+- impact;
+- reproduction steps;
+- whether the issue exposes private data, credentials, or unsafe automation behavior.
+
+## Scope
+
+In scope:
+
+- GitHub Actions workflow risks;
+- unsafe validation or generation scripts;
+- accidental exposure of private data;
+- malicious schema, registry, or template changes.
+
+Out of scope:
+
+- subjective design quality;
+- benchmark score disagreement;
+- missing features;
+- unsupported forks or private modifications.
+
+## Response
+
+Maintainers will review valid reports, patch the repository when needed, and document security-relevant changes in release notes.

package/assets/logo.svg

@@ -0,0 +1,9 @@
+<svg width="128" height="128" viewBox="0 0 128 128" fill="none" xmlns="http://www.w3.org/2000/svg">
+  <rect x="8" y="8" width="112" height="112" rx="24" fill="#111827"/>
+  <path d="M40 42H70C80 42 88 50 88 60V86" stroke="#F9FAFB" stroke-width="8" stroke-linecap="round"/>
+  <path d="M40 86H58C68 86 76 78 76 68V42" stroke="#F97316" stroke-width="8" stroke-linecap="round"/>
+  <circle cx="40" cy="42" r="12" fill="#F9FAFB"/>
+  <circle cx="88" cy="86" r="12" fill="#F9FAFB"/>
+  <circle cx="40" cy="86" r="12" fill="#F97316"/>
+  <circle cx="76" cy="42" r="6" fill="#111827"/>
+</svg>

package/benchmarks/README.md

@@ -0,0 +1,19 @@
+# Benchmarks
+
+Benchmark scenarios define reproducible product briefs for comparing:
+
+```text
+Baseline AI -> AI + AI Design Context
+```
+
+Do not add implementation code here.
+
+Each scenario should include:
+
+- product brief;
+- constraints;
+- expected user;
+- expected platform;
+- evaluation criteria.
+
+Use `docs/BENCHMARK.md` for procedure and `docs/EVALUATION_RUBRIC.md` for scoring.

package/benchmarks/chat.md

@@ -0,0 +1,37 @@
+# Chat Benchmark
+
+## Product Brief
+
+Create a modern consumer chat surface for a small trusted group.
+
+The app should help users read recent messages, send a message quickly, understand unread state, and inspect a conversation without losing context.
+
+## Expected User
+
+- Consumer coordinating with a small trusted group.
+- Uses mobile frequently.
+
+## Expected Platform
+
+- Responsive web app.
+- Mobile-first behavior required.
+
+## Constraints
+
+- No enterprise admin tools.
+- No public channels.
+- No bot marketplace.
+- Include empty, loading, failed-send, and offline states.
+- Keep message sending fast and clear.
+
+## Evaluation Criteria
+
+- Product Thinking
+- UX
+- Information Architecture
+- Navigation
+- Accessibility
+- Mobile-first
+- State Design
+- Performance Awareness
+- Overall Product Quality

package/benchmarks/mobile-home-screen.md

@@ -0,0 +1,38 @@
+# Mobile Home Screen Benchmark
+
+## Product Brief
+
+Create a mobile home screen for a consumer productivity app.
+
+The screen should help users understand what needs attention today, take the primary action quickly, and navigate to important areas without feeling like a dashboard.
+
+## Expected User
+
+- Consumer opening the app repeatedly during the day.
+- Wants quick orientation and one obvious next action.
+
+## Expected Platform
+
+- Mobile web app at approximately 390px width.
+- Desktop is not required for this benchmark.
+
+## Constraints
+
+- No analytics cards.
+- No dense admin dashboard.
+- Include empty, loading, and error states.
+- Primary action must be reachable.
+- Navigation must not bury the main daily action.
+
+## Evaluation Criteria
+
+- Product Thinking
+- UX
+- Information Architecture
+- Navigation
+- Accessibility
+- Mobile-first
+- Visual Hierarchy
+- State Design
+- Simplicity
+- Overall Product Quality

package/benchmarks/notes-app.md

@@ -0,0 +1,37 @@
+# Notes App Benchmark
+
+## Product Brief
+
+Create a modern consumer notes app for quick personal capture and retrieval.
+
+The app should help a user create a note quickly, find recent notes, inspect note details, and recover from failed save or sync states.
+
+## Expected User
+
+- Consumer capturing thoughts, lists, snippets, and reminders.
+- Uses mobile for quick capture and desktop for review.
+
+## Expected Platform
+
+- Responsive web app.
+- Mobile-first behavior required.
+
+## Constraints
+
+- No team workspace.
+- No publishing flow.
+- No complex folder management required.
+- Include empty, loading, and error states.
+- Preserve note content during failures.
+
+## Evaluation Criteria
+
+- Product Thinking
+- UX
+- Information Architecture
+- Navigation
+- Accessibility
+- Mobile-first
+- State Design
+- Simplicity
+- Overall Product Quality

package/benchmarks/settings.md

@@ -0,0 +1,37 @@
+# Settings Benchmark
+
+## Product Brief
+
+Create a modern consumer settings experience for account, notifications, privacy, and preferences.
+
+The app should help a user find a setting, understand consequences, change it safely, and recover from failed save states.
+
+## Expected User
+
+- Consumer configuring a personal or household app.
+- Needs clarity and trust more than density.
+
+## Expected Platform
+
+- Responsive web app.
+- Must work on mobile and desktop.
+
+## Constraints
+
+- No admin dashboard.
+- No advanced developer settings.
+- Include confirmation or recovery for risky changes.
+- Include loading, error, disabled, and saved states.
+- Privacy-related settings must be understandable.
+
+## Evaluation Criteria
+
+- Product Thinking
+- UX
+- Information Architecture
+- Navigation
+- Accessibility
+- Mobile-first
+- State Design
+- Consistency
+- Overall Product Quality

package/benchmarks/shopping-list.md

@@ -0,0 +1,37 @@
+# Shopping List Benchmark
+
+## Product Brief
+
+Create a modern consumer shopping list app for shared household use.
+
+The app should help users add items quickly, mark items bought, group or scan items, and recover from sync or save failures.
+
+## Expected User
+
+- Consumer shopping for household items.
+- Often uses the app one-handed on mobile.
+
+## Expected Platform
+
+- Responsive web app.
+- Mobile-first behavior required.
+
+## Constraints
+
+- No ecommerce checkout.
+- No delivery tracking.
+- No heavy inventory system.
+- Include empty, loading, error, and completed item states.
+- Item capture should not require category or assignee first.
+
+## Evaluation Criteria
+
+- Product Thinking
+- UX
+- Information Architecture
+- Accessibility
+- Mobile-first
+- State Design
+- Simplicity
+- Performance Awareness
+- Overall Product Quality