# Verbs that fix

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

Module: The /design-engineering toolkit · Level: intermediate · 9 min · https://school.agents.org.in/design/toolkit/verbs-that-fix

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

*[Interactive demo: polish: the edits first, then up to five rows of the changes that matter most.]*

```bash
/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.

*[Interactive demo: motion: should it move? Then every After names its milliseconds, curve and properties.]*

```bash
/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 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 |

**Remove before you add (paste into your agent):**

```text
/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.

*[Interactive demo: mobile: a few lines, not a report. What was wrong, what changed, and what still needs a phone.]*

```bash
/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`.

> **Honest about what code can't prove.** Sticky hover, the tap flash, input zoom, safe areas and the keyboard only show up on real hardware. mobile lists each unverified fix with exactly what to look for on a phone, and never claims it checked.

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

*[Interactive demo: tokens: the map from each token to where it lands, and any literal it kept, with the reason.]*

```bash
/design-engineering tokens
```

  **Step: 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.

  **Step: Read the normative core.** For a `.design`: instructions, intent, constraints, policy, tokens, voice, components, in that order.

  **Step: Map and apply.** Tokens onto CSS variables, a Tailwind theme or component props.

  **Step: 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` |

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

- [ ] Polish it anyway: states and shadows are always worth it
- [x] Say the layout is the problem and fix the foundations first
- [ ] Run motion instead
- [ ] Refuse and do nothing

*Why:* polish checks the phase first. Polishing a layout that's going to change wastes the pass, so it names the real problem and starts from the foundations.

## In the skill

- https://school.agents.org.in/skill/commands/cmd-polish.md
- https://school.agents.org.in/skill/commands/cmd-motion.md
- https://school.agents.org.in/skill/commands/cmd-mobile.md
- https://school.agents.org.in/skill/commands/cmd-tokens.md