design-first
Skill7 starsChanged 8 days agoMITView on GitHub
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.
5 other projects use a version of this.
Adopted by
Most recently taken up by
- arumaekawa/codex-skillstheir own version, first seen Oct 25, 2026
- techygarg/latticetheir own version, first seen Oct 13, 2026
- getsentry/sentry-darttheir own version, first seen Oct 12, 2026
- getsentry/sentry-react-nativetheir own version, first seen Sep 2, 2026
- valsecchi75/project-scaffoldertheir own version, first seen Aug 3, 2026
Other versions5 projects use a version of this.
Word for word · 0
None found.
Edited · 0
None found.
Wrote their own version · 5
- getsentry/sentry-react-native★ 1.8ksame name
- getsentry/sentry-dart★ 877same name
- techygarg/lattice★ 209same name
- valsecchi75/project-scaffolder★ 9same name
- arumaekawa/codex-skills★ 4same name
How matches are found. Word for word: the exact same text. Edited: shares passages with this file (“99% same” means 99% of its five-word phrases also appear here; 10% or more counts). Their own version: similar meaning, or, weakest, the same name. We can’t tell which project had it first. Projects are counted among the 200 most-starred candidates, and mentions are links to the repository we found, up to 50 per site, so both counts are a floor.
In this repository27 other files it gives its agents.
- CLAUDE.mdCLAUDE.md
- accessibility-auditSkill
- algorithmic-artSkill
- api-docsSkill
- beautiful-shadowsSkill
- brainstormingSkill
- bridge-eyesSkill
- bridge-feature-sliceSkill
- bridge-shipSkill
- bridge-worktreeSkill
- changelogSkill
- color-paletteSkill
- content-strategySkill
- design-implementSkill
- design-reviewSkill
- design-tokensSkill
- emil-design-engSkill
- empty-statesSkill
- frontend-designSkill
- landing-pageSkill
- micro-interactionsSkill
- mystical-assistant-designSkill
- ogilvy-copywritingSkill
- onboarding-guideSkill
- typography-scaleSkill
- visual-style-presetsSkill
- writing-guidelinesSkill
The file
We split this skill into the rules it gives an agent
1 rule. 0 are common, 0 are distinctive, and 1 is very specific to this project.
0
Common
Most of the 5 edited versions we read keep these.
0
Distinctive
This author's own choices. Worth a look.
1
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Very specific: line 15
Read ~/.bridge_state/project_config.json.
“Common” is measured: kept by at least 6 in 10 of the 5 edited versions of this file we could read. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
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
SETTINGS ▸ Projects ▸ Design system), 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.
With the experimental switch on, use the design view instead of steps 3 to 5. Read
design_context (find_tools), then call show_design. When the direction is open, make three
rough directions as three pages on one board, say how they differ and ask which way to go. The
user opens PREVIEW DESIGN, points, draws, tweaks and remixes, and their comments come back as a
message naming the elements. Keep editing the page files: edits appear live. inspect_ui and
critique_design are there for checking it. Then ask for approval, and implement after it.
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.
Choices ride in the question, not loose in the transcript. Directions to
pick between (A · TOKEN, B · HEADER…) don't get Attached one by one — that
pile is what made the user match file names to letters. The crops go in step 5's
question: each direction's crops in its option's preview, one markdown image
per state, . The card shows them on a stage
beside the options, tabbed by state. Attach only what isn't a choice: the one
design up for approval, a before shot.
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. Several directions: one option per direction (up to three),
lettered (A · TOKEN, the one you recommend first), its crops in preview,
plus Park it; revising is the card's own free-text answer. One design:
Approve & implement (its crops in that option's preview) / 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.
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

