Design iteration: the user request

Design work starts from the project's contract and ends with the user's choice. The rules are in ~/.codex/guidance/design-standards.md and the references are in ../design-standards/references/. Each step leaves a file or a stated decision, so a skipped step shows. If a reference cannot be read or a tool is unavailable, carry on with these steps, mark what it would have checked as Unverified and name it in the report. Do not stop to ask for access.

Keep the run lean. Read only the section of a reference that a step names, and load companions.md only when a companion is missing. Build brand mark sheets, strips and boards with board.py in the scripts/ folder beside this skill instead of writing HTML. Write before and after boards for screen changes by hand as capture.md describes, and write board.html by hand whenever the script cannot run. Screen from the compact strips only. Never read the full board or test sheets back, because they are for the user. Allow at most two drawing rounds per option before the board. With quick in the arguments, make one round of three options, build strips and the board only, and skip the second opinion.

1. Contract. Read the project's DESIGN.md, at the root or where the project instructions point, and its Decisions section (SYS-1). If the project has none, draft one from the code with design-contract.md, show the draft and its open questions, and wait for the user to confirm it. Offer the pointer line for the project's AGENTS.md from design-contract.md.
2. Classify. State the class of the request, use, extend or change, and whether it is specified, such as "make the buttons pill-shaped", or open, such as "make it look modern" (SYS-2). A logo, an icon, a shared token and a shared component are changes.
3. Before. Capture every affected screen in .design/iterations/<date>-<slug>/, labelled before. On the web follow capture.md. On Android and iOS use $android-run-app or $ios-run-app with the platform verifier, or the platform's own tools when those kits are absent. For a brand mark, copy the current mark in as before.svg and run the board script on it with --sheets before. Diagnose from strip-before.png, and open the sheet only if the strip leaves a question.
4. Diagnose. Apply the screening checklist in options.md to the before images. Cite each image and region, and name what works and must stay.
5. Route.
   • A use change goes to step 9.
   • A specified extend or change gets one option. Build its before and after board first, then ask for approval at step 7. Asking for approval without the board does not meet SYS-2.
   • An open request, a new screen and all brand work go to step 6.
6. Options. Write the brief from options.md. Take three anchors from the References section of DESIGN.md, from the user's links, or from a read-only research subagent that follows the source rules in options.md. Make three options, or four or five only when the user asks, each from a different anchor and each different from the others on at least two of type, colour, layout, density and shape. Write each option's plan and check it against the default looks, as options.md describes, before rendering it. Brand work gets three concepts by default and follows brand-marks.md. When several concepts need drawing, draft them in parallel subagents pinned to sonnet that each return only the SVG path and a five-line note, where pictorial marks stop at concepts plus a designer brief. For web aesthetics, load frontend-design when it is installed and follow the precedence guard in companions.md. When it is missing, give its install line once and continue.
7. Board. Render each option as in step 3 and screen it with the checklist. Build the blind board with the board script, passing --before, the project's colours, wordmark and font. It writes board.html even when nothing can be rendered, then get a second opinion on it from another model family as options.md describes. Fix or drop any option that either screen shows is broken, then stop. Ask the user to pick, combine or reject, and open the notes and the second opinion only after they answer.
8. Record. Update DESIGN.md in the same change as the code, with the tokens, any new Do or Don't, the chosen anchor under References and a Decisions entry naming what was chosen, what was rejected and why. Keep the ten most recent Decisions entries.
9. Implement. Change the code through tokens and components only. A new or refined brand mark first gets its full test sheet (--sheets with its letter), then becomes one master SVG and the platform assets in brand-marks.md.
10. Verify. Run the project's lint and type check. Capture the after state of every affected screen. Hand the ui-reviewer agent the diff, the before and after paths, the board path and DESIGN.md. Confirm each Blocker and Major in the code, fix the confirmed ones, send the same reviewer the finding IDs to re-review the fix delta, and stop after two rounds.
11. Encode feedback. Turn each correction the user gave into a token constraint, a lint rule from design-contract.md or a Do or Don't (SYS-3).
12. Commit only if asked, then report the files changed, the captures, the board path, the Decisions entry, the second opinion's CLI and model or why it was skipped, and anything Unverified.