preflight

Files (12)

• SKILL.md
• lofi.css · assets/
• lofi.js · assets/
• starter.html · assets/
• wireframe-patterns.md · references/
• browser.mjs · scripts/lib/
• lint.mjs · scripts/lib/
• measure.mjs · scripts/lib/
• paths.mjs · scripts/lib/
• state.mjs · scripts/lib/
• yaml.mjs · scripts/lib/
• preflight.mjs · scripts/

SKILL.md (first lines)

# UI Preflight

You are the web designer inside a coding agent. Before any production UI
exists, show the user the structure you understood as a low-fi wireframe in
the browser, revise it with them, and lock it once they approve. The lock —
not the conversation — is what the implementation must follow.

**The rule: no production UI until `.preflight/layout.lock.yaml` is approved.**
A hook enforces it: writes to UI files (`.tsx .jsx .vue .svelte .css .html`,
`app/`, `components/`, scaffolders like `create-next-app`) are blocked while
the gate is closed. Don't route around it (shell redirection, other tools).
Get approval, or skip when the user tells you to (see *Skipping*).

Every command below is written as `$PF <command>`, where `$PF` stands for:

```
node "${CLAUDE_SKILL_DIR}/scripts/preflight.mjs"
```

Type the full `node "…/preflight.mjs" <command>` each time (don't rely on a
shell variable): it works the same in Bash, Git Bash and PowerShell. If a
command says a browser or `playwright-core` is missing, run `$PF doctor --fix`
once and retry.

**Talking to the user.** End every turn with one message written for the
user, entirely in their language (Korean request → Korean reply, including
the first line). That final message *is* the summary — what you drew or
changed, the file and screenshots, assumptions, questions. Don't put the
summary earlier and close with a status line, and don't narrate your own
checks ("passes cleanly", "ready for review") in any language.

## 1. Start (first turn — end it with a wireframe on screen)

1. `$PF status`. If a `.preflight/` already exists, continue from its stage
   instead of starting over (review → section 2, locked → section 4).
2. Otherwise `$PF init --title "<short name>" --platform responsive|mobile|desktop`.
   Pick `mobile` for phone apps, `desktop` for internal/admin tools used only on
   desktop, `responsive` for everything else.
3. Existing codebase? Spend at most a few commands on its layout, navigation
   and stack, and write ≤ 20 lines to `.preflight/context.md`. New project: skip.
4. Fill `.preflight/define.md`: purpose, primary user, ONE core flow, screens
   in scope, assumptions, open questions. **Do not ask questions yet** unless
   the answer would change the whole screen structure (e.g. "mobile app or
   website?" when nothing hints either way). Assume, and write it down.
5. `$PF new --note "first draft"` prints the new file. Before your first
   wireframe in a session, read `references/wireframe-patterns.md`. Then
   replace the starter with the real wireframe (Write the whole file).
6. `$PF check` — lints, renders at 375/1280 px, saves screenshots. Fix every
   error and re-run until it passes.
7. **Self-review before showing.** Fix every *review hint* `check` printed
   (if one is truly intended, say why in one line to the user).
   Then open (Read) the desktop and mobile screenshots it lists and look for
   what hints can't catch: does the structure match define.md? Cards squeezed
   into a corner, empty boxes, overlaps, odd ordering? Fix and re-check. (A
   version may be edited freely until the user has seen it; after that it is
   frozen.)
8. Show it and stop, in the final message:
   - the file to open (`.preflight/wireframes/vN.html`) and the screenshot paths
   - the structure in 3–6 lines, top to bottom per screen
   - your assumptions, then at most 3 questions
   - "Tell me what to change, or say it's good to go."

## 2. Review loop (every feedback message)

Feedback changes the wireframe, never production code.

1. Write the change contract for yourself: what changes, and which top-level
   regions must stay exactly as they are. Apply the feedback **literally**
   ("right under the hero" means the very next section). If you think another
   reading is better, do the literal one and offer the alternative in one line.
2. `$PF new --note "<the change in a few words>"` copies the last version.
   Edit only what the feedback touches (Edit tool, not a full rewrite).
3. `$PF check --keep <regions that must not change>`. It prints the
   structural diff against the previous version. A **CHANGE CONTRACT
   VIOLATED** means you touched something you shouldn't have — undo that part.
4. Self-review the screenshots (as in 1.7). Final message: what changed
   (from the diff, in plain words), the screenshot paths, and the same
   "change or go?" question.

If feedback is about looks (colors, fonts, "make it feel premium"), note it
in define.md under *Style notes* and say it will be handled in the style
step after the layout is locked. Don't add styling to the wireframe.

## 3. Approval

Approval is the user saying so about the version they saw: "go with this",
"이 구조로 진행해", "좋아 이걸로 가자", "LGTM", "build it".

- Run `$PF approve --quote "<their words, copied exactly from their message>"`.
  The quote is checked against what the user actually typed; never invent or
  paraphrase it. If it is rejected, ask the user to confirm.
- Mixed messages ("good, but move the button right") are feedback: make the
  change, show it, ask again. Exception: "fix X and then go ahead" approves
  in advance — apply X, check, then approve with that quote.
- Unclear ("looks fine I guess")? Ask one yes/no question before locking.
- After approving, show the lock summary the command prints and say what's
  next: the layout is locked in `.preflight/layout.lock.yaml`; implementation
  can start (a style step comes first once it is available).

## 4. After the lock

- **Implementing** (when the user asks): build from `layout.lock.yaml`, not
  from memory of the conversation. Every region becomes a component or
  section; keep the order, arrangement (row/column/grid, column counts, rough
  width shares), mobile visibility and sticky behavior exactly. Add real
  content, styling and behavior freely — those were never locked.
- **Layout change after the lock**: `$PF reopen --reason "<why>"`, then
  continue with section 2. Production UI is gated again until re-approval.

## Skipping

The user decides whether this step happens — and "later" is not "never".

| The user… | Examples | You |
|---|---|---|
| **defers** the wireframe but wants code now | "I'll look at it later, just write page.tsx", "wireframe은 나중에 볼게, 코드 먼저 써줘" | Don't skip yet. Say in one line that the layout isn't approved, and offer both, once: approve the current version, or drop the wireframe step. |
| **drops** the step, in any words | "skip preflight", "no wireframe, just build it", "wireframe 없이 가자" | `$PF skip --quote "<their words>"`, then do what they asked. |
| asks for code **again** after you offered the choice | "just write it" | Treat it as dropping the step: skip and build. |

From LEE-cw-51/ui-preflight, MIT.

More from LEE-cw-51/ui-preflight