This article documents the workflow I used to turn a Figma design system into maintainable engineering assets for Scanat.

I divide the work into three layers:

1. Tokens — turn Figma Variables into reliable, repeatable code data;
2. Components — decide whether the team needs component code or framework-independent specifications;
3. Validation — keep Figma, code, and documentation aligned over time.

Together, these layers make the design system easier to update and verify after the initial handoff.

Preserve the Primitive–Semantic Relationship. I keep the same two-layer token structure used in Figma:

Primitives → Semantic → Component

For example:

ocean/700 = #0068B0
text/brand-primary → ocean/700

The code pipeline produces two outputs. CSS variables are optimized for browser use:

--color-text-brand-primary: #0068B0;

Structured JSON keeps the relationship for scripts and validation tools:

"text/brand-primary": {
  "value": "#0068B0",
  "aliasOf": "ocean/700"
}

This relationship is useful for theming. A semantic token can point to different primitives in light and dark modes while components continue to consume the same semantic name.

Make Extraction Repeatable. Token extraction should be a script that can be rerun whenever the design system changes.

Values available through the Figma API can be generated automatically. Information that is not exposed through the API, such as usage notes stored in documentation tables, can be maintained separately and cross-checked against the source values.

For values such as spacing and radius, a simple assertion can stop generation when the manually maintained data no longer matches Figma:

def cross_check():
    for label, table in (("Radius", RADIUS), ("Spacing", SPACING)):
        mine = {name: val for name, val, _ in table}
        theirs = VARIABLES_CHECK[label]
        assert mine == theirs, f"{label} mismatch: {mine} vs {theirs}"

Use Predictable Naming Rules. Figma names should map to code through a stable transformation rule.

Once the mapping is predictable, new tokens can be handled consistently by people or automation without adding one-off naming decisions.

Define Unit Conversion Rules Up Front. If the codebase uses rem while Figma stores values in px, I use a standard conversion rule such as 1rem = 16px. Some values remain in pixels, including thin borders and technical values such as a 9999px full radius. These exceptions are listed explicitly so similar tokens are handled consistently.

Verify the Source Data. During implementation, I found several source-data issues that could not be resolved safely from names alone: inconsistent historical naming; token names that did not match their actual color values; more Figma changes than were mentioned in handoff notes; large primitive collections where only a subset was actually used by components.

For these cases, I read the real values through the Figma Plugin API before updating the generated data.

The code token set also does not need to pretend to be complete. If only a verified subset is currently used, I document it as a subset and add more tokens as they are confirmed.

After tokens are available, the component delivery strategy depends on what the team already has.

I separate projects into two cases: a new product building its component system from scratch; an existing product with a working component library.

A new project can encode the design system directly into reusable components.

Encode Invalid Combinations in the Type System. If Figma defines restrictions between component properties, TypeScript can encode them directly:

type ButtonAppearance =
  | { styleVariant?: "fill"; theme?: ButtonTheme }
  | { styleVariant: "line" | "tint"; theme?: "light" }

Invalid combinations then fail during development instead of appearing later in visual review.

Map Figma States to Real Runtime Behavior. Figma component sets often include Hover, Focus, Disabled, Filled, and Placeholder as variants.

In code, many of these already have native browser behavior:

• Hover → :hover
• Focus → :focus-visible / :focus-within
• Disabled → :disabled
• Placeholder → ::placeholder

Application states such as validation, selected, or open can remain explicit component state or props.

Preserve How Visual States Are Generated. If a hover effect in Figma is built by layering a translucent color over a brand token, I keep the same token-based composition in code instead of replacing it with a new hard-coded hex value.

This allows the state effect to follow future brand-token changes automatically.

Let Components Consume Tokens Directly. With Tailwind, components can reference CSS variables directly:

bg-[var(--color-bg-brand)]
text-[var(--color-text-primary)]

This keeps component styles close to the generated token source.

