Simple Design System (alpha)

Using Figma's Code Connect.

Simple Design System (SDS) is a base design system that shows how Figma’s Variables, Styles, Components, and Code Connect can be used alongside a React codebase to form a complete picture of a responsive web design system.

SDS is not just another design system in Figma. There are still many gaps between design and development, and SDS provides some best practices for how to bridge them. SDS tries 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.

Whether you’re looking to use SDS to start a new project, or are looking for examples of some common design systems best practices, you'll find tools inside this codebase and design file to steer you in the right direction.

Resources

• Storybook
• Figma Community File

Setup

• npm i to install dependencies
• npm run app:dev will run server at localhost:8000 which renders contents of App.tsx
• npm run storybook to start storybook at localhost:6006

Figma Auth

• Create a Figma API token
  • Add Code Connect scope
  • Add File Read, Dev Resources Write, and Variables scopes if you want to use the integrations in scripts
  • More on scopes
• Duplicate .env-rename
• Rename it to .env, it will be ignored from git.
  • Set FIGMA_ACCESS_TOKEN= as your token in .env
  • Set FIGMA_FILE_KEY= as your file's key (grab it from the file URL) in .env

Code Connect

SDS is fully backed by Figma's Code Connect. This includes examples for how to connect primitives, as well as compositions of those primitives for your design system.

This repo utilizes documentUrlSubstitutions in figma.config.json. This allows us to keep our docs Figma file-agnostic and colocates all the Figma file-specific information for easy url swapping. The document URL substitutions are also named in a way that helps you find the associated component without clicking a link. A key <FIGMA_INPUTS_CHECKBOX_GROUP> is broken down as <FIGMA_[PAGE_NAME]_[COMPONENT_NAME]>.

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

Allows us to have more expressive URLs in our Code Connect docs:

figma.connect(CheckboxGroup, "<FIGMA_INPUTS_CHECKBOX_GROUP>");

Connecting this repo to a duplicated Figma file

With the above in mind, a fresh clone of the Simple Design System Figma file should maintain all the node-ids. The steps should be as follows:

• Duplicate the Figma Community File
• Clone this repo
• Update urls in figma.config.json to point to your Figma file
  • Note: the file keys (eg. J0KLPKXiONDRssXD1AX9Oi) should be the only change in the urls unless you're creating new components, detaching and recreating.
• Create and set your Figma Auth Token
• At that point, npx figma connect publish should work and your new file should have Code Connect.

Structure

All components and styles are in src/ui. Within that directory, code is broken down into a few categories.

src/ui/components

APIPASS addition, not part of upstream SDS. Composed, reusable blocks assembled from primitives to solve a specific recurring UI pattern (Card, DataTable, ConfirmDialog, FormModal, PageHeader, Sidebar, Widget/WidgetGrid). Unlike compositions, these carry real app-facing behavior and are meant to be imported directly, not just copied as a layout example.

src/ui/compositions

Example arrangements of primitive components to demonstrate how you might use SDS to build a responsive website.

src/ui/hooks

Custom React hook definitions

src/ui/icons

All icon components. Automatically generated by scripts/icons

src/ui/images

Placeholder images.

src/ui/layout

Layout components. Crucial to SDS layouts, but do not have analogous component in Figma.

src/ui/primitives

The main component library. SDS primitives can't be reduced further into sub components.

src/ui/providers

Custom React provider definitions

src/ui/utils

Custom utilities and utility components

Code Connect and Storybook

All Code Connect docs and Storybook stories follow the same categorization are defined in src/figma and src/stories.

Scripts

Some example integrations are available in scripts directory. They may require additional API scope that your org may or may not have access to. Where possible, there are some plugin examples to help fill gaps.

scripts/component-metadata

• Scripts to run in the JS Console in Figma
• Bulk manage descriptions for all components in the file. Instead of making a complicated plugin, you can do this more simply by running scripts directly from the JavaScript console.
• Copy the contents of scripts/component-metadata/exportComponentJSON.js and run in the console with the file open.
  • "Copy as object" the result and paste into scripts/component-metadata/components.json.
• There you can modify descriptions more easily.
• Once you have modified the descriptions, copy the JSON and paste at the top of scripts/component-metadata/importComponentJSON.js as the value of the json variable.
• Copy all the contents of the import file and run in the console to batch update descriptions for the entire file.
• This will only update the descriptions. To update Dev Resources, you can use scripts/dev-resources.

scripts/dev-resources

• npm run script:dev-resources (REST API only)
• Sets dev resources for all components described in scripts/dev-resources/devResources.mjs to match.
• Useful when swapping urls in bulk. Requires Dev Resources: Write scope on your REST API token.

scripts/icons

• npm run script:icons:rest
• Gets all icons from the file, and generates components in the src/ui/icons directory.
• Also generates src/figma/icons/Icons.figma.tsx for Code Connect.

scripts/tokens

• npm run script:tokens:rest
• Gets all variables and styles from Figma, and converts them to src/theme.css.
• Creates scripts/tokens/tokensCodeSyntaxes.js which is a script you can run in the JS console in Figma to update all the variable's codeSyntaxes with CSS that matches this repo.
• Includes some example plugins for how to get the same data without the Variables REST API.
  • Install plugins in Development
  • Run plugins, and copy plugin outputs into scripts/tokens/styles.json and scripts/tokens/tokens.json
  • Run npm run script:tokens (without :rest) and it will reference the JSON files directly without making a REST API request to update them