Skip to main content
Agent skill

Read Design

Use before building, changing, or reviewing any client screen, or the design itself — it points at the state inventory a screen is built from and at the artboard files behind it.

Get started

Get the complete skill folder, including its scripts and reference files.

When to use this skill

Use Read Design when an AI agent needs a reusable SKILL.md workflow for this job: Use before building, changing, or reviewing any client screen, or the design itself — it points at the state inventory a screen is built from and at the artboard files behind it.

When not to use it

Skip Read Design when the task is outside the creativity category, or when a more specific skill in this directory already covers the same workflow with clearer triggers.

How to install

Where will you use it?

Install scope
Claude Code folder setup
mkdir -p ~/.claude/skills/read-design
# Save SKILL.md to ~/.claude/skills/read-design/SKILL.md
  1. Claude Code personal install: place the skill and its bundled files at ~/.claude/skills/read-design/SKILL.md. For a shared project, commit the folder at .claude/skills/read-design/ instead.
  2. Current Claude Code detects SKILL.md changes in watched directories during the session. If you just created a top-level skills directory, run /reload-skills. Check that the skill is listed before testing its trigger.
  3. For Claude chat or Cowork in the Desktop app, manage uploaded skills in Customize > Skills; copying files into a local Claude Code folder is not a Desktop install. Other agents may use different install locations.

Full install guide for Claude, Cursor, and Codex →

Try a starter prompt

After installing the skill, paste this starter prompt into your agent to verify it triggers on a small task.

Starter prompt
Use the Read Design skill for this task: Use Read Design when this documented workflow matches the task. Confirm any required inputs or files before making changes.

What supports this recommendation?

69/100 provisional content score. This measures documentation, practical detail and source signals. It is not a measured task success rate or a security certification.

Documentation
77/100
Practical detail
68/100
Source evidence
54/100
Source signals
72/100
Model compatibility evidence
  • claudeuntested

    No model-specific signal or recorded compatibility test was found.

  • chatgptuntested

    No model-specific signal or recorded compatibility test was found.

  • geminiuntested

    No model-specific signal or recorded compatibility test was found.

  • copilotuntested

    No model-specific signal or recorded compatibility test was found.

  • llamauntested

    No model-specific signal or recorded compatibility test was found.

  • perplexityuntested

    No model-specific signal or recorded compatibility test was found.

  • mistraluntested

    No model-specific signal or recorded compatibility test was found.

  • grokuntested

    No model-specific signal or recorded compatibility test was found.

Inferred compatibility is based on content signals. Check the app, its available tools and setup requirements before running a skill.

What this skill does

# Read Design

The client is built UX-first, and what a screen looks like is settled in `design/` — artboards written in this repository, each split into a template, a stylesheet, a component, and the sample data it shows, beside a state inventory naming every state each one has and the pairing the parity loop reads. This skill is how that is **read**, and what a change to it owes.

Everything under `design/` is tracked, so a contributor reads exactly what a maintainer's session reads, and `scripts/capture-design.sh` serves the same files in either clone. `design/README.md` is the page for the directory.

## The source is the inventory, not a preview

A rendered preview shows the one state it was clicked into. The source states every screen, every variant and every reaction at once, and most of a screen's states — the empty one, the failing one, the one that only exists under `pointer: coarse`, the one no click reaches at all — are invisible in a picture. A screen built from a screenshot is built from a partial reading of a complete document.

So the reading order is: **`design/state-inventory.md` first**, the artboard when the inventory is not specific enough, and a rendered page last and only to settle something the source genuinely does not say.

A state's name in the inventory is the flag name in the source, so one `grep` finds both the gate in the template and the line that decides it:

```bash grep -n 'showThreadPane' design/prototype.dc.html design/logic/prototype/component.js ```

What a screen shows is in `design/data/` — the prototype's by concern (`threads.js`, `people.js`, `calendar.js`, …), every other artboard's in one file named after it. The template in a `.dc.html` page, its stylesheet under `styles/`, and its component under `logic/` are the rest of one artboard.

