Designer MCP — Research-First Design
Start with the user's source
- Capture. For a webpage or document, inspect it on the host. Save
DESIGN.md
and DESIGN.evidence.json in a reproducible design-system package with a
shared stylesheet, preview, and starter for the target medium.
- Build from a theme. Use the selected gallery reference or supplied
DESIGN.md for appearance. If an artifact is also supplied, preserve its
section order and content hierarchy. Explicit user overrides take precedence.
For
designer:opendesign:*, start with design_get to discover the selected
package's local files, then follow the OpenDesign steps in the linked workflow.
- Verify a build. Render the target, resample the applied roles, and check
coverage and visual fidelity against the selected design.
A user-selected source is sufficient grounding. Follow the
DESIGN.md workflow for these requests.
Use catalog research when the task needs a reference.
Ground every design in real product evidence before implementation. This skill
combines a research-first methodology with a local, free library of 1,540
extracted design systems.
The research library has two layers, plus a component layer:
- Styles — visual direction and taste, extracted from real web
marketing/product pages (1,342).
- Design systems — curated, hand-written design-system packages with
full typed token sets (198).
- Components and presets — 109 AI components with complete, typed TSX
source (250 variants), and 159 background gradients/patterns and
liquid-glass effects with real CSS.
Each design system also ships a Claude Design package — the files Claude
itself uses — and a rendered preview. design_claude_package reads them, so
a system can be handed to Claude directly rather than re-described.
Layers 1 and 2 are reachable through the same tools. Where the design_*
tools are available they cover both layers plus the component layer; the
refero_* tools cover styles only.
Screens and flows exist in the paid Refero product but are not in this
deployment. For screen-level or journey-level questions, use the bundled craft
references and the user's own material, and say so plainly rather than
inventing precedent.
Non-Negotiables
- Research before design work. Every design must be grounded in references
before implementation. Do not rely on the model's generic design taste.
- Use styles first for open-ended visual research. If the MCP server is
unavailable, use the bundled craft references for gaps in the brief.
- Synthesize when exploring a new direction. Study several strong references
when the user has left the visual direction open.
- Do not average references into a safe middle. When references conflict,
choose one dominant direction and preserve its sharp traits. Secondary
references may add narrow details only.
- Do not change token meanings. If a reference says a color, font, radius,
shadow, gradient, or component is for a specific role, use it only for that
role or omit it.
- Respect imagery guidance. If a style depends on photography, illustration,
product shots, or graphics, preserve the media role. Use real/generated/stock
assets when available; otherwise create an intentional placeholder with art
direction. Do not fake complex imagery with weak CSS, text, or decorative
boxes.
- Do not use generic frontend/product design skills as a parallel design
authority when this skill is available. This is the design methodology;
generic design skills tend to pull work back toward generic AI design. The
bundled
frontend-design/ sub-skill is the sanctioned implementation-craft
layer, and the bundled ui-sdk/ sub-skill (@ui-sdk/core, @ui-sdk/react,
@ui-sdk/web) is the sanctioned headless behavior/accessibility primitive
layer (also searchable via design_docs_search / design_docs_get).
- Research output must be specific. Name the references, describe concrete
choices, and explain what will be adapted.
- No design from vibe memory. Every major visual, layout, content, or
interaction decision must trace to research, the user's brief, or a craft
reference.
- Synthesize before implementation. Turn research into a concept, token
direction, and concrete decision ledger before drawing or coding.
- A brief is not a build target. Before implementation, lock either a
user-provided visual source, an existing product/design-system target, a
selected generated mockup, or an explicit reference-locked direction approved
for direct build.
- Use image generation only when it changes the outcome. Image generation
can be slow and may not exist in every coding environment. Use it for visual
exploration, mockups, imagery, illustrations, textures, and difficult assets;
skip it for small fixes, obvious production edits, or code-native UI work.
- Validate after building visual work. Compare the rendered implementation
against the locked target/reference before handoff. Fix actionable design
drift instead of treating research as sufficient.
MCP Setup
This skill is useful on its own as a research-first design methodology and
craft reference. The generic design_* server provides the offline catalog
and Markdown tools. The refero_* server is a fallback for Refero catalog reads.
The local server runs in Docker:
# Register the MCP server (Hermes / any stdio MCP client)
hermes mcp add designer \
--command docker \
--args run --rm -i --network none \
designer-mcp:latest node scripts/mcp-server.mjs
Then restart the gateway (or /reload-mcp) so the tools register.
For a browser gallery of the same data — thumbnails, swatches, type scales:
cd designer-mcp-docker && docker compose up -d # http://127.0.0.1:8787
For full tool details, read
references/mcp-tools.md.
Discovery
Before researching, form a short design brief. Ask only for missing information
that would materially change the result; otherwise make reasonable assumptions
and proceed.
Clarify:
- what is being designed
- platform: web, iOS, or both
- audience and technical level
- primary user goal
- desired feeling or brand direction
- business/user objections to overcome
- constraints: existing brand, framework, deadline, accessibility, content
- whether the task needs visual direction, concrete UI patterns, journey logic, or a mix
- whether the task should go directly to code, produce visual options first, or
create generated assets during implementation
Brief format:
Designing [WHAT] for [WHO] on [PLATFORM].
Goal: [PRIMARY USER GOAL].
Tone: [DESIRED FEELING].
Main objection/risk: [OBJECTION].
Must remember: [HOOK OR DISTINCTIVE IDEA].
Constraints: [CONSTRAINTS].
Research needed: [styles/screens/flows].
Path: [direct build / visual exploration / audit / asset generation].
Workflow Routing
Choose the lightest workflow that can produce a high-quality result.
- Direct build: use for small UI fixes, clear production edits, existing
design-system work, or tasks with a concrete source to match. Research and
lock the direction, then code.
- Visual exploration: use when the user asks for variants, a new visual
language, a major redesign, a landing page, or another high-visibility surface
with several plausible directions. Default to three reference-locked options
and ask the user to choose; see
references/visual-workflow.md.
- Audit: use captured screenshots or style references as evidence before
critique.
- Asset generation: use generated imagery only when the reference lock
requires bitmap media that code, icons, or existing assets cannot faithfully
provide; see references/visual-workflow.md.
Document and Deliverable Skills
This skill bundles complete document toolchains as sub-skills. When the task
requires producing, reading, editing, or converting an actual file
deliverable, read the matching sub-skill and follow it:
| Deliverable |
Sub-skill |
| Word documents (.docx, .dotx) |
docx/SKILL.md |
| Slide decks (.pptx, .potx) |
pptx/SKILL.md |
| Spreadsheets (.xlsx, .xlsm, .csv) |
xlsx/SKILL.md |
| PDF creation, forms, merging, OCR |
pdf/SKILL.md |
| Reading PDFs from disk |
pdf-reading/SKILL.md |
| Implementation craft for UI work |
frontend-design/SKILL.md |
The division of authority is fixed. This skill's research workflow and
reference lock own every design decision: palette, type, layout, imagery, copy.
The document sub-skills supply the file mechanics and the render-and-inspect QA
loop; frontend-design/ supplies implementation craft inside this workflow.
When a deliverable is a design artifact (brand guidelines, spec deck, token
workbook), style it from the locked reference instead of falling back to
default document styling. Script paths inside each sub-skill are relative to
that sub-skill's own directory.
The sub-skills span two runtimes. Match the runtime to the task; do not
install everything for every job.
| Sub-skill |
Create (Node.js) |
Edit, inspect, validate (Python) |
| pptx |
pptxgenjs; scripts/apply_theme.js injects the theme |
python-pptx, Pillow, defusedxml, lxml; LibreOffice via scripts/office/soffice.py |
| docx |
docx (docx-js) |
lxml, defusedxml, validators; LibreOffice via scripts/office/soffice.py |
| xlsx |
none |
openpyxl, pandas; scripts/recalc.py drives LibreOffice |
| pdf |
none required (pdf-lib is the named JS alternative) |
pypdf, pdfplumber, pdf2image, Pillow |
| pdf-reading |
none |
pypdf, pdfplumber (optional: pypdfium2, pytesseract) |
Dependencies: Python packages in requirements.txt, npm
packages in package.json (docx, pptxgenjs, jszip), plus
the system tools (soffice, pdftoppm, pandoc) named in the sub-skills that
use them. Conditional npm packages are deliberately not in the
manifest: react-icons, react, react-dom, and sharp (the pptx icon
recipe) and pdf-lib (PDF work in JavaScript) install on demand when a
require fails. Check what is available before relying on any of it and
install only what is missing.
Tool Routing
Use Styles First For Visual Work
Use design_search when visual work needs a reference.
A style is a semantic design reference extracted from a real web
marketing/product page. It is not a screenshot and not a component library.
Search results give previews. Full style references from design_get provide
design guidance such as visual thesis, tokens, typography, layout/composition,
section rhythm, spacing, elevation, surfaces, components, imagery treatment,
implementation notes, and do/don't rules.
Coverage: web marketing/product pages — landing pages, pricing pages, product
marketing sites, editorial brand sites, and SaaS websites. In-app dashboards,
auth screens, settings screens, and iOS app screens are not covered as style
systems. For product UI tasks, establish visual language from styles, then use
the craft references for the product logic.
Use styles for:
- look and feel
- brand direction
- landing pages and marketing pages
- typography, palette, layout, section structure, spacing, radius, elevation, surfaces
- component treatments and sometimes component/code examples
- imagery and product screenshot treatment
- design-system inspiration
- making a generic interface feel more tasteful
After finding strong styles:
- use
design_get for full details
- use
design_markdown to retrieve the catalog's DESIGN.md
- use
design_facets to see what fonts, colors, themes, and industries the
catalog actually contains before committing to a direction
Use Components For Implementation
Styles tell you what a visual direction should feel like. Components are the
other half: actual working code, not a description of it.
The library holds 109 AI components across 250 variants — prompt inputs,
conversations, tool calls, agents, voice, media generation, usage meters,
writing surfaces. Each variant's source is complete, typed TSX: props
declared, motion/react and lucide-react imported, no elisions.
Use components for:
- building a chat or agent interface rather than describing one
- a prompt box, streaming response, tool-call row, or agent activity feed
- voice input, media generation states, usage and limit meters
Workflow:
design_component_search with a query or category to find candidates
design_component_get for the full record — variants, FAQ, dependencies
design_component_code to pull the source for a specific variant
These are third-party MIT-licensed components, not your design system. Treat
them as reference implementations: adapt them to the visual direction you
locked from styles, rather than dropping them in unchanged.
Use Presets For Backgrounds And Effects
design_preset_search and design_preset_get cover 139 background
gradients and patterns plus 20 liquid-glass effects. Each carries real CSS
and a React template. Use them for hero and section backgrounds, ambient
gradients, and glass surfaces.
Use Templates For Starting A System
Six vendored design-system templates ship in the image: modernist, classical,
nocturne, organic, broadsheet, industry. Each is a complete, generic system
with a token sheet (styles.css), written rules (readme.md), foundation and
component demo cards, and two starter templates (a landing page and a 21-slide
deck). Use them when the task is to start a project or product from a coherent
system rather than from scratch.
Workflow:
design_template_list to see all six (swatches, fonts, token counts)
design_manifest_template with a slug to get the design-system manifest:
a manifest JSON with sections for overview/principles, colors, typography,
spacing, corner radius, shadows, components, and assets, already filled
from that system. Call it without slug for the blank template when
building a system from a style reference instead.
design_template_get for the full record: theme parameters, every token,
the component class table, the file listing
design_template_file to copy an individual file (the token sheet, a
starter page, the guide). Binary assets are refused.
Rules:
- Treat the manifest as a contract, not documentation. Keep it beside the
work and design against it. No color outside roles and ramps. No raw px
where a token exists. No font family outside the two roles.
- Keep the system's anti-patterns (
overview.antiPatterns). Each template
has deliberate extremes (zero radius, dark-only, pill shapes); do not
soften them toward generic.
- Blend with research: start from the template closest to the locked
direction, then retune its theme knobs. Or fill a blank manifest from the
primary style reference.
- Seed a manifest from a catalog design or your own DESIGN.md with
design_manifest_from. Its provenance records available tokens, conflicts,
and gaps.
For Product Patterns and Journeys
This deployment has no screens or flows layer. When the task needs
concrete UI patterns (a specific screen type, a form state, a pricing page
layout) or journey logic (onboarding, checkout, cancellation):
- use the bundled craft references — they cover forms, focus, empty states,
onboarding patterns, and conversion craft
- use the user's existing product, screenshots, or design system when provided
- be explicit that these are craft-grounded rather than reference-grounded
Do not fabricate precedent you did not look up.
Use Visual Workflow For Images And QA
For image generation, visual options, generated assets, and visual QA, read
references/visual-workflow.md when the task
needs it.
Research Workflow
1. Research Visual Direction With Styles
For any visual design task, start here.
Recommended loop:
- Search 3-5 different visual angles.
- Include one broad aesthetic query.
- Include one domain/category query.
- Include one known-brand or strong-product query when relevant.
- Retrieve 3-4 strong styles with
design_get. Full styles are large, so
split larger research into multiple batches.
- Compare what each style contributes.
- Choose one primary foundation and borrow 1-2 specific details from other styles.
- Lock the primary reference's signature traits before implementation.
Good style queries and the full extraction checklist (what to pull from each
style: thesis, type, color roles, spacing, layout, components, imagery, media
strategy, do/don't rules) are listed in
references/research-playbook.md.
Synthesis rule:
- Primary style: overall mood, density, and structure.
- Secondary styles: specific borrowed details.
- User context: adapt everything to the product, audience, and task.
- Do not use the average/intersection of all references. If one reference is
dark, one is acid, and one is serif, the answer is not warm cream + muted
orange + polite serif.
Never present the result as "copying X". Present it as a new direction inspired
by several references.
Before implementation, create a reference lock:
Primary reference/direction: [one dominant source]
Preserve: [3-5 traits that must survive: canvas, type, accent, layout, density, media]
Borrow only: [1-2 specific secondary details]
Role rules: [source token/component meanings to preserve, e.g. CTA-only, code-only, decorative-only]
Media strategy: [real/generated/stock/code-native/placeholder, with aspect ratio and art direction]
Reject: [defaults/averages that would collapse the direction]
Token commitments: [background, type, accent, radius, border/shadow, imagery treatment, with roles]
If implementation drifts from the lock, stop and correct it. Do not soften
distinctive traits into safer colors, safer fonts, softer radius, or generic
section layouts. Reference lock is not cloning; it preserves selected traits
while adapting content, brand, and interaction details to the user's product.
When combining styles, assign each source a bounded job. For example: one
source may own canvas/type, another may own code-window treatment, and another
may own primary CTA. Never move a token outside its source role: CTA colors stay
CTA-only, syntax colors stay inside code, decorative gradients stay decorative,
and card/button rules keep their specified radius, shadow, and state behavior.
If the primary style is image-led, do not replace it with text-only layout. If
you cannot produce the needed image or graphic, preserve the slot with stable
dimensions, aspect ratio, caption/alt text, and a short art-direction note.
Build simple diagrams, icons, code windows, or geometric primitives only when
they match the source style.
For substantial visual exploration, generated mockups, bitmap assets, or
post-build visual QA, follow
references/visual-workflow.md.
2. Product Patterns Without a Screens Layer
Use the craft references when the task needs to know what an interface should
contain or how real products solve a specific UI problem.
| Need |
Reference |
| Form design, focus states, empty states, tables, onboarding patterns |
references/craft-details.md |
| CTA copy, trust signals, objection handling, conversion structure |
references/copywriting.md |
| Component/icon selection |
references/icons.md |
| Type roles and hierarchy decisions |
references/typography.md |
| Color roles, contrast, palette discipline |
references/color.md |
Extract from these:
- layout structure
- information hierarchy
- component choices
- CTA patterns
- content/copy patterns
- states and edge cases
- trust or conversion tactics
- concrete details worth adapting
3. Journey Logic Without a Flows Layer
When the task has multiple steps or a user changes state over time, reason from
the interaction pattern rather than claiming precedent:
- entry point and exit state
- step count
- decisions the user makes
- friction reducers
- required confirmations
- save/recovery states
- error handling
- retention or persuasion moments
- system response at each step
Research Depth and Synthesis
Match depth to task risk, then separate findings into three buckets: visual
direction (from styles), product pattern (from craft references and user
material), and journey logic (from interaction reasoning).
For the depth ladder per task type, the output formats for each bucket, the
research-summary template, and the decision-ledger table, read
references/research-playbook.md.
Design Craft
After research, execute like a senior product designer. Use the bundled
references only when relevant; do not load every file by default.
- Typography: references/typography.md
- Color: references/color.md
- Motion: references/motion.md
- Icons: references/icons.md
- Forms, focus, images, touch, performance, accessibility: references/craft-details.md
- Copywriting and persuasion: references/copywriting.md
- Anti-AI-slop checks: references/anti-ai-slop.md
Core craft rules:
- Define tokens before implementation: type scale, colors, spacing, radius, shadows.
- Preserve the primary reference's strongest traits instead of normalizing them.
- Preserve token roles from references. Do not turn a CTA accent into a
background, a code-only color into UI chrome, or a decorative gradient into an
interface surface.
- Preserve imagery roles from references. Use capable assets when available;
otherwise prefer an honest, well-sized placeholder over a poor fake
illustration or photo.
- Use brand-appropriate colors from research. Do not default to indigo/violet
unless the user explicitly asks for it.
- Treat "calm editorial" as a current AI-slop risk. Do not default to decorative
headline word swaps: one word or short phrase set in a different
display/serif/script/italic style or accent color, warm ivory/cream canvases,
or olive/clay/terracotta palettes unless research and product context
justify them.
- Avoid generic hero -> features grid -> pricing -> FAQ -> CTA unless research
supports it.
- Use real product evidence for copy, trust signals, objection handling, and
section order.
- Create at least one memorable detail: a visual move, interaction, layout
choice, or copy detail users would remember.
- Balance headings and short display text with
text-wrap: balance; use
text-wrap: pretty selectively for prose. Check key breakpoints for orphan
words and awkward final lines.
- Keep accessibility and responsive behavior in the design, not as a late pass.
Quality Gate
Before final delivery, confirm:
- Did I use styles for visual taste?
- Did I avoid copying one style directly?
- Did I synthesize multiple references into a unique direction?
- Did I avoid averaging references into a safe centroid?
- Did I preserve the primary reference's signature traits?
- Did I preserve source token/component roles instead of repurposing them?
- Did I preserve required imagery/media roles with real assets, appropriate
primitives, or intentional placeholders?
- Can I name which references influenced the design and why?
- Can every major design choice be traced to a reference, user constraint, or
craft rule?
- Did I produce a concept and decision ledger before implementation?
- Does the implementation avoid generic AI design defaults?
- Did I avoid decorative serif/italic/color word swaps unless reference and
content role justify them?
- Does the result fit the user's product, audience, and constraints?
If the answer is no, research or refine more before delivering.
For substantial visual work, run the visual QA pass in
references/visual-workflow.md before handoff.
Example
For a complete walkthrough, see
references/example-workflow.md.
Provenance
The methodology and the bundled craft references are adapted from Refero's
MIT-licensed refero_skill
(Copyright (c) 2026 Refero). The MCP tools, cache pipeline, and gallery in this
deployment are local and free — they read public pages rather than the paid
Refero API, so the screens and flows layers are not available here.
1---2name: designer-mcp3description: "Capture the design and structure of a webpage or document as DESIGN.md and a companion evidence file. Use for UI design, applying an existing DESIGN.md or a selected gallery theme, and verifying visual implementation. Includes an offline design catalog and bundled skills for Word, PowerPoint, Excel, and PDF."4metadata:5 source: https://skillmd.com/skills/whit3rabbit/designer-mcp6---78# Designer MCP — Research-First Design910## Start with the user's source1112- **Capture.** For a webpage or document, inspect it on the host. Save `DESIGN.md`13 and `DESIGN.evidence.json` in a reproducible design-system package with a14 shared stylesheet, preview, and starter for the target medium.15- **Build from a theme.** Use the selected gallery reference or supplied16 DESIGN.md for appearance. If an artifact is also supplied, preserve its17 section order and content hierarchy. Explicit user overrides take precedence.18 For `designer:opendesign:*`, start with `design_get` to discover the selected19 package's local files, then follow the OpenDesign steps in the linked workflow.20- **Verify a build.** Render the target, resample the applied roles, and check21 coverage and visual fidelity against the selected design.2223A user-selected source is sufficient grounding. Follow the24[DESIGN.md workflow](references/design-md-workflow.md) for these requests.25Use catalog research when the task needs a reference.2627Ground every design in real product evidence before implementation. This skill28combines a research-first methodology with a **local, free** library of 1,54029extracted design systems.3031The research library has two layers, plus a component layer:32331. **Styles** — visual direction and taste, extracted from real web34 marketing/product pages (1,342).352. **Design systems** — curated, hand-written design-system packages with36 full typed token sets (198).373. **Components and presets** — 109 AI components with complete, typed TSX38 source (250 variants), and 159 background gradients/patterns and39 liquid-glass effects with real CSS.4041Each design system also ships a **Claude Design package** — the files Claude42itself uses — and a rendered preview. `design_claude_package` reads them, so43a system can be handed to Claude directly rather than re-described.4445Layers 1 and 2 are reachable through the same tools. Where the `design_*`46tools are available they cover both layers plus the component layer; the47`refero_*` tools cover styles only.4849Screens and flows exist in the paid Refero product but are **not** in this50deployment. For screen-level or journey-level questions, use the bundled craft51references and the user's own material, and say so plainly rather than52inventing precedent.5354## Non-Negotiables5556- **Research before design work.** Every design must be grounded in references57 before implementation. Do not rely on the model's generic design taste.58- **Use styles first for open-ended visual research.** If the MCP server is59 unavailable, use the bundled craft references for gaps in the brief.60- **Synthesize when exploring a new direction.** Study several strong references61 when the user has left the visual direction open.62- **Do not average references into a safe middle.** When references conflict,63 choose one dominant direction and preserve its sharp traits. Secondary64 references may add narrow details only.65- **Do not change token meanings.** If a reference says a color, font, radius,66 shadow, gradient, or component is for a specific role, use it only for that67 role or omit it.68- **Respect imagery guidance.** If a style depends on photography, illustration,69 product shots, or graphics, preserve the media role. Use real/generated/stock70 assets when available; otherwise create an intentional placeholder with art71 direction. Do not fake complex imagery with weak CSS, text, or decorative72 boxes.73- **Do not use generic frontend/product design skills as a parallel design74 authority** when this skill is available. This is the design methodology;75 generic design skills tend to pull work back toward generic AI design. The76 bundled `frontend-design/` sub-skill is the sanctioned implementation-craft77 layer, and the bundled `ui-sdk/` sub-skill (`@ui-sdk/core`, `@ui-sdk/react`,78 `@ui-sdk/web`) is the sanctioned headless behavior/accessibility primitive79 layer (also searchable via `design_docs_search` / `design_docs_get`).80- **Research output must be specific.** Name the references, describe concrete81 choices, and explain what will be adapted.82- **No design from vibe memory.** Every major visual, layout, content, or83 interaction decision must trace to research, the user's brief, or a craft84 reference.85- **Synthesize before implementation.** Turn research into a concept, token86 direction, and concrete decision ledger before drawing or coding.87- **A brief is not a build target.** Before implementation, lock either a88 user-provided visual source, an existing product/design-system target, a89 selected generated mockup, or an explicit reference-locked direction approved90 for direct build.91- **Use image generation only when it changes the outcome.** Image generation92 can be slow and may not exist in every coding environment. Use it for visual93 exploration, mockups, imagery, illustrations, textures, and difficult assets;94 skip it for small fixes, obvious production edits, or code-native UI work.95- **Validate after building visual work.** Compare the rendered implementation96 against the locked target/reference before handoff. Fix actionable design97 drift instead of treating research as sufficient.9899## MCP Setup100101This skill is useful on its own as a research-first design methodology and102craft reference. The generic `design_*` server provides the offline catalog103and Markdown tools. The `refero_*` server is a fallback for Refero catalog reads.104105The local server runs in Docker:106107```bash108# Register the MCP server (Hermes / any stdio MCP client)109hermes mcp add designer \110 --command docker \111 --args run --rm -i --network none \112 designer-mcp:latest node scripts/mcp-server.mjs113```114115Then restart the gateway (or `/reload-mcp`) so the tools register.116117For a browser gallery of the same data — thumbnails, swatches, type scales:118119```bash120cd designer-mcp-docker && docker compose up -d # http://127.0.0.1:8787121```122123For full tool details, read124[references/mcp-tools.md](references/mcp-tools.md).125126## Discovery127128Before researching, form a short design brief. Ask only for missing information129that would materially change the result; otherwise make reasonable assumptions130and proceed.131132Clarify:133134- what is being designed135- platform: web, iOS, or both136- audience and technical level137- primary user goal138- desired feeling or brand direction139- business/user objections to overcome140- constraints: existing brand, framework, deadline, accessibility, content141- whether the task needs visual direction, concrete UI patterns, journey logic, or a mix142- whether the task should go directly to code, produce visual options first, or143 create generated assets during implementation144145Brief format:146147```text148Designing [WHAT] for [WHO] on [PLATFORM].149Goal: [PRIMARY USER GOAL].150Tone: [DESIRED FEELING].151Main objection/risk: [OBJECTION].152Must remember: [HOOK OR DISTINCTIVE IDEA].153Constraints: [CONSTRAINTS].154Research needed: [styles/screens/flows].155Path: [direct build / visual exploration / audit / asset generation].156```157158## Workflow Routing159160Choose the lightest workflow that can produce a high-quality result.161162- **Direct build:** use for small UI fixes, clear production edits, existing163 design-system work, or tasks with a concrete source to match. Research and164 lock the direction, then code.165- **Visual exploration:** use when the user asks for variants, a new visual166 language, a major redesign, a landing page, or another high-visibility surface167 with several plausible directions. Default to three reference-locked options168 and ask the user to choose; see169 [references/visual-workflow.md](references/visual-workflow.md).170- **Audit:** use captured screenshots or style references as evidence before171 critique.172- **Asset generation:** use generated imagery only when the reference lock173 requires bitmap media that code, icons, or existing assets cannot faithfully174 provide; see [references/visual-workflow.md](references/visual-workflow.md).175176## Document and Deliverable Skills177178This skill bundles complete document toolchains as sub-skills. When the task179requires producing, reading, editing, or converting an actual file180deliverable, read the matching sub-skill and follow it:181182| Deliverable | Sub-skill |183|---|---|184| Word documents (.docx, .dotx) | [docx/SKILL.md](docx/SKILL.md) |185| Slide decks (.pptx, .potx) | [pptx/SKILL.md](pptx/SKILL.md) |186| Spreadsheets (.xlsx, .xlsm, .csv) | [xlsx/SKILL.md](xlsx/SKILL.md) |187| PDF creation, forms, merging, OCR | [pdf/SKILL.md](pdf/SKILL.md) |188| Reading PDFs from disk | [pdf-reading/SKILL.md](pdf-reading/SKILL.md) |189| Implementation craft for UI work | [frontend-design/SKILL.md](frontend-design/SKILL.md) |190191The division of authority is fixed. This skill's research workflow and192reference lock own every design decision: palette, type, layout, imagery, copy.193The document sub-skills supply the file mechanics and the render-and-inspect QA194loop; `frontend-design/` supplies implementation craft inside this workflow.195When a deliverable is a design artifact (brand guidelines, spec deck, token196workbook), style it from the locked reference instead of falling back to197default document styling. Script paths inside each sub-skill are relative to198that sub-skill's own directory.199200The sub-skills span two runtimes. Match the runtime to the task; do not201install everything for every job.202203| Sub-skill | Create (Node.js) | Edit, inspect, validate (Python) |204|---|---|---|205| pptx | `pptxgenjs`; `scripts/apply_theme.js` injects the theme | `python-pptx`, `Pillow`, `defusedxml`, `lxml`; LibreOffice via `scripts/office/soffice.py` |206| docx | `docx` (docx-js) | `lxml`, `defusedxml`, `validators`; LibreOffice via `scripts/office/soffice.py` |207| xlsx | none | `openpyxl`, `pandas`; `scripts/recalc.py` drives LibreOffice |208| pdf | none required (`pdf-lib` is the named JS alternative) | `pypdf`, `pdfplumber`, `pdf2image`, `Pillow` |209| pdf-reading | none | `pypdf`, `pdfplumber` (optional: `pypdfium2`, `pytesseract`) |210211Dependencies: Python packages in [requirements.txt](requirements.txt), npm212packages in [package.json](package.json) (`docx`, `pptxgenjs`, `jszip`), plus213the system tools (`soffice`, `pdftoppm`, `pandoc`) named in the sub-skills that214use them. Conditional npm packages are deliberately not in the215manifest: `react-icons`, `react`, `react-dom`, and `sharp` (the pptx icon216recipe) and `pdf-lib` (PDF work in JavaScript) install on demand when a217require fails. Check what is available before relying on any of it and218install only what is missing.219220## Tool Routing221222### Use Styles First For Visual Work223224Use `design_search` when visual work needs a reference.225226A style is a semantic design reference extracted from a real web227marketing/product page. It is not a screenshot and not a component library.228Search results give previews. Full style references from `design_get` provide229design guidance such as visual thesis, tokens, typography, layout/composition,230section rhythm, spacing, elevation, surfaces, components, imagery treatment,231implementation notes, and do/don't rules.232233Coverage: web marketing/product pages — landing pages, pricing pages, product234marketing sites, editorial brand sites, and SaaS websites. In-app dashboards,235auth screens, settings screens, and iOS app screens are not covered as style236systems. For product UI tasks, establish visual language from styles, then use237the craft references for the product logic.238239Use styles for:240241- look and feel242- brand direction243- landing pages and marketing pages244- typography, palette, layout, section structure, spacing, radius, elevation, surfaces245- component treatments and sometimes component/code examples246- imagery and product screenshot treatment247- design-system inspiration248- making a generic interface feel more tasteful249250After finding strong styles:251252- use `design_get` for full details253- use `design_markdown` to retrieve the catalog's DESIGN.md254- use `design_facets` to see what fonts, colors, themes, and industries the255 catalog actually contains before committing to a direction256257### Use Components For Implementation258259Styles tell you what a visual direction should feel like. Components are the260other half: **actual working code**, not a description of it.261262The library holds 109 AI components across 250 variants — prompt inputs,263conversations, tool calls, agents, voice, media generation, usage meters,264writing surfaces. Each variant's source is complete, typed TSX: props265declared, `motion/react` and `lucide-react` imported, no elisions.266267Use components for:268269- building a chat or agent interface rather than describing one270- a prompt box, streaming response, tool-call row, or agent activity feed271- voice input, media generation states, usage and limit meters272273Workflow:274275- `design_component_search` with a `query` or `category` to find candidates276- `design_component_get` for the full record — variants, FAQ, dependencies277- `design_component_code` to pull the source for a specific variant278279These are third-party MIT-licensed components, not your design system. Treat280them as reference implementations: adapt them to the visual direction you281locked from styles, rather than dropping them in unchanged.282283### Use Presets For Backgrounds And Effects284285`design_preset_search` and `design_preset_get` cover 139 background286gradients and patterns plus 20 liquid-glass effects. Each carries real CSS287and a React template. Use them for hero and section backgrounds, ambient288gradients, and glass surfaces.289290### Use Templates For Starting A System291292Six vendored design-system templates ship in the image: modernist, classical,293nocturne, organic, broadsheet, industry. Each is a complete, generic system294with a token sheet (`styles.css`), written rules (`readme.md`), foundation and295component demo cards, and two starter templates (a landing page and a 21-slide296deck). Use them when the task is to start a project or product from a coherent297system rather than from scratch.298299Workflow:300301- `design_template_list` to see all six (swatches, fonts, token counts)302- `design_manifest_template` with a `slug` to get the design-system manifest:303 a manifest JSON with sections for overview/principles, colors, typography,304 spacing, corner radius, shadows, components, and assets, already filled305 from that system. Call it without `slug` for the blank template when306 building a system from a style reference instead.307- `design_template_get` for the full record: theme parameters, every token,308 the component class table, the file listing309- `design_template_file` to copy an individual file (the token sheet, a310 starter page, the guide). Binary assets are refused.311312Rules:313314- Treat the manifest as a contract, not documentation. Keep it beside the315 work and design against it. No color outside roles and ramps. No raw px316 where a token exists. No font family outside the two roles.317- Keep the system's anti-patterns (`overview.antiPatterns`). Each template318 has deliberate extremes (zero radius, dark-only, pill shapes); do not319 soften them toward generic.320- Blend with research: start from the template closest to the locked321 direction, then retune its theme knobs. Or fill a blank manifest from the322 primary style reference.323- Seed a manifest from a catalog design or your own DESIGN.md with324 `design_manifest_from`. Its provenance records available tokens, conflicts,325 and gaps.326327### For Product Patterns and Journeys328329This deployment has **no screens or flows layer**. When the task needs330concrete UI patterns (a specific screen type, a form state, a pricing page331layout) or journey logic (onboarding, checkout, cancellation):332333- use the bundled craft references — they cover forms, focus, empty states,334 onboarding patterns, and conversion craft335- use the user's existing product, screenshots, or design system when provided336- be explicit that these are craft-grounded rather than reference-grounded337338Do not fabricate precedent you did not look up.339340### Use Visual Workflow For Images And QA341342For image generation, visual options, generated assets, and visual QA, read343[references/visual-workflow.md](references/visual-workflow.md) when the task344needs it.345346## Research Workflow347348### 1. Research Visual Direction With Styles349350For any visual design task, start here.351352Recommended loop:3533541. Search 3-5 different visual angles.3552. Include one broad aesthetic query.3563. Include one domain/category query.3574. Include one known-brand or strong-product query when relevant.3585. Retrieve 3-4 strong styles with `design_get`. Full styles are large, so359 split larger research into multiple batches.3606. Compare what each style contributes.3617. Choose one primary foundation and borrow 1-2 specific details from other styles.3628. Lock the primary reference's signature traits before implementation.363364Good style queries and the full extraction checklist (what to pull from each365style: thesis, type, color roles, spacing, layout, components, imagery, media366strategy, do/don't rules) are listed in367[references/research-playbook.md](references/research-playbook.md).368369Synthesis rule:370371- Primary style: overall mood, density, and structure.372- Secondary styles: specific borrowed details.373- User context: adapt everything to the product, audience, and task.374- Do not use the average/intersection of all references. If one reference is375 dark, one is acid, and one is serif, the answer is not warm cream + muted376 orange + polite serif.377378Never present the result as "copying X". Present it as a new direction inspired379by several references.380381Before implementation, create a reference lock:382383```text384Primary reference/direction: [one dominant source]385Preserve: [3-5 traits that must survive: canvas, type, accent, layout, density, media]386Borrow only: [1-2 specific secondary details]387Role rules: [source token/component meanings to preserve, e.g. CTA-only, code-only, decorative-only]388Media strategy: [real/generated/stock/code-native/placeholder, with aspect ratio and art direction]389Reject: [defaults/averages that would collapse the direction]390Token commitments: [background, type, accent, radius, border/shadow, imagery treatment, with roles]391```392393If implementation drifts from the lock, stop and correct it. Do not soften394distinctive traits into safer colors, safer fonts, softer radius, or generic395section layouts. Reference lock is not cloning; it preserves selected traits396while adapting content, brand, and interaction details to the user's product.397398When combining styles, assign each source a bounded job. For example: one399source may own canvas/type, another may own code-window treatment, and another400may own primary CTA. Never move a token outside its source role: CTA colors stay401CTA-only, syntax colors stay inside code, decorative gradients stay decorative,402and card/button rules keep their specified radius, shadow, and state behavior.403404If the primary style is image-led, do not replace it with text-only layout. If405you cannot produce the needed image or graphic, preserve the slot with stable406dimensions, aspect ratio, caption/alt text, and a short art-direction note.407Build simple diagrams, icons, code windows, or geometric primitives only when408they match the source style.409410For substantial visual exploration, generated mockups, bitmap assets, or411post-build visual QA, follow412[references/visual-workflow.md](references/visual-workflow.md).413414### 2. Product Patterns Without a Screens Layer415416Use the craft references when the task needs to know what an interface should417contain or how real products solve a specific UI problem.418419| Need | Reference |420|---|---|421| Form design, focus states, empty states, tables, onboarding patterns | [references/craft-details.md](references/craft-details.md) |422| CTA copy, trust signals, objection handling, conversion structure | [references/copywriting.md](references/copywriting.md) |423| Component/icon selection | [references/icons.md](references/icons.md) |424| Type roles and hierarchy decisions | [references/typography.md](references/typography.md) |425| Color roles, contrast, palette discipline | [references/color.md](references/color.md) |426427Extract from these:428429- layout structure430- information hierarchy431- component choices432- CTA patterns433- content/copy patterns434- states and edge cases435- trust or conversion tactics436- concrete details worth adapting437438### 3. Journey Logic Without a Flows Layer439440When the task has multiple steps or a user changes state over time, reason from441the interaction pattern rather than claiming precedent:442443- entry point and exit state444- step count445- decisions the user makes446- friction reducers447- required confirmations448- save/recovery states449- error handling450- retention or persuasion moments451- system response at each step452453## Research Depth and Synthesis454455Match depth to task risk, then separate findings into three buckets: visual456direction (from styles), product pattern (from craft references and user457material), and journey logic (from interaction reasoning).458459For the depth ladder per task type, the output formats for each bucket, the460research-summary template, and the decision-ledger table, read461[references/research-playbook.md](references/research-playbook.md).462463## Design Craft464465After research, execute like a senior product designer. Use the bundled466references only when relevant; do not load every file by default.467468- Typography: [references/typography.md](references/typography.md)469- Color: [references/color.md](references/color.md)470- Motion: [references/motion.md](references/motion.md)471- Icons: [references/icons.md](references/icons.md)472- Forms, focus, images, touch, performance, accessibility: [references/craft-details.md](references/craft-details.md)473- Copywriting and persuasion: [references/copywriting.md](references/copywriting.md)474- Anti-AI-slop checks: [references/anti-ai-slop.md](references/anti-ai-slop.md)475476Core craft rules:477478- Define tokens before implementation: type scale, colors, spacing, radius, shadows.479- Preserve the primary reference's strongest traits instead of normalizing them.480- Preserve token roles from references. Do not turn a CTA accent into a481 background, a code-only color into UI chrome, or a decorative gradient into an482 interface surface.483- Preserve imagery roles from references. Use capable assets when available;484 otherwise prefer an honest, well-sized placeholder over a poor fake485 illustration or photo.486- Use brand-appropriate colors from research. Do not default to indigo/violet487 unless the user explicitly asks for it.488- Treat "calm editorial" as a current AI-slop risk. Do not default to decorative489 headline word swaps: one word or short phrase set in a different490 display/serif/script/italic style or accent color, warm ivory/cream canvases,491 or olive/clay/terracotta palettes unless research and product context492 justify them.493- Avoid generic hero -> features grid -> pricing -> FAQ -> CTA unless research494 supports it.495- Use real product evidence for copy, trust signals, objection handling, and496 section order.497- Create at least one memorable detail: a visual move, interaction, layout498 choice, or copy detail users would remember.499- Balance headings and short display text with `text-wrap: balance`; use500 `text-wrap: pretty` selectively for prose. Check key breakpoints for orphan501 words and awkward final lines.502- Keep accessibility and responsive behavior in the design, not as a late pass.503504## Quality Gate505506Before final delivery, confirm:507508- Did I use styles for visual taste?509- Did I avoid copying one style directly?510- Did I synthesize multiple references into a unique direction?511- Did I avoid averaging references into a safe centroid?512- Did I preserve the primary reference's signature traits?513- Did I preserve source token/component roles instead of repurposing them?514- Did I preserve required imagery/media roles with real assets, appropriate515 primitives, or intentional placeholders?516- Can I name which references influenced the design and why?517- Can every major design choice be traced to a reference, user constraint, or518 craft rule?519- Did I produce a concept and decision ledger before implementation?520- Does the implementation avoid generic AI design defaults?521- Did I avoid decorative serif/italic/color word swaps unless reference and522 content role justify them?523- Does the result fit the user's product, audience, and constraints?524525If the answer is no, research or refine more before delivering.526527For substantial visual work, run the visual QA pass in528[references/visual-workflow.md](references/visual-workflow.md) before handoff.529530## Example531532For a complete walkthrough, see533[references/example-workflow.md](references/example-workflow.md).534535## Provenance536537The methodology and the bundled craft references are adapted from Refero's538MIT-licensed [`refero_skill`](https://github.com/referodesign/refero_skill)539(Copyright (c) 2026 Refero). The MCP tools, cache pipeline, and gallery in this540deployment are local and free — they read public pages rather than the paid541Refero API, so the screens and flows layers are not available here.