Iterate
Take an existing design artifact and a critique/change request. Produce a revised artifact + a changelog of what changed and why.
Input¶
$ARGUMENTS is structured as:
Where:
- Artifact: a path to an existing file in this repo (e.g., examples/palette-saas-violet.md) or pasted markdown content.
- Critique: free-form feedback ("primary feels too saturated"), a list of changes ("add error/danger color, increase border-radius"), or a design-critique agent output.
If the input doesn't separate the two with ---, ask one clarifying question.
Steps¶
1. Diagnose what kind of artifact this is¶
| Artifact type | Identifying signature |
|---|---|
| Color palette | Contains "Tokens", contrast matrix, ramp tables |
| Component spec | Contains "Anatomy", "API", "States" sections |
| Design system bootstrap | Contains foundations + component baseline + starter set |
| UX audit report | Contains severity sections (🔴 / 🟠 / 🟡 / 🟢) |
| Handoff spec | Contains screens + interactions + responsive sections |
The artifact type determines which skill's playbook to re-apply.
2. Parse the critique into discrete changes¶
Decompose the critique into a list of actionable items:
Critique: "Primary feels too saturated. Also need a tertiary text color and the
focus ring isn't visible enough on light bg."
→ Parsed:
1. Reduce primary chroma (~0.18 → ~0.13?)
2. Add `--color-text-tertiary` if not present
3. Increase focus-ring contrast (current ratio? target 3:1+)
If items are vague (e.g., "make it more modern"), ask for specifics OR pick a defensible interpretation and note the assumption.
3. Apply each change with citation¶
For each item, re-open the relevant skill playbook section and apply per the rules. Cite the rule:
1. Reduced primary chroma from 0.24 → 0.16 (cite color-theory.md: "muted brands
feel more trustworthy"). Re-validated contrast: still 5.1:1 on white ✓.
When a change has knock-on effects (e.g., changing primary forces hover/active to be re-derived), apply them all and note them in the changelog.
4. Re-run verification¶
Run the original skill's verification phase against the revised artifact. Fix anything that regressed.
5. Output — the revised artifact + changelog¶
Two outputs:
A. Revised artifact¶
The original artifact, modified in place. Don't strip the front-matter — update extracted_at to today; bump a version: 1.1 field if not present (start at 1.0).
B. Changelog¶
# Iteration changelog: <artifact name>
> Revised on: <date>
> From: <previous version>
> To: <new version>
## Changes applied
### 1. <change description>
- **Why**: <reason from critique>
- **What changed**: <before → after>
- **Knock-on effects**: <derived adjustments>
- **Cited rule**: <link to knowledge/ source>
### 2. ...
## Verification
- [✓] All re-validations passed
- [✓] No regressions vs prior version
## Items NOT applied
If the critique included items I didn't apply, list them with reasoning:
- "X" — declined because <reason>. Suggest <alternative path> instead.
Examples¶
Example 1 — palette iteration¶
Artifact: examples/palette-saas-violet.md
---
Primary feels too punchy for an enterprise audit tool. Also our brand has a
secondary teal that should be the accent. And we need warmer neutrals — current
slate reads cold against our marketing photos.
Output: - Revised palette with chroma reduced + accent swapped from amber to teal + neutrals shifted toward warm-gray (slight C ~ 0.01 with H ~ 50–80°). - Changelog explaining each, citing color-theory.md and the warm-neutral rationale.
Example 2 — component spec iteration¶
Artifact: examples/component-button.md
---
We don't need the `link` variant — link styling is its own component. And
add a `size="xs"` for inline buttons in dense tables.
Output:
- Revised spec: link variant removed (with note "use Link component"), xs size added (height 24px, font 12px).
- Changelog noting the API shrink + the new size's spec values + a "Don't" updated to redirect link use.
Example 3 — UX audit reaction¶
Artifact: <pasted ux-audit-report-from-yesterday.md>
---
We fixed Critical #1 (contrast) and Critical #2 (missing labels). Re-audit.
Output: - Revised audit removing items #1 and #2 from Critical - Renumbering the rest - Adding any new findings if the artifact text suggests changes elsewhere - Changelog with the closure notes for #1 and #2
When NOT to iterate¶
If the critique is fundamental ("the entire approach is wrong") rather than incremental ("primary is too saturated"), don't iterate — restart with /design-from-brief or fresh color-palette skill. Iteration is for refinement, not reset.
Done when¶
- Revised artifact has been updated with
extracted_at+ version bumped. - Changelog enumerates every change with why + what changed + citation.
- Items declined are listed with reasoning.
- No regressions in re-run verification.
- Both files (revised + changelog) referenced clearly so user knows what to read.