Open Design

---
name: open-design
description: Generate design artifacts (landing pages, decks, prototypes, dashboards, components) using Open Design's bundled design skills and design systems. Use whenever the user asks to design, build, mock up, or generate something visual — a landing page, pitch deck, dashboard, prototype, or marketing page — even if they don't say "Open Design" explicitly.
---

Open Design is a bundled catalog of design skills and design templates (reusable task recipes and rendering styles — both usable interchangeably as a `skillId`) plus design systems (brand-inspired visual token sets), exposed through the `open-design` MCP server's tools.

Every skill/template id is namespaced as `od:<mode>:<name>` (e.g. `od:deck:guizang-ppt`), where `mode` is one of: `prototype`, `deck`, `design-system`, `image`, `video`, `template`, `utility`, `audio`. Always pass the full namespaced id as `skillId`. Note: mode `design-system` means "a skill that helps author a design-system deliverable" — it has nothing to do with `designSystemId`, which selects from the separate library of ~150 prebuilt brand design systems (see step 2).

A small, curated subset of skills/templates also has its own explicit `/open-design:<id>` skill — if the user's request closely matches one of those, prefer invoking it directly; it pins the exact skillId and often a ready-made example brief, removing any guesswork. Otherwise, follow the flow below yourself.

All Open Design content (skill/template text, design system tokens, example briefs) is delivered to you as plain text through the MCP tool calls below — never as a file path. You never need to, and should not, browse or search for Open Design's own files anywhere on disk; `list_open_design_skills` and `prepare_open_design_brief` already return everything you need as plain text.

Follow this flow:

0. **Check the tools are wired up.** This skill does nothing on its own — every step below calls a tool the `open-design` MCP server provides. If `list_open_design_skills` (or any other tool named below) isn't available to you right now, the server hasn't been registered in this project yet. Set it up, then retry from step 1:
   - **Claude Code:** run `npx @feimacode/open-design-agent-kit init --tools claude` in the project root, or `claude mcp add open-design -- npx -y @feimacode/open-design-agent-kit-mcp`.
   - **Codex CLI:** run `npx @feimacode/open-design-agent-kit init --tools codex` in the project root.
   - **Any other MCP-capable agent** (Cursor, etc.): register `npx -y @feimacode/open-design-agent-kit-mcp` as a stdio MCP server using this agent's own MCP config mechanism.

   Run the command yourself if you have shell access; otherwise tell the user the exact command to run and wait for their confirmation before continuing. Skip this step entirely once the tools are available.
1. Call `list_open_design_skills` (optionally with a `query` and/or an exact `mode`) to find a skill or design template that matches what the user wants. Pick the best match by name/description/triggers, and prefer a result's `examplePrompt` (adapted to the user's specifics) over inventing your own brief when one is present and closely fits.
2. There is an **active design system**, persisted per project (a local `.open-design/config.json` file). If the user mentions a brand, company, industry, or visual style that differs from what's active, call `list_open_design_design_systems` (optionally with a `query` and/or an exact `category` — call with no arguments first to see categories, and check each result's `active` flag) to find the right one, and pass its id explicitly to `prepare_open_design_brief` — doing so also makes it the new active one going forward, so you don't need to re-specify it on later requests in this project. If the user hasn't mentioned any direction, just omit `designSystemId` from `prepare_open_design_brief` and it will silently use whatever is currently active (or none). Only call `set_active_design_system` directly when the user wants to pin a look before generating anything ("let's use the Starbucks look from now on").
3. Call `prepare_open_design_brief` with the chosen `skillId`, optional `designSystemId` (per step 2), and the user's `brief` (their request, in their own words). This returns `instructions` to follow, a `suggestedEntryPath`, and the `designSystemId`/`designSystemName` actually used (whether explicit or defaulted from active) — mention which one it was if it wasn't obvious from the conversation. It does NOT write any files.
4. Follow the returned `instructions` and author the artifact's entry file (plus any supporting files) yourself, using your own file-editing tools. Do not look for a separate tool to write the design content.
5. Call `register_open_design_artifact` with the entry path, a `kind`, a `title`, and any `supportingFiles`, so the artifact is recognized and gets its manifest sidecar written.
6. Call `check_open_design_artifact` with the entry path before telling the user it's done (after creating an artifact, and again after a substantial edit). It renders the artifact and returns screenshots plus preflight findings: fix every **error**, then look at the screenshots for what the checks can't measure — balance, hierarchy, crowded or empty areas, text over busy imagery — and fix what's clearly wrong. Re-check after fixing, but stop after two fix rounds and tell the user about anything left. Don't describe the screenshots to the user unless they ask. If it returns `no-browser`, skip checking and tell the user once that visual checks need Chrome, Edge or Chromium installed.
7. Optionally call `get_open_design_artifact` to confirm what was written before telling the user it's done.