## Opening a page

A page opens as it is, from the file system or from any static server rooted at `design/`; it boots on `design/runtime/support.js` and fetches React from a CDN, so a browser without network access renders nothing. Open it in `playwright-cli` at the composition that matters — `frontend/AGENTS.md` § *Holding a screen against the design* lists the window-size matrix and which of its sizes take a coarse pointer. An artboard takes its component properties (`theme`, `layout`, `state`, …) from the `data-props` attribute of its `data-dc-script` element, and a running page sets them with `window.__dcSetProps(window.__dcRootName(), { … })`.

## The design half of the parity pairing

`design/parity.json` holds which artboard each screen in `frontend/design-parity/screens.json` is drawn on, the component properties it takes, and what is pressed to reach the state that manifest names. It is what `scripts/capture-design.sh` reads, and it lives beside the artboards rather than beside the client manifest because every one of those is a fact about the design — the manifest in `frontend/` describes the client and carries none.

```json { "screens": { "<screen id from the client manifest>": { "file": "<artboard page under design/>", "properties": { "theme": null }, "steps": [{ "click": { "text": "<what is pressed>" } }] } } } ```

`theme` is set to `null` rather than left out, because an artboard declaring a default theme would otherwise be captured in it whatever the browser was told — and both sides of a pair are captured under one `prefers-color-scheme`. Beyond that, a step names an element by its `text`, or by `role` and `name` where the artboard has an accessibility tree; `nth` picks one of several, and `exact` holds a `name` to the whole accessible name rather than a substring of one — which a name that is also the tail of another control's name needs. A click marked `"optional": true` is pressed only where its element is drawn at that composition — opening the drawer a touch composition hides the folder tree in, say — and is passed over where it is not, so one list of steps reaches the same state at every size.

## What the inventory holds

Every screen, the states it has, what reveals each one, and the controls that react — written so it is read instead of the prototype. Its last section is the one that has to be there: **the states the source has and a preview does not reach.** A gate whose condition is a constant, a state behind a component property, an empty state no sample record produces, a composition only a width reaches. Each of those is a screen somebody would otherwise not know they owed, and a screenshot reports none of them.

A state the source gates but nothing draws is not a screen to invent in the client. It is a gap in the design, and it is closed in `design/` — ahead of the client, or in the pull request that builds the screen.

## When the task is the design itself

A change to the design is a decision about the product, made in one of two places — on its own ahead of the client, or in the client pull request that would otherwise ship something the design does not show, as the root `AGENTS.md` § *The design leads the client, never the other way round* requires. `design/AGENTS.md` holds how it is authored: the vendored design skills a screen is drawn with, and the bar an artboard's own code is held to. In the same change it updates:

- `design/state-inventory.md`, for every state it adds, removes, or gates differently; - `design/parity.json`, when a paired screen moves to another artboard or is reached by different presses.

It keeps the split the directory is built on: sample content goes in `data/`, behaviour in `logic/`, styles in `styles/`, and the page holds the template alone. Sample data is made up — no real mail, person, address, or credential, and nothing from a signed-in client — because this directory is public. A changed artboard is checked by opening it at the compositions it reaches, in both themes, before the change is finished. Every file carries the licensing header except `design/runtime/support.js`, which is generated and replaced whole rather than edited.

## What this skill does not do

- It takes no screenshots of its own. Holding a running screen against the design is its own step: `scripts/capture-design.sh`, `scripts/capture-client.sh` and `scripts/compare-captures.sh`, in that order, with `frontend/AGENTS.md` § *Holding a screen against the design* as the rule. - It never redraws the design to excuse a client defect. Where the client is right for one of the three reasons `design/README.md` names, the correction is named in the pull request and made in `design/` in that same pull request.

Intended uses

  • Use Read Design when this documented workflow matches the task.

Implementation notes

  • Review the source instructions and adapt inputs before running the workflow.

Try it, then tell us how it went

A copied prompt does not tell us whether the task worked. Report your result after checking the output. We collect your tool and outcome, never your files or prompt.