x-design — Visual Design System Router

Resolves user design intent to a curated DESIGN.md file from VoltAgent/awesome-design-md and installs it into the current project. Index-only by design — fetches via GitHub raw URLs, never bundles upstream files.

When to Use

Trigger phrases:

• "Use Linear's style" / "make it look like Stripe" / "apply Claude's design"
• "Drop a DESIGN.md here" / "install a design reference"
• "Make this look warm editorial / dark minimal / stark futuristic / premium luxury / playful / terminal-native"
• "What design styles are available?"

When NOT to use:

• User wants bespoke design with no brand reference → use ui-ux-pro-max directly (note: if there is a brand reference, x-design will chain into ui-ux-pro-max via step 6 anyway)
• User wants to review an existing design → use x-review
• User wants to generate a DESIGN.md from a screenshot → delegate to multimodal-looker + write directly
• Project already has a DESIGN.md the user is happy with → point to it, don't overwrite

Bootstrap

Read these files before routing any request: 0. ../x-shared/capability-loading.md — pin capabilities for the session (used to gate the optional ui-ux-pro-max and shadcn MCP handoffs in steps 6-7).

1. config.json — pinned commit, URL templates, defaults
2. references/catalog.md — 58 sites with slugs, categories, intent tags, tag vocabulary

Detection

Workflow

1. Resolve target directory. Confirm cwd is a project root (has .git, package.json, pyproject.toml, or user confirms explicitly). If ambiguous, ask before proceeding. Never write outside the user-confirmed directory.

   • Vision-search recall (only when agentmemory.server_up pinned per ../x-shared/capability-loading.md): one curl -fsS -X POST "${AGENTMEMORY_URL:-http://localhost:3111}/agentmemory/vision-search" -H 'content-type: application/json' -d '{"query":"<design topic>","limit":5}' call. Surface prior screenshots / mockups as supplementary context for slug resolution. When agentmemory.server_up is not pinned, skip silently — Claude's native auto-memory file still applies.

2. Resolve slug from intent.

   • Named: find catalog row whose slug or name matches. Slugs are irregular (linear.app, mistral.ai, x.ai, cal, not cal.com) — always verify against the catalog.
   • Descriptive: match user's adjectives against the Intent Tags column. Return top 2–3 candidates with their one-liners. Ask the user to pick.
   • Listing: print the category section verbatim from references/catalog.md.

3. Preview before install. Show the user:

   • Chosen slug + site name + category
   • Preview URL (substitute {commit} and {slug} into preview_url_template from config.json)
   • One-liner from the catalog Ask for confirmation before fetching.

4. Fetch the DESIGN.md. Build the raw URL from config.json raw_url_template, substituting {repo}, {commit}, {slug}:

   curl -fsSL "https://raw.githubusercontent.com/VoltAgent/awesome-design-md/<commit>/design-md/<slug>/DESIGN.md" -o <target>/DESIGN.md

   curl -f fails loudly on 404 (stale commit or wrong slug). If a DESIGN.md already exists at the target, warn and ask before overwriting.

