designer-skill
A plug-and-play MCP that gives your agent UI superpowers: design, refactor, and ship interfaces that don't look AI-made.
Foundation: Brief by default → commit direction before code → deep refs on demand → deterministic gate before done.
This file is the router. Substance lives in fifteen reference files under reference/; load them on demand via MCP — do not work from memory.
MCP workflow (every UI task)
When the designer-skill MCP server is connected:
get_preflight_brief — compact binding rules (~500 tokens). Call first.commit_design_direction — declare register, aesthetic, physical scene, layouts, type direction, anti-slop risks, inverse test. Must PASS before code.load_project_context — PRODUCT.md / DESIGN.md when present. If NO_PRODUCT_MD on greenfield, run get_command({ verb: "setup" }).dispatch_intent — map the user's request to verb(s) + which references to load (2–4 files, not all fifteen).get_reference — load only the files dispatch_intent recommends.- Implement. When writing or fixing CSS, pull
get_reference({ name: "css-techniques" }) for idiomatic patterns (centering, specificity, logical properties, container queries, :has(), clamp()).
review_and_gate — scan changed files; score ≥85, zero blocking slop. Do not claim done on FAIL.
Optional: get_palette_seed on greenfield (no committed brand colors); detect_antipatterns for ad-hoc scans; web-search MCP for contemporary UI references on visually-led net-new work (extract moves, don't copy layouts).
If MCP is unavailable, read local reference/ files using the routing map below.
Session preflight (after MCP bootstrap)
- Project context — PRODUCT.md / DESIGN.md are authoritative when present. DESIGN.md wins visual decisions; PRODUCT.md wins strategic/voice; anti-references beat one-off prompts.
- Register — brand (distinctiveness) vs product (earned familiarity). Write one physical-scene sentence.
- One aesthetic system — from
reference/aesthetic-systems.md. Never mix two signatures on one surface.
- Positive direction —
reference/differentiation-playbook.md: inverse test, layout families, named references, one weird thing (brand).
- Existing UI — audit → diagnose → redesign in
reference/refactor-and-redesign.md; preserve functionality.
Project context files
- PRODUCT.md — register, users, purpose, 3-word personality, anti-references, strategic principles, a11y commitments.
- DESIGN.md — tokens + named visual rules. Recipe in
reference/refactor-and-redesign.md.
Reference routing map
| Open this |
When the task is about |
reference/differentiation-playbook.md |
How to be distinctive — inverse test, layout menu, one weird thing, named references, physical scene |
reference/design-principles.md |
Visual fundamentals — typography, spacing, color, layout, hierarchy, depth (neutral baseline) |
reference/aesthetic-systems.md |
Five design languages + brand-identity font procedure |
reference/avoid-ai-slop.md |
What to refuse — ban-list, category-reflex, output-completeness, ship checklist |
reference/motion-and-interaction.md |
Animation timing, springs, scroll, reduced-motion |
reference/engineering-and-performance.md |
Tokens, a11y, responsive, CWV, framework-honest output |
reference/refactor-and-redesign.md |
Improve existing UI without breaking it |
reference/command-playbook.md |
Intent → verb dispatch |
reference/interaction-design.md |
Cognitive laws, forms, navigation, errors, loading |
reference/visual-critique.md |
Seven-dimension critique instrument |
reference/design-systems.md |
Token architecture, component specs, theming |
reference/project-init.md |
Discovery, PRODUCT.md, DESIGN.md setup |
reference/craft-flow.md |
Shape-then-build pipeline with user gates |
reference/live-mode.md |
Browser variant mode: HMR hot-swap |
reference/css-techniques.md |
How to write the CSS — resets, centering, selectors/specificity, logical properties, container queries, :has(), clamp(); the cookbook for applying CSS fixes |
Precedence rule
design-principles.md is the neutral baseline. Committing to a system in aesthetic-systems.md overrides baseline for that surface. Existing brand identity beats both on edits; never second-guess committed fonts, lanes, or palettes.
Cross-file ownership
- Contrast, type ramp, spacing, layout →
design-principles.md
- Palettes, fonts, shadow tokens per system →
aesthetic-systems.md
- Distinctive / creative direction →
differentiation-playbook.md
- Bans + completeness contract →
avoid-ai-slop.md
- Easing, durations →
motion-and-interaction.md
- GPU, tokens, a11y engineering →
engineering-and-performance.md
- Idiomatic CSS implementation, applying CSS fixes →
css-techniques.md
Ship gate
review_and_gate replaces manual checklist-only shipping. It runs the 44-rule detector, computes a slop score, and returns blocking fixes. Also verify: category-reflex pass, no truncated code output, text ≥4.5:1, focus-visible rings, reduced-motion alternative, touch targets ≥44×44px, tested at 375/768/1440px.
Source: hashgraph-online/awesome-codex-plugins → plugins/Pythoughts-labs/designer-skill/skills/designer-skill/SKILL.md
1---2name: designer-skill3description: Plug-and-play MCP for UI superpowers. Use when building, designing, redesigning, refactoring, polishing, auditing, or enhancing any web or app user interface — landing pages, marketing sites, dashboards, product UI, components, forms, or design systems. Use when an interface looks generic or "AI-made", or needs better typography, color, spacing, layout, hierarchy, motion, accessibility, or performance. For any coding agent doing frontend visual work. Not for backend logic, data pipelines, CLI tools, or non-UI code.4---5
6
7# designer-skill
8
9A plug-and-play MCP that gives your agent UI superpowers: design, refactor, and ship interfaces that don't look AI-made.
10
11**Foundation:** Brief by default → commit direction before code → deep refs on demand → deterministic gate before done.
12
13This file is the router. Substance lives in fifteen reference files under `reference/`; load them on demand via MCP — do not work from memory.
14
15## MCP workflow (every UI task)
16
17When the **designer-skill** MCP server is connected:
18
191. **`get_preflight_brief`** — compact binding rules (~500 tokens). Call first.
202. **`commit_design_direction`** — declare register, aesthetic, physical scene, layouts, type direction, anti-slop risks, inverse test. Must **PASS** before code.
213. **`load_project_context`** — PRODUCT.md / DESIGN.md when present. If `NO_PRODUCT_MD` on greenfield, run `get_command({ verb: "setup" })`.
224. **`dispatch_intent`** — map the user's request to verb(s) + which references to load (2–4 files, not all fifteen).
235. **`get_reference`** — load only the files `dispatch_intent` recommends.
246. Implement. When writing or fixing CSS, pull `get_reference({ name: "css-techniques" })` for idiomatic patterns (centering, specificity, logical properties, container queries, `:has()`, `clamp()`).
257. **`review_and_gate`** — scan changed files; score ≥85, zero blocking slop. Do not claim done on **FAIL**.
26
27Optional: `get_palette_seed` on greenfield (no committed brand colors); `detect_antipatterns` for ad-hoc scans; web-search MCP for contemporary UI references on visually-led net-new work (extract moves, don't copy layouts).
28
29If MCP is unavailable, read local `reference/` files using the routing map below.
30
31## Session preflight (after MCP bootstrap)
32
330. **Project context** — PRODUCT.md / DESIGN.md are authoritative when present. DESIGN.md wins visual decisions; PRODUCT.md wins strategic/voice; anti-references beat one-off prompts.
341. **Register** — **brand** (distinctiveness) vs **product** (earned familiarity). Write one physical-scene sentence.
352. **One aesthetic system** — from `reference/aesthetic-systems.md`. Never mix two signatures on one surface.
363. **Positive direction** — `reference/differentiation-playbook.md`: inverse test, layout families, named references, one weird thing (brand).
374. **Existing UI** — audit → diagnose → redesign in `reference/refactor-and-redesign.md`; preserve functionality.
38
39## Project context files
40
41- **PRODUCT.md** — register, users, purpose, 3-word personality, anti-references, strategic principles, a11y commitments.
42- **DESIGN.md** — tokens + named visual rules. Recipe in `reference/refactor-and-redesign.md`.
43
44## Reference routing map
45
46| Open this | When the task is about |
47|---|---|
48| `reference/differentiation-playbook.md` | **How to be distinctive** — inverse test, layout menu, one weird thing, named references, physical scene |
49| `reference/design-principles.md` | Visual fundamentals — typography, spacing, color, layout, hierarchy, depth (neutral baseline) |
50| `reference/aesthetic-systems.md` | Five design languages + brand-identity font procedure |
51| `reference/avoid-ai-slop.md` | **What to refuse** — ban-list, category-reflex, output-completeness, ship checklist |
52| `reference/motion-and-interaction.md` | Animation timing, springs, scroll, reduced-motion |
53| `reference/engineering-and-performance.md` | Tokens, a11y, responsive, CWV, framework-honest output |
54| `reference/refactor-and-redesign.md` | Improve existing UI without breaking it |
55| `reference/command-playbook.md` | Intent → verb dispatch |
56| `reference/interaction-design.md` | Cognitive laws, forms, navigation, errors, loading |
57| `reference/visual-critique.md` | Seven-dimension critique instrument |
58| `reference/design-systems.md` | Token architecture, component specs, theming |
59| `reference/project-init.md` | Discovery, PRODUCT.md, DESIGN.md setup |
60| `reference/craft-flow.md` | Shape-then-build pipeline with user gates |
61| `reference/live-mode.md` | Browser variant mode: HMR hot-swap |
62| `reference/css-techniques.md` | **How to write the CSS** — resets, centering, selectors/specificity, logical properties, container queries, `:has()`, `clamp()`; the cookbook for applying CSS fixes |
63
64## Precedence rule
65
66`design-principles.md` is the neutral baseline. Committing to a system in `aesthetic-systems.md` **overrides baseline** for that surface. **Existing brand identity beats both** on edits; never second-guess committed fonts, lanes, or palettes.
67
68## Cross-file ownership
69
70- Contrast, type ramp, spacing, layout → `design-principles.md`
71- Palettes, fonts, shadow tokens per system → `aesthetic-systems.md`
72- Distinctive / creative direction → `differentiation-playbook.md`
73- Bans + completeness contract → `avoid-ai-slop.md`
74- Easing, durations → `motion-and-interaction.md`
75- GPU, tokens, a11y engineering → `engineering-and-performance.md`
76- Idiomatic CSS implementation, applying CSS fixes → `css-techniques.md`
77
78## Ship gate
79
80`review_and_gate` replaces manual checklist-only shipping. It runs the 44-rule detector, computes a slop score, and returns blocking fixes. Also verify: category-reflex pass, no truncated code output, text ≥4.5:1, focus-visible rings, reduced-motion alternative, touch targets ≥44×44px, tested at 375/768/1440px.
81
82---
83
84**Source:** [`hashgraph-online/awesome-codex-plugins`](https://github.com/hashgraph-online/awesome-codex-plugins) → `plugins/Pythoughts-labs/designer-skill/skills/designer-skill/SKILL.md`
thedixitjain