Component Library Handoff When Designer Also Codes

Most component library articles assume a designer and an engineer working on opposite sides of a handoff. Figma files, redline rounds, staging reviews. That is the right advice for most teams. It is not the advice that applies to my practice or to the class of DTC brands I see winning in 2026, where one person concepts the page, designs the component, and ships the code.

When the designer also codes, the component handoff is a one-person loop. The optimization question stops being "how do we reduce friction between designer and engineer" and starts being "what work stays in Figma, what moves to code, and where does the documentation live so a future collaborator can read it."

These are the field notes from running a one-person component library for the last two years.

2026-04-02: what lives in Figma

Figma still has a place. I use it for three things and not for a fourth.

First, for sketching. A new component usually starts as a Figma frame at roughly the right proportions, with placeholder content. The goal is not pixel-perfect design; the goal is to get the structural decisions out of my head so I can look at them together and decide whether the component is shaped right before I write any code.

Second, for stakeholder review. If a client wants to see a proposed change before code ships, Figma is the fastest way to put it in front of them. They can comment. I can iterate. No staging deploys required.

Third, for marketing team handoff. When the marketing team needs to produce an ad creative or an email banner using brand components, the Figma file with the master styles is what they reference. The Figma styles are pulled from the code token file via a quarterly sync script; they are a mirror, not a source.

What does not live in Figma: the production component specification. The implementation lives in code. The documentation of what the component does, how it is used, what props it accepts, lives alongside the code in a README.

2026-04-05: the token contract

Even though one person is doing both sides, the token file is still the contract. Every design decision I make in Figma has to trace to a token. If Figma uses a color that is not in the token set, that is a signal that either the token set is incomplete or the design is drifting.

The discipline: before I start building a component, I check whether every color, type size, spacing, and motion value it needs is already in the token file. If yes, I proceed. If no, I either pick an existing token that is close enough (usually the right call) or add a new token with a specific production use case (occasionally necessary).

This discipline is the same one that a separate designer and engineer would enforce on each other. When both roles are one person, the discipline has to be internalized as a checklist. I have the checklist in my README and it takes about 60 seconds to run before any component work.

2026-04-07: the loop collapses, but the documentation does not

The biggest time gain when the designer also codes is not the speed of the work per step. Each individual step takes about the same time. The gain is the elimination of round-trips.

In a traditional handoff, a component might go through 2-3 round-trips: designer ships Figma, engineer codes it, designer reviews the staged build, engineer fixes, designer re-reviews, engineer polishes. Each round-trip is roughly a day of calendar time. A component that takes 4 hours of actual work stretches to a week.

When one person does both, the round-trip count goes to zero. The component ships in the 4 hours of actual work, because the "does this match the design intent" question is answered by the same person who had the intent. No handoff, no redline.

The thing that does not collapse is documentation. A component still needs a README. Future-me-in-six-months will not remember why the card has 24px of vertical padding and 16px of horizontal. Future-collaborator does not have access to my head; they have access to the repo. The documentation is how the one-head advantage becomes transferable.

2026-04-10: what a component README contains

Six fields. I keep it boring on purpose.

Name. The tag name as used in JSX, plus the file path.

Purpose. One paragraph. What this component is for, in words a non-engineer could understand.

Props. Table of prop names, types, whether required, default values, and a one-line usage note.

Examples. 2-3 MDX or JSX snippets showing canonical use. Real examples, not synthetic ones; link to a production page where the component appears in the wild.

Do and don't. A short list of common misuses, with the correct alternative. "Do not put body text on a --signal background; use --ink on --paper instead."

Last touched. The date and PR number of the most recent meaningful change. This is the cheapest freshness signal in the system.

That is it. No usage diagrams, no long rationale, no design history. A collaborator can read a complete component README in 90 seconds and start using it correctly.

2026-04-12: the Storybook question

I tried Storybook for six weeks at one point. It worked, but maintaining it cost more than linking to production pages.

The pitch of Storybook is that you can view a component in isolation with controls for each prop. For a team with dedicated QA and a widget engineer, this is valuable. For a one-person practice, the workflow of "open the component file, write a quick test page, navigate to it in the dev server" is faster than writing a Storybook story and maintaining it separately.

When Storybook earns its keep: when the team is three or more, when regression testing is formalized, when components are published to a shared package consumed by multiple projects. None of those apply to my current practice. Cut.

The replacement is a simple /dev/components route in the Next.js app that renders every component with canonical examples. It is not fancy. It is not isolated from the rest of the app. But it is honest: if a component looks right on the /dev/components route, it is going to look right in production because the context is the same.

2026-04-15: what a real collaborator needs

Every once in a while, a real collaborator joins. A design intern, a subcontract engineer, an agency team helping with an event. They need to use the component library correctly without me sitting next to them.

The handoff artifact in that case is three files:

First, the token file with comments. Every semantic token has a comment explaining what role it plays and what not to use it for.

Second, the components README index. A list of every component with a one-line description and a link to its own README.

Third, the voice doc. A short markdown file with the brand's writing rules (tone, no em dashes, no staccato negation, specific claim rules). This catches most of the "is this on brand" question before it needs a design review.

Total: about 30 pages of readable content, which a new collaborator can absorb in an afternoon. That is the same deliverable that a 60-page brand guide used to deliver, compressed by a factor of two because we deleted the parts that were aspirational or didactic and kept only the parts that tell a collaborator what to do.

2026-04-18: where it breaks

Two failure modes.

Failure mode 1: documentation rot. When I update a component without updating its README, the next collaborator onboards to the wrong information. Catch: a quarterly check that compares each README's "last touched" date to the actual file's git log. Any gap flags a rot candidate.

Failure mode 2: overconfidence about what I remember. I have caught myself committing a component change with a note like "minor cleanup, no behavior change" which turned out to be a breaking change for one specific usage a month later. Discipline: any component change that modifies props, removes a style, or changes a default gets a brief note in the PR description about downstream impact, and the README gets updated to reflect the new contract.

Both failure modes are solvable by institutionalized laziness: make it easier to update the doc than to not update it. I keep the README open in a split pane while editing any component file. The cost of updating is small. The cost of not updating shows up later.

2026-04-21: how this scales

The hybrid-operator model caps out around 4-5 collaborators as long as the documentation stays honest. Past that, the overhead of keeping everyone aligned on token decisions, component contracts, and brand voice starts to require formal systems: design reviews, lint rules, automated style checks. I wrote about the upper bound of the creative-tech operator role in the solo-brand hub.

Within the 1-4 collaborator range, the same handoff discipline that works for one person works for the whole team, as long as the docs carry the weight. I ran the same pattern on a 5-person marketing team at a DTC client (see the brand asset hub case) and it held for a year, until the team grew past 5 and needed stronger enforcement tooling.

Frequently asked questions

Sources and specifics

• Pattern running on this site (Next.js 16, MDX component library with about 150 components) and on four other DTC Shopify and Next.js builds across 2024-2026.
• The 60-70 percent calendar-time saving is from comparing my own pre-hybrid (designer + agency engineer) and post-hybrid (one person) timelines on comparable component scopes.
• The 5-person brand asset hub engagement is documented in the brand asset hub case, where the same discipline scaled for a year before team growth required stronger tooling.
• Storybook was tried for 6 weeks on one project in Q1 2025 before being cut in favor of an in-app /dev/components route. The maintenance-cost comparison is from direct tracking during those 6 weeks.
• See also: the brand architecture hub, design tokens that survive a rebrand, and the typography scale article.
• Full methodology is part of the Shopify theme starter.