Skip to content
ExamsLibraryFor agentsConnect your agent
metaMeta: working with agents·18/26

Review format (required)

Mandatory format for UI code reviews — Before | After | Why markdown table.

Raw markdown On GitHub

Taught in

When the user asks for a UI code review, output a markdown table with three columns: Before, After, Why. This is non-negotiable — it forces concrete diffs instead of vague advice.

The required format

| Before | After | Why |
|---|---|---|
| `transition: all 200ms` | `transition: transform 200ms, opacity 200ms` | Animating `all` triggers layout/paint on properties the browser doesn't know are safe. Specify the GPU-cheap ones explicitly. See [transform-opacity-only](/skill/motion/transform-opacity-only). |
| `transform: scale(0)` | `transform: scale(0.95); opacity: 0` | Scale-from-zero looks like an inflating balloon and renders blurry sub-pixel during the first frames. See [never-scale-from-zero](/skill/motion/never-scale-from-zero). |
| `transition: all 0.3s ease-in` | `transition: transform 0.2s cubic-bezier(0.25, 1, 0.5, 1)` | `ease-in` makes UI feel hesitant. Use `ease-out-quart` or similar for entrances. See [easing-curves](/skill/motion/easing-curves). |

What each column does

  • Before — the actual line(s) from the user's code. Quote in inline code or fenced if multi-line. Don't paraphrase.
  • After — the suggested replacement. Equivalent function, better feel.
  • Why — one short sentence on the rationale, plus a wikilink to the relevant skill node for depth.

Rules

  1. One issue per row. Don't combine multiple changes into a single Before/After. If a snippet has three issues, write three rows quoting overlapping sections.
  2. No row without a Why. "Just better" is not a Why. If you can't articulate why in one sentence, you're probably reaching.
  3. Link to nodes. The Why should end with a node-name wikilink. This is how the agent invites the user to learn more without bloating the response.
  4. Don't fix in prose around the table. All actionable items go in the table. Prose around it is for high-level context only (e.g., "Three issues in the modal entrance:").
  5. Order by impact. Most-impactful issue first. Don't bury the lede.

When this format applies

  • "Review this component."
  • "Critique this animation."
  • "What's wrong with this hover state?"
  • "Is this UI well-built?"
  • Any code review where the user shares CSS, motion, or component code.

When this format does NOT apply

  • High-level design questions ("should this animate at all?") — prose answer pointing at animation-decision-framework.
  • API/architecture questions — prose answer.
  • Bug diagnostics ("why isn't this working?") — investigation in prose, table only if there are multiple actionable fixes.
  • "Build me X" requests — produce the code, then optionally a table of choices made (Before: alternative approach, After: chosen approach, Why: rationale).

Counter-example

Wrong — vague prose review:

Your modal animation could be smoother. The transition is a bit too long and the scale starts too small. Consider using a different easing curve.

Right — Before/After/Why table:

| Before | After | Why |
|---|---|---|
| `transition: transform 0.6s ease` | `transition: transform 0.25s cubic-bezier(0.25, 1, 0.5, 1)` | UI animations under 300ms feel responsive; 600ms feels theatrical. See [duration-table](/skill/motion/duration-table). |
| `transform: scale(0)` | `transform: scale(0.95)` | Scale-from-zero is inflating-balloon energy and renders blurry. See [never-scale-from-zero](/skill/motion/never-scale-from-zero). |

The wrong version is unactionable. The right version tells the user exactly what to type.

Gotcha

Don't include the table if there are no issues. "This looks great — nothing to change" is a valid review and better than inventing nitpicks to fill rows.

Sources

metareviewformat