Design First

---
name: design-first
description: Use when the user sends /design-first <task> or presses the composer's DESIGN button — design the change before any implementation. Produces brand-system HTML mockups plus a short spec, screenshots them into the transcript, pushes the draft to the linked Claude Design project, and stops for approval; repo code changes start only after the user approves.
user-invocable: true
---

# Design first, implement after approval

The argument is a UI task. Do NOT implement it yet. This skill exists to put a
reviewable design in front of the user — in the transcript and in their
claude.ai design pane — before any repo code changes.

## 1. Find the linked design project

Read `~/.bridge_state/project_config.json`. The key is the repo's trailing
path (this repo: `/mystical-assistant`), with an optional `@<branch>` variant
that wins over the plain key; the field is `design_project`. No key → tell the
user the repo isn't linked (dashboard ▸ the chat header's project name ▸ ◇ Design system, or
the project modal's DESIGN tab), design in-chat anyway,
and skip step 4.

## 2. Design

Load the repo's design-system skill (here: `mystical-assistant-design`) and
design with its tokens and components — no generic styling. Deliverables go in
`.mystical/design-drafts/<slug>/` (git-ignored runtime state):

- One **self-contained** HTML file per screen or state — inline CSS, no
  external fetches, first line `<!-- @dsCard group="Drafts" -->` so claude.ai
  renders it as a preview card.
- `SPEC.md` — intent, components and tokens used, states, behavior notes,
  open questions. Short.

## 3. Show it in the transcript

Screenshot each mockup with the bridge-eyes skill and include the images in
your reply. The user reviews from a phone: the pictures are the review, the
HTML is the backup.

## 4. Push the draft to Claude Design

DesignSync: `finalize_plan` with the projectId, `writes: ["drafts/<slug>/**"]`,
`localDir: <repo>/.mystical/design-drafts/<slug>` → `write_files` using
`localPath` per file, targeting `drafts/<slug>/...`. The user confirms the
plan card; afterwards the draft is viewable in the claude.ai design project.

## 5. Stop for approval

AskUserQuestion: **Approve & implement** / **Revise** (they say what) /
**Park it**. Do not touch repo code before an approve. On revise, loop back to
step 2. On approve, implement with the mockups and `SPEC.md` as source of
truth, normal workflow. After it ships, offer once to promote the draft into
the design system proper or delete `drafts/<slug>/` remotely — never do
either silently.