X design
Use when the user wants to apply a visual design system to a project, references a specific brand's style (Linear-like, Stripe-like, Claude-like), asks for a DESIGN.md, or describes aesthetic intent (warm editorial, dark minimal, stark futuristic) for AI UI generationFrom its SKILL.md
npx -y skills add quangtran88/x-skills --skill x-designAssembled from the repository path, not quoted from the project. Check it against their README if it does not work.
2 things to look at
- no licenseNo license file was found in the repository. Code published without one is not open source by default, so using it at work is a question for whoever answers licensing questions where you are.
- 5 stars5 stars. Stars are a popularity signal and not a quality one, but at this level it is likely that nobody has read this closely except its author, and you would be relying on your own review.
SKILL.md
14.1 KB, as published. Nobody here has run it
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-maxdirectly (note: if there is a brand reference,x-designwill chain intoui-ux-pro-maxvia 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.mdthe 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).
config.json— pinned commit, URL templates, defaultsreferences/catalog.md— 58 sites with slugs, categories, intent tags, tag vocabulary
Detection
| Signal | Route |
|---|---|
| Named brand ("Linear", "Stripe", "Claude") | Direct slug lookup in catalog |
| Descriptive intent ("warm editorial", "dark minimal") | Match against intent tags → propose 2–3 candidates |
| "What's available?" / "list styles" | Show catalog section(s) the user cares about |
| "Something like X but Y" | Look up X's tags, filter by Y, propose candidates |
| "Refresh catalog" / "update pin" | See "Re-pinning" section in references/catalog.md |
Workflow
-
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.- Design-memory recall (only when
mcp.basic_memorypinned in bootstrap-active set): onemcp__basic-memory__search_notes({ query: "<design topic>", page_size: 5 })call. Surface prior design-decision notes as supplementary context for slug resolution. (basic-memory has no image-similarity search — text recall over design notes replaces the old vision-search lane.) Whenmcp.basic_memoryis not pinned, skip silently — Claude's native auto-memory file still applies.
- Design-memory recall (only when
-
Resolve slug from intent.
- Named: find catalog row whose slug or name matches. Slugs are irregular (
linear.app,mistral.ai,x.ai,cal, notcal.com) — always verify against the catalog. - Descriptive: match user's adjectives against the
Intent Tagscolumn. Return top 2–3 candidates with their one-liners. Ask the user to pick. - Listing: print the category section verbatim from
references/catalog.md.
- Named: find catalog row whose slug or name matches. Slugs are irregular (
-
Preview before install. Show the user:
- Chosen slug + site name + category
- Preview URL (substitute
{commit}and{slug}intopreview_url_templatefromconfig.json) - One-liner from the catalog Ask for confirmation before fetching.
-
Fetch the DESIGN.md. Build the raw URL from
config.jsonraw_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.mdcurl -ffails loudly on 404 (stale commit or wrong slug). If aDESIGN.mdalready exists at the target, warn and ask before overwriting. -
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 → Tailwindbg-[#hex]orclassName),nuxt.config/vuedeps (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 tobg-[#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."
-
Offer the
ui-ux-pro-maxhandoff.DESIGN.mdcaptures aesthetic intent;ui-ux-pro-maxcaptures 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.mdwith implementation rules viaui-ux-pro-max? It complementsDESIGN.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-maxwould generate enforceable rules (design-system/MASTER.md) to complementDESIGN.md. Not installed. Source: https://github.com/nextlevelbuilder/ui-ux-pro-max-skill. Skipping for now."
If user accepts, invoke
ui-ux-pro-maxwith 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 installedDESIGN.md, recommended next step. The two files coexist:DESIGN.mdis the north-star;MASTER.mdis the rules engine. If user declines, skip silently — never push twice. - Installed → ask once:
-
Offer the
shadcnMCP handoff.DESIGN.md+MASTER.mddescribe what the UI looks like;shadcnMCP is how to install matching components. Conditional — callmcp__shadcn__get_project_registriesfirst; 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 inreferences/shadcn-handoff.md(detect → ask once → seed primitives withsearch_items_in_registries+get_add_command_for_items→ optionalget_audit_checklist). Primitive: sequentialhandoffafter step 6 —shadcnconsumes 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_registriesreturns empty, check for a detectable framework and offer a one-line hint (never push, just inform):nuxt.config.*orvuein deps → "Apply DESIGN.md tokens via CSS custom properties or scoped<style>in Vue SFCs."svelte.config.*→ "Apply tokens via Svelte'sstyle:directives or a sharedtokens.css."pubspec.yaml(Flutter) → "Map DESIGN.md hex values toColor(0xFF...)constants in a theme file."index.htmlonly (vanilla) → "Apply tokens as CSS custom properties in a<style>block or linked stylesheet."- No framework detected → skip silently.
-
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.mdWhen generating or modifying UI, read DESIGN.md in the project root for visual styling rules.DESIGN.md+design-system/MASTER.mdWhen 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.basic_memorypinned in bootstrap-active set): apply the § Memory Reflex durability gate first (a real decision + rationale, not a routine run note), then onemcp__basic-memory__write_note({ title: "<area> design decision", directory: "decisions/<project-slug>", content: "<one-line design decision + rationale>", tags: ["<project-slug>", "x-design", "<area>"] })call (durability gate, placement, and Update over duplicate — same-kind only — per../x-shared/mcp-toolbox.md § Memory Reflex/ § Consumer rules). Skip silently when not pinned.
- Persist design decision (only when
Quick Reference
| Task | How |
|---|---|
| Install a named brand to cwd | Resolve slug from catalog → curl -fsSL <raw_url> -o DESIGN.md |
| List styles in a category | Read references/catalog.md → print the category table |
| Show tag vocabulary | Read the "Tag Vocabulary" section at the bottom of references/catalog.md |
| Refresh to newer upstream commit | Follow "Re-pinning" procedure in references/catalog.md |
| Preview without installing | Construct preview_url_template and print it — don't curl |
Generate matching MASTER.md (rules) | Step 6 — invoke ui-ux-pro-max with brand + tags |
| Find matching shadcn components | Step 7 — search_items_in_registries then get_add_command_for_items |
| Non-shadcn framework hint | Step 7 — when shadcn detection fails, check for Vue/Svelte/Flutter and advise |
| Offline fallback when curl 404s | Use research_fallback_path from config.json |
Dependencies
curl(fail-loud with-f) — fetches raw files from GitHubconfig.json— pinned commit + URL templates + defaultsreferences/catalog.md— 58-site index, authoritative slug + tag source- Upstream:
VoltAgent/awesome-design-mdat the pinned commit inconfig.json - Optional:
ui-ux-pro-maxskill (step 6 handoff) — generatesdesign-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:
shadcnMCP (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-designroutes to existing references;ui-ux-pro-maxhelps 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 inconfig.json→research_fallback_path); separate from this skill's index-only footprintx-review— post-install visual review pass
Three-stage pipeline (steps 4 → 6 → 7):
x-designfetchesDESIGN.md— brand vision (the what)ui-ux-pro-maxgeneratesdesign-system/MASTER.md— enforceable rules (the constraints)shadcnMCP 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
| Mistake | Fix |
|---|---|
| Fetching without confirming project root | Always resolve cwd first; ask user if ambiguous |
Overwriting existing DESIGN.md silently | Always warn + confirm |
Modifying CLAUDE.md without consent | Default is ask-first; never auto-append |
| Hardcoding the commit SHA | Always read from config.json → pinned_commit |
| Bundling upstream files into the skill | Skill is index-only — never copy design-md/ into the skill dir |
| Guessing slugs | Always check references/catalog.md (slugs have irregular forms) |
| Skipping section 9 in the report | The agent prompt examples are the highest-leverage takeaway |
| Showing section 9 without philosophy framing | Always remind to read sections 1, 5, 7 first |
| Omitting stack-aware hint | Detect framework and suggest how to adapt CSS values |
| Omitting AI slop warning | Always append the generation pitfalls advisory |
Fetching preview.html to the project | Only DESIGN.md belongs in the project; previews are for eyeballing on github.com |
| Pushing shadcn on non-shadcn projects | Step 7 must call get_project_registries first; empty result = non-shadcn advisory |
| Skipping non-shadcn framework advisory | When shadcn detection fails, check for Vue/Svelte/Flutter and offer a one-line token-application hint |
Auto-running npx shadcn add ... commands | Step 7c prints install commands; the user runs them |
Forcing ui-ux-pro-max when it isn't installed | Step 6 must check the available skills list before invoking |
Silently skipping step 6 when ui-ux-pro-max missing | Surface the install pointer (https://github.com/nextlevelbuilder/ui-ux-pro-max-skill) once, then stop — do NOT no-op |
Gotchas
See gotchas.md for known failure patterns.