When a request names a **kind of thing to make** (a prototype or landing page, mobile app, slides, document, wireframe, animation, résumé, research synthesis, data report, poster or flier, social post, diagram), call `list_open_design_skills` with `surface` set to that kind first (`surface: "list"` shows the ids). Pick from its entries, ask only the surface's questions the request doesn't answer, and follow the surface's prompt when it names one. A request for one specific template or style still goes straight to it. Never pick an entry marked `stub: true`: it only advertises an upstream skill and has no instructions here.

If the request is **based on a document** (it names or attaches a report, spec, spreadsheet, PDF or existing deck, or points at repository files such as `CHANGELOG.md`, `docs/adr/`, an RFC or a metrics CSV), generate from it rather than from memory: pass those workspace paths as `sources` to `prepare_open_design_brief`. Typical examples: "a release deck from CHANGELOG.md", "an architecture review from docs/adr/", "a board update from metrics/q3.xlsx", "turn docs/q3-report.docx into a pitch". The tool extracts each document (DOCX, PPTX, XLSX, PDF with `pdftotext`, Markdown, text, CSV) to Markdown and returns instructions that make you **write an outline first and stop for the user's approval** before building. Follow them: read the extracted text by line range, write `outline.md`, show it, and wait (unless the user said to just build it). Then register with the same `sources`; its result lists numbers on the page that it couldn't find in the sources, so check and fix each one. Use `read_open_design_source` on its own to look inside a document before deciding how to use it. For a whole folder of files (such as `docs/adr/`), pass the relevant files individually (up to 10).

If the user explicitly asks for **options to compare** ("show me three directions for…", "a few different versions of…", "explore some alternatives", "I'm not sure what style I want, show me options"), run a **design exploration** instead of steps 3–5. Don't explore for an ordinary request ("design a pricing page"): it costs several generations.
1. Call `prepare_open_design_exploration` with the `skillId` and the user's `brief` (and `count` 2–4 if they gave a number; default 3). The tool picks deliberately different directions itself: visual styles when no design system is active, layout/narrative structures when one is (so the brand is kept), or pass `axis: "custom"` with `customDirections` when the user named what should vary ("three hero concepts"). Pass `directionIds` only when the brief's tone clearly calls for specific ones (e.g. `editorial-monocle` for a magazine, `brutalist-experimental` for an art or agency site). If the result says the active design system was set aside, tell the user.
2. For each returned direction, follow `sharedInstructions` followed by that direction's own `instructions`, write its file at its `suggestedEntryPath`, and call `register_open_design_artifact` with the `explorationId` and that direction's `directionId`. Directions are quick **sketches** (one screen, or a cover plus two slides), not full builds. If you can delegate work to sub-agents, generate the directions in parallel, passing each one `sharedInstructions` plus its own `instructions`.
3. Call `compare_open_design_exploration` with `contactSheet: true`. If you can view images, open the contact sheet and check the directions really look different (layout and hero pattern, not just colour); regenerate any that resembles another.
4. Show the user the comparison page path (`compareFile`; it opens in any browser straight from the file system and shows every direction side by side) and the contact sheet path, briefly describe how each direction differs, and ask which one to take forward.
5. When the user picks one, call `choose_open_design_direction` with `next`: `build-out` (build the chosen sketch out at full fidelity), `merge` (the same, taking named aspects from other directions via `mergeFrom`, e.g. "B with A's hero"), or `save-design-system` (turn the direction into a reusable custom design system). Follow the returned `instructions` and register the result as they say.