5. Report. Show:

   • Where the file landed + its byte count
   • Brand name + one-liner
   • Philosophy-first framing: Before showing section 9 prompts, remind the user: "Read sections 1 (Visual Theme), 5 (Layout Principles), and 7 (Do's and Don'ts) first — agents that absorb the design philosophy produce far better results than those that cherry-pick hex values from the prompt guide."
   • The first paragraph of section 9 "Agent Prompt Guide" from the fetched file (these copy-pasteable prompts are the highest-leverage part of the install — surface them every time)
   • Stack-aware hint: Check the project for package.json (React/Next → Tailwind bg-[#hex] or className), nuxt.config / vue deps (Vue → scoped <style>), svelte.config (Svelte → style: directives), pubspec.yaml (Flutter → Color(0xFFhex)), or plain HTML. Append one line: "Section 9 prompts use raw CSS values — adapt to bg-[#f5f4ed] (Tailwind), style={{ background }} (React), or your framework's convention."
   • AI slop warning: Append a brief advisory referencing references/ai-slop-patterns.md — name the top 3–4 pitfalls inline (3-column feature grid, gradient backgrounds, icons in colored circles, cookie-cutter rhythm) and note: "See the full list in the AI slop reference. The site-specific Don'ts in section 7 take precedence."

6. Offer the ui-ux-pro-max handoff. DESIGN.md captures aesthetic intent; ui-ux-pro-max captures enforceable rules (a11y, palettes, stack guidelines, anti-patterns). External user-level skill (NOT shipped in this plugin) — upstream: https://github.com/nextlevelbuilder/ui-ux-pro-max-skill. Install location: ~/.omc/skills/ui-ux-pro-max/ (or ~/.claude/skills/ui-ux-pro-max/). Detect first by checking the available skills list. Behavior:

   • Installed → ask once:

     "Want me to also generate a design-system/MASTER.md with implementation rules via ui-ux-pro-max? It complements DESIGN.md — vision vs. rules."

   • Not installed → surface the install pointer once, then skip step 6 (do NOT silently no-op):

     "Optional next step: ui-ux-pro-max would generate enforceable rules (design-system/MASTER.md) to complement DESIGN.md. Not installed. Source: https://github.com/nextlevelbuilder/ui-ux-pro-max-skill. Skipping for now."

   If user accepts, invoke ui-ux-pro-max with the same intent (brand name + product type + descriptive tags from the catalog row). Primitive: handoff (sync, depends on result). Include a handoff context block: from x-design, slug + brand name + tags, path of the installed DESIGN.md, recommended next step. The two files coexist: DESIGN.md is the north-star; MASTER.md is the rules engine. If user declines, skip silently — never push twice.

7. Offer the shadcn MCP handoff. DESIGN.md + MASTER.md describe what the UI looks like; shadcn MCP is how to install matching components. Conditional — call mcp__shadcn__get_project_registries first; empty/error result triggers the non-shadcn advisory below, then proceeds to step 8 (never push shadcn onto non-shadcn projects). If registries exist, follow the workflow in references/shadcn-handoff.md (detect → ask once → seed primitives with search_items_in_registries + get_add_command_for_items → optional get_audit_checklist). Primitive: sequential handoff after step 6 — shadcn consumes MASTER.md tokens, so it must follow the ui-ux-pro-max handoff (do NOT fan out steps 6 + 7 in parallel). Print install commands; never auto-run. Include a handoff context line when surfacing the install commands so the next session knows which DESIGN.md/MASTER.md drove the picks.

   Non-shadcn framework advisory: When get_project_registries returns empty, check for a detectable framework and offer a one-line hint (never push, just inform):

   • nuxt.config.* or vue in deps → "Apply DESIGN.md tokens via CSS custom properties or scoped <style> in Vue SFCs."
   • svelte.config.* → "Apply tokens via Svelte's style: directives or a shared tokens.css."
   • pubspec.yaml (Flutter) → "Map DESIGN.md hex values to Color(0xFF...) constants in a theme file."
   • index.html only (vanilla) → "Apply tokens as CSS custom properties in a <style> block or linked stylesheet."
   • No framework detected → skip silently.

8. Optionally hint the project CLAUDE.md. Default (auto_update_claude_md: false) is to ASK first. If user consents, append one line matched to what was installed:

   Files present	Line to append
   Only DESIGN.md	When generating or modifying UI, read DESIGN.md in the project root for visual styling rules.
   DESIGN.md + design-system/MASTER.md	When generating UI: read DESIGN.md (brand vision) and design-system/MASTER.md (rules).
   Above + shadcn registries detected	When generating UI: read DESIGN.md (vision) and design-system/MASTER.md (rules); use the shadcn MCP (search_items_in_registries, get_add_command_for_items) to install matching components.

   Never modify any other content in CLAUDE.md.

   • Persist design decision (only when mcp.agentmemory pinned in bootstrap-active set): one mcp__plugin_agentmemory_agentmemory__memory_save({ content: "<one-line design decision + rationale>", type: "insight", concepts: "x-design,decision,slot:design,<area>" }) call. The slot: token in concepts substitutes for the upstream slot-store API (not present in agentmemory v0.9.21 — convention, not contract; memory_save silently drops unknown top-level fields, so a category arg would be invisible — verified at research/rohitg00/agentmemory/src/mcp/standalone.ts:104-114). Skip silently when not pinned.

Quick Reference

Dependencies

• curl (fail-loud with -f) — fetches raw files from GitHub
• config.json — pinned commit + URL templates + defaults
• references/catalog.md — 58-site index, authoritative slug + tag source
• Upstream: VoltAgent/awesome-design-md at the pinned commit in config.json
• Optional: ui-ux-pro-max skill (step 6 handoff) — generates design-system/MASTER.md. External user-level skill, NOT shipped in this plugin. Upstream: https://github.com/nextlevelbuilder/ui-ux-pro-max-skill. Install path: ~/.omc/skills/ui-ux-pro-max/ (or ~/.claude/skills/ui-ux-pro-max/).
• Optional: shadcn MCP (step 7 handoff) — get_project_registries, search_items_in_registries, get_add_command_for_items, get_audit_checklist

Related Skills

• ui-ux-pro-max — bespoke design authoring (styles, palettes, accessibility). x-design routes to existing references; ui-ux-pro-max helps author decisions from scratch. External user-level skill (not shipped here) — install from https://github.com/nextlevelbuilder/ui-ux-pro-max-skill.
• update-research — maintains the research-library clone (path in config.json → research_fallback_path); separate from this skill's index-only footprint
• x-review — post-install visual review pass

Three-stage pipeline (steps 4 → 6 → 7):

1. x-design fetches DESIGN.md — brand vision (the what)
2. ui-ux-pro-max generates design-system/MASTER.md — enforceable rules (the constraints)
3. shadcn MCP finds and installs matching components — execution (the how)

Each stage is opt-in. Stages 2 and 3 are skipped silently if the user declines or the project can't support them.

Common Mistakes

Gotchas

See gotchas.md for known failure patterns.