Designer Skill MCP README

Plug-and-play MCP. UI superpowers for your agent.

Setup · How it works · References · Tools · Development

Setup

Paste into your agent (Claude Code, Codex, Cursor, any MCP client). It installs the skill, wires the MCP and verifies the tools:

Add designer-skill. The designer core is keyless: it routes requests, loads guidance, checks contrast, converts design tokens and runs static and rendered checks. The Niblet catalogue is built in and optional: with a NIBLET_TOKEN it supplies real screens and licensed materials; without one those tools answer guidance and everything else works.

1. Install or refresh the skill into the user skill directory (not this project):
npx skills add PyModel/designer-skill --skill designer-skill -g -y

2. Add the local MCP using this client's native MCP configuration, in the user-level (not project-level) config:
Name: designer-skill
Transport: stdio
Command: npx
Args: -y @pymodel/designer-skill-mcp@latest

No API key is needed. Add NIBLET_TOKEN only if the user already has a Niblet key and asks for catalogue references.

3. Verify: list the designer-skill server's tools and confirm get_preflight_brief, dispatch_intent, review_and_gate are present. Do not run a sample check.

When setup is complete, confirm the skill is installed and the three named tools are exposed. On UI work: call get_preflight_brief, use dispatch_intent and load only relevant guidance. If an unresolved visual question warrants retrieval, use the catalogue tools (they answer guidance when no key is set; continue without them). Run review_and_gate as supplemental static evidence, then perform the required rendered, functional and accessibility checks in the host. Never treat static success as UI PASS. Preserve audit/plan scope. Continue an active authorized task; otherwise report designer-skill ready, and report Niblet paired only if its tools were actually observed.

No Niblet key? Continue from local product evidence; catalogue retrieval is optional. To get more references, see More references with Niblet.

Or pick one:

