Doxy

Doxy provides design tokens that can be shared between Church Center Web, Church Center App, and Publishing. These tokens hold atomic design decisions (eg. background color, font weight) from the Doxy Design System and ensure visual consistency across our Church Center applications.

Installation

yarn add @planningcenter/doxy

Links

• Storybook
• Contributing
• Releasing package updates
• Figma (alias tokens)
• Figma (color primitive tokens)

Development scripts

yarn build              # Generates both tokens and `/dist` directory
yarn build:rollup       # Generates dist directory
yarn build:tokens       # Generates tokens from Style Dictionary in a `/build-output` directory
yarn build:tokens:nuke  # Deletes `/build-output` and generates tokens
yarn storybook          # Starts Storybook at http://localhost:6006
yarn lint               # Checks eslint and prettier
yarn format             # Fixes any prettier issues
yarn test               # Runs vitest once
yarn test:watch         # Runs vitest continually

Alias vs Primitive Tokens

Our Figma files and Style Dictionary pipeline expects two types of tokens; primitive and alias.

• Primitive tokens represent hard-coded style values and create the underlying foundation for the alias tokens. Applications and Figma mockups don't reference primitive tokens directly.
• Alias tokens provide a way to communicate semantic meaning about a CSS value. They might reference other alias tokens or directly reference a primitive token. For colors they support both light and dark modes.

Here are some reasons one or both token types might require their JSON to be updated in src/json/…

• Token's name or value changed
• Token's deprecation status changed
• Token(s) get added or deleted
• Token(s) moves between collections (eg. From "color themeable" to "color")

Themeable Tokens

Doxy's design system includes color values that the church can customize based on its selected theme in Publishing. To reduce complexity and keep the generated token code 1-1 with Figma, the applications consuming tokens are responsible for overriding their values with the theme.

Doxy tokens helps to support this feature by providing the following utilities to applications that act as manifests of which tokens are themeable and what value to use when overriding them.

1. tokensByThemeSet — This object contains any available "themes" as keys and assigns them an array of token names that should be overriden by that theme's value.
2. themeableWebGradientTokens — This object contains themeable gradient tokens with their light and dark mode values, making it easier to override linear-gradient values.

Importing Doxy tokens into applications

All tokens and utilities can be imported via @planningcenter/doxy, but common files and directories are also available via subpath imports. This is to help filter out conflicting or otherwise unnecessary assets. (eg. Avoiding CSS files within a React Native app.)

For Web applications

All CSS tokens

For most cases, this is the import to use on the web as it manages all available tokens.

@import "@planningcenter/doxy/tokens.css";

Specific CSS tokens

@import "@planningcenter/doxy/tokens-dark.css";

@import "@planningcenter/doxy/tokens-deprecated.css";

Themeable web gradient tokens util

import {} from "@planningcenter/doxy/themeable-web-gradient-tokens"

For React Native applications

All tokens and utils

React Native applications like CCA should use this import because they can't process .css files.

import {} from "@planningcenter/doxy/ts"

Import specific React Native tokens & utils

import {} from "@planningcenter/doxy/types/react-native-types"

import {} from "@planningcenter/doxy/react-native-tokens-dark"

import {} from "@planningcenter/doxy/react-native-tokens-light"

For All applications

import {} from "@planningcenter/doxy/tokens-by-theme-set"

What else?

Something confusing as you're getting started? Jump in #doxy and ask away! We'll use those questions to help guide changes to this README. 🙂