Verbs that fix
intermediate·9 min·Markdown for agents
What this lesson teaches
Run polish when a screen works but feels unfinished, motion when something moves wrong (or shouldn't move), mobile when it feels like a website on a phone, and tokens to thread your design contract through the code.
The judge verbs report. These four edit your code, then show you what changed. Each one starts by checking it's the right moment to run at all.
polish
Reach for it when the screen works, the layout is right, and it still feels unfinished: nothing obviously wrong, just not done.
$ /design-engineering polish app/settings/page.tsxIt checks the phase first. If the layout or hierarchy is still wrong, polishing is wasted work, because the polish gets thrown away with the layout. It says so and fixes the foundations instead.
Then it walks the pass in order: states before decoration. Hover, focus, active, disabled, empty, loading and error. Then the optical details: nested radii (inner = outer − padding), whisper-thin shadows, line wrapping. Every edit uses your contract's tokens, never new literal values.
A press state with no:active is the most common thing polish adds.
motion
Reach for it when something moves wrong: it feels janky, slow, hesitant or bouncy. Or when you're about to add an animation and want to know if it should exist.
$ /design-engineering motion components/Dropdown.tsxIt decides first. If the motion shouldn't exist (it fires a hundred times a day, or on a keystroke, or has no purpose you can name in a word), it recommends removing it and stops. That's a valid result with zero code.
Then it opens only the notes for the pattern in front of it: enter and exit, hover and press, drag and momentum, lists, a state change in place, or jank.
| You give it | It returns |
|---|---|
| existing code | the review table; every After names ms, curve and properties |
| a new animation to build | the code, then three lines: gate result, ingredients, what to feel-check |
| jank | the cause named before any change, layout causes before paint |
It has three modes that change its posture:
| Mode | Does |
|---|---|
motion remove | subtracts only: walks every animation through the gate and deletes or reduces, with what was kept and why |
motion opportunities | read-only: at most 5–7 places motion should exist, a required Rejected list, one top pick |
motion audit | read-only on source: a whole codebase, written up as numbered plan files for another agent to execute |
/design-engineering motion remove app/ Then: /design-engineering motion opportunities app/ Only after both, pick one opportunity to build.
mobile
Reach for it when the app "works in Chrome but feels wrong on my phone": hover that sticks after a tap, inputs that zoom the page, a keyboard that covers the button.
$ /design-engineering mobile "the keyboard covers the send button"It matches the symptom to its platform cause and applies the narrowest fix, in your styling system: user-select: none on controls, never on the whole page; hover behind (hover: hover) and (pointer: fine); inputs at 16px so iOS doesn't zoom.
It prefers CSS and meta tags over script: no detecting phones by user agent, no maximum-scale=1, no blocking scroll with preventDefault.
tokens
Reach for it when your project has a design contract and the agent keeps ignoring it: raw hex values, almost-right radii, Inter where your brand says something else.
$ /design-engineering tokensFind the contract, nearest first
Walk up from the edited file for a.design; then look forDESIGN.md. If both exist, the.designis the contract and DESIGN.md is the rationale.Read the normative core
For a.design: instructions, intent, constraints, policy, tokens, voice, components, in that order.Map and apply
Tokens onto CSS variables, a Tailwind theme or component props.Respect precedence
Your prompt, then the contract, then the skill, then the model's defaults.
No contract? It says so, scans what your code already uses, and offers to bootstrap one. It never invents an untracked design system silently.
In what order?
For one screen, the skill's screen loop puts these in a fixed order: foundations, one material pass, then polish, then motion, mobile or a11y only if that's the problem, then review. One or two at a time, looking at the screen between them.
| The screen… | Verb |
|---|---|
| works but feels unfinished | polish |
| moves wrong, or you're not sure it should move | motion |
| feels like a website on a phone | mobile |
| ignores your colours and radii | tokens |
Quick check
You ask for polish on a screen whose layout is still clearly wrong. What should the verb do?
In the skill
The nodes your agent reads when it does this work.
Connected lessons
What this lesson builds on and leads to, across every course.