---
name: ui-atlas
description: Identify registered UI components by formal name, distinguish aliases from related patterns, design complete screens from normalized requirements, generate code for seven targets, and audit UI plans.
license: MIT
metadata:
  version: "3.0.1"
  ui-atlas-registry: "bundled"
  ui-atlas-cli: "npx -y ui-atlas@3.0.1"
---

# UI Atlas

Use UI Atlas as a deterministic UI registry and screen-design engine. The AI client interprets the user's prose; UI Atlas resolves registered terminology, screen recipes, constraints, implementation code, and audit evidence.

Invoke the exact packaged CLI as `npx -y ui-atlas@3.0.1`. Do not assume a globally installed `ui-atlas` binary exists.

## Naming contract

Present names in this order:

1. formal name and formal variants;
2. common names and colloquial aliases;
3. related but non-equivalent patterns.

Never collapse Drawer, Navigation Drawer, Side Sheet, or Apple Sheet into one synonym. Cite the design system recorded in the registry when calling a name official.

## Workflow

1. Load the current routing contract from the packaged CLI before asking implementation questions:

   `npx -y ui-atlas@3.0.1 platforms`

2. Ask the user to choose exactly one product family first: Web (`web`), desktop app (`desktop-app`), or mobile app (`mobile-app`). Do not ask for every platform and target at once.

3. Follow the selected route's `nextQuestion`: resolve the OS/platform where applicable, then choose one target from that platform's `platformOptions` entry. Do not infer either answer when it changes the generated implementation.

4. Search exact terms and inspect each result's match reasons:

   `npx -y ui-atlas@3.0.1 search "<term>" --limit 5`

5. Normalize the requirement into a JSON request containing the selected `family`, `platform`, and `target`, plus `surface`. Keep `family` even when the platform is unique; it preserves the first product choice and disambiguates `cross-platform`. Add tasks, capabilities, data shape, risk, form factor, and approved recipe decisions when known.

6. Produce the screen plan:

   `npx -y ui-atlas@3.0.1 recommend --input request.json --out screen-plan.json`

   With `--out`, read the plan from `screen-plan.json`; stdout is the `ui-atlas-write-result` save receipt, not the plan. Without `--out`, stdout is the plan JSON. Add `--force` only after the user approves replacing a different existing plan.

7. If `openDecisions` is non-empty, resolve those product decisions before generating a screen kit.

8. Audit the plan:

   `npx -y ui-atlas@3.0.1 audit --input screen-plan.json`

9. Generate one component or an audited recipe kit:

   `npx -y ui-atlas@3.0.1 add primary-button --target react --out PrimaryButton.tsx`

   `npx -y ui-atlas@3.0.1 add --plan screen-plan.json --target react --out ./generated-screen`

10. Run the destination project's build, runtime, accessibility-tree, responsive, and assistive-technology checks. Registry and generator checks do not prove destination-project runtime quality.

## Targets

- `react`: React + Tailwind CSS
- `html`: semantic HTML + CSS
- `native`: React Native
- `compose`: Jetpack Compose
- `swiftui`: SwiftUI
- `winui`: WinUI 3
- `flutter`: Flutter

## MCP (optional)

MCP is an optional transport for clients that need tool discovery. The primary agent workflow is this Skill calling the version-pinned CLI above.

Run `npx -y ui-atlas@3.0.1 mcp` as a stdio MCP server. Prefer bounded tools such as term search, component lookup, recommendation, code retrieval, and plan audit instead of loading the entire registry into model context.

## Safety

- Do not include credentials or private user data in requirements; UI Atlas redacts recognized secret fields and values.
- Do not overwrite different existing files unless the user explicitly requests `--force`.
- Do not describe a related name as an alias when the registry marks it non-equivalent.
- Do not claim all possible product-specific composites are catalogued; decompose them into registered primitives and screen recipes.