/design
Most AI-generated interfaces look the same. /design is the part of Command Code that knows why, and fixes it in your files.
- Why
/designexists — the announcement thread from the founder - Live walkthrough — the modes run against real UI
Generated UI has a look
You can recognise it in two seconds without being able to name it. Designers can name it. Asked to label what makes an interface read as machine-made, they land on the same short list, and roughly nine tenths of that recognition signal sits in ten patterns.
glossy energy on everything
indigo because ‘software’
three tiles, equal weight, no priority
decoration posing as organization
glassmorphism with no depth system
numbers where the product story belongs
template filler above every heading
elastic easing with no purpose
whatever the distribution ships
no composition decision made
Each one is defensible alone. A gradient is not a crime. Centered is sometimes right. What gives the game away is the co-occurrence: the same ten choices, together, on every surface, because each one is the safest available answer.
The model was never missing the capability
It can write any CSS you ask for. Ask for a 1.33 type scale and you get one. Ask for OKLCH and you get OKLCH.
What it lacked was the policy of when. Nothing in the request said which hue this product had earned, or whether this section wanted a grid or a lead. Absent a policy, the model picks the median answer — and the median of every landing page ever written is indigo, centered, three tiles.
Taste turned out to be small
That is the part worth knowing. The policy is low-dimensional. For UI, taste is a finite set of principles applied consistently, plus a short catalogue of common violations. Small enough to write down.
So that is what /design is: twenty-five reference documents encoding the principles, the ten tells to detect, seven work patterns to compose from, nine states every control has to survive, and a bar each mode must clear before it may claim it did anything. A curriculum, not a list of instructions.
Name the job before the pixels
A centered hero with three feature cards is not a layout decision. It is the absence of one.
So before any visual property is touched, the surface's job gets named — one of seven work patterns — and the composition follows from that.
status, alerts, live metrics, priority at a glance
command bars, canvas, inspectors, direct action
tables, matrices, ranked lists, stable scan lanes
grouped settings, forms, safe commit areas
article flow, walkthrough rhythm, progression
focused pitch, proof, one dominant action
search, filters, maps, reversible discovery
Composition follows the work, never habit. This is the chain of thought for layout.
Diagnose, then treat
A design pass that guesses is a design pass you have to check. So the work splits: audit modes localize, treatment modes repair, and the handoff between them is a file.
checkupsmellreviewLocalize what is wrong. Never edits a file.
*.md*.htmlWritten to .commandcode/design/. Context for the next pass, not a to-do list handed back to you.
deslopredesignrelayoutrecolor…Reads the reports, then edits real files and verifies the result.
Three rules hold the loop together:
- Report modes only report.
smell,checkup, andreviewwrite their.mdand.htmlartifacts and stop. Fixing is a separate, explicit command, so an audit never edits a file behind your back. - Treatment modes read the reports first. Any mode that changes the interface checks
.commandcode/design/before deciding what to change, applies the relevant findings, and then still runs its own full bar. - Truthful completion. A mode may only claim "added", "fixed", or "changed" when the change is visible in the rendered result. If something was looked at but not altered, it says inspected, not fixed.
The third rule is the one that keeps the other two honest. A pass that cannot point at a visible change does not get to say it made one.
Quick start
Open Command Code in the project you want to work on, then run three commands in order.
Reports land in .commandcode/design/: a markdown file the next mode reads, and an HTML file you open in a browser.
If you would rather not choose, run /design on its own. It checks whether a report already exists, audits first if none does, then applies the most critical fixes in the same pass.
Audit modes
These three produce reports and change nothing.
checkup [target]
Fast triage. A vital-sign read rather than a full critique: is this surface safe to keep building on, or is something unsafe to ship?
Every vital is backed by something observed. A vital that could not be verified is marked unverified, never healthy. Critical issues come with a prescription naming what is broken, why it matters, and which mode fixes it.
Writes checkup-report.md and checkup-report.html. Next: finish, recolor, relayout.
smell [target]
A detector for reflex, template, and generated sameness. The score runs backwards, because finding nothing is the perfect result.
Severity is about clustering, not count. One generic icon card is cleanup. A page built from equal cards, an indigo gradient, a centered hero, and vague copy is an identity failure, and the fix is a new lane rather than a patch.
Writes smell-report.md and smell-report.html. Next: deslop, finish.
review [target]
An honest design read. It walks the primary flow as a story — arrive, promise, act, respond, wait, succeed or fail, resolve — and marks where the story breaks.
Scores are not inflated to be polite, and a score is never given without saying what would move it. Most real work lands in the middle.
Writes review-report.md and review-report.html. Next: finish, refine.
What a report looks like
Every audit writes two artifacts into .commandcode/design/, and only those two. No summary file, no extra analysis document.
The markdown is the source of truth, because it is structured for the model to apply. It carries the same sections in plain text:
The HTML is the artifact you open: a designed diagnostic page rather than markdown dropped into a browser. Below is that page reproduced exactly, filled with mock findings from a fictional satellite-tasking product.
ORBITAL
Six of the ten tells are present and three of them cluster in the first viewport: an indigo gradient hero, three equal feature tiles, and a centered stack. Nothing on this page could only belong to a satellite-tasking product.
Structural, not cosmetic. Fix the composition reflex first, then the palette. A recolor alone will not move this score.
| # | HEURISTIC | SCORE | KEY FINDING |
|---|---|---|---|
| 1 | tech gradient | 0 | Hero.tsx:12, indigo to magenta on the hero panel |
| 2 | generic tech hue | 0 | tokens.css:4, --brand is #6366F1 |
| 3 | feature tile grid | 0 | Features.tsx:31, three tiles, equal weight |
| 4 | accent rail | 1 | absent |
| 5 | unearned blur | 0 | Nav.tsx:8, backdrop-blur with no elevation system |
| 6 | stat monument | 0 | Stats.tsx:5, "10x / 99%" above the product story |
| 7 | icon topper | 1 | absent |
| 8 | bounce everywhere | 0 | motion.ts:22, cubic-bezier overshoot on all enters |
| 9 | default type | 1 | Inter, but scaled and deliberate |
| 10 | center stack | 0 | page.tsx, every section centered on one axis |
Ten rows, one per odor. 1 = absent, 0 = detected. Four absent, six detected: 4/10.
- PASSContrast and focus rings hold throughout.
- PASSType is scaled deliberately, so Inter reads as chosen.
- WATCHMotion is everywhere but says nothing about state.
- FAILThe direction is guessable from the industry alone.
Type scale
A real 1.33 ratio with weight contrast at every step.
Focus path
Every control is reachable and the ring is visible.
Copy
Buttons name their action instead of saying Continue.
The first viewport belongs to no product
Gradient hero, centered stack, three equal tiles. Swap the logo and headline and this page fits any B2B SaaS. The orbit schedule, the actual artifact of the domain, appears below the fold as a screenshot.
The palette is the category default
--brand is #6366F1 and the hero gradient runs indigo to magenta. Nothing ties the hue to satellite tasking.
Motion decorates rather than explains
Every section enter uses the same overshoot curve. No motion marks a state change, and prefers-reduced-motion is unhandled.
checkup and review write the same shape and differ only in what they score.
ORBITAL
Readable and fast, but responsiveness is critical and accessibility is thin. The pass rate is carried by desktop; the phone experience breaks on the primary task.
Do not ship. Fix the responsive break and the focus path first, then reassess.
| # | HEURISTIC | SCORE | KEY FINDING |
|---|---|---|---|
| 1 | intentionality | 5 | Looks assembled from defaults more than chosen |
| 2 | readability | 10 | Measure, contrast, and scale all hold |
| 3 | usability | 5 | Primary task completes, but takes two extra steps |
| 4 | responsiveness | 0 | Form inputs at 14px trigger iOS Safari zoom |
| 5 | speed | 10 | No visible shift or jank on load |
| 6 | accessibility | 5 | Focus visible, but the table is not keyboard operable |
Six vitals. Healthy = 10, watch = 5, critical = 0. Total 35/60.
- PASSLoads and responds without hesitation or layout shift.
- PASSBody text is comfortable in both themes.
- WATCHThe primary task works but is longer than it needs to be.
- FAILThe schedule table cannot be operated from the keyboard.
Load behaviour
No cumulative shift; media is sized before paint.
Theme parity
Dark mode is a designed second theme, not inverted.
Empty states
Each one says what belongs there and how to start.
Form fields trigger iOS Safari zoom
Every input, select, and textarea in the tasking form is 14px. On focus, iOS Safari zooms the viewport, horizontal scroll appears, and the user has to pinch back before typing.
The schedule table is mouse-only
Rows expand on click via a div handler with no tabindex, role, or key handling. A keyboard user can reach the page but not the data.
ORBITAL
Competent and unmemorable. Interaction feel is genuinely strong; colour and first impression are where the surface loses. The primary flow holds until the wait state, which explains nothing.
Focused interventions, not a rebuild. Colour voice and first impression carry the most available points.
| # | HEURISTIC | SCORE | KEY FINDING |
|---|---|---|---|
| 1 | first impression | 5 | No point of view; category is not visible on arrival |
| 2 | hierarchy | 6 | Second and third levels compete below the fold |
| 3 | color voice | 4 | Colour carries no mood and no state meaning |
| 4 | type voice | 6 | Readable and scaled, but the register is anonymous |
| 5 | interaction feel | 10 | States, feedback, and recovery are complete |
Five lenses, ten points each. Total 31/50.
- PASSEvery control has its full life, including recovery.
- PASSUndo is offered where the action is reversible.
- WATCHHierarchy flattens once the fold is passed.
- FAILNothing about the arrival is memorable two seconds later.
Recovery
Failed passes offer a retry with the reason attached.
Feedback
Every submit resolves visibly, success or failure.
Density
The operator view holds real data without crowding.
The wait state explains nothing
Tasking a pass takes eleven seconds. The interface shows a spinner with "Loading..." for all of it. The user cannot tell whether the request reached the satellite.
Colour carries no state meaning
Success, warning, and error all resolve to the same brand indigo with different opacity. Status is only distinguishable by reading the label.
Fix mode
deslop [target]
The treatment that follows the diagnosis. It reads all three reports — generating any that are missing — and replaces every generic tell with a decision that belongs to this product.
Order matters: a new palette on a broken layout is still broken. A smell counts as fixed only when the old pattern is gone from the surface, the replacement is specific rather than a different default, and no new smell appeared in its place.
Next: checkup, finish.
System modes
typeset [target]
Builds or repairs a type system across body copy, headings, labels, buttons, form text, metadata, and empty, error, and loading copy.
Not a font-size tweak: changing only the hero headline does not count unless you asked for exactly that. If the font changes, it verifies the font actually loads rather than trusting a name in a style value.
Next: responsive, recolor.
recolor [target]
Builds or repairs a color system in OKLCH, then applies it to real components.
Not an accent swap. Every role has to appear on real UI — navigation, page header, body, controls, cards, forms, states, and at least one edge case. Neutrals get a trace of the brand hue; chroma is clamped at the lightness extremes; the palette is checked under deuteranopia, protanopia, and tritanopia.
Next: responsive, motion.
motion [target]
Creates a page-wide motion system first, then tunes what already exists.
Tuning easing values only counts as a motion pass when a complete system is already there. If nothing meaningful moves after the pass, the mode failed.
Next: interaction, responsive.
interaction [target]
Adds missing behavior rather than hover polish.
If an interaction cannot be triggered anywhere in the current UI, the mode either wires a visible trigger or says plainly that the state is implemented but not reachable. Undo is preferred over confirm wherever the action is recoverable.
Next: motion, setup.
Compose modes
relayout [target]
Changes structure, not spacing.
At least one visible structural change is required: a new focal point, a changed hero, a reordered sequence, a different relationship between text and proof object, moved navigation, or a transformed grid. If none can be justified, the right command is finish.
Next: responsive, interaction.
responsive [target]
Recomposes the interface across contexts.
Not a max-width tweak. If the desktop composition merely shrinks, the pass failed. It covers input mode, thumb reach, safe areas, text direction, table strategy, and the sub-16px form fields that silently trigger iOS Safari zoom.
Next: interaction, setup.
Build modes
redesign [target]
A full visual transformation of an existing surface, handled as a system rather than a hero makeover.
- goals
- task logic
- content priority
- a11y bar
- core flow
- composition
- color roles
- type hierarchy
- components
- depth + edges
- states
- responsive
If the old design is still recognizable after swapping colors and font sizes, the redesign failed.
Next: checkup, review.
tokenize [target]
Pulls proven repetition into reusable tokens and components, then migrates real usage.
Naming is by meaning, not value. A list of suggested token names is not a tokenize pass — at least one real usage has to move over, with the old behavior verified afterwards.
Next: redesign, responsive.
setup
Reads the repository and writes the project's design context so every later command is more specific.
brief.md is optional everywhere else. Modes work without it and never block on a missing file.
Next: tokenize, redesign.
Ship modes
finish [target]
The pre-ship pass. Use the interface like a real person — click, tab, wait, fail, resize, submit, delete, undo, come back — then remove the friction you found.
Finish is often subtraction, and it is where truthful completion bites hardest: every claim is checked against the diff and the visible result before it is made.
Next: typeset, recolor.
refine [target]
Changes the character of a design. The diagnosis picks the move.
Opposing moves are not combined unless the surface has separate zones that need separate treatment. One hover effect or one copy edit is not a refinement.
Next: finish, responsive.
voice [target]
For marketing, landing, campaign, portfolio, and editorial surfaces, where the reaction at arrival is the deliverable.
The first viewport has to answer what this is, who it is for, and why this one. A supplied name is used exactly as given. If the subject is physical, it ships real imagery: no colored rectangle stands in for the thing itself.
Next: recolor, typeset.
surface [target]
For app UI, dashboards, admin panels, settings, and tools, where trust is earned through consistency.
The bar is an experienced operator opening the screen for the eleventh time that day and moving without hesitation. A pass that changed only color, spacing, or type while product states stay missing is not a surface pass.
Next: responsive, interaction.
Register: voice or surface
Two registers, different permissions.
/design voicelanding, campaign, portfolio, product story
The interface is the experience.
- committed color, typographic risk
- ambitious motion, art direction
- the first 1.5 seconds is the deliverable
/design surfacedashboards, admin, settings, tools, app UI
The interface is the instrument.
- consistency, density, speed
- real data and every state
- the 11th visit today, no hesitation
Core rules
Every mode inherits these.
- Color: OKLCH-first. Pick a commitment level — whisper, statement, conversation, flood — before picking a hue. 60-30-10 split. Never default to indigo.
- Typography: Body at 60–76ch. Minimum 1.3 ratio between hierarchy steps. Three fonts only when each has a role: display, body, UI.
- Layout: 1-4-9 rhythm (4px, 16px, 36px). Use
gap, never sibling margins. A card inside a card is never right. - Motion: Animate
transformandopacity. Ease out, never bounce. Exits run at about 70% of entrance duration.prefers-reduced-motionis not optional. - Interaction: Nine states per control. Touch targets ≥ 44×44px. Labels are always visible; a placeholder is not a label.
- Responsive: Base experience first, more structure as space earns it. Never gate functionality behind hover. Adapt the interface, never amputate the feature.
- Copy: One verb per button. Sentence case. No exclamation points. Errors are recovery paths, not blame.
Blank projects
If no HTML/CSS/JS exists, /design creates index.html with semantic structure, Tailwind, and design tokens, then applies the requested mode to it. Design decisions are recorded in .commandcode/taste.md.