Original source pages and recordings require authorized access. The full article text here is public.
Web developers already ship UI inside real repos, so a design.md gives their AI agent a concrete visual contract instead of vague taste prompts. It keeps design direction reusable while still forcing implementation decisions to come from the current codebase.
Copy-paste workflow
When to use: When you want AI design work to follow a durable standard instead of one-off vibes. This turns visual inspiration into a design.md design contract (style DNA, color, type, layout, motion) that the agent reuses on every UI task.
Copy-paste prompt
You are my coding agent. Author a durable design contract at design.md, then build UI FROM it. The goal is to turn taste into a concrete, reusable artifact — not stale memory. Code stays the source of truth; design.md is a stable design brief.
1. First, gather visual inspiration: collect the generated inspiration images I provide (or generate a sheet of options) and note what I actually picked.
2. Distill those references into design.md with these sections, each concrete and specific:
- references (the images/directions I chose)
- style DNA (the overall feel in a few words)
- color (palette + usage rules)
- typography (families, scale, weights)
- layout (grid, spacing, density)
- composition
- shape (radii, borders, elevation)
- motion (timing, easing, where motion is/ isn't used)
- constraints (hard rules the UI must respect)
3. Now build the UI FROM design.md (e.g. a landing page <PAGE/COMPONENT>), referencing the contract for every visual decision so the result reflects the standard, not ad-hoc choices.
4. To explore directions, pair this with the throwaway multi-route variant move: generate a few variants, compare, keep one, delete the rest.
How it works
- The workflow is: collect generated inspiration images first, then distill them into
design.md, then have the agent build UI FROMdesign.mdso taste becomes a concrete artifact. - The
design.mdsections (references, style DNA, color, typography, layout, composition, shape, motion, constraints) form a stable design contract the agent reuses. - Code is the source of truth;
design.mdis a stable design brief, not stale memory to drift from. - Pair it with the throwaway multi-route variant move (generate, compare, keep one) to explore directions cheaply.
- Reference: Inspiration Board, Codex CLI.
Reusable skill
Install as ~/.agents/skills/design-md-standard/SKILL.md, then restart Codex.
---
name: design-md-standard
description: Trigger when starting UI/design work that should follow a durable standard rather than one-off prompts — author or update a design.md design contract, then build UI from it. Do NOT use as stale long-term project memory.
---
# design.md standard
Create or maintain a durable `design.md` design contract, then build UI FROM it so taste becomes a concrete, reusable artifact. Code stays the source of truth; `design.md` is a stable brief, not memory to drift.
## Steps
1. Gather visual inspiration first: collect the generated inspiration images the user provides (or generate a sheet of options) and note which direction was actually picked.
2. Distill the references into `design.md` with these sections, each concrete and specific:
- **references** — the chosen images/directions
- **style DNA** — the overall feel in a few words
- **color** — palette + usage rules
- **typography** — families, scale, weights
- **layout** — grid, spacing, density
- **composition**
- **shape** — radii, borders, elevation
- **motion** — timing, easing, where motion is / isn't used
- **constraints** — hard rules the UI must respect
3. Build the UI FROM `design.md`, referencing the contract for every visual decision (color, type, spacing, motion) so the result reflects the standard, not ad-hoc choices.
## Guardrails
- Treat code as the source of truth; `design.md` is a stable design brief, NOT stale long-term memory.
- Pair with the throwaway route-variants move (generate, compare, keep one) when exploring directions.
Scenarios
Rescue a drifting SaaS dashboard redesign
Role: As a frontend lead maintaining a Next.js SaaS dashboard
A Next.js app has accumulated one-off AI-generated cards, empty states, tables, and settings screens. The current dashboard works, but every new agent pass makes the UI feel less coherent because there is no shared design contract.
As a frontend lead, I want the agent to inspect the current dashboard code, author a design.md from selected generated inspiration, and refactor one screen from that contract, so that future UI work follows the same visual standard instead of adding more drift.
Agent brief
You are my coding agent in this repo. Treat the current code as the source of truth. First inspect the existing app structure, routes, shared components, styling setup, and one representative dashboard screen. Do not rely on stale memory. Then create or update design.md with these sections: references, style DNA, color, typography, layout, composition, shape, motion, and constraints. Use only the generated inspiration references I provide or the selected direction I name; do not scrape or clone live websites. After design.md exists, refactor exactly one dashboard route or component to follow it. Run the repo's normal lint/typecheck/test command if available, start the local dev server, and verify the edited screen in a browser. Expected output: design.md, a small focused diff to the selected screen/components, terminal test output, and a short note explaining which design.md rules drove the visual decisions.
Implementation references
local commands: inspect package.json, then run the repo's existing lint/typecheck/test and dev-server scripts
Browser verification
Use the running local app, ideally in a CMUX browser pane or an agent-browser style flow. Open the edited dashboard route, take an accessibility snapshot, verify the main landmarks/headings/buttons are still present, click through at least one existing interactive control, and capture a screenshot or browser note showing the screen follows design.md. If using Playwright, script the same route load and one interaction rather than relying on visual claims only.
Definition of done
- design.md exists and includes references, style DNA, color, typography, layout, composition, shape, motion, and constraints
- the changed dashboard screen visibly follows design.md and does not introduce unrelated route or architecture changes
- lint/typecheck/test or the closest repo-local verification command has been run and logged
- browser proof includes the local URL, the edited route, an accessibility snapshot or equivalent DOM evidence, and a screenshot or concise visual review note
Failure modes and mitigations
- The agent writes a generic design.md without inspecting the repo first; mitigate by requiring a short source-of-truth evidence section listing the files/components/routes it inspected before editing
- The agent treats design.md like permanent stale memory and overrides current implementation constraints; mitigate by stating that code remains the source of truth and design.md is only the visual brief
- The agent makes broad design-system rewrites; mitigate by limiting implementation to one route or one component family and requiring a small focused diff
Pick a landing page direction with disposable route variants
Role: As an indie product developer launching a marketing page
A new product landing page needs a strong visual direction, but the developer does not want to set up Storybook or maintain a gallery of experiments. The app already has a local dev server and route-based pages.
As an indie product developer, I want the agent to turn selected generated inspiration into design.md, generate several temporary landing-page route variants, let me compare them in the browser, and delete the losers, so that I can choose a direction quickly without creating maintenance baggage.
Agent brief
You are my coding agent. Use the current app code as the source of truth for routing, styling, and component conventions. First create design.md from my selected generated inspiration with the required sections: references, style DNA, color, typography, layout, composition, shape, motion, and constraints. Then generate 3 to 5 temporary route-level variants of the same landing page inside the running app. Add simple left/right navigation between variants if it fits the app, such as links or arrow-key handling. Do not create a permanent Storybook-style catalog. Start the dev server, open the variants in the browser, and produce a comparison note that names the strongest variant and why. After I choose a winner, promote that implementation to the real landing route and delete the rejected temporary routes. Expected output: design.md, temporary variants only during review, a promoted final route, deleted losers, and browser proof from the local app.
Implementation references
local commands: run the repo's dev server and verify the temporary variant routes in browser
Browser verification
Use a local browser session to compare each temporary route in the real app. In CMUX, keep the dev server visible and open a browser pane on the variant index or first variant. Use browser snapshot/click/evaluate actions to move through left/right navigation, confirm each variant renders, and record the winning route. A screenshot grid or one screenshot per variant is useful proof here.
Definition of done
- design.md is created before variants and each variant visibly follows the same contract
- 3 to 5 temporary route-level variants render in the local app with simple navigation or clear links between them
- a comparison note identifies the winning variant using concrete design.md criteria
- the final route is promoted and rejected temporary routes are deleted
- browser proof shows the variants were reviewed in the running app, not just inferred from source
Failure modes and mitigations
- The agent keeps all variants and leaves a maintenance mess; mitigate by making deletion of rejected routes part of the definition of done
- The agent builds variants before writing design.md, causing random styles; mitigate by requiring design.md first and asking each variant to cite which contract rules it uses
- The browser review only checks the happy screenshot and misses broken navigation; mitigate by requiring click or keyboard navigation through every variant
Standardize AI UI work for an existing component library
Role: As a design-minded full-stack developer maintaining a shared React component set
A repo has reusable components but no durable visual language. Agents keep adding new button, card, modal, and form styles that technically compile but do not feel like one product.
As a full-stack developer, I want the agent to extract stable visual rules from current components and selected generated inspiration into design.md, then update one component example page from that contract, so that future AI-assisted UI work has a practical standard to follow.
Agent brief
You are my coding agent. First inspect the current component files, styling conventions, route examples, and package scripts. Summarize the source-of-truth evidence before writing anything. Then create or update design.md as a design contract with references, style DNA, color, typography, layout, composition, shape, motion, and constraints. The contract should preserve stable conventions already present in the code unless they conflict with the chosen generated inspiration direction. Next update exactly one example/demo route or one small component cluster, such as Button/Card/Form, to follow design.md. Run the repo's available lint/typecheck/test command and start the local dev server. Expected output: design.md, one focused component/example diff, verification logs, and a browser review of the demo route.
Implementation references
cmux markdown open design.md --direction right --focus false
local commands: inspect package.json, run existing lint/typecheck/test, run the dev server
Browser verification
Open design.md in a live CMUX Markdown pane while the dev server and browser are visible. In the browser, open the component example/demo route, use an accessibility snapshot to confirm labels and roles survived the visual pass, then click/fill one interactive component such as a button, input, select, or modal trigger. Browser proof matters because component styling can compile while still breaking focus states, labels, or layout.
Definition of done
- the agent records which current component files and routes were inspected before writing design.md
- design.md captures both selected inspiration and existing repo constraints without becoming a stale architecture memory file
- one demo route or component cluster is updated from the contract with a focused diff
- lint/typecheck/test or closest available verification command passes or has a documented failure with exact output
- browser proof includes a rendered demo route plus at least one accessibility or interaction check
Failure modes and mitigations
- The agent invents a design system from scratch and ignores existing components; mitigate by requiring source-of-truth evidence from current component files before design.md
- The agent edits too many components at once; mitigate by limiting the first pass to one component cluster or one demo route
- The agent verifies only with tests and skips browser behavior; mitigate by requiring a browser snapshot plus one click/fill interaction on the changed example
Implementation notes
- Require the agent to inspect current repo files before writing or applying design.md; implementation details come from live code, not memory.
- Keep design.md human-readable and stable: it should describe visual decisions, not duplicate fast-changing component internals.
- Browser verification is part of the web-dev workflow here. A compile pass is not enough when the task changes layout, interaction, focus, or responsive behavior.
- When exploring visual direction, prefer temporary route/page variants inside the app and delete rejected variants after selection.
- Use generated inspiration as direction-setting material. Do not ask the agent to scrape or clone live websites.
- Keep the first implementation slice small: one route, one page, or one component cluster. A design standard gets trusted by proving it on a narrow diff first.
Boundaries and caveats
- Do not reintroduce AGENTS.md, Codex Sandbox approvals, Beads, Chrome DevTools MCP, Deep Wiki Map, Impeccable implementation steps, or YOLO-style approval bypassing for this topic.
- Do not present million-token snapshots as a proven design.md workflow; this workflow treated that as an unproven possible direction.
- Do not build a permanent Storybook-style catalog unless the project already requires one; the taught move is disposable route variants.
- Do not treat design.md as an auto-updated memory system that must change on every commit.
Agent reference map
Validated lesson 04 references
Use this as the ground truth for taught concepts: code as source of truth, lightweight Markdown memory, generated inspiration, design.md, and throwaway route variants.
Design.md standard prompt
Use this as the copy-paste implementation prompt shape for authoring design.md and building UI from it.
Design.md Codex skill
Use this when packaging the workflow for Codex so the agent knows when to create or maintain design.md and when not to treat it as stale memory.
Throwaway route variants skill bundle
Use this for the anti-Storybook move: generate route-level variants, compare in the app, keep one, and delete the rest.
Inspiration Board
Use this when the human needs generated visual references before asking the agent to write design.md.
CMUX CLI reference
Use this only for taught local workflow support such as opening a live Markdown design.md pane or inspecting panes while the dev server/browser run.