design-from-code

Verify facts in code → agree on HTML → lock it in a .md → delegate the build.

A workflow skill for Claude Code and OpenAI Codex that designs changes to existing UI from the real source — not from imagination.

_{Actual output of the skill (issue #976): the current bar reproduced from MobileBottomBar.tsx (AS-IS), the proposed change (TO-BE — green = new / yellow = changed), and the data-zero empty state — all as one self-contained HTML file, zero dependencies.}

Before drawing anything, it reads the actual component JSX and traces the data model in code, then reproduces the current screen pixel-for-pixel and iterates self-contained HTML mockups until you approve. The result is a design doc grounded in facts, ready to hand to an implementer.

Built and maintained by the team behind nlook.me — a publishing platform where writers ship documents and watch readership grow. The worked example here is a real nlook feature.

Why this exists

Most "design a UI change" prompts fail the same two ways:

1. The model guesses how the data works. "What does this visitor count actually count?" — if you imagine the answer, you are wrong ~100% of the time. This skill traces handler → use-case → repository → schema and confirms it as fact before designing.
2. The mockup is schematic, so it doesn't match reality. This skill reads the actual JSX (render functions, class names, labels, spacing) and reproduces the current component so the proposal sits believably inside the real product.

It also bakes in the things people forget: one decision at a time, explicit keep / new / changed tags, and the empty (data-zero) state as a first-class screen.

What you get

• An 8-step workflow (issue → code map → data verification → HTML mockup → confirm → faithful AS-IS/TO-BE → design doc → delegated build + verify)
• Self-contained HTML mockups: phone frames, inline-SVG charts (no chart library), monotone big numbers, keep/new/changed outlines, empty states
• A restraint-by-default guardrail against the generic "AI look" (no emoji-icons, gradient blobs, or rainbow accents) — it matches your product's real tokens or a reference you give, and is fully overridable
• A portable .design/ output format that persists every mockup with its decisions, verified data meanings, and version history — so designs outlive the session and any viewer can load them
• Reference guides for each hard part and a fully worked real example

Install

This repo is both a Claude Code plugin and a plain skill folder. Pick one path.

Option A — Claude Code plugin (recommended)

From inside Claude Code:

/plugin marketplace add nlook-service/design-from-code
/plugin install design-from-code@design-from-code

The first command registers this repo as a marketplace; the second installs the bundled skill. Restart the session and the design-from-code skill is available.

Replace nlook-service/design-from-code with your fork's owner/repo if you forked it.

Option B — Manual skill install (Claude Code or Codex)

Both tools read the same SKILL.md format and load skills from a skills/ directory.

git clone https://github.com/nlook-service/design-from-code.git
cd design-from-code

# Claude Code (user-wide)
ln -s "$PWD/skills/design-from-code" ~/.claude/skills/design-from-code

# OpenAI Codex CLI (user-wide)
ln -s "$PWD/skills/design-from-code" ~/.codex/skills/design-from-code

Use cp -r instead of ln -s if you prefer a copy. For a single project only, symlink into that repo's .claude/skills/ instead of the home directory.

Updating (already installed?)

There's no build step — updating just means getting the new files in place and starting a fresh session. How depends on how you installed:

Then start a fresh session (the host only scans skills at session start) and run bash verify.sh to confirm. Check the installed version in .claude-plugin/plugin.json, and see CHANGELOG.md for what changed.

Your existing .design/ outputs are safe — they live in your own project repos, not in the skill, so updating never touches them.

Verify your install

Three quick levels — run the first one, do the others once.

1. Files & manifests are intact (one command):

bash verify.sh

Expected: a list of ✓ checks ending in PASS — N checks ok. It validates the skill frontmatter, the name/folder match, bilingual triggers, every referenced file, the self-contained example, the plugin JSON, and (if installed) that the symlinks resolve. Exit code 0 on success, so you can wire it into CI.

2. It actually loads (fresh session):

• Claude Code: start a new session and type /design-from-code. It should appear and load. Running /help or the skill picker should list it with the English description.
• Codex: start a session; design-from-code should be in the skill list.

3. It actually triggers and produces a mockup (the real test):

In a repo that has some UI, say:

Design how to add a "last updated" label to the existing card header. Mockup first.

You should see it (a) read the real component, (b) ask one narrow question, and (c) hand you a self-contained .html you can open in a browser. That round-trip — real source → HTML you can see — is the skill working end to end. Korean works too: try "이 카드 헤더에 ~ 추가 설계해줘".

The example artifact is pre-rendered, so you can sanity-check the output shape before installing: open examples/mobile-bottom-brand-status-v5.html in any browser.

How loading works (you probably don't need to "load" anything)

After install you don't import or enable the skill anywhere. There are exactly two ways it fires — and the everyday one needs no command at all.

Either way, start a fresh session after installing — the host only scans skills at session start.

What happens under the hood

You don't keyword-match; the model does an intent match. Here is the actual mechanism, so the behavior isn't a black box:

1. At session start — Claude Code / Codex loads only the frontmatter of every installed skill (its name and description) into context. The full SKILL.md body and the references/ files are not loaded yet, which keeps your context cheap.
2. On each message — the model compares what you asked against those description lines and decides whether one matches.
3. On a match — it loads that skill's full body and starts the workflow. Only then does it read the reference guides it needs.

So the description: field in skills/design-from-code/SKILL.md is the entire trigger surface. The phrases written there are examples that bias the match — not a fixed keyword list the model checks literally:

Anything close in meaning to these will trigger it — you don't have to say them word-for-word. To see or extend the list, open the description: line in SKILL.md.

Languages — what you do and don't do

You do nothing per language. One install covers every language. There is no separate Korean build, no locale flag, no config.

If you want another language to fire as reliably as EN/KO, add a few of its trigger phrases to the single description: line in skills/design-from-code/SKILL.md (keep it one line), then re-run bash verify.sh and restart the session. Nothing else changes — the workflow body itself is language-agnostic and the model replies in whatever language you wrote in.

Usage

Trigger it with any UI-design request that touches existing code:

Issue #976: add a brand-status card (posts / visitors / likes) to the mobile
bottom bar. Show me a mockup first.

The skill then runs:

See examples/ for a runnable HTML deliverable and the issue-976 walkthrough for the full v1→v5 story (including where the user corrected the layout).

Output — the .design/ artifact format

Steps 4–7 don't just chat mockups at you and vanish; they persist to a small, tool-agnostic format inside your project, so a design (and why it ended up that way) survives the session and can be browsed later.

The point is a clean separation — three things that change at different rates and shouldn't be bundled:

So the skill is the producer; a viewer is built separately and just consumes the format. The reusable asset isn't the UI — it's the metadata: what each version changed, which decision was made and why, what each number actually counts. That's also what the AI re-reads as grounded context for the next design.

.design/
  index.json                  # DERIVED rollup + global timeline (generated, never hand-edited)
  issue-976/
    meta.json                 # the contract: status, versions[], decisions[], dataModel[]
    design.md                 # the Step-7 design doc
    v1.html … v5.html         # every iteration, self-contained
    v5.png                    # optional thumbnail for the viewer

Two layers of time: per-subject (meta.json.versions[], the v1→vN history) and global (index.json.events[], one activity feed across all subjects — created / version / status / shipped). index.json is derived by scanning every meta.json, so it can't drift.

Full schema, field reference, producer rules, and the viewer consumer contract: references/artifact-format.md. Any other skill or tool can adopt .design/ by writing a conforming meta.json — that's the federation point.

A runnable, schema-valid example lives at examples/.design/ and is checked by verify.sh, so the format always has a working reference that can't silently drift from the spec.

Repository layout

design-from-code/
├── .claude-plugin/
│   ├── plugin.json              # plugin manifest
│   └── marketplace.json         # lets the repo act as its own marketplace
├── skills/
│   └── design-from-code/
│       ├── SKILL.md             # skill definition + 8-step workflow
│       ├── references/          # the hard parts, one file each
│       │   ├── code-fidelity-reproduction.md   # ★ read JSX → reproduce HTML 1:1
│       │   ├── data-model-verification.md
│       │   ├── html-mockup-recipe.md
│       │   ├── artifact-format.md              # the .design/ output format (schema + index/timeline)
│       │   └── prompt-templates.md
│       └── examples/
│           └── issue-976-walkthrough.md
├── examples/
│   ├── mobile-bottom-brand-status-v5.html   # open in a browser
│   ├── .design/                             # conforming .design/ fixture (validated by verify.sh)
│   │   ├── index.json                       # derived rollup + timeline
│   │   └── issue-976/{meta.json, v5.html}   # one design subject
│   └── images/
│       └── mobile-bottom-brand-status-v5.png
├── verify.sh                    # `bash verify.sh` → checks the install
├── CHANGELOG.md                 # what changed per version
├── README.md
└── LICENSE

Requirements

No build step, no chart library, no runtime — mockups are plain self-contained HTML.

Where it fits — and where it degrades gracefully

This skill's superpower is reading real source and real data. The author's case worked well because the code and the data were both there to read. If yours are different, here's exactly what happens — nothing breaks, but know the limits:

Rule of thumb: the more real code and data you have, the better the output. With neither, it still helps you think, but it can't reproduce what doesn't exist — and it won't pretend to.

What if there's no code to read at all?

The skill's headline move — "reproduce the real component, verify the real data" — needs source to read. So before anything else it runs a Step 0 gate: is there enough real code to read? It locates the target component and its data path, then picks a branch and tells you which one up front. So what happens when there's none? (Brand-new product, empty repo, pure idea, or you just don't have the code handy.) It doesn't fail and it doesn't hallucinate a fake "current screen." It drops the steps that need source and keeps the rest:

The important guarantee: when it can't read a fact, it does not invent one silently. It will say "this is an assumption, confirm it" rather than draw a screen that looks authoritative but is guessed. The output degrades from "reproduced from real source" to "a clearly-labeled proposal" — which is still a self-contained HTML mockup you can open, react to, and iterate.

If you do have code but it just isn't in this repo, point the skill at it (open that project, or paste the relevant component/query) and it switches back to full-fidelity mode. The line that decides output quality is simply: how much real source it was allowed to read.

Is this only for redesigning what I already have? Where does new design come from?

Worth being blunt about the scope, because it's easy to expect the wrong thing. This skill answers "does this match the real component and the real data?" — fidelity and truth. It does not answer "what should this look like?" — aesthetic direction, style, novelty. Code doesn't contain "how it should feel," so the skill won't invent a visual direction out of nothing, and won't pretend to.

That means:

• Changing something inside an existing design → design-from-code is strong on its own. The surrounding screen is the reference.
• A genuinely new look → you supply the direction as input first, then hand it to this skill to ground and ship. Sources, cheapest first:
  1. Real references — screenshots or sites of products you want it to feel like. Point at them or paste them. (Strongest signal.)
  2. A named style direction — something concrete enough to constrain choices: editorial · Swiss · neo-brutalism · glassmorphism · bento · dark-luxury. "Clean and minimal" is too vague to be a direction.
  3. Your own design system / tokens, if you have them — that is your reference.
  4. A dedicated design-ideation skill to diverge on options (e.g. a frontend-design / UI-mockup skill), then bring the chosen direction back here.

Mental model — diverge, then converge. References and ideation skills diverge ("what could it look like?"). design-from-code converges ("pin it to real data, reproduce faithfully, lock the doc, delegate the build"). It's the second half of the pipeline, not the first — pair it with a source of visual direction and you get both novelty and fidelity.

About nlook

design-from-code comes out of building nlook.me — a platform for publishing your writing and growing an audience: ship a document, then watch real readership (visitors, likes, weekly trends) instead of guessing. The example in this repo is the exact workflow we used to design nlook's own mobile experience: read the real component, verify what each number counts, and only then draw the screen.

If you write — essays, docs, newsletters, research — and want it to actually be seen, try it at nlook.me.

Contributing

Issues and PRs welcome. The skill is plain Markdown plus self-contained HTML examples — no build step. If you add a worked example, keep mockups dependency-free (inline CSS + inline SVG) so they open in any browser.

License

MIT — see LICENSE. Fork and adapt freely.