Skip to content
ExamsLibraryFor agentsConnect your agent

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.

  1. 1polish
  2. 2motion
  3. 3mobile
  4. 4tokens
  5. 5In what order?

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.

app — claude
~/app❯
Layout is settled · running the polish pass
Edited 3 files
BeforeAfterWhy
no :active statescale(0.97) on pressA press needs an answer
16px radius inside 16px8px inner radiusinner = outer − padding
border: 1px solid #000oklch(0 0 0 / 0.08)Borders recede
polish: the edits first, then up to five rows of the changes that matter most.
Terminal
$ /design-engineering polish app/settings/page.tsx

It 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.

app — claude
~/app❯
Purpose: spatial · tens a day · keep it
BeforeAfterWhy
400ms ease-in180ms cubic-bezier(0.23, 1, 0.32, 1)Entrances decelerate
scale(0)scale(0.96) + opacity 0Nothing grows from nothing
origin: centerorigin: the triggerOpens from its button
motion: should it move? Then every After names its milliseconds, curve and properties.
Terminal
$ /design-engineering motion components/Dropdown.tsx

It 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 itIt returns
existing codethe review table; every After names ms, curve and properties
a new animation to buildthe code, then three lines: gate result, ingredients, what to feel-check
jankthe cause named before any change, layout causes before paint

It has three modes that change its posture:

ModeDoes
motion removesubtracts only: walks every animation through the gate and deletes or reduces, with what was kept and why
motion opportunitiesread-only: at most 5–7 places motion should exist, a required Rejected list, one top pick
motion auditread-only on source: a whole codebase, written up as numbered plan files for another agent to execute
Remove before you add· for your agent
/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.

app — claude
~/app❯
Matched: sticky hover on touch
What was wrong :hover styles fire on tap and stay
What changed globals.css: hover behind (hover: hover) and (pointer: fine)
Needs a phone tap a card on an iPhone; no grey state stays behind
mobile: a few lines, not a report. What was wrong, what changed, and what still needs a phone.
Terminal
$ /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.

app — claude
~/app❯
Found app.design (extends brand.design) · DESIGN.md is rationale
TokenLands in
colors.accent--accent → Button primary, links
rounded.md · 8pxCard, Input, Menu
motion.duration.base · 400msDialog (above the 300ms default; said once)
Left literal: #fff in Logo.svg, a brand asset.
tokens: the map from each token to where it lands, and any literal it kept, with the reason.
Terminal
$ /design-engineering tokens
  1. Find the contract, nearest first

    Walk up from the edited file for a .design; then look for DESIGN.md. If both exist, the .design is the contract and DESIGN.md is the rationale.
  2. Read the normative core

    For a .design: instructions, intent, constraints, policy, tokens, voice, components, in that order.
  3. Map and apply

    Tokens onto CSS variables, a Tailwind theme or component props.
  4. 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 unfinishedpolish
moves wrong, or you're not sure it should movemotion
feels like a website on a phonemobile
ignores your colours and radiitokens

Quick check

You ask for polish on a screen whose layout is still clearly wrong. What should the verb do?

What this lesson builds on and leads to, across every course.

  • break and ship
  • Install design-engineering
  • Make the skill yours
  • One command, many verbs
  • The phone's platform layer