Koombea AI Design System

A Koombea prototype using Figma's Code Connect.

Koombea AI Design System is a React/TypeScript design system built for Koombea AI projects. It demonstrates 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.

Resources

• Storybook (run npm run storybook to start)

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

This design system 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 Figma file

• 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.
• Create and set your Figma Auth Token
• At that point, npx figma connect publish should work and your 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/compositions

Example arrangements of primitive components to demonstrate how you might use this design system 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 layouts, but do not have analogous component in Figma.

src/ui/primitives

The main component library. 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