Design Process
How a component moves from a first sketch to something developers can build. The page below proposes a process; the bottom half compares it to how big design systems handle the same problem.
The stoplight tells you where each component is in the design process. Five colors, one for each stage. Red means just starting; green means ready for developers to build. The proposal below explains what each color means, what you'll see while you're there, and what to check off to move forward.
Two homes for a component
A component lives in two places during its life: Figma while you're designing it, then the docs site once it's far enough along to be written up. Developers come in after that, taking the finished design from the docs site and building it in Storybook. The stoplight is a designer's tool — it tracks how far along the design itself is, not the engineering work.
Figma — where you're designing
Sketching, exploring, building out variants and states. Nothing on the docs site yet. The Figma page name carries a colored prefix that tells everyone how far along the work is.
Docs site — where the finished design lives
The component has a page, a written spec, examples, and a status badge. Anyone in the company can see it and use it for product work. Green means the design is locked and developers can start building.
The five stages at a glance
The five stages, in detail
Each stage is a card with three sections: what the stage means, what you'll see while you're there, and what you need to check off before moving forward.
Red — Exploration
You've just started thinking about a new component. You're sketching ideas in Figma — trying different shapes, sizes, and approaches to see what feels right.
- There's a Figma page for this component with the red prefix
- You've drawn at least one rough version on the canvas
- The questions you're trying to answer are written down somewhere on the page (sticky notes, comments, a notes frame — whatever works)
- The component doesn't appear on the docs site yet
- You've picked one of your sketches as the direction you want to build out
- The other sketches are tucked away or labeled so you remember what you tried
- You rename the Figma page from red to orange
Orange — In Progress
You've picked a direction and you're building it out properly — drawing all the variants (small/medium/large, primary/secondary, etc.) and all the states (hover, focused, disabled).
- The Figma page has the orange prefix
- You've drawn the variants the component needs (sizes, fills, icon options, etc.)
- You've drawn the states the component needs (default, hover, focused, active, disabled — plus anything specific like error or loading)
- Everything uses the design system's colors, spacing, and typography (no hardcoded values)
- You've labeled each part of the component in Figma so someone reading later knows what each piece is called
- The component still doesn't appear on the docs site
- The design feels settled enough that someone could write a description from it
- You rename the Figma page from orange to yellow
- You ask the assistant to set the component up on the docs site (it creates the page, a starter example, and a spec template you fill in next)
Yellow — In Review
The component now has a page on the docs site. You're writing the spec — the description, when to use it, when not to use it, what props it has, what keyboard shortcuts it supports. A yellow "Not production-ready" banner sits at the top so anyone visiting knows the spec is still being written.
- The component has a page on the docs site with Examples, Code, Guidelines, Changelog, and Playground tabs
- The Guidelines tab has the basics filled in: a description, when to use it, when not to use it, the parts it's made of, and the keyboard interactions it supports
- At least one example is rendered on the page so people can see it in action
- The "Spec X/22" pill on the Guidelines tab climbs as you fill in more fields — aim for at least 80%
- The yellow "Not production-ready" banner is visible at the top
- A peer designer can review the spec while you're here (optional, but a good idea)
- The "Spec X/22" pill is at 80% or higher
- You're confident the description, props, and behavior are final — not still moving
- You rename the Figma page from yellow to green
- You change the status on the component's page from "In Review" to "Production Ready"
Green — Production Ready
The design is locked. Marking it Green is how you tell developers "you can build this now — the spec won't keep changing on you." From here, developers pick the component up and build the production version in Storybook.
- The status shows "Production Ready" on the sidebar and on the page
- The "Not production-ready" banner is gone
- The Figma page has the green prefix
- Developers can implement the component knowing the spec is stable
- Product teams can use the spec when planning new features
- Developers build the component in Storybook — that's their workstream, not part of the stoplight
- If they hit small issues during build, those become spec tweaks (recorded as updates, no status change)
- Real product features start using the component
- A replacement component exists (ideally also Production Ready)
- The "when not to use" section points at the replacement
- You rename the Figma page from green to black
- You change the status from "Production Ready" to "Deprecated"
- This needs an explicit "yes, I'm doing this" — Green is a public contract that developers may already be building against
- The reason for going back is written down so consumers know why
Black — Deprecated
This component is being phased out. Projects that already use it can keep using it, but new work should reach for the replacement listed in the spec.
- The status shows "Deprecated"
- "When not to use" tells people what to use instead
- The Figma page has the black prefix
- The component is still visible on the docs site so old projects can find it
- This is the end of the line — no progressing forward from here
- Old projects keep using it without issue
- New projects are pointed at the replacement
- Eventually the component is removed entirely in a major release of the design system — that's a separate, deliberate decision, not something that happens automatically
When things change
The real world isn't perfect. Designs evolve. Specs need tweaks. Components occasionally need to go backward before they can go forward. Three patterns cover almost every case.
1. Small changes (the most common kind)
You're at Yellow and you tighten the description. Or you're at Green and you fix the wording in an example. Most edits look like this — just make the change, write a short note in the component's changelog (one sentence is fine), and you're done. The component stays at its current color.
2. The design needs more work (going backward)
Yellow back to Orange. While writing the spec you realize the Figma design isn't actually settled yet. Take it back to Figma — rename the page back to orange, change the status to "In Progress," and jot down why. The docs-site page stays put. Your spec work is preserved for when you come back.
Yellow back to Red. Rare. You want to throw out the current direction and explore alternatives. Same idea, status goes back to "Exploration."
Green back to Yellow. A major redesign. This is the only backward move that needs explicit confirmation — Green is a public contract, and developers might already be implementing against it.
The component's history keeps a record of every status change, so going back and forth is fully preserved — you can look back later and see how it evolved.
3. The docs site and Figma fall out of sync
Sometimes Figma gets updated but the docs site doesn't catch up (or the other way around). When that happens, the assistant can compare the two and propose updates. Safe changes get applied automatically; anything risky stops for your review before anything is changed.
Default when you're not sure
Stay at the current color and write a short changelog note. Going backward is a real option, but use it when you mean to — not on reflex. A good rule: if you'd be willing to defend the move in a one-sentence note, do it; if not, just make the edit in place.
Where the status shows up
- The Figma page name carries a colored prefix (red, orange, yellow, green, or black) — the most visible signal of where a component is
- The sidebar status badge on the docs site shows the current color for any component that has a page (Yellow and later)
- The "Not production-ready" banner sits at the top of Yellow component pages so visitors know the spec might still change
- The component's history records every status change, so you can always look back and see how it got here
Five things worth considering
When you look at how the biggest design systems work — Shopify's Polaris, IBM's Carbon, Salesforce's Lightning, Adobe's Spectrum, Google's Material — they all do a few things the proposal above doesn't. Here are five ideas worth weighing.
Add a "Beta" stage between approved and locked-forever
Almost every big design system has a stage that says: "you can use this, but the spec might still change." For example:
- Polaris: Stable / Experimental / Legacy / Deprecated
- Carbon: Experimental / Draft / Stable / Deprecated
- Lightning: Drafted / Beta / Released / Deprecated
- Spectrum: Working draft / Beta / Released
The proposal jumps straight from Yellow (private review) to Green (locked). With nothing in between, when a developer sees Green they assume "this never changes" — and then they're surprised when an update lands later.
What this would look like
Add a sixth stage, or a small "Beta" badge that sits on top of Green. Developers building against a Beta spec know things might shift. Green (or "Stable") is reserved for components that are genuinely locked.
Drop the Red (Exploration) stage
None of the big design systems publicly track design exploration. That happens in a designer's working file and stays private until it's coherent enough to be a real direction. Tracking it publicly makes the system look bigger and messier than it really is.
What this would look like
Figma pages for early sketches still exist, but they don't get a red prefix and they don't appear in the design system at all. A component only enters the stoplight when it reaches Orange — when there's a real direction with real variants. The five stages collapse to four: Orange → Yellow → Green → Black.
Track that the Storybook build actually exists at Green
The big design systems treat "shipped" as the spec AND the working code, not just the spec. They don't call something Stable until the implementation exists. The proposal puts Storybook on a parallel track, gated by Green but otherwise off the stoplight — which risks the same drift problems we already see between Figma and code.
What this would look like
The Green stage checklist gains one item: "Storybook implementation exists and matches the spec." It doesn't have to block the flip to Green (a designer can mark it Green to signal "ready for development"), but it should be tracked and visible somewhere on the page.
Require a written reason when a component goes backward
Successful design systems make backward moves a little painful on purpose — a written reason, a peer review, something visible. The proposal lets a designer move backward freely. That risks ping-ponging — Yellow → Orange → Yellow → Orange — without ever committing.
What this would look like
Every backward move requires a short reason: "Variants for icon-only need rework," or whatever. The reason shows up on the component page as a small "Why this regressed" note. Public visibility creates the discipline — designers who know the reason will be public think twice before going back.
Add a "How this differs from most design systems" note
The two-homes model (Figma owns half the lifecycle, docs site owns the other half) is unusual. Most big design systems have a single home — the docs site is the spec, code is the implementation, and the Figma file is downstream of both (or even auto-generated from them).
What this would look like
A short callout on this page that acknowledges the difference:
"Most design systems treat the documentation site as the single source of truth. We split it: Figma owns design while it's still in motion (Red and Orange), the docs site owns the finished design (Yellow, Green, Black). This works for a small team where most of the design work happens in Figma — but if you're coming from Material, Polaris, or Carbon, expect to look in two places during the early stages of a component."
If we adopted all five
The stoplight would look like this — four stages instead of five, with a Beta badge that can sit on top of Green:
Concrete changes from the proposal in Part 1:
- Stages drop from five to four: In Progress, In Review, Production (with optional Beta), Deprecated
- Red goes away. Early sketches happen in private Figma files, not in the design system
- A "Beta" badge can sit on Green for components that are usable but not yet locked
- Green's checklist gains: "Storybook implementation exists and matches the spec"
- Backward moves require a short reason that's visible on the component page
- This page adds the "how this differs from most design systems" note so newcomers aren't confused
Open for discussion
This page captures both the proposal and the comparison side-by-side so they can be debated together. Resolved decisions will land either as edits to this page or as a real change to the live system. Until then, what's running today hasn't changed.