buzzvilbuzzvil:design

Workflow

How design ships at Buzzvil. Discovery explores. Delivery earns. The environment makes both fast.

Discovery

Build to learn. Tools are whichever let you explore fastest.

Spatial exploration

Spread 8 to 10 directions across a single canvas and compare them simultaneously. Code-based tools are linear; spatial layouts prevent sunk-cost thinking. Figma is the established option. Paper (paper.design) is purpose-built for design tokens and code, removing the translation step from canvas to codebase. Stitch is another emerging option. Use any of these to compare 5+ directions, present options to a stakeholder, or explore brand and illustration work.

Code prototypes for validated ideas

A quick prototype built with Claude Code can go in front of users with real data, real interactions, and real responsive behavior. This used to require engineering allocation. The prototype's job is to answer a question, not to ship. Use code when the idea has enough signal to test at higher fidelity.

Discovery artifacts are disposable

A prototype that tested value and failed did its job. A Figma exploration that clarified the wrong direction saved weeks. Treat discovery artifacts as learning instruments, not as partially-completed products. The discipline is knowing when to stop exploring and start building.

Delivery

Build to earn. The validated direction becomes production-ready code through a 5-step loop.

1

Write the intent

The direction is validated. Capture it as a user story, a constraint set, or a written description of what should exist and why. Paper works. A markdown file works. Precision matters more than format.

2

Build in code

Open Claude Code, describe what you want, iterate until it's right. The agent uses your tokens, your components, your standing orders. Code forces reality — you can't fake responsiveness or data behavior in a canvas.

3

Open a PR

Push the branch, describe what changed, request review. The PR is the unit of output. It makes the work visible, reviewable, and traceable from day one.

4

Review

Every UI PR — opened by a designer, PM, or engineer — goes through Design Review for visual quality and harness compliance. Engineering review covers correctness, performance, and accessibility. One process, not two separate handoffs. Feedback happens in the PR, not in a separate meeting.

5

Ship

Deploy on merge using whichever pipeline the project runs (Vercel, GitHub Pages, internal CI). No staging bottleneck, no separate deploy step, no waiting for the next release window. The entire loop from intent to production can be hours, not weeks.

Harness

The environment that makes delivery fast: library, skills, hooks, tokens.

@buzzvil/design-library

The React component library powering Buzzvil products. Tokens, components, and interaction patterns consumed by 5+ repos. The agent's primary building material.

Buzzvil internal · access required

Claude Code skills

Reusable playbooks for recurring tasks: buzzvil-brand, buzzvil-dashboard, SDK docs releases, blog posts. Skills encode craft knowledge that would otherwise exist only in someone's head.

AGENTS.md + design.md

Canonical agent rules on Buzzvil/design-library. Every Claude Code session in a consuming repo reads these. Encodes token rules, brand voice, production lessons, and layer map.

Buzzvil internal · access required

Hooks

Automated checks on commit: Biome lint, TypeScript type-checking, spacing conventions, destructive-operation warnings. Silent on success, loud on failure.

Tokens

A single source of truth covering color, spacing, type, radii, shadows, motion timings, and animation personalities. Tokens are layered: primitives, semantic intent, and component-specific. Brand variants (Chameleon) swap the semantic layer to retheme an entire surface without touching components. The agent reads tokens as the shared vocabulary between design and code.

Roles

How designers, PMs, and engineers work under the AI-native model.

Shipping UIs isn't only for designers. Just like writing code isn't only for engineers, anyone on the team can open a UI PR using the design harness and library. Every UI PR goes through Design Review.

Designers

  • ·Write user stories and intent documents before opening Claude Code.
  • ·Ship changes through PRs. Own the experience layer from discovery through delivery.
  • ·Use Figma for spatial exploration and stakeholder alignment. Use code for everything that needs to ship.
  • ·Judgment and accountability remain the designer's. The agent executes; the designer decides.
  • ·Reviews UI PRs from anyone on the team.

PMs

  • ·Define the problem and validate the solution. Run discovery loops alongside designers rather than waiting for specs.
  • ·Review PRs instead of Figma files. The working implementation is the spec.
  • ·Prototype flows directly using the design system and AI agent when useful. The designer reviews visual quality.
  • ·Open UI PRs for product flows; Design reviews.

Engineers

  • ·Review design PRs for correctness, performance, and accessibility. This is the engineering side of the shared review process.
  • ·Build and maintain the infrastructure: harness, hooks, token pipeline, CI.
  • ·Collaborate on discovery when technical feasibility is an open question. Code-based feasibility testing is now a design activity too.
  • ·Open UI PRs alongside backend work; Design reviews.