ai-design-context 0.4.0

package/docs/EVALUATION_RUBRIC.md

@@ -0,0 +1,154 @@
+# Evaluation Rubric
+
+Use this rubric to score generated products in AI Design Context benchmarks.
+
+Score every category from `0` to `10`.
+
+## Score Meaning
+
+- `0`: absent or actively harmful.
+- `1-2`: mostly missing, confusing, or unusable.
+- `3-4`: partially present but weak or inconsistent.
+- `5-6`: acceptable baseline with visible gaps.
+- `7-8`: strong, coherent, and mostly production-ready.
+- `9-10`: excellent, polished, and hard to improve within the benchmark scope.
+
+Use whole numbers only.
+
+## Product Thinking
+
+Measures whether the output understands the user, product job, and primary repeated action.
+
+- `0`: no clear product goal.
+- `5`: plausible goal, but weak prioritization.
+- `10`: crisp user goal, primary action, and product purpose.
+
+## UX
+
+Measures flow clarity, ease of use, recovery, and task completion.
+
+- `0`: user cannot complete the core task.
+- `5`: task is possible but has friction.
+- `10`: task flow is direct, clear, and forgiving.
+
+## Information Architecture
+
+Measures object model, hierarchy, labels, grouping, and status clarity.
+
+- `0`: objects and navigation are incoherent.
+- `5`: understandable but inconsistent.
+- `10`: clear object model and predictable structure.
+
+## Navigation
+
+Measures movement between surfaces, return paths, and wayfinding.
+
+- `0`: user gets lost or trapped.
+- `5`: basic navigation exists with weak return paths.
+- `10`: navigation is simple, stable, and fast.
+
+## Accessibility
+
+Measures labels, keyboard path, contrast-sensitive choices, target size, focus, and reduced-motion awareness.
+
+- `0`: inaccessible for core actions.
+- `5`: basic accessibility is partially addressed.
+- `10`: accessibility is built into controls, states, and flow.
+
+## Mobile-First
+
+Measures narrow viewport behavior, touch reach, target size, and mobile flow quality.
+
+- `0`: mobile is unusable or ignored.
+- `5`: mobile layout works but feels secondary.
+- `10`: mobile behavior is first-class.
+
+## Visual Hierarchy
+
+Measures typography, spacing, density, visual priority, and scanability.
+
+- `0`: hierarchy is chaotic.
+- `5`: readable but generic or uneven.
+- `10`: clear, restrained, and product-specific.
+
+## State Design
+
+Measures empty, loading, error, disabled, success, and recovery states.
+
+- `0`: states are missing.
+- `5`: some states exist but are incomplete.
+- `10`: states preserve context and guide action.
+
+## Consistency
+
+Measures consistent patterns, labels, status, controls, and interaction behavior.
+
+- `0`: inconsistent and unpredictable.
+- `5`: mostly consistent with visible drift.
+- `10`: consistent without becoming rigid.
+
+## Performance Awareness
+
+Measures responsiveness, perceived performance, loading stability, and avoidance of heavy unnecessary UI.
+
+- `0`: performance risks block the task.
+- `5`: basic loading exists but may shift or block.
+- `10`: feedback is immediate and loading preserves orientation.
+
+## Simplicity
+
+Measures whether the output avoids unnecessary features, screens, fields, and decoration.
+
+- `0`: bloated or overcomplicated.
+- `5`: moderate complexity with some unnecessary elements.
+- `10`: focused and appropriately simple.
+
+## Overall Product Quality
+
+Measures the integrated product experience.
+
+- `0`: not a usable product.
+- `5`: usable prototype with meaningful gaps.
+- `10`: coherent, useful, and convincing as a modern consumer product.
+
+## Evaluation Template
+
+```md
+# Evaluation
+
+Scenario:
+Run:
+Model:
+Evaluator:
+Date:
+
+| Category | Baseline | AI Design Context | Notes |
+| --- | ---: | ---: | --- |
+| Product Thinking |  |  |  |
+| UX |  |  |  |
+| Information Architecture |  |  |  |
+| Navigation |  |  |  |
+| Accessibility |  |  |  |
+| Mobile-first |  |  |  |
+| Visual Hierarchy |  |  |  |
+| State Design |  |  |  |
+| Consistency |  |  |  |
+| Performance Awareness |  |  |  |
+| Simplicity |  |  |  |
+| Overall Product Quality |  |  |  |
+
+Baseline average:
+AI Design Context average:
+Difference:
+
+## Evidence
+
+- Baseline prompt:
+- AI Design Context prompt:
+- Baseline output:
+- AI Design Context output:
+- Screenshots or preview links:
+
+## Reviewer Notes
+
+```

