# UI Atlas AI Design Engine — v1 architecture

Status: implementation contract

## 1. Responsibility boundary

UI Atlas does **not** pretend to be a language model.

- The AI client interprets the user's product request and converts it into a structured `DesignRequest`.
- UI Atlas resolves canonical UI names, selects a validated screen recipe, returns component contracts and implementation assets, and audits the result.
- The AI must not invent a UI component ID or silently replace a platform-native pattern. Every selected component must resolve to the registry.
- Deterministic site/CLI search is labelled **term search**, not “AI search” or “natural-language search”. It searches canonical names, IDs, aliases, and structured facets. Requirement-level interpretation belongs to the AI through MCP or the Skill workflow.

This split makes the same registry usable by the browser, `npx` CLI, MCP clients, and offline tests.

## 2. Public layers

```text
User request
    ↓
AI client + installed UI Atlas Skill
    ↓ structured DesignRequest
UI Atlas recommend / MCP ui_atlas_recommend_screen
    ↓
ScreenDesignPlan (recipe + decisions + regions + states + checks)
    ↓
UI Atlas add / MCP ui_atlas_generate_code
    ↓
Generated or copied implementation assets
    ↓
UI Atlas audit / MCP ui_atlas_audit_plan
    ↓
AuditReport with machine-readable findings and evidence
```

Public interfaces:

1. `https://ui-atlas.pages.dev/` — human reference and canonical component URLs.
2. `/registry/ui-atlas.registry.json` — stable machine-readable registry.
3. `/llms.txt` — concise AI discovery file.
4. `npx ui-atlas ...` — install, recommend, add, inspect, and audit.
5. `npx ui-atlas mcp` — stdio MCP server exposing the same registry and rules.
6. Installed `ui-atlas` Skill — a thin workflow that calls the CLI/MCP instead of embedding 306 components in prompt text.

## 3. Versioned data model

All public JSON documents contain `schemaVersion`. Breaking schema changes require a new major schema version. Component IDs and recipe IDs are stable citation keys.

### 3.1 ComponentRecord

A `ComponentRecord` combines catalog naming, component contract, platform support, and asset links.

Required fields:

- `id`, `ja`, `en`, `aliases`, `description`
- `category`, `kind`, `placement`
- `intentFacets`: deterministic purpose/task concepts; not free-form “AI keywords”
- `semantics`: element, role, input type, selection model, persistence, background interaction
- `anatomy`, `states`, `keyboard`, `accessibility`
- `useWhen`, `avoidWhen`, `differences`, `relatedIds`
- `platformSupport`
- `assets`: canonical site URL and seven implementation paths
- `verification`: level, date, and checks actually performed

### 3.2 ScreenRecipe

A screen recipe expresses composition and behavior, not a screenshot template.

Required fields:

- `id`, bilingual names, summary, product surfaces, tasks, form factors, supported targets
- `fit`: structured recommendation facets and explicit exclusions
- `requiredDecisions`: product decisions the AI must resolve or report as assumptions
- `regions`: ordered landmarks/regions with purpose, parent, required component IDs, alternatives, content contract, and responsive behavior
- `flows`: user actions and state transitions
- `states`: loading, empty, error, success, offline, permission, or unsaved coverage as applicable
- `responsive`: named layout modes and transitions; never desktop-only coordinates
- `qualityRuleIds`: deterministic rules required by this recipe
- `references`: component IDs and canonical URLs

A recipe may reference only component IDs present in the same registry.

### 3.3 DesignRequest

The AI should call `recommend` with structured fields:

```json
{
  "schemaVersion": 1,
  "goal": "Users review orders and update fulfillment status",
  "surface": "data-management",
  "platform": "web",
  "target": "react",
  "formFactor": "responsive",
  "navigationDepth": "application",
  "dataShape": "tabular",
  "dataVolume": "high",
  "tasks": ["scan", "filter", "bulk-update", "inspect-detail"],
  "riskLevel": "medium",
  "capabilities": ["search", "sort", "bulk-actions"],
  "constraints": ["keyboard-operable", "mobile-read-only-detail"],
  "locale": "ja-JP"
}
```

`goal` is retained as human context but is not parsed as proof of intent by the deterministic engine. Recommendation is based on the structured fields. Missing high-impact decisions are returned in `openDecisions` rather than guessed silently.

### 3.4 ScreenDesignPlan

`recommend` returns a plan that can be reviewed before code is written:

```json
{
  "schemaVersion": 1,
  "kind": "ui-atlas-screen-plan",
  "registryVersion": "1.0.0",
  "request": {},
  "recipe": { "id": "data-management", "score": 92, "reasons": [] },
  "alternatives": [],
  "openDecisions": [],
  "decisionLog": [],
  "layout": {
    "modes": ["compact", "wide"],
    "transitions": [],
    "regions": []
  },
  "componentDecisions": [],
  "states": [],
  "interactions": [],
  "responsive": {},
  "quality": { "ruleIds": [], "rules": [] },
  "tokens": {},
  "warnings": [],
  "citations": [],
  "verification": {
    "registry": "verified",
    "contract": "validated",
    "runtime": "not-run",
    "accessibilityTree": "not-run",
    "visualRegression": "not-run",
    "assistiveTechnology": "not-run"
  }
}
```

Every recommendation reason names the structured request field that matched. The output must never cite model confidence as registry evidence.

### 3.5 AuditReport

