documentation

README.md

@@ -1,17 +1,109 @@
-# SDS + Storybook + Code Connect Demo
+# Simple Design System (alpha)
 
 Using Figma's [Code Connect](https://github.com/figma/code-connect).
 
-## Auth
-
-Create an API token with Code Connect scope (add Dev Resources and Variables scopes as well if you want to use those integrations). Duplicate `.env-rename` and rename it to `.env` and put your token there. It will be ignored from git.
-
-## Codebase setup
+## Setup
 
 - `npm i` to install dependencies
-- `npm run app:dev` will run server at [localhost:8000](http://localhost:8000) which renders contents of [App.tsx](src/App.tsx).
+- `npm run app:dev` will run server at [localhost:8000](http://localhost:8000) which renders contents of [App.tsx](src/App.tsx)
 - `npm run storybook` to start storybook at [localhost:6006](http://localhost:6006)
 
+### Figma Auth
+
+- [Create a Figma API token](https://www.figma.com/developers/api#authentication)
+  - Add Code Connect scope
+  - Add File Read, Dev Resources Write, and Variables scopes if you want to use the integrations in [scripts](./scripts/)
+  - [More on scopes](https://www.figma.com/developers/api#authentication-scopes)
+- Duplicate [.env-rename](./.env-rename)
+- Rename it to `.env`, it will be ignored from git.
+- Set `FIGMA_ACCESS_TOKEN=` as your token in `.env`
+
+### Code Connect
+
+SDS is fully backed by Figma's Code Connect. This includes examples for how to connect [primitives](./src/figma/primitives/), as well as [compositions](./src/figma/compositions/) of those primitives for your design system.
+
+This repo utilizes `documentUrlSubstitutions` in [figma.config.json](./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]>`.
+
+```json
+{
+  "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:
+
+```js
+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 SDS file from Figma Community
+- Clone this repo
+- Update urls in [figma.config.js](./figma.config.js) 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](#figma-auth)
+- 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](./src/ui). Within that directory, code is broken down into a few categories.
+
+- [compositions](./src/ui/compositions/)
+  - Example arrangements of primitive components to demonstrate how you might use SDS to build a responsive website.
+- [hooks](./src/ui/hooks/)
+  - Custom React hook definitions
+- [icons](./src/ui/icons/)
+  - All icon components. Automatically generated by [scripts/icons](./scripts/icons)
+- [images](./src/ui/images/)
+  - Placeholder images.
+- [layout](./src/ui/layout/)
+  - Layout components. Crucial to SDS layouts, but do not have analagous component in Figma.
+- [primitives](./src/ui/primitives/)
+  - The main component library. SDS primitives can't be reduced further into sub components.
+- [providers](./src/ui/providers/)
+  - Custom React provider definitions
+- [utils](./src/ui/utils/)
+  - Custom utilities and utility components
+
+All Code Connect docs and Storybook stories follow the same categorization are defined in [src/figma](./src/figma) and [src/stories](./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 plugins examples to help fill gaps.
+
+### [scripts/component-metadata](./scripts/component-metadata)
+
+- JS Console in Figma scripts
+- Used to bulk manage descriptions for all components in the file. Instead of making a complicated plugin, you can do this more simply by running scripts in the JavaScript console.
+- Copy the contents of [scripts/component-metadata/exportComponentJSON.js](./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](./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](./scripts/component-metadata/importComponentJSON.js) as the value of the `json` variable.
+- Then copy the contents of the 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](#scriptsdev-resources).
+
+### [scripts/dev-resources](./scripts/dev-resources)
+
+- `npm run script:dev-resources`
+- Sets dev resources for all components described in [scripts/dev-resources/devResources.mjs](./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](./scripts/icons)
+
+- `npm run script:icons:rest`
+- Gets all icons from the file, and generates components in the [src/ui/icons](./src/ui/icons) directory.
+- Also generates [src/figma/icons](./src/figma/icons) for Code Connect.
+
+### [scripts/tokens](./scripts/tokens)
+
+- `npm run script:tokens:rest`
+- Gets all variables and styles from Figma, and converts them to [src/theme.css](./src/theme.css).
+- Creates [scripts/tokens/tokensCodeSyntaxes.js](./scripts/tokens/tokensCodeSyntaxes.js) which is a script you can run in the JS console in Figma to update all the variable's [codeSyntaxes](https://www.figma.com/plugin-docs/api/Variable/#codesyntax) with CSS that matches this repo.
+- Includes some example plugins for how to get the same data without the Variables REST API.
+  - [Install plugins](https://www.figma.com/plugin-docs/plugin-quickstart-guide/) in Development
+  - Run plugins, and copy plugin outputs into [scripts/tokens/styles.json](./scripts/tokens/styles.json) and [scripts/tokens/tokens.json](./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

package.json

@@ -23,7 +23,7 @@
     ]
   },
   "devDependencies": {
-    "@figma/code-connect": "^0.2.1",
+    "@figma/code-connect": "^1.0.1",
     "@react-aria/accordion": "^3.0.0-alpha.28",
     "@react-aria/focus": "^3.17.0",
     "@react-aria/interactions": "^3.21.2",

scripts/component-metadata/README.md

@@ -1,9 +1,3 @@
-# SDS Component Metadata console scripts
+# SDS Component Metadata (JS Console)
 
-This is use to manage descriptions for all components in the file. Instead of making a complicated plugin, you can do this more simply by running scripts in the JavaScript console.
-
-Copy the text in `exportComponentJSON.js` and run in the console with the file open. It will yield a JavaScript object. You can "copy as object" and paste into `componentJSON.json`.
-
-There you can modify descriptions more easily. Once you have modified the descriptions, copy the JSON and paste at the top of `importComponentJSON.js` as the value of the `json` variable. Then copy the contents of the file and run in the console to batch update descriptions for the entire file.
-
-This will only update the descriptions. Dev Resources you must use the REST API integration.
+[Instructions](/README.md#scriptscomponent-metadata)

scripts/dev-resources/README.md

@@ -1,7 +1,3 @@
-# SDS Dev Resources updater
+# SDS Dev Resources (REST)
 
-This script goes through all components described in `devResourceUrls` and updates / sets their dev resources to match what is described there. It does not update, it only removes / adds when there is a discrepancy.
-
-The identifiers must match a key in `documentUrlSubstitutions` field in the `figma.config.json` file for Code Connect. This is how the integration determines which node id to update.
-
-You must have Dev Resource write scope enabled for your API token in `.env` in order for this to work.
+[Instructions](/README.md#scriptsdev-resources)

scripts/dev-resources/app.mjs

@@ -1,4 +1,5 @@
 import * as figmaJSON from "../../figma.config.json" with { type: "json" };
+import { devResources } from "./devResources.mjs";
 
 // run with node --env-file=.env app.mjs
 const TOKEN = process.env.FIGMA_ACCESS_TOKEN;
@@ -8,22 +9,8 @@ const FILE_KEY = "J0KLPKXiONDRssXD1AX9Oi";
 
 const figmaUrls = figmaJSON.default.codeConnect.documentUrlSubstitutions;
 
-const STORYBOOK_URL =
-  "https://studious-happiness-n8g71ww.pages.github.io/storybook/?path=/story/";
-
-// prettier-ignore
-const devResourceUrls = {
-  "<FIGMA_ACCORDION_ACCORDION>": [{ name: "Storybook", url: `${STORYBOOK_URL}sds-primitives-accordion--accordion-story` }],
-  "<FIGMA_ACCORDION_ACCORDION_ITEM>": [{ name: "Storybook", url: `${STORYBOOK_URL}sds-primitives-accordion--accordion-item-story` }],
-  "<FIGMA_CARD_PRODUCT_INFO_CARD>": [{ name: "Storybook", url: `${STORYBOOK_URL}sds-compositions-cards--block-product-info-card` }],
-  "<FIGMA_CARD_PRICING_CARD>": [{ name: "Storybook", url: `${STORYBOOK_URL}sds-compositions-cards--block-pricing-card` }],
-  "<FIGMA_CARD_TESTIMONIAL_CARD>": [{ name: "Storybook", url: `${STORYBOOK_URL}sds-compositions-cards--block-testimonial-card` }],
-  "<FIGMA_CARD_STATS_CARD>": [{ name: "Storybook", url: `${STORYBOOK_URL}sds-compositions-cards--block-stats-card` }],
-  "<FIGMA_CARD_REVIEW_CARD>": [{ name: "Storybook", url: `${STORYBOOK_URL}sds-compositions-cards--block-review-card` }],
-};
-
 const urlKeyToNodeId = {};
-for (let key in devResourceUrls) {
+for (let key in devResources) {
   if (figmaUrls[key] && figmaUrls[key].includes(FILE_KEY)) {
     urlKeyToNodeId[key] = new URLSearchParams(figmaUrls[key].split("?")[1])
       .get("node-id")
@@ -46,8 +33,8 @@ async function run() {
   let deleteCount = 0;
   let createCount = 0;
   let possibleCreateCount = 0;
-  for (let key in devResourceUrls) {
-    const resources = devResourceUrls[key].reduce((into, resource) => {
+  for (let key in devResources) {
+    const resources = devResources[key].reduce((into, resource) => {
       possibleCreateCount++;
       into[resource.url] = {
         ...resource,

scripts/dev-resources/devResources.mjs

@@ -0,0 +1,13 @@
+const STORYBOOK_URL =
+  "https://studious-happiness-n8g71ww.pages.github.io/storybook/?path=/story/";
+
+// prettier-ignore
+export const devResources = {
+  "<FIGMA_ACCORDION_ACCORDION>": [{ name: "Storybook", url: `${STORYBOOK_URL}sds-primitives-accordion--accordion-story` }],
+  "<FIGMA_ACCORDION_ACCORDION_ITEM>": [{ name: "Storybook", url: `${STORYBOOK_URL}sds-primitives-accordion--accordion-item-story` }],
+  "<FIGMA_CARD_PRODUCT_INFO_CARD>": [{ name: "Storybook", url: `${STORYBOOK_URL}sds-compositions-cards--block-product-info-card` }],
+  "<FIGMA_CARD_PRICING_CARD>": [{ name: "Storybook", url: `${STORYBOOK_URL}sds-compositions-cards--block-pricing-card` }],
+  "<FIGMA_CARD_TESTIMONIAL_CARD>": [{ name: "Storybook", url: `${STORYBOOK_URL}sds-compositions-cards--block-testimonial-card` }],
+  "<FIGMA_CARD_STATS_CARD>": [{ name: "Storybook", url: `${STORYBOOK_URL}sds-compositions-cards--block-stats-card` }],
+  "<FIGMA_CARD_REVIEW_CARD>": [{ name: "Storybook", url: `${STORYBOOK_URL}sds-compositions-cards--block-review-card` }],
+};

scripts/icons/README.md

@@ -1,3 +1,3 @@
-# SDS Icon Generator
+# SDS Icon Generator (REST or Plugin)
 
-This script goes to a file, finds a page, pulls out all the icons on that page and creates an index file, React component, and Figma Code Connect doc for each icon.
+[Instructions](/README.md#scriptsicons)