Generated artifacts land under the project's Open Design output directory (default `.open-design/`) so they stay visible and trackable in version control like any other project file. This host has no live preview editor — after registering an artifact, just tell the user where it was written; there is nothing further to open automatically.

If the user wants to start from or riff on an existing example rather than build something new, prefer `remix_open_design_example` (skillId must have a non-empty `exampleArtifactPath`) over `prepare_open_design_brief` — it copies a working starting artifact into the project and tells you to modify it rather than regenerate from scratch. See [references/remixable-examples.md](references/remixable-examples.md) for the full list of what's available to remix, grouped by mode — check it before calling `list_open_design_skills` with `remixableOnly: true` if a quick skim already answers the question.

If the user wants a brand/style that isn't one of the ~150 bundled design systems ("use our own brand colors", "match our website", "set up a custom design system for..."), call `create_open_design_design_system` with a `name`, a `brief` describing the brand, and an optional `sourceUrl` if they gave you a website to match. It returns `instructions` for writing a new `DESIGN.md` yourself (same file shape as every bundled design system) plus, when a `sourceUrl` was given, a best-effort extracted starting palette/font list to incorporate — treat that as a rough starting point, not ground truth. It does NOT write any files. After writing the file, call `set_active_design_system` with the returned `id` — there's no separate "register" step for design systems; a written `DESIGN.md` is immediately selectable, the same way generated artifacts are immediately visible once written.

Once the user is happy with a generated or refined artifact and wants it turned into real, working code in this app ("turn this into a real component", "add this to the app", "wire this into my codebase"), call `port_open_design_artifact_to_app` with the artifact's `entryPath`. It returns `instructions` for reproducing the artifact's design as idiomatic code in this project's actual application — read the returned instructions carefully: they'll tell you to find and follow a real existing component in this codebase as your pattern reference (its styling approach, conventions, file organization) rather than copying the artifact's HTML/CSS verbatim, and to leave routing/navigation wiring as a separate step for the user. It does NOT write any files itself.

