Workflow
Two lanes
Explore decides whether and what to build. Deliver puts it in users' hands.
Explore
- Purpose
- Decide whether and what to build
- Starts from
- An open question
- Tools
- Whatever is fastest: Figma, prototypes, AI
- Quality bar
- Enough to learn
- Ends with
- A decision in the ticket: build, change or stop
- The work afterwards
- Left behind once decided
Deliver
- Purpose
- Put it in users' hands
- Starts from
- A clear task, or a yes from exploration
- Tools
- Code, the design library, repo skills
- Quality bar
- The craft bar
- Ends with
- A merged PR, tested, then released
- The work afterwards
- Lives in the product
Exploration is optional.
Use it when the question is open: is this worth building, and what should it be? A clear task skips it.
Keep the lanes apart.
Work that sits between the lanes gets done twice: a prototype built to learn, redrawn as a spec, then rebuilt for production. Once the answer is yes, delivery starts in the real product.
Stopping is a good result.
An exploration that ends in a no saves the delivery lane weeks of work.
Three delivery paths
Each path sets who builds the change and who reviews it.
Designers, PMs and engineers all open UI PRs. They build with the design library and the repo's design skills, and the designer of that surface makes the final design call.
Designer owns it
When
The default for designers
Spot the problem, or take the ticket, and carry it all the way: build the fix in code with AI, get the code reviewed, ship it and check it live. One person, from problem to production.
PM or engineer builds, designer reviews
When
UI changes on existing screens: copy, states, layout, small flows
The PM or engineer builds with the design library and the repo's design skills, and opens the PR. The designer of that surface reviews it and makes the final design call. We want more of this path: the person closest to the problem ships the fastest.
Build together
When
New screens that need data, logic or tracking
The designer builds the UI PR in the real product. The engineer adds data, logic and tracking on the same branch, or in a PR that links it. The designer checks the result before merge.
The designer's review
Code review, turned around: you review our logic, we review your interface. Every review ends in one of three outcomes.
Approve
- When
- It meets the bar
- What the designer does
- Approves the PR.
Fix
- When
- Small gaps: spacing, tokens, copy, a missing state
- What the designer does
- Pushes the fix to the same branch and notes what changed.
Send back
- When
- The direction or the problem is unclear
- What the designer does
- Comments with the reason, and suggests building together when the change is bigger than it looked.
- ·Review happens within one working day.
- ·UI PRs merge with the designer's approval. Engineering reviews the code as usual.
- ·The craft check and an AI reviewer go through the PR first, so the designer's time goes to flow, copy and feel.
From branch to release
Every change takes the same route, from a branch in the product repo to the product page.
Build in the real product
Work on a branch in the product repo with Claude Code. Check every state: loading, empty, error and a narrow screen. Open a draft PR with a preview link a PM can click.
Review
The designer reviews the interface and an engineer reviews the code. A PR is a proposal: nothing goes live before an engineer approves it.
Early testing
Before public release, the team tests the change: self tests, or early users through a flag or a beta.
Public release
The change ships through the project's own release path, the same way as every other change.
Product page
When the PM judges the team is confident, the PM or product designer updates the product page with Claude and our brand skill. After our marketing team reviews the content, the page can go live ahead of the public release.
Harness
The environment that makes delivery fast: tokens, skills, agent rules, checks and AI review.
Tokens and brand kit (@buzzvil/design-library)
The shared token and brand engine: OKLCH color tokens, the brand kit and theming. We narrowed the library to this engine in August 2026, and its component tier is frozen. Products build with the components in their own repos.
Claude Code skills
Skills in the buzzvil-design plugin: brand foundations, decks, docs, reports, dashboards, icons and illustrations, web page editing and SDK release notes. Product repos add their own design skills, such as finding similar components before building new UI.
CLAUDE.md and AGENTS.md
Every repo carries its own agent rules: tokens, conventions, brand voice and lessons from production. The agent reads them at the start of every session.
Hooks and checks
Automated checks on commit: Biome lint, TypeScript type-checking, spacing conventions, destructive-operation warnings. A craft check runs before review: hard-coded colors, type below 12px on product surfaces, reduced motion, image weight and accessible names, each with file and line. Silent on success, loud on failure.
AI review
An AI reviewer reads UI PRs against the craft bar before a designer looks, and returns findings with file and line. Our rule: designers answer each finding before they mark a PR ready.
Tokens
One shared set covering color, spacing, type, radii, shadows, motion timings and animation personalities. Tokens come in three layers: primitives, semantic intent and component-specific. Brand variants (Chameleon) swap the semantic layer to retheme a whole surface and leave the components as they are. The agent reads tokens as the shared vocabulary between design and code.
Resources
The playbook, the library docs and the story behind this workflow.