--- name: UX Create Manifest slug: ux-create-manifest category: AI Engineering description: UX Create Manifest audits an existing app repository and generates a project-specific UX bible, architecture YAML, and decision notes from observed code. Use it when a repo needs a baseline UX manifest or the current one is stale or disconnected from implementation. github: "https://github.com/h0x91b/dev-3.0/tree/main/.claude/skills/ux-create-manifest" language: TypeScript stars: 249 forks: 31 install: "npx degit https://github.com/h0x91b/dev-3.0/tree/main/.claude/skills/ux-create-manifest ~/.claude/skills/ux-create-manifest" installs_to: ~/.claude/skills/ux-create-manifest source_path: .claude/skills/ux-create-manifest/SKILL.md collection_size: 11 category_size: 2631 collection_url: "https://dirskills.com/collections/h0x91b/dev-3.0" added: 2026-09-02T05:20:56.465Z last_synced: 2026-09-02T05:20:56.465Z canonical_url: "https://dirskills.com/skills/ux-create-manifest" --- # UX Create Manifest UX Create Manifest audits an existing app repository and generates a project-specific UX bible, architecture YAML, and decision notes from observed code. Use it when a repo needs a baseline UX manifest or the current one is stale or disconnected from implementation. **Install:** ```bash npx degit https://github.com/h0x91b/dev-3.0/tree/main/.claude/skills/ux-create-manifest ~/.claude/skills/ux-create-manifest ``` ## README # UX Create Manifest You are a principal-level product UX architect creating the project's initial UX architecture bible. Use this skill when: - The repository has no `docs/ux/PRODUCT_UX_BIBLE.md` or `docs/ux/ux-architecture.yaml`. - The existing UX manifest is stale, shallow, or disconnected from the actual app. - The user asks for a UX bible, UX architecture, product UX manifest, IA manifest, surface model, action taxonomy, or baseline UX audit. ## Non-negotiable goal Create a trustworthy, project-specific UX manifest derived from the current repository. Do not write a generic UX manifesto. Do not invent product features. Every observed fact must cite file paths or code evidence. Every inferred rule must be marked as inferred. Every proposed improvement must be marked as proposed. ## Default write scope You may create or update only UX documentation unless the user explicitly requests implementation changes: - `docs/ux/PRODUCT_UX_BIBLE.md` (include the glossary as a section here — no separate glossary file) - `docs/ux/ux-architecture.yaml` - `docs/ux/UX_DECISIONS.md` (seeded, kept compact — see `ux-principal`'s decision log diet) The manifest records **placement, architecture, and the project's own deltas** — its real token classes, documented exceptions, and any override of a `better-*` rule. It does NOT restate general craft rules; those belong to `better-accessibility`, `better-colors`, `better-typography`, `better-writing`, `better-layout`, and `better-ui`. A quality-floor section that could have been written about any project is a section to delete. If the project has a test budget on doc size (dev3: `src/bun/__tests__/ux-docs-budget.test.ts`), respect it — compact rather than raise it. **Never stamp a generated-looking header on a hand-authored file.** No `updated_at`, no `confidence`, no `source: derived_from_repository` on content a human will keep editing: those fields go stale within weeks and then invite the next reader to delete the file as a disposable cache. Say what the file is and let git carry the dates. Do NOT create `UX_MANIFEST_CHANGELOG.md` (git history is the changelog), `UX_AUDIT_REPORT.md` (the audit is your final chat response, not a repo file), or `UX_GLOSSARY.md` (a bible section). Three files is the complete on-disk footprint of this skill. You may **also** add a short pointer to the manifest in the project's agent-instruction file (`AGENTS.md` / `CLAUDE.md`) — this is an expected part of the loop (step 5), not an implementation change. Do not modify product UI code during this skill unless explicitly asked. ## Mandatory operating loop 1. **Map the repository** - Identify framework, router, app entry points, design system, component library, styling method, token files, routes, pages, screens, layouts, menus, toolbars, tabs, drawers, tables, cards, forms, modals, inspectors, command palettes, empty states, loading states, error states, and onboarding/help surfaces. - Prefer fast commands: `find`, `rg`, `git ls-files`, `tree`, package manifests, route files, and existing docs. - If possible, run `python scripts/ux_inventory.py --root /path/to/repo` from this skill directory. By default it writes a single throwaway `ux-inventory.json` into a temp dir **outside the repo** — read it for leads, then ignore it. Treat its output as a starting point, not a substitute for reading the code. - **Never commit the inventory.** It is a scratch review aid, not a manifest artifact, and is not part of the write scope below. Do not write it under `docs/ux/generated/` or anywhere inside the repo. If a previous run left an inventory inside the repo, delete it before finishing. 2. **Use sub-agents aggressively when available** - If the environment supports sub-agents, Task tools, parallel workers, or planner agents, spawn the sub-agents in `references/subagent-briefs.md`. - Run them in parallel where possible. - Require each sub-agent to return evidence with file paths and concise structured findings. - If sub-agents are unavailable, simulate them sequentially and label the report sections by role. 3. **Derive the product UX architecture** - Build the object model: product entities, owners, relationships, primary routes, detail routes, and lifecycle states. - Build the route and navigation model: top-level destinations, section nav, subnav, tabs, breadcrumbs, hidden routes, auth routes, settings routes. - Build the surface model: global nav, sidebar, page header, page toolbar, selection toolbar, row actions, object header, inspector, drawer, modal, command palette, settings, dashboards, diagnostics, notifications. - Build the action taxonomy: primary actions, page actions, object actions, row actions, bulk actions, configuration actions, destructive actions, diagnostic actions, creation actions, expert shortcuts. - Build the design-token policy: existing token names, button variants, badge variants, semantic colors, spacing/density rules, icon conventions, state colors, danger/warning/success/info usage. - Build the complexity budgets: max visible actions, max navigation depth, max visible tabs, overflow rules, primary-action limits, density rules, default responsive behavior. 4. **Generate the manifest files** - Use the templates in `templates/`. - Create a human-readable bible and a machine-readable YAML policy. - Preserve useful existing docs. Merge rather than overwrite unless the existing docs are clearly generated and stale. - Do not add changelog files — the commit message and git history record what changed. 5. **Wire the manifest into the project's agent instructions (MANDATORY)** - The manifest is useless if future agents never read it. Add a short pointer to the project's agent-instruction file — `AGENTS.md` and/or `CLAUDE.md` (often `CLAUDE.md` is a symlink to `AGENTS.md`; edit the real file once, do not duplicate). - The pointer must state three things: (a) the UX bible lives at `docs/ux/PRODUCT_UX_BIBLE.md` (+ `docs/ux/ux-architecture.yaml`) and is the canonical reference for **where** features live; (b) agents MUST invoke the `ux-principal` skill before adding a destination, surface, or action — a new screen, panel, button, menu item, modal, or nav change — and use this `ux-create-manifest` skill to regenerate the manifest when it is stale; (c) craft work on an **existing** control — colour, contrast, typography, copy, motion, layout, accessibility — goes to the owning `better-*` skill instead, and `/better-interface` reviews a whole screen. Do not mandate `ux-principal` for every visible pixel: reading the whole manifest to restyle a badge buys nothing. - Keep it concise (a few lines + links). Place it near existing design-system / UI guidance if present. If no such file exists, ask the user where their agents read project instructions before creating one. - Respect the project's own conventions (commit/changelog rules, language policy) when making this edit. 6. **Final answer** - Summarize what was created. - List evidence coverage by project area. - List major UX risks and recommended next actions. - State confidence level and missing evidence. - Tell the user to use `ux-principal` before the next UI feature. ## Evidence discipline Use this notation in reports: - `Observed`: directly supported by code or docs. - `Inferred`: likely product rule inferred from repeated patterns. - `Proposed`: recommended rule not yet consistently implemented. - `Unknown`: not enough evidence. For each important claim, include file references like: ```text Evidence: app/users/page.tsx, components/layout/sidebar.tsx, components/ui/button.tsx ``` Avoid line numbers unless you have already inspected exact lines. ## Default UX principles to encode when project evidence is absent Only use these as provisional defaults, and mark them as `Proposed`: - Navigation contains stable destinations, not one-off actions. - Top-level navigation should stay small, stable, and grouped by user goals. - Do not exceed 2 navigation levels unless the product is expert-only and the manifest says so. - One screen should have one primary action. - Page-scoped frequent actions belong in page headers or page toolbars. - Selected-item actions belong in a selection toolbar that appears only after selection. - Object-scoped actions belong in row actions, object headers, object detail pages, or inspectors. - Durable configuration belongs in settings or object settings. - Rare expert actions belong in overflow, command palette, or advanced panels. - Destructive actions need confirmation and destructive token roles. - Dashboard surfaces show status, health, trends, and decision-support. They should not become random control panels. - New visible controls require a complexity-budget check. ## Button and color policy extraction When documenting variants, prefer actual token and component names from the codebase. Classify variants semantically: - `primary`: one main safe action for the current screen or flow. - `secondary`: visible supporting action with lower priority than primary. - `tertiary` or `ghost`: low-emphasis visible action. - `outline`: secondary action where the design system uses borders for emphasis separation. - `destructive`: delete, revoke, reset, disable, irreversible, security-sensitive, or data-loss actions. - `neutral`: non-semantic utility actions. - `accent` or `alternative`: product-specific emphasis distinct from primary. Use only if the design system already has such a role. - `link`: navigation or inline non-button action. - `icon`: compact repeated action, normally with accessible label and tooltip. Never invent exact color values unless the repo lacks tokens and the manifest explicitly proposes a token schema. ## Required output files Create or update exactly these — nothing more: 1. `docs/ux/PRODUCT_UX_BIBLE.md` (with the glossary as a section) 2. `docs/ux/ux-architecture.yaml` 3. `docs/ux/UX_DECISIONS.md` The audit report is delivered as the final chat response (see `references/report-format.md`), never as a committed file. ## Read more bundled references - `references/discovery-protocol.md` - `references/subagent-briefs.md` - `references/manifest-schema.md` - `references/heuristics-and-defaults.md` - `references/report-format.md`