@ztothez/design-engineering 2.0.0

package/clean-room-ux-design-spec.md

@@ -0,0 +1,1431 @@
+# Clean-Room Design Specification: UX Design Intelligence, Audit, Preview, and Agent Integration Platform
+
+**Status:** Clean-room engineering specification
+**Reference inputs:** `ux-pilot-main.zip` and `ui-ux-pro-max-skill-2.15.0-source-code.zip`
+**Purpose:** Define an implementation-independent system that can reproduce the externally meaningful UX-design, design-intelligence, audit, preview, persistence, and agent-integration behaviors evidenced by the two reference projects without reconstructing their source code.
+
+## Classification Legend
+
+- **Observed** — directly evidenced by documentation, manifests, command help, generated-output behavior, or behavioral tests in the reference material.
+- **Required** — necessary for compatibility with an externally observable behavior identified in the references.
+- **Inferred** — a requirement reasonably necessary to make the observed behavior reliable, secure, or operable, but not uniquely dictated by the references.
+- **Implementation Choice** — one of multiple valid ways to satisfy the requirement; an independent team is free to choose another method.
+
+---
+
+# 1. Executive Summary
+
+The reference material describes two complementary product concepts.
+
+**Reference A** is an end-to-end UX workflow assistant. It conducts structured product discovery, stores a persistent UX brief, audits an existing interface, optionally supplements static analysis with browser screenshots, presents a scored report, runs a local live-preview environment, supports iterative screen approval, and exports a UX specification and framework-oriented components.
+
+**Reference B** is a design-intelligence and agent-integration platform. It maintains local searchable design knowledge covering product categories, visual styles, color systems, typography, charts, UX guidance, animation guidance, icon guidance, and implementation stacks. It can synthesize a project-level design system, persist a global design direction plus page overrides, expose targeted search through a command-line interface, and install assistant-specific skill material for multiple coding agents.
+
+The clean-room target system specified here combines those externally meaningful capabilities into one modular platform with six principal responsibilities:
+
+1. **Project understanding and discovery** — determine product type, audience, workflows, design goals, implementation stack, and operational constraints.
+2. **Design intelligence** — query a versioned local knowledge catalog and synthesize coherent design-system recommendations.
+3. **UX auditing** — inspect static project artifacts and, when available, rendered interfaces; produce traceable findings and a score.
+4. **Interactive preview and validation** — present candidate screens or design directions locally, support live reload, and record user decisions.
+5. **Persistence and export** — maintain a durable project brief/design-system source of truth and export implementation-independent specifications plus optional framework adapters.
+6. **Agent and CLI integration** — expose stable commands, machine-readable output, and assistant-specific installation adapters.
+
+The target architecture deliberately does **not** require the original search algorithm, original file layout, internal module names, original wording of design rules, or source-code transformations. Compatibility is defined by observable contracts, not internal replication.
+
+---
+
+# 2. System Purpose
+
+The system shall help an AI coding assistant, designer, or developer move from an ambiguous UI/UX request to a validated and documented interface direction.
+
+### Core purpose
+
+**Required:** The system must be able to answer four classes of user intent:
+
+- **Design:** create or recommend a coherent visual/interaction direction for a new page, product, component, or flow.
+- **Review:** inspect an existing project or rendered interface for usability, accessibility, responsive-design, SEO/UI, and consistency problems.
+- **Iterate:** present alternatives, collect approval/rejection/commentary, and maintain decisions across sessions.
+- **Implement/Export:** provide implementation guidance appropriate to the detected or selected technology stack and emit a durable specification.
+
+### Secondary purpose
+
+**Observed:** The larger reference also supports installation into multiple AI coding assistants and provides broader design-related capabilities such as design systems, brand-oriented assets, slides, banners, icons, and visual-identity workflows.
+
+**Implementation Choice:** These broader capabilities should be implemented as optional extension modules rather than coupled to the core UX engine. Core compatibility does not require every asset-generation capability unless those skills are intentionally exposed as public product features.
+
+---
+
+# 3. Scope
+
+## 3.1 In scope
+
+- Natural-language requirement interpretation for UI/UX work.
+- Structured discovery dialogue.
+- Persistent project UX brief.
+- Local design-knowledge search.
+- Design-system synthesis.
+- Domain-specific guidance queries.
+- Stack-specific implementation guidance.
+- Static interface/code audit.
+- Optional rendered/browser-based visual audit.
+- Scoring and severity classification.
+- Human-readable HTML and Markdown reports.
+- Local preview server with live reload.
+- Multiple named design alternatives.
+- User validation state for screens/design decisions.
+- Design-system persistence with global and page-level scopes.
+- Machine-readable output for automation.
+- Framework-aware export adapters.
+- Multi-assistant installation adapters.
+- Catalog versioning, validation, provenance, and freshness management.
+- Security controls around local project data, tokens, preview serving, and persistence.
+
+## 3.2 Out of scope
+
+- Reproducing the original source code or internal algorithms.
+- Recreating original wording of proprietary or copyrighted rule text.
+- Treating internal class/function/file organization as architectural requirements.
+- Automatically installing operating-system software on behalf of an AI agent.
+- Executing arbitrary project code as part of a static scan.
+- Guaranteeing legal compatibility or licensing equivalence with the reference repositories.
+- Full application business logic generation unrelated to UI/UX.
+
+---
+
+# 4. Functional Requirements
+
+## FR-1: Intent Classification
+
+**Required:** Given a user request, the system shall classify it into one or more of:
+
+- new design/system direction;
+- focused UX/design question;
+- project audit;
+- preview/iteration;
+- export;
+- stack-specific implementation guidance;
+- installation/update/removal of assistant integration.
+
+**Inferred:** Intent classification should be deterministic enough that equivalent requests produce the same operational mode unless additional context changes the result.
+
+## FR-2: Project and Stack Detection
+
+**Observed:** The references detect common web frameworks and provide guidance across web, native mobile, and desktop stacks.
+
+**Required:** The system shall inspect recognizable project metadata and classify the implementation stack when evidence exists.
+
+**Required:** If stack detection is inconclusive and stack-specific guidance materially affects the answer, the system shall report uncertainty rather than silently selecting a stack.
+
+**Implementation Choice:** Detection may be signature-based, manifest-based, AST-based, or delegated to an adapter framework.
+
+## FR-3: Structured Discovery
+
+**Observed:** Reference A conducts one-question-at-a-time discovery, offers fixed choices plus free text, skips irrelevant questions, and attempts to reach a useful brief with minimal questioning.
+
+**Required:** Discovery shall cover at minimum:
+
+- product purpose;
+- user/audience;
+- principal tasks and flows;
+- business or conversion goals where relevant;
+- content/data characteristics;
+- accessibility constraints;
+- responsive/device context;
+- design/style preferences;
+- SEO/discoverability needs where relevant;
+- technical stack and deployment constraints.
+
+**Required:** Questions may be skipped when prior answers make them irrelevant or redundant.
+
+**Required:** The resulting brief must clearly distinguish user-provided facts from inferred assumptions.
+
+## FR-4: UX Brief Persistence
+
+**Observed:** Reference A persists a project-level Markdown brief and updates design-decision and validated-screen sections over time.
+
+**Required:** The system shall maintain a durable project brief as a source of truth for later design, audit, preview, and export phases.
+
+**Required:** Updates shall preserve unrelated sections.
+
+**Inferred:** Writes should be atomic and recoverable from interruption.
+
+## FR-5: Design-Knowledge Search
+
+**Observed:** Reference B exposes local search over design domains and stack-specific guidance. Search can return human-readable or JSON output, and an empty result is explicitly distinguishable from a match.
+
+**Required:** The system shall support focused search across conceptual domains including at least:
+
+- visual style;
+- color/palette;
+- typography;
+- product/category patterns;
+- landing/flow patterns;
+- UX/accessibility guidance;
+- chart/data-visualization guidance;
+- icon guidance;
+- animation/motion guidance;
+- framework/stack-specific implementation guidance.
+
+**Required:** Search results shall include stable identities or provenance metadata sufficient to trace why a recommendation was returned.
+
+**Required:** A zero-match query shall be reported as zero results and must not be silently converted into fabricated catalog evidence.
+
+## FR-6: Design-System Generation
+
+**Observed:** Reference B synthesizes a coherent design direction from multiple knowledge domains and returns pattern, style, colors, typography, effects, constraints, anti-patterns, and checklist-like guidance.
+
+**Required:** For new projects/pages or system-wide visual direction, the system shall be able to produce a design-system recommendation containing:
+
+- project/category interpretation;
+- structural/pattern recommendation;
+- visual-style direction;
+- semantic color roles;
+- typography direction;
+- spacing/density guidance;
+- interaction/motion guidance;
+- accessibility constraints;
+- component/state guidance;
+- anti-patterns/avoidances;
+- source/provenance information;
+- assumptions and unresolved choices.
+
+**Required:** Recommendations must be internally coherent; e.g., dark-theme intent must not be paired with a contradictory light-only palette without an explicit rationale.
+
+## FR-7: Adjustable Design Dials
+
+**Observed:** Reference B exposes three user-tunable axes roughly corresponding to visual variance, motion intensity, and density.
+
+**Required for compatibility mode:** The system shall accept bounded numeric controls for:
+
+- design variance / conventionality;
+- motion intensity;
+- interface density.
+
+**Implementation Choice:** Internally these may influence ranking, generation constraints, token values, or post-processing.
+
+## FR-8: Design-System Persistence
+
+**Observed:** Reference B persists a global design-system master plus page-specific overrides. Existing global state is preserved unless explicit overwrite is requested.
+
+**Required:** The persistence model shall support:
+
+- one project-wide canonical design-system document;
+- zero or more page/screen override documents;
+- override precedence where page-specific values supersede global defaults only for that page;
+- non-destructive default behavior;
+- explicit authorization for overwrite/force operations.
+
+## FR-9: Static UX Audit
+
+**Observed:** Reference A scans markup/project artifacts for issues such as heading hierarchy, missing alternative text, missing form labels, missing metadata, viewport issues, responsive-table problems, fixed widths, small touch targets, small text, navigation wrapping, and horizontal overflow.
+
+**Required:** Static audit shall evaluate at minimum:
+
+- accessibility semantics;
+- form labeling and feedback;
+- document structure;
+- responsive-layout hazards;
+- touch-target usability;
+- typography legibility;
+- image/media semantics;
+- navigation resilience;
+- basic SEO/document metadata relevant to front-end UX;
+- obvious overflow and fixed-dimension hazards.
+
+**Required:** Every finding shall include:
+
+- severity;
+- category;
+- human-readable explanation;
+- affected artifact/location when known;
+- violated requirement or rule identity;
+- suggested remediation expressed as behavior or outcome;
+- confidence/evidence type.
+
+## FR-10: Rendered Visual Audit
+
+**Observed:** Reference A optionally uses browser automation to capture multiple viewport sizes and identify visual problems that static analysis cannot reliably establish.
+
+**Required:** When browser-rendered inspection is available, the system shall support visual checks for:
+
+- viewport overflow;
+- clipping;
+- overlap;
+- unreadable text;
+- dense or undersized touch targets;
+- navigation fit;
+- responsive failures;
+- horizontal scrolling;
+- state/interaction issues observable in the rendered page.
+
+**Required:** When browser automation is unavailable, the audit shall degrade gracefully to static analysis and explicitly state that rendered visual validation was not performed.
+
+## FR-11: Audit Scoring and Reports
+
+**Observed:** Reference A produces a score out of 100, severity grouping, category breakdown, a self-contained HTML report, and natural-language fix prompts. Mobile/responsive issues receive elevated penalty weight in the tested behavior.
+
+**Required:** The system shall produce:
+
+- normalized overall score;
+- findings grouped by severity;
+- category-level summary;
+- count of actionable findings;
+- remediation guidance;
+- evidence references and optional screenshots;
+- both machine-readable and human-readable output.
+
+**Required for Reference-A compatibility:** A self-contained HTML report shall be available and shall not depend on remote assets to render its core content.
+
+**Implementation Choice:** The exact scoring formula may differ if the output scale and severity meaning remain documented and consistent. If strict score compatibility is required, a separate compatibility profile should freeze weights and penalties.
+
+## FR-12: Preview and Iteration
+
+**Observed:** Reference A runs a local preview server, serves screen HTML and shared styling, supports server-sent live reload, and presents multiple named design variants.
+
+**Required:** The preview subsystem shall:
+
+- bind to a local-safe interface by default;
+- select an available port without disrupting common project development ports;
+- serve generated preview artifacts;
+- provide a live-update mechanism;
+- return explicit not-found responses for missing preview resources;
+- support 2–3 meaningful variants for a screen when alternatives are requested;
+- use descriptive variant names rather than numeric-only labels;
+- associate each variant with rationale and applicable UX rules/constraints.
+
+## FR-13: Validation State
+
+**Observed:** Screen approvals and design decisions are written back into persistent project documentation.
+
+**Required:** A user shall be able to mark a design alternative as approved, rejected, or requiring revision.
+
+**Required:** Approved decisions shall be durable and discoverable by later export/build steps.
+
+## FR-14: Export
+
+**Observed:** Reference A exports a UX specification and can convert approved screens into multiple front-end framework formats.
+
+**Required:** The system shall always be able to export an implementation-independent UX specification containing:
+
+- brief;
+- flows;
+- validated screens;
+- design-system decisions;
+- accessibility requirements;
+- rules/constraints applied;
+- unresolved assumptions.
+
+**Optional compatibility adapter:** It may also generate framework-specific components for supported targets. Such generation must preserve behavior and semantics rather than reproduce source code from the references.
+
+## FR-15: Assistant Integration Installer
+
+**Observed:** Reference B exposes an installer capable of targeting multiple AI coding assistants, project-local or global installation, forced overwrite, update, version listing, and uninstall workflows.
+
+**Required:** The system shall use an adapter abstraction so assistant-specific file layout and activation instructions are isolated from the core design engine.
+
+**Required:** Installation must be idempotent where possible and must not overwrite existing user files without explicit force/overwrite authorization.
+
+---
+
+# 5. Non-Functional Requirements
+
+## 5.1 Reliability
+
+- **Required:** Catalog query failure must not be presented as a successful result.
+- **Required:** Persistence operations must avoid partial/corrupt canonical documents.
+- **Required:** Preview-server shutdown must release resources cleanly.
+- **Required:** Unknown frameworks or missing optional tools must result in degraded capability, not catastrophic failure.
+
+## 5.2 Performance
+
+- **Inferred target:** Typical local focused-search operations should complete interactively, ideally well under one second on a developer workstation for catalog sizes comparable to the references.
+- **Inferred target:** Design-system synthesis should normally complete within a few seconds excluding external model latency.
+- **Inferred target:** Static audit should scale approximately linearly with project files scanned.
+- **Inferred:** Rule/catalog loading should be demand-driven rather than eagerly loading the entire knowledge base into an AI model context.
+
+## 5.3 Portability
+
+- **Observed:** Reference behavior spans common desktop operating systems and many front-end/native stacks.
+- **Required:** Core local search and persistence should avoid platform-specific dependencies where practical.
+- **Required:** OS-specific behaviors such as opening reports or storing global integrations must be abstracted behind platform adapters.
+
+## 5.4 Accessibility
+
+- **Required:** Generated design recommendations and audits must treat accessibility as a first-class constraint, including keyboard operation, focus visibility, contrast, reduced motion, touch target sizing, semantic labeling, and non-color-only meaning.
+
+## 5.5 Determinism and Explainability
+
+- **Required:** Given the same catalog version, query, explicit mode, and settings, the system should provide stable result identities unless nondeterminism is explicitly documented.
+- **Required:** Recommendations must be traceable to catalog entries, rules, user constraints, or clearly labeled fallback reasoning.
+
+## 5.6 Extensibility
+
+- **Required:** New design domains, technology stacks, assistant adapters, audit rules, and export adapters must be addable without redesigning the entire platform.
+
+---
+
+# 6. Observable Behavior
+
+## 6.1 Reference A observations
+
+The following are externally meaningful behaviors evidenced by its README, skill instructions, manifests, and tests:
+
+- A primary UX workflow has four phases: discovery, audit, preview, export.
+- Discovery is adaptive and persists a Markdown brief.
+- Static framework detection recognizes common web stacks and falls back to a generic/vanilla classification.
+- Audit findings contain severity, rule information, source location, and natural-language remediation.
+- A self-contained HTML audit report includes a score, severity groups, category summaries, finding numbering, and optional screenshot references.
+- Rendered visual audit is optional and has a static-only fallback.
+- Preview uses a local HTTP server with a live-reload stream and missing-resource handling.
+- Screen alternatives use descriptive names.
+- Export can produce Markdown specification material and framework-specific output.
+
+## 6.2 Reference B observations
+
+- A local command-line search accepts a free-text query and can select a design domain or implementation stack.
+- The search command provides text and JSON output modes.
+- Design-system mode aggregates multiple design dimensions.
+- Optional bounded dials affect variance, motion, and density.
+- Persistence can create a project-level master design document and page-level override.
+- Existing persisted master state is preserved by default; explicit force is required to replace it.
+- Zero results are explicitly reported as zero results, with guidance to retry rather than fabricate.
+- Multiple assistant environments can receive installed skill/instruction files through a CLI installer.
+- The repository includes data-quality, provenance, relevance, freshness, and regression tests for catalogs.
+
+## 6.3 Metadata drift observation
+
+**Observed:** Version numbers and catalog counts are not perfectly consistent across archive names, README text, manifests, and subpackages. Therefore:
+
+- exact catalog counts are **not** treated as stable compatibility requirements;
+- version metadata should be generated from one canonical release source in the clean-room design;
+- capability compatibility should be defined by schema and behavior, not by hard-coded marketing counts.
+
+---
+
+# 7. High-Level Architecture
+
+```mermaid
+flowchart LR
+    U[User / AI Coding Assistant] --> ORCH[UX Orchestrator]
+    ORCH --> DISC[Discovery & Brief Service]
+    ORCH --> INTEL[Design Intelligence Service]
+    ORCH --> AUDIT[Audit Service]
+    ORCH --> PREV[Preview & Validation Service]
+    ORCH --> EXP[Specification & Export Service]
+
+    INTEL --> CAT[(Versioned Design Catalog)]
+    INTEL --> RULES[(UX / Accessibility Rules)]
+    INTEL --> STACK[Stack Guidance Adapters]
+
+    AUDIT --> STATIC[Static Inspectors]
+    AUDIT --> BROWSER[Optional Browser Inspection Adapter]
+    AUDIT --> REPORT[Report Generator]
+
+    PREV --> LOCAL[Local Preview Server]
+    PREV --> STATE[(Validation State)]
+
+    DISC --> PROJECT[(Project State Store)]
+    INTEL --> PROJECT
+    PREV --> PROJECT
+    EXP --> PROJECT
+
+    CLI[CLI / Assistant Installer] --> ORCH
+    CLI --> ADAPTERS[Assistant Integration Adapters]
+```
+
+### Architectural principle
+
+**Required:** The AI-facing orchestration layer must consume clean contracts from deterministic local services. The model should not need to load or reason over the entire catalog at once.
+
+### Suggested deployment model
+
+**Implementation Choice:** A single local CLI package may host all services in-process, or the system may split preview/browser functions into subprocesses. No network service is required for core catalog search.
+
+---
+
+# 8. Component Responsibilities
+
+## 8.1 UX Orchestrator
+
+- classify intent;
+- inspect project context;
+- choose discovery/search/audit/preview/export workflow;
+- maintain phase state;
+- enforce user authorization boundaries;
+- combine deterministic tool output into an AI-facing context package.
+
+## 8.2 Discovery & Brief Service
+
+- maintain question definitions independent of presentation;
+- choose the next relevant question;
+- record explicit answers and assumptions;
+- render/update durable brief artifacts;
+- expose current project facts to later phases.
+
+## 8.3 Design Intelligence Service
+
+- normalize queries;
+- route them to the appropriate domain or stack;
+- rank catalog entries;
+- synthesize design-system output;
+- explain provenance and confidence;
+- abstain on unsupported or empty matches;
+- apply user-specified design dials.
+
+**Implementation Choice:** Ranking may use lexical ranking, embeddings, rules, hybrid retrieval, or deterministic expert systems. The exact algorithm is not externally required.
+
+## 8.4 Catalog Manager
+
+- load validated catalog snapshots;
+- provide stable entry IDs and aliases;
+- distinguish active, supplemental, deprecated, and legacy entries;
+- validate referential integrity;
+- record source/provenance/freshness metadata;
+- support deterministic release builds.
+
+## 8.5 Audit Service
+
+- discover scannable artifacts;
+- run static rules;
+- optionally invoke rendered/browser checks;
+- normalize findings to a common schema;
+- score results;
+- generate HTML/Markdown/JSON reports.
+
+## 8.6 Preview & Validation Service
+
+- allocate a safe local port;
+- serve generated screens/assets;
+- provide live reload;
+- handle approval/rejection/commentary events;
+- write validated decisions back to project state.
+
+## 8.7 Export Service
+
+- render canonical UX specification;
+- expose adapter interface for framework-specific component generation;
+- preserve design tokens, semantic roles, accessibility requirements, and validated behavior.
+
+## 8.8 Assistant Integration Manager
+
+- identify target assistant;
+- map generic skill material to target-specific file layout;
+- install project-local or global integration;
+- list versions/update/uninstall;
+- preserve existing files unless overwrite is explicit.
+
+---
+
+# 9. Interfaces and Contracts
+
+## 9.1 Design Search CLI Compatibility Surface
+
+A clean-room implementation seeking behavioral compatibility with Reference B should accept an interface equivalent to:
+
+```text
+search <query>
+  [--domain <domain>]
+  [--stack <stack>]
+  [--max-results <1..20>]
+  [--json]
+  [--full]
+  [--design-system]
+  [--project-name <name>]
+  [--format <ascii|markdown>]
+  [--persist]
+  [--page <name>]
+  [--output-dir <path>]
+  [--force]
+  [--variance <1..10>]
+  [--motion <1..10>]
+  [--density <1..10>]
+```
+
+### Domain values observed
+
+- style
+- color
+- chart
+- landing
+- product
+- ux
+- typography
+- icons
+- gsap/motion
+- react/performance guidance
+- web/native interface guidance
+- google-fonts/font catalog
+
+### Stack values observed
+
+- React
+- Next.js
+- Vue
+- Svelte
+- Astro
+- SwiftUI
+- React Native
+- Flutter
+- Nuxt
+- Nuxt UI
+- HTML + Tailwind
+- shadcn/ui
+- Jetpack Compose
+- Three.js
+- Angular
+- Laravel
+- JavaFX
+- WPF
+- WinUI
+- Avalonia
+- Uno Platform
+- UWP
+
+### Validation rules
+
+- query is required;
+- maximum result count must be bounded;
+- dial values must be integers in the configured range;
+- unsupported domain/stack must fail with a validation error rather than silently reroute;
+- `--format` is relevant to human-readable design-system output and should not corrupt JSON mode;
+- persistence requires a writable destination;
+- force may overwrite only the artifact explicitly governed by that flag.
+
+## 9.2 Search JSON Result Contract
+
+A machine-readable design-system result should expose conceptual fields equivalent to:
+
+```json
+{
+  "design_system": {
+    "project_name": "...",
+    "category": "...",
+    "pattern": { "...": "..." },
+    "style": { "...": "..." },
+    "colors": { "...": "..." },
+    "typography": { "...": "..." },
+    "spacing": { "...": "..." },
+    "effects": [],
+    "anti_patterns": [],
+    "constraints": [],
+    "activated_rules": [],
+    "source_identities": {},
+    "dials": {}
+  },
+  "persistence": {
+    "status": "not_requested|written|skipped|overwritten|error",
+    "paths": []
+  }
+}
+```
+
+**Implementation Choice:** Field names may differ in a new API, but a compatibility adapter should map them.
+
+## 9.3 Zero-Result Contract
+
+**Required:** A focused search with no verified match shall produce:
+
+- zero-result status;
+- searched domain/stack;
+- original query;
+- no fabricated primary result;
+- optional suggestions or retry guidance.
+
+## 9.4 UX Workflow Command Surface
+
+Reference A exposes a main UX workflow with modes equivalent to:
+
+```text
+ux-pilot
+ux-pilot audit
+ux-pilot preview
+ux-pilot export
+```
+
+A clean-room implementation may use different command names internally, but compatibility wrappers should preserve these observable modes if drop-in compatibility is a goal.
+
+## 9.5 Audit Finding Contract
+
+```text
+Finding
+- id: stable within report
+- category
+- severity: critical | high | medium | low
+- message
+- evidence_type: static | rendered | both
+- source_location: optional file/path/route/selector
+- viewport: optional
+- rule_id / requirement_id
+- remediation
+- screenshot_reference: optional
+- confidence: optional
+```
+
+## 9.6 Preview HTTP Contract
+
+At minimum:
+
+- GET screen/static resource → content or explicit 404;
+- GET shared preview styling → content;
+- live-update channel → push reload/change notification;
+- shutdown → closes listener and watchers.
+
+**Implementation Choice:** Live updates may use SSE, WebSocket, or another local mechanism; SSE is required only for strict Reference-A behavioral compatibility.
+
+## 9.7 Installer CLI Surface
+
+Observed operations include:
+
+- initialize/install integration for one assistant or all supported assistants;
+- project-local vs global installation;
+- offline/bundled asset use;
+- forced overwrite;
+- version listing;
+- CLI/asset update;
+- uninstall;
+- optional GitHub token for release metadata/download access.
+
+---
+
+# 10. Data Model
+
+## 10.1 Project
+
+Fields/concepts:
+
+- project identity and root;
+- detected stack(s);
+- user-specified product category;
+- audience/context;
+- brief status;
+- current design system;
+- validated screens;
+- audit history;
+- export history.
+
+## 10.2 UX Brief
+
+Conceptual sections:
+
+- goals;
+- user groups;
+- product/feature scope;
+- primary flows;
+- business/conversion context;
+- content/data context;
+- design preferences;
+- accessibility requirements;
+- responsive/device context;
+- SEO/discoverability requirements;
+- design decisions;
+- validated screens;
+- assumptions/unknowns.
+
+## 10.3 Catalog Entry
+
+Common fields:
+
+- stable ID;
+- display name;
+- domain;
+- status;
+- aliases;
+- searchable terms;
+- applicability constraints;
+- recommendation content;
+- anti-patterns;
+- platform/stack applicability;
+- provenance metadata;
+- freshness/version metadata;
+- deprecation/replacement relationship.
+
+## 10.4 Design System
+
+- project/category identity;
+- structural pattern;
+- style family;
+- semantic color tokens;
+- typography roles;
+- spacing/density scale;
+- radius/elevation where relevant;
+- interaction/motion rules;
+- responsive rules;
+- accessibility rules;
+- component-state guidance;
+- anti-patterns;
+- provenance/source identities;
+- page-level overrides.
+
+## 10.5 Screen Decision
+
+- screen/page identifier;
+- candidate variant identifier/name;
+- status: proposed/approved/rejected/revise;
+- rationale;
+- user comments;
+- applicable design-system version;
+- applied rules;
+- timestamp/revision.
+
+## 10.6 Audit Report
+
+- project snapshot;
+- framework/stack classification;
+- scan mode;
+- files/routes scanned;
+- browser/viewport coverage;
+- score;
+- category scores;
+- findings;
+- report version;
+- generated artifacts.
+
+---
+
+# 11. State and Data Flows
+
+## 11.1 End-to-end design flow
+
+```mermaid
+flowchart TD
+    A[User request] --> B{Existing brief?}
+    B -- no --> C[Adaptive discovery]
+    C --> D[Persist brief]
+    B -- yes --> E[Load brief]
+    D --> F[Detect project stack]
+    E --> F
+    F --> G[Generate or retrieve design system]
+    G --> H[Propose screen direction / alternatives]
+    H --> I[Local preview]
+    I --> J{User decision}
+    J -- revise --> H
+    J -- approve --> K[Persist validated screen]
+    K --> L[Export UX spec / implementation adapter]
+```
+
+## 11.2 Audit flow
+
+```mermaid
+flowchart TD
+    A[Audit request] --> B[Detect project/route]
+    B --> C[Run static inspectors]
+    C --> D{Browser inspection available?}
+    D -- yes --> E[Render selected routes at viewports]
+    E --> F[Collect visual findings/screenshots]
+    D -- no --> G[Record visual-audit unavailable]
+    F --> H[Normalize findings]
+    G --> H
+    H --> I[Score and categorize]
+    I --> J[Generate JSON/Markdown/HTML report]
+```
+
+## 11.3 Persisted design-system state
+
+```mermaid
+stateDiagram-v2
+    [*] --> Absent
+    Absent --> MasterCreated: persist
+    MasterCreated --> MasterUnchanged: persist without force
+    MasterCreated --> MasterReplaced: force overwrite
+    MasterCreated --> PageOverrideCreated: persist with page
+    PageOverrideCreated --> PageOverrideUnchanged: page exists, no force
+    PageOverrideCreated --> PageOverrideReplaced: authorized overwrite
+```
+
+---
+
+# 12. Error Handling
+
+## 12.1 Search errors
+
+- Empty or invalid query → validation error.
+- Unsupported domain/stack → validation error naming allowed values.
+- No catalog match → successful query with zero-match status, not an exception.
+- Catalog read/parse failure → error; do not return partial data as if verified.
+- Stale/deprecated-only match → either abstain or return with explicit legacy/deprecation status depending on query intent.
+
+## 12.2 Persistence errors
+
+- Destination not writable → non-destructive failure.
+- Existing master without force → skipped, not overwritten.
+- Concurrent writers → one writer succeeds; others receive conflict/skip status.
+- Interrupted write → prior complete artifact remains intact.
+- Path escaping requested output root → reject.
+
+## 12.3 Audit errors
+
+- Unsupported project framework → generic scan mode.
+- Browser automation unavailable → static-only mode plus report note.
+- Route fails to render → finding/report warning for that route; continue other routes where safe.
+- Unparseable source artifact → skip with diagnostic; do not execute it.
+
+## 12.4 Preview errors
+
+- Preferred port in use → select another allowed local port.
+- Missing preview file → HTTP 404.
+- Watcher failure → preview remains readable; live reload degrades with warning.
+- Bind to non-local interface requires explicit opt-in.
+
+## 12.5 Installer errors
+
+- Target assistant unknown → list supported targets.
+- Destination already populated → preserve unless force specified.
+- Remote rate limit → explain token/offline options without exposing secrets.
+- Update fails → keep prior installed integration intact.
+
+---
+
+# 13. Security Model
+
+## 13.1 Trust boundaries
+
+Trust zones:
+
+1. user/agent request;
+2. local project files, treated as untrusted input;
+3. validated local design catalog;
+4. optional browser runtime;
+5. local preview server;
+6. optional network updater/release source.
+
+## 13.2 Project-data protection
+
+**Required:** Core catalog search should operate locally and should not require sending project source or private identifiers to external services.
+
+**Required:** If an AI model or external generation service is used, the integration must define exactly what project data is transmitted and obtain appropriate user authorization.
+
+## 13.3 Static-scan safety
+
+- Parse project files as data.
+- Do not execute discovered scripts during static scanning.
+- If a dev server must be launched for rendered audit, do so only through an explicit project command or user-approved adapter.
+
+## 13.4 Preview-server safety
+
+- Bind to loopback by default.
+- Prevent directory traversal.
+- Serve only configured preview roots.
+- Escape user/project-derived text in generated HTML reports.
+- Do not expose secrets or arbitrary project files.
+
+## 13.5 Token management
+
+For optional remote release/update access:
+
+- accept tokens through environment variables or ephemeral CLI input;
+- never write them into generated skill files;
+- redact tokens from logs/errors;
+- prefer narrowly scoped or no-scope tokens for public-release access.
+
+## 13.6 Persistence integrity
+
+- canonicalize output paths;
+- reject writes outside allowed project/global integration roots;
+- use atomic replace for canonical files;
+- require explicit overwrite authorization;
+- optionally maintain checksums/revision metadata.
+
+## 13.7 Catalog supply-chain security
+
+- validate schema before release;
+- track provenance and source version;
+- prevent malformed aliases/duplicate stable IDs;
+- distinguish active vs deprecated entries;
+- verify bundled CLI assets match source catalog release.
+
+---
+
+# 14. Configuration
+
+Configuration should be layered:
+
+1. command-line arguments;
+2. project-local configuration;
+3. user/global configuration;
+4. safe defaults.
+
+Configurable areas:
+
+- design-search domain;
+- result count;
+- stack override;
+- design dials;
+- persistence root;
+- report output location;
+- browser-audit enablement;
+- audit viewport set;
+- preview preferred port/range;
+- catalog version;
+- assistant installation target;
+- project-local/global integration mode;
+- update source/token variable names.
+
+**Required:** Configuration must never silently override explicit user instructions.
+
+---
+
+# 15. External Dependencies and Integrations
+
+## 15.1 Core local runtime
+
+**Observed:** One reference uses TypeScript with a JavaScript runtime; another uses Python standard-library tooling for local search and TypeScript for CLI installation.
+
+**Implementation Choice:** A clean-room implementation may use one runtime or multiple runtimes. Runtime selection is not a compatibility requirement as long as command behavior and file outputs are preserved.
+
+## 15.2 Browser automation
+
+Optional integration with a browser automation provider is required for rendered visual auditing. It must support:
+
+- navigation/open local file;
+- viewport resizing;
+- screenshot capture;
+- optional DOM/console inspection.
+
+## 15.3 AI coding assistants
+
+Assistant adapters may target environments such as Claude Code, Cursor, Windsurf, GitHub Copilot, Kiro, Gemini CLI, Codex-style agents, Roo-like agents, Continue-like tools, and a generic/universal agent-skill layout.
+
+**Required:** The core design engine must not depend on any one assistant’s file layout.
+
+## 15.4 Network release/update sources
+
+Optional updater functionality may interact with a public source-control release API and/or package registry. This is separate from the local design-search runtime.
+
+---
+
+# 16. Performance and Scalability
+
+## 16.1 Catalog search
+
+- Index catalog data once per version where practical.
+- Rebuild cache/index when catalog content changes.
+- Avoid reloading large datasets into an LLM context.
+- Support hundreds to thousands of catalog entries without noticeable interactive delay.
+
+## 16.2 Auditing
+
+- Parallelize independent static inspections when safe.
+- Bound browser concurrency to avoid resource exhaustion.
+- Allow route sampling for large applications.
+- Cache unchanged-file scan results for incremental audits as an optional enhancement.
+
+## 16.3 Preview
+
+- Initial preview should become available without requiring a production build.
+- Live-reload notification should be lightweight.
+- Preview rendering should remain independent of the main application’s production server where possible.
+
+## 16.4 Persistence
+
+- Project state is small and human-readable; prioritize reliability and mergeability over database complexity.
+- For team/enterprise scale, a structured store may be added behind the same logical model.
+
+---
+
+# 17. Testing Strategy
+
+## 17.1 Unit-level behavior
+
+Test:
+
+- query validation and routing;
+- zero-result semantics;
+- alias resolution;
+- active/deprecated catalog behavior;
+- design-dial bounds;
+- project stack detection;
+- discovery skip rules;
+- brief update preservation;
+- finding normalization;
+- score calculation;
+- port selection;
+- path canonicalization;
+- persistence non-overwrite semantics.
+
+## 17.2 Catalog contract tests
+
+Validate:
+
+- unique stable IDs;
+- deterministic alias ownership;
+- referential integrity between product, style, palette, pattern, and stack records;
+- known enum values;
+- freshness/provenance shape;
+- no duplicate or malformed semantic roles;
+- current vs legacy guidance separation;
+- font/icon source consistency where applicable.
+
+## 17.3 Search relevance tests
+
+Maintain a locked evaluation set with:
+
+- positive queries;
+- hard-negative queries that should abstain;
+- ambiguous queries;
+- typo queries;
+- legacy-version queries;
+- product-category exact matches;
+- accessibility-outcome queries.
+
+Measure precision at K, reciprocal rank, and graded ranking quality or equivalent metrics.
+
+## 17.4 Discovery tests
+
+- starts with a valid first question;
+- advances after an answer;
+- skips irrelevant questions;
+- terminates when complete;
+- preserves all collected answers;
+- produces a brief containing required conceptual sections.
+
+## 17.5 Audit contract tests
+
+- missing alternative text detected;
+- missing labels detected;
+- document hierarchy issue detected;
+- responsive overflow hazards detected;
+- small touch targets detected;
+- small text detected;
+- clean fixture returns no false critical findings;
+- each finding contains remediation;
+- HTML report escapes untrusted strings;
+- screenshots render only when references exist;
+- browser-unavailable mode produces explicit fallback note.
+
+## 17.6 Preview tests
+
+- binds a local port;
+- chooses an alternate port on collision;
+- serves screen resource;
+- serves shared styling;
+- live-update channel connects;
+- missing resource returns 404;
+- stop releases port;
+- generated preview opens without console errors in supported browser baseline.
+
+## 17.7 Persistence concurrency tests
+
+- first writer creates canonical master;
+- second non-force writer does not overwrite;
+- explicit force replaces only target artifact;
+- simultaneous writes do not corrupt content;
+- page override does not mutate master unless explicitly intended.
+
+## 17.8 Installer tests
+
+For each assistant adapter:
+
+- correct project-local destination;
+- correct global destination;
+- activation guidance is accurate;
+- install is idempotent;
+- force behavior is explicit;
+- uninstall removes only managed files;
+- update preserves unrelated user files;
+- bundled asset version matches reported release version.
+
+## 17.9 Security tests
+
+- path traversal attempts rejected;
+- HTML injection in finding text escaped;
+- secret token redaction;
+- preview server not externally bound by default;
+- static audit does not execute project scripts;
+- malformed catalog fails closed.
+
+---
+
+# 18. Deployment and Operations
+
+## 18.1 Packaging
+
+The platform may be distributed as:
+
+- a CLI package;
+- a plugin/skill bundle;
+- a standalone local application;
+- or a combination of these with shared catalog assets.
+
+## 18.2 Versioning
+
+**Required:** Use one canonical release version source and generate all manifests from it.
+
+Catalog schema version and catalog content version should be independently identifiable from CLI version.
+
+## 18.3 Upgrades
+
+- Upgrades must not silently overwrite user-maintained project design state.
+- Assistant integration templates may be regenerated only with documented overwrite behavior.
+- Catalog migrations must validate schema before activation.
+- Deprecated entries should preserve stable replacement mapping when possible.
+
+## 18.4 Observability
+
+Local logs should include:
+
+- selected workflow mode;
+- catalog version;
+- detected stack/confidence;
+- files/routes scanned count;
+- browser audit availability;
+- persistence result;
+- installer target/result.
+
+Logs must not include secrets or unnecessary private project content.
+
+---
+
+# 19. Architectural Constraints
+
+1. **Behavior over implementation:** Compatibility is defined by output and interaction contracts, not original algorithms.
+2. **Local-first intelligence:** Core design search should work offline from bundled/installed data.
+3. **Demand-driven context:** Only relevant rules/catalog material should be surfaced to the model for a given task.
+4. **Non-destructive persistence:** Existing user decisions are preserved by default.
+5. **Optional visual enhancement:** Rendered audit improves quality but cannot be a hard dependency for static audit.
+6. **Adapter boundaries:** Assistant integrations and framework-specific exports must remain modular.
+7. **Explicit abstention:** The system must distinguish “no verified match” from “fallback recommendation.”
+8. **Human-readable source of truth:** Project brief and design-system state should remain inspectable without specialized tooling.
+
+---
+
+# 20. Assumptions and Unknowns
+
+## 20.1 Exact catalog counts
+
+**Observed conflict:** Catalog counts vary across README text, manifests, and archive snapshots. Exact counts are therefore not reliable external invariants.
+
+**Decision:** Treat counts as release metadata, not API requirements.
+
+## 20.2 Version identifiers
+
+**Observed conflict:** Archive naming, plugin manifests, skill manifests, package versions, and “what’s new” text are not perfectly synchronized.
+
+**Decision:** The clean-room implementation must centralize release versioning.
+
+## 20.3 Licensing metadata
+
+**Observed:** Top-level repository metadata in the larger reference indicates one license, while at least one CLI-facing document states a different license.
+
+**Unknown:** Which license governs every bundled subartifact.
+
+**Decision:** No licensing conclusion is incorporated into the technical design. Independent legal/license review is required before reusing any reference assets or text. The clean-room implementation should create its own original catalog content or use appropriately licensed sources.
+
+## 20.4 Exact audit-score formula
+
+The score is externally visible, but the exact internal weighting is only partly inferable from tests and documentation.
+
+**Decision:** Define a documented scoring model. Provide a compatibility profile only if exact numerical matching becomes a formal requirement.
+
+## 20.5 Exact search-ranking algorithm
+
+A lexical ranking approach is referenced, but it is not necessary to reproduce it.
+
+**Decision:** Preserve deterministic ranking quality, traceability, and abstention semantics; algorithm is an implementation choice.
+
+## 20.6 Optional broad design skills
+
+The larger archive contains skills beyond core UI/UX intelligence.
+
+**Unknown:** Whether these are intended as public baseline features for the same product tier.
+
+**Decision:** Treat them as extension modules unless explicitly required.
+
+---
+
+# 21. Alternative Implementation Strategies
+
+## Strategy A: Single-runtime monolith
+
+A TypeScript or Python CLI contains discovery, search, audit, preview, persistence, and installer adapters.
+
+**Advantages:** Simple packaging, one process model, easier cross-platform distribution.
+**Trade-offs:** Browser tooling and data-science/search libraries may complicate dependency management.
+
+## Strategy B: Deterministic core + thin agent adapters
+
+A standalone local core exposes JSON commands or a local RPC interface. Each AI assistant receives only a small instruction/adapter layer.
+
+**Advantages:** Strong separation, easy multi-agent support, consistent behavior.
+**Trade-offs:** More packaging/version coordination.
+
+## Strategy C: Library-first architecture
+
+Core services are libraries with separate CLIs for search, UX workflow, audit, and installer.
+
+**Advantages:** Highly testable and composable.
+**Trade-offs:** More public interfaces to version.
+
+## Strategy D: Hybrid retrieval engine
+
+Use lexical ranking for deterministic identity matching plus embeddings/rules for semantic expansion.
+
+**Advantages:** Better natural-language retrieval.
+**Trade-offs:** More complexity; must preserve reproducibility and zero-result semantics.
+
+## Strategy E: Rule engine for design-system synthesis
+
+Represent applicability and constraints in declarative data rather than procedural code.
+
+**Advantages:** Auditable, data-driven, easy catalog maintenance.
+**Trade-offs:** Requires strict schema governance and conflict resolution.
+
+---
+
+# 22. Clean-Room Implementation Guidance
+
+## 22.1 Build from contracts, not source structure
+
+An independent team should begin with the public behaviors defined in Sections 4, 6, 9, and 23. Do not copy internal filenames, class names, function names, source layout, or exact rule phrasing from the references unless a name is itself an external protocol/command that compatibility requires.
+
+## 22.2 Recreate design knowledge independently
+
+The catalog should be authored from independent sources such as:
+
+- public accessibility standards;
+- official framework/platform documentation;
+- independently authored UX heuristics;
+- public typography/color metadata with appropriate licensing;
+- original product-category reasoning rules.
+
+Avoid copying large descriptive passages from the reference datasets.
+
+## 22.3 Treat compatibility surfaces explicitly
+
+Create a compatibility layer for:
+
+- command names and flags;
+- output JSON mapping;
+- persisted artifact layout where necessary;
+- assistant-specific installation locations;
+- preview/report behavior.
+
+Keep the core implementation free to evolve behind those adapters.
+
+## 22.4 Prefer semantic output
+
+Recommendations should say what the UI must accomplish:
+
+- “interactive targets must remain comfortably operable on touch devices”;
+- “focus must remain visible”;
+- “page-specific decisions override global defaults only for that page”;
+
+rather than prescribing the original repository’s exact code patterns.
+
+## 22.5 Make abstention a feature
+
+If a design query has no verified catalog match, return no match and give a labeled fallback. This is materially safer than forcing a superficially relevant result.
+
+## 22.6 Preserve user decisions
+
+The project brief and design system are user-owned state. Regeneration must never silently erase them.
+
+---
+
+# 23. Acceptance Criteria
+
+An independent implementation satisfies this specification when the following are true.
+
+## A. Discovery and state
+
+- [ ] A new UX request can enter adaptive discovery.
+- [ ] Discovery asks one focused question at a time in compatibility mode.
+- [ ] Irrelevant questions can be skipped based on known answers.
+- [ ] A persistent project brief is generated.
+- [ ] Later design decisions can update the brief without deleting unrelated content.
+
+## B. Design intelligence
+
+- [ ] Focused local queries can target design domains.
+- [ ] Stack-specific implementation guidance can be requested separately.
+- [ ] A new-project/page request can generate one coherent design-system object.
+- [ ] Design-system output includes pattern, style, semantic colors, typography, spacing/density, motion, accessibility constraints, anti-patterns, and provenance.
+- [ ] Variance, motion, and density inputs are validated in a bounded range.
+- [ ] Zero-result queries return explicit zero-match status and do not fabricate evidence.
+
+## C. Persistence
+
+- [ ] A project-wide design master can be persisted.
+- [ ] Page-specific overrides can be persisted separately.
+- [ ] Existing master state is not replaced by default.
+- [ ] Explicit overwrite is required for destructive replacement.
+- [ ] Concurrent persistence does not corrupt artifacts.
+
+## D. Audit
+
+- [ ] Static audit identifies representative accessibility, form, metadata, responsive-layout, touch-target, typography, and overflow problems.
+- [ ] Each finding contains severity, location/evidence, rule identity, and remediation.
+- [ ] Browser-rendered audit can add viewport-specific findings when available.
+- [ ] Missing browser tooling results in a clear static-only fallback notice.
+- [ ] A normalized score and category breakdown are produced.
+- [ ] A self-contained HTML report can be generated.
+
+## E. Preview and validation
+
+- [ ] A local preview can start on an available safe port.
+- [ ] Missing preview resources return 404.
+- [ ] Preview updates can propagate without manual restart.
+- [ ] Multiple meaningful named variants can be shown.
+- [ ] Approval/rejection/revision state is persisted.
+
+## F. Export
+
+- [ ] A complete implementation-independent UX specification can be exported.
+- [ ] Validated screens and design decisions appear in the export.
+- [ ] At least one framework adapter can demonstrate implementation-specific export without depending on the original source code.
+
+## G. Agent integration
+
+- [ ] The installer can target at least one project-local and one global assistant integration path.
+- [ ] Adapter architecture supports adding further assistant targets.
+- [ ] Existing user files are preserved unless force is explicit.
+- [ ] Update/uninstall operates only on managed integration artifacts.
+
+## H. Security and governance
+
+- [ ] Core catalog search works without transmitting project data externally.
+- [ ] Preview binds to localhost by default.
+- [ ] Path traversal is rejected.
+- [ ] Secrets are redacted from logs.
+- [ ] Catalog schema/provenance validation runs before release.
+- [ ] Release version metadata is generated from one canonical version source.
+
+---
+
+# Appendix A. Compatibility-Oriented Traceability Matrix
+
+| Observable capability | Clean-room requirement |
+|---|---|
+| Four-phase UX workflow | Discovery, Audit, Preview, Export orchestration |
+| Persistent UX brief | Project state + non-destructive brief updater |
+| Framework detection | Stack detector with generic fallback |
+| Static UX checks | Rule-based static audit service |
+| Optional screenshots | Browser audit adapter with graceful fallback |
+| Scored HTML report | Report normalizer + self-contained HTML renderer |
+| Multiple named variants | Preview candidate model with descriptive names |
+| Live reload | Local update channel |
+| UX spec export | Canonical implementation-independent exporter |
+| Local design search | Domain-aware catalog search service |
+| Design-system generation | Multi-domain synthesis service |
+| Master + page overrides | Hierarchical design-state persistence |
+| Zero-result abstention | Explicit no-match contract |
+| Stack-specific guidance | Stack adapter/catalog layer |
+| Multi-agent installation | Assistant integration adapter layer |
+| Catalog relevance/freshness tests | Data governance and evaluation suite |
+
+---
+
+# Appendix B. Clean-Room Review Checklist
+
+Before implementation or release, verify:
+
+- [ ] No original source code has been copied or translated.
+- [ ] Internal names are used only when they are externally visible compatibility surfaces.
+- [ ] Rule prose is independently authored.
+- [ ] Search/reasoning algorithms are independently designed.
+- [ ] Catalog data has independent provenance and license review.
+- [ ] Exact marketing counts are not hard-coded as protocol requirements.
+- [ ] Version metadata comes from one canonical source.
+- [ ] Behavioral compatibility tests verify outputs, states, and errors rather than internal structure.
+- [ ] User-owned persisted state is non-destructive by default.
+- [ ] Zero-result and fallback behavior remain explicit.
+- [ ] Accessibility, security, and local-data protections are regression-tested.