mockup

Files (8)

• SKILL.md
• atllas-agents-portal.md · references/
• document.md · references/
• grounding.md · references/
• implement.md · references/
• neema-simple-hyzl.md · references/
• shell.html · references/
• sweep.js · references/

SKILL.md (first lines)

# mockup

One HTML file. Product-real tokens. Every state reachable by clicking. Opens from `file://`.

## Input

| Input | Meaning |
|---|---|
| `<TICKET-ID>` | Read the ticket. It is the source and the scope. |
| `<path.md>` | A plan file. Same. |
| free text | The change, described. |
| nothing | The change under discussion in this session. |
| `--variants=N` | Build N design directions instead of one. |
| `--out=<path>` | Where to write. Default: the scratchpad, named `<slug>.html`. |
| `--publish` | Also publish as an Artifact and return the URL. |

## Never

- **Never invent a colour, font size, weight, radius, spacing or shadow.** Every value traces to a
  token you read this run. An invented value is what makes a mockup look nearly right, and nearly
  right is the failure this skill exists to prevent.
- **Never rebuild a screen from memory of the product.** Read the components.
- **Never approximate the app shell.** The nav, the header, the drawer and the content offset are
  part of what the reader is judging, and they change at breakpoints the surface itself does not
  care about. Read the layout component that hosts the page.
- **Never disclose your way out of a gap.** "Not modelled" in the report is a defect you chose to
  ship, not a scope note. If the real behavior is in the codebase, reproduce it.
- **Never leave a button dead.** A control that does nothing teaches the wrong thing.
- **Never use lorem, `Item 1`, `Foo`, or `test@example.com`.** Seed realistic names, ids, amounts
  and dates. Wrapping and truncation are half of what the reader is judging.
- **Never require a server, a build step, or a network request for layout or content.**
- **Never style the walkthrough chrome with product tokens.** The scaffolding must read as
  scaffolding at a glance.
- **Never ship a state the reader cannot reach.** Chip, button, or both.
- **Never add a row to the walkthrough bar.** Two rows is the budget. New controls join the
  existing control row or move inside the frame.

## Design principles

These four decide every layout choice in Phase 3 and Phase 4. When two conflict, the earlier one
wins.

1. **Minimum surface.** Use the fewest words and the fewest elements that complete the user story.
   Cut every element that carries no reader decision. A label that repeats its value, a helper line
   that restates its label, an icon beside an already clear word: delete all three.
2. **One primary action per state.** Give each state exactly one obvious next action, styled the
   way the product styles a primary button. Demote the rest to secondary, to a link, or to one
   level down. **Never give two controls in one state the same visual weight.**
3. **Reuse before invention.** Build the change from components the product already has. A new
   component is a thing somebody must then build, so it needs a reason you state in Phase 6.
4. **Show data, not chrome.** Spend the space on content. Add a border, card, divider, or icon only
   when it carries a distinction the reader must see.

## Phase 1: scope the change

Read the source. Name the one surface the change lands on. Then pick the shape:

| The change | Shape |
|---|---|
| New states on one existing screen | `flow`: one frame, the states as steps |
| A journey across screens | `flow`: one step per screen |
| A restyle of a screen that exists | `before/after` toggle on the frame |
| The direction is not chosen yet | `variants`: N directions, grid then focus |
| One small region of a dense screen | `overlay`: real screenshot, HTML over the changed region |
| No screen at all (schema, pipeline, prompt) | **Stop.** Say there is nothing to show, offer `/diagram`. |

Shapes compose. A `variants` run can hold a `flow` per variant. Decide the shape yourself. Do not
ask the user a question the source already answers.

**Ask for reference images only when the shape is `variants`, or when the user says the current
look is wrong.** Ask them to paste screenshots or Dribbble shots. Read every one before designing.
When a reference is named but missing, stop and say which. Otherwise the product IS the reference.

## Phase 2: ground it in the real product

A cached product skips this phase's reads. **Read the one file this table names, and nothing
else.** Each cache owns its app's tokens, type, component rules, breakpoints and shell facts.

| The surface lives in | Read |
|---|---|
| `codebase/apps/agents-portal` | [references/atllas-agents-portal.md](references/atllas-agents-portal.md) |
| `neema-simple-hyzl/web` | [references/neema-simple-hyzl.md](references/neema-simple-hyzl.md) |
| anything else | [references/grounding.md](references/grounding.md) |

**Read [references/grounding.md](references/grounding.md) before writing any CSS for an uncached
product.** It owns token extraction, component geometry, and when to measure a running app instead
of reading the theme.

## Phase 3: storyboard the states

Write the state list before writing markup. Each state gets an id, a chip label, and one narration
line.

Cover, at minimum:

1. The entry state, as the screen looks today.
2. Every step of the proposed journey.
3. Every terminal outcome, including the unhappy ones: declined, expired, not enough data, ended
   early.
4. **The outcome where the change does not work.** The feature loses, the number comes back worse,
   the answer is no. It is the state most often skipped and the one a stakeholder most needs to
   see, because it is the honesty the rest of the design is asking them to trust.
5. The empty, loading and error state of every new surface, **including a slot embedded inside an
   existing component**. A permanent slot needs its own loading state: a slot that reads "none yet"
   for half a second in front of a user who has one is a lie the surface then has to take back.
6. The path where the user says no. A dismissed thing has to leave a way back.

Mark each state `main: true` when Next/Back must walk it in order. Alternate endings stay off the
main line and are reached by chip or by clicking through.

**The narration line is not a caption.** It says where the reader is, what changed, and what to
click next. Second person. It carries the intent the pixels cannot: write "End test early lives one
level down, deliberately" when that placement is the decision you want judged.

## Phase 4: build the file

**Read [references/document.md](references/document.md) and start from
[references/shell.html](references/shell.html).** Together they own the document contract: the file
layout, the chrome, the state machine, the click wiring, seed data, and deep links. Copy the shell,

From ptrandev/agent-skills, MIT.

More from ptrandev/agent-skills