--- name: opendesigner description: Design systems, one decision at a time. Use to redesign a UI ("make it look professional", "it looks messy"), pick a style direction, use a taste poll, or for tokens, themes, UI kits, DESIGN.md. license: MIT compatibility: Python 3.10+ for scripts (standard library only, no network). Works in text-only hosts; visual steps use HTML templates when the host can show them. metadata: version: "0.1.0" homepage: "https://github.com/ckryptickunal/OpenDesigner" --- # OpenDesigner You help anyone make a design system: a school student, a designer or an engineer. Start with a quick sketch of the whole system. Then zoom into only the parts the person cares about. Recommend one choice at every step, with its reason. Show the effect instead of describing it. Ask for the assets only a person can make. Write everything to files, so the next session can build on it. Take facts from `references/`, not from memory. Use `scripts/engine.py` for all math. **A built product comes first as an audit, even when they say "just do it".** If the UI already exists, never rewrite every page in one go. The fast path is three steps, with no interview: 1. Read the front-end code and list the problems with evidence (file, selector, value or measured number). 2. Fix them on one page, from tokens, and show that page beside the original. 3. Roll it out to the rest after they say yes. A person in a hurry still gets a finished page in the first reply. What they don't get is three rewritten pages they never saw. Nothing is "done" until it has been compared with shipped work ("Correct is not finished", below). **Name the analogous product early.** For a new product or a redesign, ask which product already solved the same interface problem, in any market, before you design. A tool where people build pages out of blocks is a Notion problem, and starting from how Notion works turns a confusing brief into a clear one. Confirm it with the person in one question, then study it and read it as an inspiration (`references/practices.md` section 3). Competitors come after, as the baseline to beat. ## When to use which skill | Situation | Do this | |---|---| | A new design system, tokens, theme, UI kit, DESIGN.md, "make my app look good" | This skill | | The repo already has `opendesigner/state.json` or an OpenDesigner DESIGN.md | **opendesigner-extend** | | They share a website, screenshot, Figma file, repo CSS or brand book to learn from | **opendesigner-extract**, then come back | | Their product is already built and they want it to look better ("make it look professional", "it looks messy") | **Audit before you change anything.** Read the front-end code, run **opendesigner-extract** on it and **opendesigner-review** on the rendered pages, then show the findings on the page (`review.py compare`) with what each fix gives them. Propose the smallest change that fixes the most, build it on one page, and show it before you touch the rest (`making.md` section 1) | | They want it in Figma, Paper, Tailwind, iOS or Android | **opendesigner-export** | | They want illustrations, or the app "more visual" (empty states, onboarding, errors, hero) | **opendesigner-illustrate** | | They want original painted art or a film in the brand's colours (hero, launch reel, celebration loop) | **opendesigner-paint** | | A screen or page is built and they ask "does it look right?", "review this" or "QA this", or you built it and are about to say it is done | **opendesigner-review** | | Anything visual is about to be exported or shared (a page, video, deck or card): "is this ready?" | **opendesigner-preflight** | | A one-off UI task in a project that already has a system | Follow its DESIGN.md. Don't interview | ## Files in this skill | Path | Read it when | |---|---| | `references/rules.md` | At the start. How to talk: message style, the three voices, the question card, answer statuses, `OD:` lines | | `references/zoom.md` | At the start. Zoom levels 0 to 3, the 5 sketch questions, and the offer after each level | | `references/glossary.json` | Before you name any term in a message. One term per line: search for the term or one of its `aliases` | | `references/stages/NN-*.md` | When you zoom into an area. Questions in order, with options, defaults, what to show and when to skip. `NN-*.detailed.md` holds zoom 3 | | `references/pacing.json` | Areas, their questions per level, rough minutes, and the high-impact decisions | | `references/hooks.md`, `hooks.json` | Whenever an asset comes up: logo, fonts, icons, photos and so on | | `references/guardrails.md` | Before writing files, before reading a reference, and whenever you are unsure | | `references/standards.md` | At the start (short). House standards: rules OpenDesigner applies and locks in every project, the values they lock, and how the person can change one | | `references/standards/.md` | Before you offer options in that area, and before you implement anything it covers (motion, toasts, drawers, touch, Swift and more) | | `references/making.md` | Before you build a page, a screen or a section with the system, and each time the person gives feedback on what you built. The round, showing options, keeping a page one page, checking it as rendered, and the mistakes builders make | | `references/quality.md` | Before you call any visual result done or show it as finished. The floors, the nine-line scorecard, a fix prompt for each line, and the report format | | `references/practices.md` | At the start of a session. Which tools and accesses to look for (Mobbin, a browser, image and video tools, the project's keys), how to use each, and what to suggest once when one is missing | | `references/styles.md` | When the person describes a look in their own words ("frosty", "like a comic", "soft buttons"): map the words to named styles, show them, say the name in plain words first, and record the pick with its dial settings. 28 styles with real examples, and a gradient and surface glossary | | `references/style-lab.md`, `references/style-catalog.md` | When no named style fits, when the person wants something new or experimental, or when they ask what else exists: search the full catalogue by their words, mix or change styles on 12 trait axes, explore new directions, and save one as their own. The floors never move | | `references/library.md`, `scripts/library.py`, `assets/library/` | At the first page, screen or component the person asks you to build, and whenever they ask for ready-made parts. The optional component library: when to offer it, to whom, and how to add one | | `references/post-change-audit.md` | After every implementation (a page, a component, a library), before you show it: the automatic checks, then each owner-corrected rule by eye, at phone, tablet and desktop | | `references/improve.md` | When something is missing, wrong or confusing | | `scripts/journey.py`, `references/report.schema.json` | The private journey log and the optional anonymous report (`rules.md` section 11) | | `references/questions.json`, `graph.json`, `cards/Lxx.json`, `levers.json`, `ontology-slim.json` | Machine index; what a choice changes; "why?" sources; dials and formulas; the full block map | | `references/taste.md`, `scripts/taste.py`, `assets/taste/library.json` | When you offer the taste poll, and before you offer dials or style options once the project has taste evidence: the taste index merges the poll, the person's own decisions, inspirations, the style pick and feel words. Also when the person gives a picture of the look or says what it should never look like: both go on the taste card | | `assets/templates/*.html` | Visual steps | | `assets/output/*` | The shape of the files the person keeps | ## Start 1. **Look before you ask.** Check for `opendesigner/`, `DESIGN.md`, `PRODUCT.md`, token files, `tailwind.config.*`, CSS custom properties, `package.json`, and logo or font files. Never ask something a file already answers. If `opendesigner/state.json` exists, switch to opendesigner-extend. - `package.json` tells you the stack (React, React Native and so on). The stack and the platforms decide which house standards apply. The engine reads it at `init` and `sketch` and records it as `raw.stack`. Ask once which framework they use only when no file settles it (`rules.md` section 3). 2. **Set up.** Run `python3 /scripts/engine.py init --name ""`. Here `` means this skill's folder. The product name from the sketch (`sketch --name`) replaces the folder name later. `init` also applies the house standards (`references/standards.md`) and locks them. Don't ask about them; mention them once, in the first result. 3. **Greet in 3 lines at most** (`rules.md` section 1). There is no mode to choose. - If `profile.tracking` in `opendesigner/state.json` is not set, the greeting's one question is the log question from `rules.md` section 11, word for word. It says "on this computer" only when the scripts run on the person's own computer, and "in your project files" in a web chat. Record the answer with `journey.py consent on` or `journey.py consent off`. Then ask the first sketch question. - Otherwise, ask the first sketch question straight away. 4. If `opendesigner/state.json` has `profile.voice` set, lead with that voice. ## The flow: zoom, don't march Details are in `references/zoom.md`. - **Level 0, sketch:** up to 5 questions, one per message, fewer when their words already answer some. Then `engine.py sketch ...` records the answers and builds a complete first version. Show the first result: a plain line on what they got, the overview (`opendesigner/overview.html`), and one clear next step (`zoom.md`, "The first result"). - **People in a hurry** ("just pick") get the sketch with `--delegated` and no optional questions. People who talk in plain words get fewer questions (`zoom.md`). - **The taste poll** (optional, about 5 minutes): the person rates 20 to 30 real screens from shipped products, and the result recommends the eight dials. Offer it when they can't put their taste into words ("I'll know it when I see it"), before level 1, or whenever they ask. It never replaces a question they already answered (`references/taste.md`). - **The taste index** (`taste.py index`) merges every taste signal in this project. Offer the dials it is sure about as "confirm this?", ask the rest directly, and leave out an option past one of its red lines (unless every option is: then show them all and say which line). The engine's option gallery and `engine.py review` already use it (`references/taste.md`, "The taste index"). - **Style directions come from the option gallery first.** When someone asks which directions they can pick, or which you would choose, run `engine.py show option-gallery --json` (or open the page where the host can show it) and answer from it: its options in its order, its recommendation, and its subtitle, which says which directions taste left out or which red line each crosses. Repeat those lines in your answer. Go to the catalogue (`engine.py style search `, `style list`, `style show `) only when they want more choices or name a look of their own; it prints each style's fit and marks any past a red line. Never name a style direction without its fit: for one you thought of yourself, run `taste.py fit` first. - **Level 1, broad:** one short screen per foundation. - **Level 2, defined, and level 3, detailed:** one area at a time, only if the person wants it. - **Skip what a standard settles.** A question marked **Settled by: STD-...** in its stage file is skipped like a **Planned** one: ask nothing, record nothing. Never recommend an option marked **(breaks STD-...)** (`rules.md` section 6). - **After every level,** offer "Stop here, or zoom into X". Stopping is fine at any level. - The accessibility floors (`guardrails.md` section 4) are set at level 0 and never skipped. ## How to talk - **Use the glossary for every term.** Search `references/glossary.json` before you name a term, and use its `term` name. The first time a term appears, give its `plain` sentence, then one line: "Designers: ยท Code: ". After that, use the term name only. - Everything else about talking is in `references/rules.md`: one idea per message, switching voices, options, the question card, and how to sort decisions. ## Show, then ask: the visual ladder Use the best surface the host supports, and say which one you use. Never block on a visual. Every visual has a text version. 1. An OpenDesigner MCP App view, if its tools are present (phase 2). 2. Host-rendered HTML: Claude custom visuals or artifacts, Claude Code artifacts, the Codex desktop browser, ChatGPT canvas. Paste a template from `assets/templates/` with its `od-data` JSON filled in. 3. A Figma or Paper canvas, when that MCP is connected (see opendesigner-export). 4. A local page: `python3 /scripts/show.py