Synchronizing Design and Code with Design Tokens

Sometimes, building a design system at a startup can actually slow you down. This is due to the tedious, repetitive work of having developers manually translate the values modified by designers back into code. You must automate this process so that the team can focus on essential product challenges.

Unifying the Design Language with Tokens

Do not manually map design tool values to code variables one by one. By introducing design tokens, this connection becomes data-driven.

1. Primitive tokens: Define raw color values, such as blue-500.
2. Semantic tokens: Specify the actual usage, such as action.primary.bg, and reference the primitive tokens above.
3. CSS variable mapping: Store the semantic tokens as CSS variables.

By setting it up this way, even if a designer changes a color value, developers do not need to touch the code. The system automatically updates the CSS files. For font scales, define them mathematically by entering a Base and Ratio in Penpot’s token panel. Using the formula $Size_{n} = Base \times Ratio^{n}$ forces design consistency to be maintained.

Automating Penpot and GitHub Integration

Having developers manually verify design changes is inefficient. Since Penpot follows the W3C Design Tokens standard, building a pipeline is possible.

1. Generate a Penpot API key.
2. Create a penpot-export.config.js file in the project root. Configure the tokens to extract and the save path here.
3. Install the @penpot-export/cli package and execute the npx penpot-export command.

Hundreds of token values are imported into the codebase in an instant. Human errors that occur during manual input disappear. Large-scale services like Shopify also leverage this token-based workflow to update designs instantly without modifying code.

Understanding Design Intent Through Git Reviews

Do not communicate design changes via Slack messages or verbally. Manage them with Git, which is what developers are most accustomed to.

1. Create a .github/workflows/design-sync.yml file to automate design token extraction.
2. Automatically generate a PR containing the changes using the peter-evans/create-pull-request action.
3. Once the PR is up, check the style(tokens) commit message and view the diff during the code review process.

Developers can immediately understand what value changed and why through the PR. This saves time spent walking around asking why something was changed.

Coexisting with Legacy Code

Do not try to change all the code at once. Using a fallback technique where you mix existing CSS and new tokens is more realistic.

1. Place the automatically generated token files in the src/styles/tokens directory.
2. Use the var(--new-token, #legacy-value) format in your existing CSS.

Components for which tokens have not yet been defined will retain their existing values. You can modernize the system bit by bit without worrying about the UI breaking. Start by connecting just one small color token to the pipeline. It is a way to prevent the massive technical debt that would otherwise occur in the future.