justskill-ai/justskill-design

SKILL.md

---
name: justskill-design
description: >-
  Take a product from idea to approved screens to code, and design the pages on
  the way. Use this skill whenever the user describes a product idea — an app,
  site, tool or mini program — or asks to add, change or remove a user-facing
  product feature, even without saying "design": it guides a soft, skippable
  route through feature breakdown and confirmation, then page design on a canvas
  the user watches and adjusts, then implementation. Use it whenever the user
  wants to design, mock up, wireframe, redesign or restyle a web page, app screen
  or mobile screen — landing page, dashboard, settings, pricing, onboarding — or
  wants to change spacing, colour, typography or layout, turn a design into
  deliverables, or import a `.pen` file. Also use it for a page editor, a design
  file, editing design tokens, or reviewing someone else's design. Prefer it over
  hand-written markup: the file is validated and the user can adjust it on a
  canvas without code. For a concrete edit in an existing design, skip the route.
compatibility: Node 18 or newer. No dependencies, no install step, no build.
allowed-tools: Bash(node:*), Read, Write, Edit
---

# justSkill

You write one HTML file with inline CSS. It is the design. This skill checks it,
lets you edit it one change at a time, and gives the user a canvas to drag.

You are also the product designer. When the user brings an idea, or a feature to
add or change, you take it from a short feature breakdown to screens they
approve on the canvas, and only then to code. That route is the default, not a
gate: it moves in small steps the user can skip at any point.

Nothing installs, nothing logs in, nothing runs between sessions. Every command
is `node design.mjs <verb>`.

## From an idea to a product

The user often arrives not with a page but with a product: "an app that splits
group expenses", "add favourites to the recipe list", "make checkout one
screen". Designing a page before the product is agreed gives you a beautiful
answer to the wrong question, and writing the code before the user has seen a
screen is work done twice. So when the request is product-shaped, lead this
route. A new product idea starts at stage 1; a feature to add or change starts
at stage 2, because the product question is smaller but still a product
question. A bug fix, a code task, or a question with no screens in it is not
this route: do the work, and do not start the route around it.

| # | Stage | What you do | Done when |
|---|---|---|---|
| 1 | Idea | Restate the product in one sentence, and who it is for. Ask at most the two or three questions that change the screens. | The user recognises the idea in your sentence. |
| 2 | Feature breakdown | Propose the smallest first version: the core loop, one to five screens with a job each, the empty, loading and error states they need, the data each shows, and what is deliberately out. | The breakdown is short enough to read in one message. |
| 3 | Feature confirmation | Ask for a clear yes, and what is missing or must-have. Fold the answer back into the breakdown. | The user confirms the scope, or tells you to decide. |
| 4 | Design takeover | Say you are taking over the screens, and propose the page list and one visual direction. Create the design file and its tokens — or open the existing file when the product already has one. | The page list and the direction are stated. |
| 5 | Design first | State the order once — in the same message as the feature confirmation is fine: screens first, your approval, then code. | The user agrees, or has already given you the order. |
| 6 | Canvas | Start `serve` in the background, give the user the URL, then design page by page. Every `add` and `set` appears in the open canvas as you go. | The first screen is on the canvas. |
| 7 | UI adjustment | Teach the handshake once: select an element, press `⌘C`, paste the copied pointer back with the change. Apply it with `set`, `move`, `add`, `remove` or `tokens`. | The user stops asking for changes. |
| 8 | Page sign-off | Run `validate`, walk the checklist — every planned screen, its states, the copy, the images, the tokens — and ask for approval. | The user approves the screens. |
| 9 | Code | Treat the validated file as the spec, then implement the screens in the user's stack. | The running product matches the approved screens. |

This route is soft. It is the default because rebuilding a project twice costs
more than asking twice, not because the user must walk it:

- **Begin, do not ask to begin.** Do not open with "shall we do product design
  first?". Do stages 1 and 2, then end with one confirmation, so a user who
  wanted something else can redirect in one message.
- **Every stage is skippable.** "Just do it", "I'll tell you what I want",
  "write the code now": do that instead, and do not re-argue the route later.