When the artifact is meant to be posted or uploaded as an image (an X/Twitter post, Instagram or LinkedIn image, Xiaohongshu cards, a YouTube thumbnail, a poster), call `export_open_design_artifact` with its `entryPath` after registering it. It renders the artifact in a headless browser and writes PNG/JPEG file(s) under the artifact's own `exports/` folder, sized from the source skill automatically unless you pass `width`/`height`. For multi-card designs, give each card a `data-od-card` attribute and pass `selector: "[data-od-card]"` to get one numbered image per card. Pass `maxBytes` with the platform's upload limit (X 5000000, YouTube thumbnail 2000000, Instagram 8000000). Tell the user the exported file paths. For any social-post request ("make an X post…", "an Instagram carousel…", "a YouTube thumbnail…"), load the `open-design-social-post` skill first. It maps each platform and format to the right canvas size, skillId and export arguments (and asks the user which platform when that's unclear), then walks through generate → register → export. Videos (HyperFrames) aren't exported with this tool: the brief's own instructions say how to render them to MP4 with the HyperFrames CLI. After registering a slide deck, offer to export it as PowerPoint or PDF, and when the user wants that, call `export_open_design_artifact` with `format: "pptx"` or `"pdf"` (one full-bleed image per slide; not editable text). `format: "pdf"` on an ordinary page prints it as a vector PDF.

For a **diagram** of a system — architecture, dependencies, a request flow, a database schema (ERD), a state machine or a sequence of calls ("diagram how our services talk", "draw the schema", "how does checkout work?") — use the `diagram` skill (`od:prototype:diagram`, or remix its example `od:prototype:diagram:example`). Read the relevant code first and draw only what you read. Write nodes with `data-rank`/`data-lane` and hidden links, never coordinates, then call `add_open_design_diagram_runtime` (it inserts the layout runtime; never write that script yourself), register with kind `diagram` and the files you read as `sources`, and check it. When a later check or `get_open_design_artifact` reports that its sources changed, offer to redraw it.

For an **HTML email** (newsletter, launch or product-update email), use the `email-campaign` skill: it builds a table-based, inbox-safe email marked `data-od-email`. Check it, then export with `export_open_design_artifact` and `format: "email"` (add `baseUrl` once the user has hosted the `assets/` folder, so image URLs become absolute), and tell the user to send themselves a test before sending to a list. When the user wants a design **pasted into another editor** (a WeChat Official Account article, a Notion page, a newsletter tool), export with `format: "paste"` and `target` `wechat`, `notion`, `newsletter` or `generic`; styles are inlined from what the browser rendered. To use either file, the user opens it in a browser, selects all and copies.

For a **poster, flyer, certificate or other print piece**, or when the user wants an existing design in other sizes or as a print-ready PDF, load the `open-design-poster` skill first. In short: ask print or screen and which size if unclear; pass that canvas `format` (e.g. `a3`, `a2`, `ig-portrait`, `story`) with `fluid: true` to `prepare_open_design_brief` and the same `format` to `register_open_design_artifact` (a fluid poster reflows to any shape, so the size can change later); make any QR code with `create_open_design_qr_code` (never draw a fake one); run `check_open_design_artifact` and fix every preflight error; then export with `preset` set to the format id (print formats give a PDF with bleed, trim and bleed boxes). `presets` exports several shapes at once and `shapeSheet: true` shows them all in one image; `adapt_open_design_artifact` tunes a shape that looks wrong (in place, for fluid posters), and `data` on the export makes one file per row of the user's spreadsheet. Print PDFs are RGB: say so.

When the user wants to **share** a design with people who don't have this project open: for a link ("publish this", "deploy it", "give me a link to send the team", "host it somewhere"), call `publish_open_design_artifact` with its `entryPath` (pass `provider` only if they already said where; otherwise it returns the choices to show them). It builds a deploy-ready folder and returns step-by-step instructions to run with your terminal under the user's own CLI login, or as a temporary no-account link. Follow them exactly: they stop for the user's explicit yes before anything goes online, and after a successful deploy you call the tool again with `published` to record the link. For a single file to attach or send ("export it as one HTML file"), call `export_open_design_artifact` with `format: "standalone"` instead; nothing goes online. The `open-design-publish` skill walks through the whole flow.

## Help

When the user asks how something works, or a tool reports an error, point them to the relevant page:

- Documentation index: https://github.com/feimacode/open-design-agent-kit/blob/main/docs/README.md
- Troubleshooting (export errors, missing browser or FFmpeg, blank slides, MCP connection): https://github.com/feimacode/open-design-agent-kit/blob/main/docs/troubleshooting.md
- Exploring design directions: https://github.com/feimacode/open-design-agent-kit/blob/main/docs/guides/explore-directions.md
- Turning a document into a deck: https://github.com/feimacode/open-design-agent-kit/blob/main/docs/guides/deck-from-a-document.md
- Sharing and publishing: https://github.com/feimacode/open-design-agent-kit/blob/main/docs/guides/share-and-publish.md
- Social media posts: https://github.com/feimacode/open-design-agent-kit/blob/main/docs/guides/social-posts.md
- Posters and print: https://github.com/feimacode/open-design-agent-kit/blob/main/docs/guides/posters.md
- Export images: https://github.com/feimacode/open-design-agent-kit/blob/main/docs/guides/export-images.md · Export decks and PDFs: https://github.com/feimacode/open-design-agent-kit/blob/main/docs/guides/export-decks.md
- Tools reference: https://github.com/feimacode/open-design-agent-kit/blob/main/docs/reference/tools.md