Immutable, tokenized values defined in Figma by the UX Design Team, synced/managed with Specify.

Using Tokens

CSS Custom Properties:

Include this stylesheet in your CSS/SCSS manifest:

• @planningcenter/tapestry-design-tokens/dist/tokens.css
  • "Default tokens" are scoped to the document :root and values can be referenced regardless of color scheme.
  • Theme-specific tokens are based on their corresponding color theme ("light" or "dark") and are scoped to the data-color-scheme data attribute. Token names are consistent between both themes so referencing var(--tapestry-button-interaction-solid-default-bg) will update the element's background accordingly if/when the theme is switched to "dark".
  • In order for scoped token values to be globally-available and in the same context as the "default tokens", [data-color-scheme] should be added to the top-level HTML element, and not the body element.

Technical Considerations:

• Because of the way Specify classifies token modes, there are some duplicate CSS properties between the :root and data-color-scheme="light" scopes. Planning Center only currently supports "light mode" in our admin products so having duplicate selectors is creating redundancy in the CSS file, but this is an intentional trade-off to instill confidence that all token values from Specify are being included in the package.

• A CSS token defined in the :root scope that is also defined in the data-color-scheme selector will resolve to the more-specific definition in the data-color-scheme scope. Admittedly, this adds a some extra context to sort through, but hopefully this pattern will pay dividends if/when our products are prepared to support "dark mode".

Javascript:

import { tokens } from "@planningcenter/tapestry-design-tokens/dist/tokens"

• base-level tokens use "defaultMode"

  • const fontSize = tokens.["numeric.fontSize.textLg"].defaultMode

• theme-specific tokens, use either "light" or "dark"

  • const colorLight = tokens["color.product.groups.08"].light
  • const colorDark = tokens["color.product.groups.08"].dark

📚 Available tokens

• Documentation site
• Token manifest (automatically generated based on incoming tokens from Specify)

Adding New Tokens

1. New/updated tokens are created in Figma (design "source of truth") by UX
2. When synced to Specify, a PR will be created here
3. Once the "tokens" PR is merged to main, follow the steps below publish a new release

Publishing

1. Navigate to package.json on main and click the "Edit" button

2. Update the package version accordingly

• MAJOR version: breaking changes (primarily removing previously-defined design tokens)
• MINOR version: non-breaking changes (updating or adding design tokens)
• PATCH version: bug fixes or documentation updates

3. Click Commit changes... and create a new branch

• 1️⃣ commit message: update package version (vX.X.X)
• 2️⃣ branch name: release-vX.X.X
• 3️⃣ click Propose changes

4. Under "Code", choose your new branch and edit the CHANGELOG.md
5. Create a new Changelog entry, following the format specified in the "ENTRY TEMPLATE" comments (version info at the top + reference link at the bottom)
6. Click Commit changes... and choose "Commit directly to the release-vX.X.X branch
7. Under "Code > Branches", click the ••• beside your branch and choose New pull request

• PR title: package updates for vX.X.X
• PR description: provide any additional context for the version update or provide link back to the CHANGELOG.md

8. Merge PR with +1 and the Github actions will take care of publishing to NPM and updating the tokens documentation