package/docs/GITHUB_SETUP.md

@@ -0,0 +1,28 @@
+# GitHub Setup
+
+Use this file when preparing the public GitHub repository.
+
+The project is named **AI Design Context** and the npm package is `ai-design-context`. Keep the GitHub repository URL at `https://github.com/dev-ik/ai-design-rules`; the repository slug intentionally retains the original name.
+
+## Repository Description
+
+Evidence-driven design context and benchmarks for AI agents building products, not dashboards.
+
+## Suggested Topics
+
+- ai
+- design
+- ux
+- product-design
+- ai-agents
+- codex
+- cursor
+- design-systems
+- accessibility
+- frontend
+
+## Release Positioning
+
+The first public release should present AI Design Context as a schema-first knowledge base with benchmark-backed validation, not as a UI kit, component library, or generic design system.
+
+Do not claim broad product-quality improvement until benchmark evidence supports it across repeated runs.

package/docs/GLOSSARY.md

@@ -0,0 +1,45 @@
+# Glossary
+
+## Rule
+
+A reviewable design instruction. A rule explains why it exists, what good output looks like, what bad output looks like, and how to review the result.
+
+## Pattern
+
+A reusable product or UI solution derived from one or more rules. A pattern should describe when to use it, when not to use it, and what tradeoffs it carries.
+
+## Skill
+
+A packaged agent workflow that applies stable rules, prompts, and review steps to a recurring task.
+
+## Prompt
+
+Task-specific instruction text that helps an AI agent apply the knowledge base to a product, screen, or review. A prompt should guide decisions, not replace reasoning.
+
+## Review
+
+A structured check of an agent's output against product goals, rules, patterns, accessibility expectations, and implementation constraints.
+
+## Design QA
+
+The final quality check for design output. Design QA looks for product fit, hierarchy, spacing, responsive behavior, accessibility, and rule coverage.
+
+## Reference Project
+
+A real or realistic product archetype used to validate whether the rules work in practice. Public reference projects are omitted from the first OSS release and should be backed by benchmark evidence when added.
+
+## Product Thinking
+
+Reasoning from the user's goal, context, repeated action, and product value before choosing UI structure or visual treatment.
+
+## UX
+
+User experience: the flow, feedback, states, and interaction model that determine whether a person can complete a task with low effort.
+
+## IA
+
+Information architecture: how information, navigation, hierarchy, and destinations are organized so the product is understandable.
+
+## Design System
+
+The reusable foundation for visual and interaction decisions. In this repository, design system guidance supports rules and product outcomes; it is not a component library.

package/docs/INDEX.md