- **Ask about the product, decide the design.** Who the user is, what "done"
  means, and what must be in the first version are the user's answers. Colour,
  spacing and layout are yours; one direction is enough, and a direction the
  user already stated is not offered back as a question.
- **One short message of questions.** A form of eight questions is not a
  conversation; two or three at stage 1 is the ceiling, and a confirmation
  already given is not asked again.
- **Scale the ritual to the risk.** A typo needs no breakdown; a new state or
  flow does. A request that already names the screen and its content ("add a
  pricing row to this page") is an edit: make it directly, with no route.

The per-stage playbook — the questions worth asking, the breakdown template,
the canvas handshake, the handoff to code, and how to stay soft under pressure
— is in `references/product-flow.md`. Read it when this route is in play.

## The one rule

**The design file is the truth. Write it, do not rewrite it.**

- Write the file with `Write`. Give every element a `data-id` and a `data-type`.
- `format` rewrites a file into canonical form. Use it when a file came from
  somewhere else; do not use it to change a design.
- Change it with `set`, `add`, `remove`, `move`, `rename`. Never rewrite the whole
  file to change one value: an op is one undo step, and a rewrite is an afternoon
  of lost work for the user who has the canvas open.
- Run `validate` before you hand anything back.

If the user has the canvas open, you are not the only writer. `set` and friends
re-read the file first, so they never clobber the user's drag. A full-file
`Write` does.

## The file

```html
<!doctype html>
<html lang="en">
<head>
  <meta charset="utf-8">
  <title>Landing</title>
  <meta name="design-schema" content="3.0">
  <style>:root{ --color-ink:#111827; --space-md:16px }</style>
  <style>section[data-type="page"]{ margin:0 0 24px }</style>
</head>
<body>
  <section data-id="home" data-type="page" data-name="Home" data-canvas="0,0" style="width:390px;height:844px">
    <div data-id="home__root" data-type="frame" style="display:flex;flex-direction:column;gap:16px;padding:24px">
      <p data-id="home__title" data-type="text" style="font-size:32px;font-weight:700;color:var(--color-ink)">你好</p>
    </div>
  </section>
</body>
</html>
```

Three things to notice, because they are the ones that get refused:

1. **Every element carries `data-id` and `data-type`.** `data-id` is unique in
   the whole file. `data-type` must match the tag.
2. **Exactly two `<style>` blocks, both in `<head>`:** the token block (`:root`)
   and the page-frame block. Everything else is inline in a `style` attribute.
3. **One file holds many pages.** A page is `<section data-type="page">`.

Run `node design.mjs new design.html --name home` for a starting file that is
already correct, and `node design.mjs show design.html home__title` to read one
element back.

## The command loop

```sh
# 1. Start from a valid file, or read what is there.
node design.mjs new design.html --name home --title "Landing"
node design.mjs ls design.html --pages
node design.mjs show design.html home__root

# 2. Add content. The fragment is plain HTML: the model's own language.
node design.mjs add design.html --html-file /tmp/card.html --in home__root

# 3. Change one thing at a time.
node design.mjs set design.html home__title --style 'font-size:40px;color:#111827'
node design.mjs set design.html home__title --text "Ship faster"
node design.mjs move design.html home__card --after home__title
node design.mjs remove design.html home__notice
node design.mjs tokens design.html ls
node design.mjs tokens design.html set color.accent '#7c3aed'
node design.mjs tokens design.html rm space.xxl

# 4. Check. Always.
node design.mjs validate design.html --json
node design.mjs format design.html --check    # is the file in canonical form?
node design.mjs migrate design.html           # only if validate asks for it

# 5. Hand over deliverables, or let the user drag.
node design.mjs export design.html --all -o dist          # HTML, one file per page
node design.mjs export design.html --format svg -o page.svg
node design.mjs export design.html --format png --scale 2 -o page.png
node design.mjs serve design.html
```

`add` reads a fragment from `--html-file` or `--html -` (stdin). Prefer a file
or stdin: a fragment inside shell single quotes breaks on the first apostrophe.

### Images

When a page has a place for a photograph — a hero, a card, a gallery, an avatar —
and the user has not supplied an image, fill it from `references/images.md`:
verified Unsplash URLs, grouped by what the photo shows. Choose by subject — a
hero wants a wide landscape, an avatar a face — and write the URL as it appears
there. `alt` says what a person would see; the credit goes in `data-credit`,
which never renders.

The user's own image always wins: a URL, a file, or an image inside the `.pen` is
never replaced. If no catalogue photo fits, a solid colour or a gradient scrim is
the honest placeholder — never a made-up URL, never a local path that does not
exist. The catalogue is hotlinked, so a design renders its photos only with a
connection.

### Tokens

A design token is the one thing in the file that is not an element, so no other
verb can reach it. Changing a brand color is **one op**:

```sh
node design.mjs tokens design.html set color.accent '#7c3aed'
```

- The name is `<group>.<name>`, or the file's own `--group-name` after a `--`:
  `tokens design.html set -- --color-accent '#7c3aed'`.
- The seven groups are `color`, `font`, `space`, `radius`, `size`, `shadow`,
  `border`. There is no eighth: `surface.warm` is refused, and so is a token
  file that already says `--surface-warm`.
- `space`, `radius` and `size` carry a unit. `set space.md 16` writes `16px` and
  the receipt says so; a value that is not a length is refused.
- A color is normalized to hex, so `red` becomes `#ff0000` in the file.
- A token may reference a token (`var(--color-ink)`). A cycle is refused.
- Never rewrite the file to change a token. That is the one thing this workflow
  exists to prevent, and the user may have the canvas open.

## Reading a receipt

Every write prints what it did. You cannot see the file, so read this:

```
added:      home__cta, home__cta-label  (2 elements)
normalized: #fff → #ffffff
normalized: 12px 12px 12px 12px → 12px
dropped:    cursor:pointer — The format describes appearance, not interaction. A cursor is behavior.
applied 1 op, revision a161db2c (0 errors, 0 warnings)
```

- `normalized` is not an error. It is the canonical form doing its job, and the
  file now holds the value on the right of the arrow.
- `dropped` means the file does **not** hold that declaration. If it mattered,
  write it again the way the message says.
- Nothing is ever dropped in silence. If a declaration is not in the file, it is
  in this receipt.

## Reading a refusal

```
REFUSED  display:grid — grid is not a value of display.
  Accepted: flex | block | none
design.html was not changed.
```

A refusal means the file is byte-identical to what it was. Read the hint: it
always names what to write instead. The common ones:

| Refusal | What to write instead |
|---|---|
| a one-sided `margin`, such as `margin-top` | the shorthand: `margin: 0 8px 0 0` |
| `display:grid` | `display:flex` with `flex:1` on the children |
| `position:fixed` | `position:absolute` with `left` and `top` |
| a missing `alt` | `alt=""` for a decorative image. Missing is not the same as empty |
| a duplicate `data-id` | the hint names a free id, such as `home__a-2` |
| `transform: translateX(-50%)` | `transform: rotate(<deg>)` only; centre with `left` |

Not refused, but reported: `cursor` and `animation` are outside the format's
property table, so the write goes through and the receipt lists them under
`dropped`. A `transform` is in the table, but only as `rotate(<deg>)` — a
`translate()` or `scale()` is a refusal, not a drop. And `#fff` or `rgba(...)` is not a refusal either — the file
takes it and writes the canonical hex, and the receipt calls that `normalized`
(see the receipt above).

## What the format is, and is not

Supported: flexbox layout, absolute positioning, a fixed set of 47 CSS
properties, images, inline SVG icons, design tokens, and text in one run per text
element.

Not supported, and refused by name rather than ignored: grid, `position:fixed`,
transform functions other than `rotate()`, rotation about a point other than the
element's centre, animation, responsive breakpoints, rich text inside one text
element, and any property outside the table.

The full property list, with the accepted values for each, is in
`references/styling.md`. The element contract is in `references/schema.md`.
Read one of them before writing a big fragment; they are short, and they prevent
most refusals.

## The canvas

```sh
node design.mjs serve design.html
```

Prints a URL and opens it. The service stays in the foreground for as long as the
canvas is open, so start it as a background process when you want to keep
designing with the canvas up, and read the URL it prints. The canvas follows the
file: every `add` and `set` appears in the user's tab as you go, which is what
makes a design appear gradually instead of arriving finished. The user drags;
changes go through the same funnel as your commands, so a drag cannot write
something `validate` would refuse. If a drag is refused, the canvas shows what it
would have introduced. Clicking the empty canvas clears the selection; dragging it
pans.

Picking is by rungs, not by depth: hovering outlines the container the canvas is
standing on (solid) and that container's direct children (dashed). A click
selects that container — never the deepest element under the pointer — so a
person selects a card without landing on the word in it, and a drag that follows
moves the card. A double-click steps into the dashed box under the pointer, one
rung deeper. Escape walks back up a rung.

Picking one element and pressing `⌘C` copies a pointer to it, not the design:
`Use justSkill tools. Current file <uri>. Page id: <page>. Selected node ids:
<id>`, confirmed by a toast. (`Page id:` appears only when the selection is not
itself a page.) A user who pastes that into the chat is pointing at one node in
this file — read it with `show`, then change it. This is the normal way a user
asks for a small adjustment, so tell them the shortcut when the canvas opens.

The canvas has three columns: a layer tree (every page, its elements nested,
opening fully collapsed, with expand-all and collapse-all in the header — picking
an element on the canvas opens the tree down to it and selects that row), the
design, and the selected element's properties in sections. The right panel only ever shows properties the element already has —
it cannot add a declaration the file does not carry, so use `set` for that. Either
panel folds away with `⌘\` / `⇧⌘\` or the button on the canvas edge, and either
edge drags to resize; that state lives in the browser, never in the file.

Close the tab and the service exits. The user can also `set` from the command
line while the canvas is open: both writers re-read the file first.

## Rules that save you a round trip

1. **Run `validate` when you are unsure.** It is faster than guessing, and it
   tells you the exact offset and the exact fix.
2. **Never edit `data-id` with `set`.** It is refused, because an id is an
   address rather than a property. Use `node design.mjs rename design.html card
   product`, which is the one verb that changes what an element is called.
3. **Do not add a `<style>` block** for a one-off value. Only the two allowed
   blocks are read; a third is an error.
4. **Do not write a one-sided `margin`.** Spacing is `gap` and `padding`.
   `margin` itself is allowed, but only the shorthand: a one-sided `margin-top`
   and friends are refused, because they are a second spelling of the same
   intent. Offset an element with `margin: 0 8px 0 0`, never `margin-right`.
5. **Prefer tokens.** If `:root` has `--color-ink`, use `var(--color-ink)`
   instead of a literal. The user can then restyle the whole design in one edit.
6. **Small edits, in order.** Three `set` commands beat one rewrite, and each
   one is a step the user can undo.

## Deliverables, and which need a browser

| `--format` | Needs | Notes |
|---|---|---|
| `html` (default) | nothing | One page, or `--all` for a site. Self-contained. |
| `svg` | nothing | Wraps the page in `<foreignObject>`. A browser draws it; Figma, Illustrator and Sketch show an empty rectangle. |
| `png` `jpeg` `webp` | a Chrome-family browser, or the canvas | `--scale 1..3`, `--size WxH` |

The image formats find a browser already on the machine — no download, no
bundled Chromium. When there is none the export **fails** and names three ways
forward: install Chrome, Chromium or Edge, leave the canvas open, or use
`--format svg`. It never quietly writes a different format, because a different
format is a different deliverable.

Before any image export, make sure the fonts are declared. `export` adds the
stylesheet links itself from the families the page uses, and the browser waits
for them; a screenshot taken before a web font arrives is captured in the
fallback family, where the text wraps at different words and everything below it
moves.

The HTML deliverable takes the page's own `background-color` onto `<body>`. A
page covers its own box and nothing more, so a viewport taller than the page
shows what is behind it: left white, that is a colour the design never chose. A
page that states no colour, or states `transparent`, keeps a plain document.

## Working with a `.pen` file

```sh
node design.mjs import pen design.pen -o design.html
```

One direction only: pen in, design file out. Every run prints a ledger:

```
26 pages · 2197 elements · 239 references inlined · 140 with overrides · lost: perCornerRadius×1
```

`lost` names what this format has no spelling for. Read it and tell the user,
rather than letting them find out on the review screen. `--report r.json` writes
the whole ledger.

Four things the reader translates rather than copies, because the format has no
spelling for pen's version of them:

- **A glyph is measured.** A `path` node's outline is drawn on its own grid, and
  that grid becomes the icon's `viewBox` — pen's own export writes
  `viewBox="0 0 14 14"` on a 366×366 arrow. An outline whose box cannot be
  measured keeps the node's box, which is what every glyph in the reference file
  happens to have anyway.
- **A stroked outline is drawn as a stroke**, on the `<path>`, with
  `vector-effect: non-scaling-stroke` so the width stays the width pen drew.
  It is not a `border` on the `<svg>` — that is a ring around a box, not a
  drawing.
- **A rotation is baked into the outline** for a `path` node (the ledger counts
  `bakedRotation`): a path is an opaque drawing with no box to turn, and pen turns
  an element about its top-left corner while this format turns it about its
  centre. Any other rotated node is drawn upright and named in `lost.rotation`,
  because reproducing pen's origin would need a `transform-origin` the format does
  not have.
- **A line break the author placed survives** as `white-space: pre-line`. Written
  as a literal newline it is a space, and the line then wraps wherever the font
  puts it.

The ledger also counts what it rewrote: `themedVariables` (a themeable variable
takes the document's default theme, which is the entry with no `theme` of its
own), `hardBreaks`, `pathAsGeometry`, `bakedRotation`. A variable that cannot be
reduced to one value is left out of the token block and counted as
`lost.unresolvedVariable` — never written as the string `[object Object]`, which
is a value that validates and means nothing.

**A reference is inlined, because this format has no reference.** pen stores a
`ref` node and the master it points at; the reader copies the master's subtree in
where the reference stood. The copy's root keeps the reference's own id and
everything under it is renumbered as `<reference-id>__<its own id>`, which is why
an imported file has 239 more subtrees in it than the `.pen` had nodes. Four
things follow, and they are the ones to tell the user:

- Editing a copy edits that copy alone. The master is a separate element now, so
  a change meant for every card has to be made on each one — or on the `.pen`,
  which is where the sharing lives.
- `descendants` patches are applied during the import: the text, the size, the
  swapped glyph are all in the file, and nothing applies them later.
- A reference that names nothing is refused (`pen/unresolved-ref`), as is one
  inside a loop (`pen/ref-cycle`) or nested more than 16 deep (`pen/ref-depth`).
- Children on a reference node are not part of the master's subtree, so they are
  counted in `lost.refChildren` and not written.

## What the skill needs at run time

The skill runs from `SKILL.md`, `references/`, `design.mjs`, `lib/` and
`canvas/` — about 1 MB. The repository also carries media that no command reads:

| Media only | What it is | Size |
|---|---|---|
| `docs/justskill-demo.gif`, `docs/justskill-demo.mp4` | the README demo (English) | ~4 MB |
| `docs/justskill-demo-zh.gif`, `docs/justskill-demo-zh.mp4` | the same demo in Chinese, for the Chinese README | ~4 MB |
| `docs/*.png` | the screenshots, including the case wall | ~1 MB |

If the skill was copied into the skills directory (not symlinked to a checkout),
the user can remove those and free about 9 MB; nothing in `validate`, `set`,
`serve` or `export` changes, and every other file is text:

```sh
rm -rf docs/*.gif docs/*.mp4 docs/*.png
```

Ask before removing anything, and never prune a symlinked checkout — that is
the user's repository. Everything else stays: the docs, examples, tests and
READMEs are text, small, and worth reading. Keep `LICENSE` and `package.json`.

README

Run `npx skills use "https://github.com/justskill-ai/justskill-design" --skill "justskill-design"` and follow the printed instructions.

我想做一个笔记 App：记录我每天值得被记住的事情，以及当时的心情。可以有个日历展示我的心情晴雨表。

读取一下当前程序的产品设计、理念，帮我整理一份属于这个程序的设计风格，并使用 justskill-design 出一份设计稿。等我确认设计稿效果后，按照设计重构 UI。