In an existing product, rebuilding the component layer in a different framework can create more maintenance work than the design-system update solves.

Scanat was already running Vue with bootstrap-vue-next. In that context, I deliver:

1. tokens — colors, typography, spacing, radius, borders, and other shared values;
2. visual specifications — component sizes, states, and allowed combinations.

The reference site itself does not need to use the product's framework. A lightweight static setup such as Storybook html-vite can be enough because its purpose is to display the specification.

I decide the delivery model before choosing implementation tools.

For a greenfield project, a reusable code component library can be part of the design-system deliverable.

For a mature product with an existing component stack, tokens and framework-independent specifications are often the more practical handoff.

I have also started treating Figma component descriptions as part of the design-system documentation.

Descriptions used to be mostly notes for designers. Now that Figma Agent and coding agents can read component metadata, a clear description also helps the agent understand what the component is for and how its parts relate to each other.

Figma Agent can draft the first version of a component description from the component structure. I then review it and make sure a few things are explicit:

• Component usage. Give general guidance when the component is reusable across contexts. If it is intentionally designed for one specific scenario, state that directly.
• Nested component relationships. If the component contains referenced subcomponents, describe what they are and what role they play inside the parent component.
• Boolean properties. Explain what each Boolean controls and what changes when it is enabled or disabled.

A property name such as Show Leading Icon or Show Description may already be understandable to a designer. An agent implementing the component still needs to know which layer it controls, whether it affects layout, and how it relates to nested components. Keeping that context in the Description reduces guesswork when generating Storybook documentation or code.

I now treat the component Description as lightweight structured documentation that stays next to the source design and can be read by both people and agents.

Once an agent repeats the same type of task several times, I prefer to move the stable workflow into a reusable Skill.

I currently use a Skill for reading components from Figma and implementing or documenting them in Storybook. The goal is to keep the repeated process consistent without rewriting a long prompt for every new component.

The workflow is roughly:

Read the Figma component
↓
Read its Description, properties, and nested references
↓
Interpret Variant / Boolean states
↓
Organize the implementation structure and specification
↓
Generate or update Storybook
↓
Check visual states and interaction

The Skill contains rules that stay stable across components. Component-specific constraints remain in the Figma Description or the current task, so the reusable workflow stays separate from local design details.

This has been useful for reducing repeated instructions and keeping different batches of components on the same implementation path. As the design system grows, I can update the Skill once and reuse the same process for later components.

The long-term chain is:

Figma Variables
        ↓
Token Files
        ↓
Components / Documentation

Render Documentation with the Real Tokens. The component reference site imports the generated token files directly. It does not maintain a second copy of colors or spacing values.

If a token is wrong, the documentation will also look wrong, which makes the reference site an additional visual check on the data.

Run Full Comparisons Regularly. I compare the complete Figma variable set used by the system with the generated code tokens and documentation output.

Full comparison catches newly added variables and less frequently used collections that sampling can easily miss.

When Figma changes frequently, I fetch the complete source data again and compare the before/after state rather than updating only the items mentioned in handoff notes.

Test Interaction States with Real Input. Automation handles static values well, but pseudo-class states still need actual interaction.

I manually check at least: mouse hover; keyboard focus with Tab; disabled states; selected / open application states; repeated state behavior across different appearances.

If several appearances are expected to share one state rule, I still sample the resulting implementations to confirm that assumption.

Figma Variables
↓
Read verified source data
↓
Generate tokens through fixed rules
↓
Validate names, values, and units
↓
Check the team's existing component stack
↓
Greenfield: build code components
Existing product: deliver tokens + component specifications
↓
Render documentation with the real tokens
↓
Compare Figma / tokens / documentation
↓
Manually verify hover, focus, and other interaction states

The practical benefit is that fewer parts of the design system depend on manual translation. Token relationships, component rules, and validation paths stay explicit, so later changes are easier to trace and easier to verify.