@thatch-health/slab-tokens 0.0.0

package/README.md

@@ -0,0 +1,91 @@
+# Slab Tokens
+
+This package is the pipeline for importing Figma tokens defined in [Token Foundations](https://www.figma.com/design/AMVtHovyyMCo78skFvePV4/Token-Foundations?node-id=32-93&p=f&t=fLz0IYz5irefoKsl-11) and then outputing in appropriate formats for web, the marketing website, and slab design system itself. This package uses [Terrazzo](https://terrazzo.app/) to manage the conversion from the [Design Token Community Group](https://www.designtokens.org/) specification which is a universal token specification. The package itself exports a few endpoints for consumers to use:
+
+- `@thatch-health/slab-tokens/tokens-raw` - The raw JSON values of the DTCG specification downloaded from Figma
+- `@thatch-health/slab-tokens/css` - The output from terrazzo using the css plugin
+- `@thatch-health/slab-tokens/tailwind-v3-plugin` - A plugin for tailwind v3 that maps css variables
+
+## Development
+
+- Install dependencies:
+
+```bash
+vp install
+```
+
+- Build the library:
+
+```bash
+vp pack
+```
+
+## Figma Conversion
+
+While Figma does export tokens in a DTCG format it does not do appropriate unit conversions for tokens like using rem and px for certain spacing tokens. The way the conversion works is looking at the tokens `$.extensions.['com.figma.scopes']` value in order to see what the usages are. Rather than always using rem units, we map tokens to [the appropriate unit based on the use case](https://www.joshwcomeau.com/css/surprising-truth-about-pixels-and-accessibility/). Token mappings are as follows:
+
+| Figma Scope   | Unit type |
+| ------------- | --------- |
+| CORNER_RADIUS | px        |
+| GAP           | px        |
+| STROKE_FLOAT  | px        |
+| WIDTH_HEIGHT  | rem       |
+
+All color tokens use the srgb color space
+
+Typography tokens need to be merged into [a typography DTCG $type](https://www.designtokens.org/tr/drafts/format/#typography). This can be done by collapsing typography types from `type.tokens.json` where the structure is `Display.Large.Size` to `display.large` with the following mapping of units:
+
+| Figma Scope    | Unit type | DTCG type     |
+| -------------- | --------- | ------------- |
+| FONT_SIZE      | rem       | fontSize      |
+| FONT_FAMILY    | string    | fontFamily    |
+| FONT_STYLE     | number    | fontWeight    |
+| LINE_HEIGHT    | number    | lineHeight    |
+| LETTER_SPACING | rem       | letterSpacing |
+
+**Note**: In Figma, variable line height is represented in figma as a pixel unit, therefore, line height is converted to a percentage value of the typeography style's font size.
+
+### Importing tokens from Figma
+
+Importing tokens from Figma is currently a manual process. In order to import tokens, you need to right click each collection and press export. Tokens are then placed into this file structure:
+
+```
+tokens-raw-import/
+├── color/
+│   └── [mode].tokens.json
+├── color-core.tokens.json
+├── color-primitives.tokens.json
+├── spacing.tokens.json
+├── spacing-primitives.tokens.json
+├── type.tokens.json
+└── type-primitives/
+    └── [mode].tokens.json
+```
+
+When extracting tokens, you will have to format the tokens as they're exported which means that files will be downloaded as the collection name and then you'll need to rename the extracted json file to match the token name.
+
+#### Collection with only one mode
+
+1. Download file from figma by right clicking and selecting "Export modes"
+2. Unzip directory
+3. Rename the extracted file, `default.tokens.json`, to `[collection name in kebab case].tokens.json`
+
+#### Collection with many modes
+
+1. Download file from figma by right clicking and selecting "Export modes"
+2. Unzip directory
+3. Rename the directory file to kebab case, all files nested should already be in the correct format.
+
+## Further reading
+
+### Our docs
+
+- [About this package](https://www.notion.so/thatchhealth/DS-Code-Structure-Proposal-342114874bc280c1bba6c2c184b8e83b?source=copy_link#343114874bc280f4b87cc67208911bf1)
+- [About our color tokens](https://www.notion.so/thatchhealth/Color-Tokens-33e114874bc280e88ecbee9c28cb60af)
+- [The strategy in our tokens](https://www.notion.so/thatchhealth/Proposed-Token-Changes-32d114874bc280e08f6feb3b32326a29)
+
+### External docs
+
+- [Mode.place](https://mode.place/)
+- [What are design tokens](https://www.youtube.com/watch?v=q5qIowMyVt8)
+- [DTCG](https://www.designtokens.org/)