Figma SDS: bridging a Figma file and a React codebase with Code Connect

A reference system, and an honest one

The positioning sentence in the README is unusually direct. SDS is a base design system that shows how Figma Variables, Styles, Components and Code Connect can be used alongside a React codebase to form a complete picture of a responsive web design system, and the project states that it is not just another design system in Figma. The reason is that there are still many gaps between design and development, and SDS provides some best practices for how to bridge them. What the project promises is to remain honest about its implications in code while also offering customizability in design beyond the simple theming layer that is typical of many code-first component libraries. That is the pitch in full, and it explains who this is for. Whether you are starting a new project with it or reading it for the patterns, the repository holds tools in the codebase and in the design file that are meant to steer you in the right direction. The status line at the top says alpha, and that is the honest label for what it is.

The src/ui categories, and what each one is for

All components and styles live under src/ui, broken into categories that map onto how a design system is actually built. Primitives are the main component library, and the README makes a strong claim about them, that SDS primitives cannot be reduced further into sub components. Compositions are arrangements of primitive components that show how you might use SDS to build a responsive website. Layout components are called crucial to SDS layouts and are explicitly noted as having no analogous component in Figma, which is the clearest admission in the repository that code and design are not symmetric. Then there are the supporting directories, hooks for custom React hook definitions, providers for custom React provider definitions, utils for custom utilities and utility components, icons for all icon components, and images, which hold stand-in images. The icon directory is not maintained by hand, since the README says the icon components are automatically generated by the scripts in scripts/icons. Code Connect templates and Storybook stories follow the same categorisation, in src/figma and src/stories respectively.

documentUrlSubstitutions is the trick that makes it reusable

Code Connect templates have to point at real nodes in a real Figma file, which is normally what stops a template set from being portable. SDS handles that with documentUrlSubstitutions in figma.config.json, and the effect is that the templates stay Figma file agnostic while all the file specific information is collected in one place for easy swapping. The key naming is deliberate as well, since a key such as <FIGMA_INPUTS_CHECKBOX_GROUP> is broken down as <FIGMA_[PAGE_NAME]_[COMPONENT_NAME]>, and that naming is chosen so a developer can find the associated component without clicking through a link. The configuration itself is small:

{
  "documentUrlSubstitutions": {
    "<FIGMA_INPUTS_CHECKBOX_GROUP>": "https://figma.com/design/whatever?node-id=123-456"
  }
}

The templates then reference those keys rather than a hard coded address, and the comment in the template says it plainly with a url comment pointing at the substitution group. The result is a template set that you can point at your own file by editing a handful of entries.

Making the Figma file yours in five steps

The README is explicit that a fresh clone of the Simple Design System Figma file should keep all of the node ids, and then it gives the sequence. You duplicate the Figma Community File, you clone the repository, and you update the urls in figma.config.json to point at your copy of the file. The note there is important: the file key, a string like J0KLPKXiONDRssXD1AX9Oi, should be the only change in the urls, unless you are creating new components or detaching and recreating existing ones. Then you create and set your Figma auth token, and at that point npx figma connect publish works and your new file has Code Connect. The reason the node ids survive duplication is what makes the whole approach viable, since a template that points at a node id only works if that node still exists in your copy, and duplication preserves the structure while changing the file key.

Figma tokens, scopes and the .env file

The authentication setup is the part that decides whether the scripts will work for you at all. You create a Figma API token and request the scopes the project needs. For Code Connect itself that is file_code_connect_scope:write. For the integrations in the scripts directory you also need file_dev_resources:read and file_dev_resources:write, file_variables:read and file_variables:write, file_metadata:read and file_versions:read, and the two variable scopes carry a note that they are available on the Enterprise plan only, which is a hard constraint for anyone on another plan. The token and the file are then configured in an environment file, by duplicating .env-rename, renaming it to .env, and noting that it is ignored by git. Inside it you set FIGMA_ACCESS_TOKEN to your token and FIGMA_FILE_KEY to your file's key, which you take from the file URL. The scripts in package.json read that file directly with node --env-file, so the .env is the single place the credentials live.

Running the app, Storybook and the script suite

The local setup is three commands. npm i installs the dependencies, npm run app:dev runs the development server at localhost:8000, which renders the contents of src/App.tsx, and npm run storybook starts Storybook at localhost:6006. The manifest lists the rest of the toolchain, and it is a coherent one for a Figma plus React project: a build step that runs tsc and then vite build, a lint task with the unused disable directive reporting and max warnings set to zero, a preview server, a separate Storybook build into dist/storybook, and a combined build that runs both. The scripts have their own family of entries, script:dev-resources, script:icons, script:icons:rest, script:tokens and script:tokens:rest, each of which changes into a directory under scripts, runs a node script with the environment file, and moves back. The dev dependencies tell you what the code leans on, with @figma/code-connect at 1.4.9, a full set of Storybook 8.6 packages, React 18 type definitions, Vite and the React plugin, ESLint 8 with the TypeScript plugin, and a Prettier setup that uses the organize imports plugin.

Bulk editing the file from the browser console

The scripts directory is the most surprising part of the repository, because it can modify a Figma file without a plugin. The component-metadata scripts are JavaScript that you run in the Figma JavaScript console with the file open, and the README recommends them over building a plugin for bulk description work. The flow is deliberately manual but simple: copy the contents of exportComponentJSON.js into the console, run it, copy the result as an object, and paste it into components.json, where you can edit the descriptions more easily, then copy that JSON and paste it at the top of importComponentJSON.js as the value of the json variable, and run the import file to batch update the descriptions across the file. The README is clear about the limit, that this only updates descriptions, and points to the dev-resources scripts for the rest. Those run through the REST API instead, with npm run script:dev-resources, and set the dev resources of all components to match devResources.mjs, which is useful when swapping the file URL. The caveat printed in the README is that some of these integrations need API scopes your organisation may not have. On the state of the project, it is MIT licensed, labelled alpha, the last push was on 2026-10-07, the repository is not archived, and it publishes no GitHub releases.

Editorial conclusion

Simple Design System fits a team that wants to understand how Figma Code Connect, Variables and a React component library are meant to fit together before designing that arrangement itself, and it fits a designer developer who needs a working reference for a file-agnostic Code Connect setup. It is the wrong choice if you want a component library to drop into a product, because the code here is reference code for a design system Figma itself uses, and it is a poor fit if your Figma plan is not Enterprise, since the variable read and write scopes the scripts rely on are marked as Enterprise only. Before you start, duplicate the community file rather than editing the original, set the file key in your .env and in figma.config.json, and decide which direction you want to own, since the scripts can push into Figma as easily as they read from it.

Frequently asked questions

Official sources

1. figma/sds on GitHub
2. Issues
3. License: MIT
4. README