Standalone MCP config (the plugin's own mcp.json pins the release it was tested with instead of @latest):

{ "mcpServers": { "designer-skill": { "command": "npx", "args": ["-y", "@pymodel/designer-skill-mcp@latest"] } } }

@latest tracks npm; teams pin @pymodel/designer-skill-mcp@0.27.0. Plugin skill content updates separately (/plugin update …). MCP registry name: io.github.PyModel/designer-skill-mcp. Requires Node 22+.

{ "servers": { "designer-skill": { "type": "stdio", "command": "npx", "args": ["-y", "@pymodel/designer-skill-mcp"] } } }

[mcp_servers.designer-skill]
command = "npx"
args = ["-y", "@pymodel/designer-skill-mcp"]

{ "mcp": { "designer-skill": { "type": "local", "command": ["npx", "-y", "@pymodel/designer-skill-mcp"] } } }

How it works

flowchart LR
  A[Prompt] --> B[get_preflight_brief]
  B --> C[dispatch_intent]
  C --> D[get_reference]
  D --> E[Build / polish UI]
  E --> F[review_and_gate]
  F -->|FAIL: fix| E
  F -->|static checks pass| G[Rendered checks<br/>by the host]
  classDef start fill:#f8fafc,stroke:#94a3b8,color:#18181b
  classDef route fill:#eff6ff,stroke:#3b82f6,color:#1e3a8a
  classDef know fill:#faf5ff,stroke:#7c3aed,color:#4c1d95
  classDef work fill:#fff7ed,stroke:#e87a3d,color:#7c2d12
  classDef gate fill:#ecfdf5,stroke:#10b981,color:#065f46
  classDef host fill:#fff1f2,stroke:#e11d48,color:#881337
  class A start
  class B,C route
  class D know
  class E work
  class F gate
  class G host

The gate is static only, by design: overall status is FAIL or NOT_VERIFIED, never a rendered-readiness pass. verify_rendered loads a local page in a real browser (the project's own Playwright and axe-core) and reports page load, console errors, broken images, clipped text, overflow and accessibility with screenshots; without Playwright it reports NOT_RUN. check_contrast measures explicit color pairs.

More references with Niblet (optional)

Everything above works with no account and no key. For real product screens to compare against, recorded design references, license-recorded fonts and icons, and React component source:

1. Sign up at niblet.pymodel.com and create an MCP key at niblet.pymodel.com/account (keys start with niblet_at_).
2. Add it to this server's environment and restart the client:

{ "mcpServers": { "designer-skill": { "command": "npx", "args": ["-y", "@pymodel/designer-skill-mcp@latest"], "env": { "NIBLET_TOKEN": "niblet_at_…" } } } }

The four catalogue tools (find_ui_references, get_design_reference, find_ui_materials, get_ui_component) then answer from the hosted Niblet MCP; you do not install a second server. Keep the key in the client's secret store, never in a commit or a prompt.

Without a key, with NIBLET_DISABLED=1, or when the catalogue is unreachable, those tools answer a short guidance text and every other tool keeps working: a transient failure is retried three times, then the catalogue is skipped for 60 seconds so no call waits on it. Catalogue trouble is never a tool error.

Niblet ecosystem

designer-skill is an MCP client of the hosted Niblet MCP and passes its four tools through under the same names, images included. If a Niblet server is also connected directly, use one of the two for a question, never both, and do not infer connectivity from installation. Consult niblet-catalogue for deployment differences, bounds and licensing.

Use one product-grounded design contract. Niblet's surface modes (Persuade, Operate, Read, Experience) describe the user's job; designer-skill's execution modes (audit, plan, refine, implement, system) describe permitted work. They are independent: an Operate surface can receive a read-only audit or an authorized refinement. Existing product tokens, components and real content win over reference aesthetics. Component retrieval does not authorize dependency installation or source writes, and neither MCP certifies rendered quality.

Example: "Use designer-skill to redesign this pricing page without breaking functionality." → get_preflight_brief → dispatch_intent → get_reference → edit → review_and_gate.

References

Plus 26 ux/* references, authored in skills/ux-designer/ and vendored at skills/designer-skill/reference/ux/ (generated by node scripts/sync-ux.mjs, checked by test), so a designer-skill-only install is self-contained. Each SKILL.md is a short router with a one-line description; references load only when a task needs them.

Tools

Resources: designer://skill · designer://reference/{+name} · Prompt: design (task, optional aesthetic)

Development

cd designer-skill-mcp
npm ci
npm run build   # syncs skills/ → assets/ (generated, gitignored), compiles TypeScript
node --test checks/core.mjs      # contract checks against the built dist
npm run typecheck && npm test   # tsc over src + test, then vitest; `npm run smoke` drives the packed tarball

Skill robustness checks

Edit UX guidance only in skills/ux-designer/references/; npm run sync-skill regenerates the standalone mirror before bundling. Run node scripts/sync-ux.mjs from the repository root for filesystem-only distribution.

Run reports now use v2, plus a host-owned verification plan. Validate both bundled JSON schemas, then run the dependency-free skills/designer-skill/scripts/validate-report.mjs REPORT PLAN AUTHORIZED_ROOT for evidence hashes, confinement, revision/plan matching and rendered-readiness semantics. Its own PASS means report validation, not UI certification. Legacy v1 reports fail closed and must be regenerated from real evidence; update host readers/writers together.

Behavioral action-plan cases and a deterministic grader live in evals/designer-skill/. Synthetic grader tests do not count as model evaluations, and model proposals do not prove actual tool-use compliance or rendered quality. Keep model, host, skill hash and repetitions with evaluation results.

HTTP mode (Streamable HTTP at /mcp):

node dist/index.js --http --port 3017 --root /abs/project                     # 127.0.0.1
DESIGNER_SKILL_HTTP_TOKEN=… node dist/index.js --http --host 0.0.0.0 --root /abs/project

Every HTTP bind requires at least one --root. Every bind validates the Host header and refuses a browser Origin that is not an accepted host; a non-loopback bind also requires DESIGNER_SKILL_HTTP_TOKEN (Authorization: Bearer …) and at least one --allowed-host.

Release: ./scripts/release.sh "notes" bumps and syncs every version, verifies, tags and pushes; publish.yml publishes npm (with provenance), the MCP registry entry and the GitHub release. Contract details: docs/HARDENING.md.