Skip to main content
inkbridge

Implement a component from Figma by hand

The engineering-led path: an engineer reads a Figma frame and writes the Storybook story directly. The no-AI counterpart to figma-bootstrap.

When this applies

A designer just shipped a Figma frame and you’re the engineer implementing it. The AI-assisted path (figma-bootstrap) is one way to do that. This page is the other one: read the frame yourself, write the story from scratch.

When this is the better choice:

  • The component is simple enough that typing it is faster than adapting AI output.
  • The codebase has strong conventions you want to internalise as you write (new team members benefit from doing one or two by hand before reaching for the AI bootstrap).
  • Animation-heavy or interaction-heavy components — AI drafts usually nail the static markup but miss the timing/state machinery.
  • Team policy rules out AI assistance, or the design is sensitive enough that you’d rather not paste a Figma URL into a third-party API.
  • You’re already deep in a related file and the context switch into the AI assistant is more friction than the typing it saves.

The workflow

1. Get the Figma URL and pull the design context

Open the frame in Figma Desktop and switch to Dev Mode (top-right toggle). Dev Mode shows you the relevant numbers without measuring by eye:

  • Layout: padding, gap, alignment, flex direction. Inkbridge renders the Figma design system from your Tailwind tokens, so most numbers should already map to scale tokens (e.g. a 16px padding maps to p-4) — when it doesn’t, that’s a designer-engineer conversation, not an arbitrary value.
  • Colour: should already be a Variable. Pick the semantic token name (--primary, --muted-foreground) rather than the hex.
  • Typography: Dev Mode shows the text style name. Map it to your Tailwind utility (text-sm, text-lg).
  • Composition: identify the primitives. A card with a header, body, and footer probably uses ~/components/ui/card; an input row uses Input + Label. Don’t roll bespoke versions of things that already exist.

2. Scaffold the files

The three-file pattern matches what figma-bootstrap produces:

src/components/<name>/
├── <name>.tsx
├── <name>.stories.tsx
└── index.ts

Marketing molecules go under src/feature/marketing/components/<name>/. index.ts is a one-line barrel: export { ComponentName } from "./component-name";

3. Write the component

Follow the project conventions you’d apply to any adaptation:

  • Reuse primitives. Reach for ~/components/ui/button, card, input before writing bare HTML.
  • No className prop on marketing / static feature components — the scanner needs fixed-size frames.
  • No inline styles for theme values. Tailwind classes only (text-primary, bg-card; arbitrary text-[#0a0] only when no token fits).
  • Server Component by default. Only add "use client" when you actually need state, effects, or browser APIs.
  • clsx for conditional classes everywhere except inside ui/ wrappers (those use cn() from ~/lib/utils).

4. Write one story per visual state

Default, Open, Loading, WithIcon — each visual state is its own story export. Don’t hide variants behind interactive toggles inside a single story; the Figma plugin renders one frame per story, so separate stories give designers separate frames to compare.

5. Validate locally

  1. pnpm storybook — open the new story and walk every state.
  2. pnpm check-types && pnpm lint — fix anything before the PR opens.
  3. Run the Figma plugin in a fresh design file with Generate Design System Page — confirm the new component renders as expected. If rendering is off, that’s a scanner bug, file it; don’t work around it in the story.

6. Open a PR for designer review

Hand it over via the Storybook review flow. PR description links the story name and either runs Storybook locally or deploys a preview build. Designer reviews against the spec, signs off or comments. You iterate; the story file stays the canonical artifact through every iteration.

Editing an existing component

Same workflow. The only difference is that the story file already exists — you open it instead of creating a new one. Read the updated Figma frame in Dev Mode, compare it against the current implementation, adjust the JSX or classes, add or rename stories if visual states changed, validate locally, hand off via the Storybook review flow.

Until the Pro structural round-trip ships, this is how existing- component changes land in code. Token-only changes (just colour, spacing, or radius) skip this path entirely and go through the automated token round-trip instead.

When to switch to figma-bootstrap

By-hand isn’t always the right call. Reach for figma-bootstrap when:

  • The static markup is non-trivial — long forms, dense marketing sections, table-heavy layouts. AI saves real typing.
  • You’re shipping several similar components in a row and want consistency.
  • You’re new to the codebase — the AI’s output, run through the adaptation checklist, can be a faster way to learn conventions than writing from scratch.
  • The Figma frame is dense with arbitrary values that map to specific Tailwind utilities you don’t want to look up by hand.

Both paths end at the same place — a story file in your repo, the canonical artifact. The path is a tool, not a philosophy.

Related

← Back to Methodology