On exporting cleanly

The handoff from design to engineering is mostly an export problem. A few habits that have made it less of a problem in the studio’s recent work.

Components, not pages.

Engineers cannot use a Figma file that is organised as a series of pages. They can use a Figma file that is organised as a library of components, with each component named, sized, and positioned in a way that maps to the code. The pages, in this version of the file, are example assemblies of the components. The components are the deliverable.

The shift, in the studio’s process, was to design the components first and the pages second. The pages now feel like assemblies, which they are, and the engineers spend less time guessing about which version of a component is the canonical one.

Tokens, not values.

Every colour, every spacing value, every type style, every radius. Named in Figma. Named the same in the codebase. The engineer should never have to read a hex code from a Figma swatch. They should read a token name. Tokens Studio and Style Dictionary are the two tools the studio uses for this; either will export to CSS custom properties cleanly.

The studios that ship the cleanest design systems treat tokens as the contract between design and engineering. Everything else is implementation.

Variants for state, not for content.

A button has variants for primary, secondary, tertiary, large, small, disabled, hover, focus, pressed. It does not have variants for “Sign up” and “Sign in”. The first set are state. The second set are content. Most Figma files conflate the two and end up with several thousand component variants, most of which are duplicates with different text.

Frames sized for the breakpoint, not for the artboard.

Most Figma files contain a desktop frame and a mobile frame. The desktop frame is 1440 wide. The mobile frame is 375 wide. The engineer is then asked to interpolate between the two for every screen size in between. The studio’s recent files now contain a frame for each significant breakpoint, with the layout explicit at each. The interpolation is no longer the engineer’s problem.

Naming conventions.

The components, the layers, the styles, the variants. All named with a convention the engineer can predict. Button/Primary/Default. Button/Primary/Hover. Color/Surface/Subtle. The naming is boring. It is also the single change that has saved the most hours on engineering side, by a substantial margin.

A spec page.

Every component file ships with a written spec page, in the file. Two paragraphs per component. What it is for. What states it supports. Which props it takes. The same information is in the designer’s head. Writing it down means the engineer does not have to interpret. The cost is a few hours per file. The benefit is the elimination of most “what does this do” questions during the build.

The handoff is, in the end, an empathy problem. The studios that do it well are the studios where the designer has, at some point, written front-end code, and remembers what the gap between a design file and a working implementation looks like. The studios that do it badly are the studios where the design and the engineering are entirely separate practices that meet only at the spec.

The cure is easier than studios think. Use the engineer’s tools occasionally. Read the engineer’s code occasionally. Ship a small front-end project occasionally. The hand-off problem mostly goes away.

The earlier post on hand-coding in a Figma world covers the broader argument for closing the gap between design and engineering at the role level, not just at the export level.