```json
{
  "schemaVersion": 1,
  "passed": false,
  "summary": { "errors": 1, "warnings": 2, "passedRules": 14 },
  "findings": [
    {
      "ruleId": "state.error-recovery",
      "severity": "error",
      "path": "states",
      "message": "Error state has no recovery action",
      "remediation": "Add retry or a safe navigation target",
      "evidence": { "expected": "recoveryAction", "actual": null }
    }
  ]
}
```

Audits are deterministic. A passed audit means the declared contract/rules were satisfied; it does not claim usability research, visual review, actual assistive-technology testing, or production readiness unless those checks were separately run and recorded.

## 4. Initial recipe coverage

v1 ships common product surfaces rather than claiming every possible screen:

1. `authentication`
2. `account-settings`
3. `dashboard-overview`
4. `collection-browse`
5. `list-detail`
6. `data-management`
7. `create-edit-form`
8. `search-and-results`
9. `checkout`
10. `pricing-and-upgrade`
11. `onboarding`
12. `chat`
13. `inbox`
14. `kanban-workspace`
15. `schedule-workspace`
16. `file-workspace`
17. `profile`
18. `content-feed`
19. `product-detail`
20. `notification-center`

Recipes are compositional. For example, a data-management screen may use `viewport-shell → sidebar-navigation + page-header + filter-bar + data-grid + pagination`, with `bulk-action-bar` only when selection is enabled and a mobile transition from data grid to list/detail.

## 5. Token contract

Tokens are functional defaults, not a branded theme:

- color roles with light/dark values and contrast intent
- type roles and readable line lengths
- spacing scale based on 4px steps
- radius roles (`control`, `surface`, `overlay`)
- elevation roles
- focus ring role
- target-size minimums
- motion durations plus reduced-motion behavior
- content widths and responsive breakpoints

Generated plans reference semantic token IDs. They do not hardcode one aesthetic for every product. The AI may propose a visual direction, but changing tokens may not remove focus visibility, text contrast, target size, state differentiation, or reduced-motion support.

## 6. Quality rule families

The v1 registry includes auditable rules in these families:

- `structure.*`: one page `h1`, landmark order, region parent validity, stable IDs
- `choice.*`: one explicit primary action, destructive actions separated and confirmed
- `state.*`: loading/empty/error/success coverage and recovery paths
- `form.*`: visible labels, instructions, validation timing, error summary for long forms
- `navigation.*`: current location, back/escape behavior, no dead ends
- `responsive.*`: declared compact/wide transformation and no required hover-only action
- `accessibility.*`: names, keyboard path, focus order/return, announcements, target sizes, contrast intent
- `platform.*`: target support checked and native substitutions disclosed
- `content.*`: real content contract, truncation behavior, localization expansion
- `trust.*`: verification level and unsupported claims disclosed

Rules have `id`, severity, applicability, deterministic predicate, message, remediation, and source links.

## 7. CLI contract

```text
npx ui-atlas init --agent all --scope project|user
npx ui-atlas search <term> [--json]
npx ui-atlas inspect component <id>
npx ui-atlas inspect recipe <id>
npx ui-atlas recommend --input design-request.json [--out design-plan.json]
npx ui-atlas add component <id> --target react [--out <dir>]
npx ui-atlas add recipe <id> --target react [--out <dir>]
npx ui-atlas audit design-plan.json [--format text|json]
npx ui-atlas mcp
npx ui-atlas doctor
```

Safety requirements:

- `init` previews paths, refuses unknown agent names, and never overwrites a different file without `--force`.
- Existing JSON/config files are parsed and updated atomically; malformed files are left unchanged.
- Project scope writes only inside the selected project root.
- `--scope project|user` is required; neither scope is inferred silently.
- `add` refuses path traversal and reports every file written.
- Commands support Windows, macOS, and Linux through Node APIs rather than shell-only commands.
- Output is stable JSON with non-zero exit codes for invalid input/audit errors.

## 8. MCP tool contract

The stdio server exposes bounded tools:

- `ui_atlas_list_recipes`
- `ui_atlas_search`
- `ui_atlas_get_component`
- `ui_atlas_recommend_screen`
- `ui_atlas_generate_code`
- `ui_atlas_audit_plan`

Tool inputs use JSON Schema and return registry citations. No tool executes project code or arbitrary shell commands. File-writing remains an explicit CLI/user action.

## 9. Evidence levels

- `generated-reference`: deterministic source was generated, but behavior was not compiled or run.
- `structurally-checked`: contract markers and static invariants passed.
- `compiled`: target SDK/compiler accepted the artifact.
- `browser-reviewed`: specified browser flows and DOM checks passed.
- `assistive-tech-reviewed`: named AT/browser/device combination was manually tested.

A higher label is used only when its evidence artifact exists. Platform snippets without SDK compilation remain generated references.

## 10. Release gates

Before npm/public-site release:

1. Registry schema validation and referential integrity pass.
2. Recommendation evaluation fixtures return expected recipes in top 3 with reasons.
3. Site and CLI term search use the same engine and fixtures.
4. `npm pack --dry-run` contains only declared runtime files and no secrets.
5. The packed tarball is installed in a fresh temporary project; all CLI commands and MCP handshake run there.
6. Skill installation is tested in isolated project/user homes for every claimed agent.
7. Existing 306 component contract, export, compile, browser, and responsive tests remain green.
8. Pages is redeployed and registry, `llms.txt`, deep links, console, and responsive flows are checked on the production URL.
9. npm publication and live `npx` execution are verified from a clean cache. If npm authentication is unavailable, release remains explicitly blocked rather than being reported complete.