@@ -0,0 +1,109 @@
+# Documentation Index
+
+Read these files in order when you are new to AI Design Context or when an agent needs repository context.
+
+AI Design Context is a connected knowledge graph. Each layer depends on the previous one:
+
+```text
+observations -> research -> knowledge -> rules -> patterns -> prompts -> evidence -> reviews
+```
+
+This order matters because agents should not generate UI from taste. Observations capture raw evidence, research groups it, knowledge documents explain interpretation, rules extract reusable decisions, patterns compose rules into product structures, prompts teach agents how to apply patterns, benchmark evidence validates claims, and reviews feed improvements back into the graph.
+
+The `docs/` folder is the current knowledge layer.
+
+## 1. Project Overview
+
+Start with `README.md`.
+
+It explains what AI Design Context is, what it is not, who it is for, how agents should use it, and how benchmark evidence validates the project.
+
+## 2. Philosophy
+
+Read `docs/PHILOSOPHY.md`.
+
+Use it to understand the baseline: good design reduces user effort.
+
+## 3. Product Thinking
+
+Read `docs/PRODUCT_THINKING.md`.
+
+Use it before UI decisions. The product job, user context, and repeated action come first.
+
+## 4. Mobile First
+
+Read `docs/MOBILE_FIRST.md`.
+
+Use it when the product experience includes common consumer workflows, daily actions, or touch-first behavior.
+
+## 5. Design System
+
+Read `docs/DESIGN_SYSTEM.md`.
+
+Use it to understand how tokens, themes, components, and screens relate. This repository is not a component library.
+
+## 6. Knowledge Engine
+
+Read `docs/KNOWLEDGE_ENGINE.md` before adding new object types or changing repository structure.
+
+Use it as the architectural source of truth for object metadata, relationships, navigation, and future DesignLint readiness.
+
+## 7. Traceability
+
+Read `docs/TRACEABILITY.md` before validating benchmark evidence, a future reference archetype, or a design decision.
+
+Use it to identify which knowledge layer is missing instead of inventing rules or patterns.
+
+## 8. Pattern Specification
+
+Read `docs/PATTERN_SPEC.md` before creating or editing patterns.
+
+Use it as the source of truth for every pattern document.
+
+## 9. DesignLint Readiness
+
+Read `docs/DESIGNLINT_READINESS.md` before proposing validation tooling or generated indexes.
+
+Use it to understand what is machine-readable today and what remains intentionally unimplemented.
+
+## 10. Benchmark
+
+Read `docs/BENCHMARK.md` before running or publishing product generation comparisons.
+
+Use `docs/EVALUATION_RUBRIC.md` to score outputs.
+
+## 11. Style Guide
+
+Read `docs/STYLE_GUIDE.md` before editing documentation.
+
+Use it to keep contributions concise, practical, rule-based, and free of filler.
+
+## 12. Glossary
+
+Read `docs/GLOSSARY.md` when terms are unclear.
+
+Use shared vocabulary before adding new concepts.
+
+## 13. Operational Files
+
+- `AGENTS.md` - instructions for Codex, Cursor, Claude Code, and similar agents.
+- `CONTRIBUTING.md` - contribution workflow.
+- `ROADMAP.md` - planned phases.
+- `starter-kit/INSTALL_WITH_AGENT.md` - agent-driven adoption guide for an existing product repository.
+
+## 14. Working Folders
+
+- `research/` - product observations. Start with `research/GENERATED_INDEX.md`.
+- `docs/` - knowledge layer and authoring specifications.
+- `schema/` - JSON Schema definitions for knowledge object metadata.
+- `registry/` - transitional machine-readable object and relationship registry.
+- `observations/` - first-class raw evidence objects.
+- `rules/` - reviewable design rules. Start with `rules/GENERATED_INDEX.md`.
+- `patterns/` - repeatable solutions derived from rules. Start with `patterns/GENERATED_INDEX.md`.
+- `prompts/` - task-specific instructions for agents. Start with `prompts/GENERATED_INDEX.md`.
+- `examples/` - reserved space for future public reference archetypes. Start with `examples/README.md`.
+- `benchmarks/` - reproducible benchmark scenarios.
+- `evidence/` - future benchmark results and raw outputs.
+- `starter-kit/` - copyable project bootstrap kit for adopting AI Design Context in another repository.
+- `reviews/` - first-class review and validation objects.
+- `checklists/` and `templates/` - review and authoring artifacts.