npm package: @planningcenter/doxy
Description: 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
Latest version: 1.2.0

# 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](https://planningcenter.github.io/doxy)
- [Contributing](./CONTRIBUTING.md)
- [Releasing package updates](https://www.notion.so/planningcenter/Releasing-NPM-Packages-3d31bf1bbc85441a9eeb638eee5dfba8)
- [Figma (alias tokens)](https://www.figma.com/design/DLPSeBe5Owfud0iSkfQOB2/Doxy-Component-Library?node-id=1-5&t=Uy5Hof4mzJECdiA2-1)
- [Figma (color primitive tokens)](https://www.figma.com/design/1OJnbnPFEbRpgzKN1q7Yxa/Doxy-Color-Primitives?m=auto&node-id=2482-0&t=9EiAIleJqyPsZ54n-1)

## Development scripts

```bash
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](./src/build-output/ts/tokens-by-theme-set.ts) — 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](./src/build-output/ts/themeable-web-gradient-tokens.ts) — 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.

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

#### Specific CSS tokens

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

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

#### Themeable web gradient tokens util

```TS
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.

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

#### Import specific React Native tokens & utils

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

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

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

### Forcing light or dark mode on a subtree

By default, tokens respond to the root-level color mode (`data-color-mode` or `data-color-scheme`). To force a specific mode on any element and its descendants, use the `data-doxy-color-mode` attribute:

```HTML
<!-- Force dark mode regardless of root color mode -->
<div data-doxy-color-mode="dark">
  <!-- All Doxy tokens here resolve to their dark values -->

  <!-- Force light mode back inside a dark section -->
  <div data-doxy-color-mode="light">
    <!-- Doxy tokens here resolve to their light values -->
  </div>
</div>
```

This is useful for UI that needs to render in a fixed color mode independent of the user's system theme or the application's global setting.

### For All applications

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

## What else?

Something confusing as you're getting started? Jump in [#doxy](https://pco.slack.com/archives/CBQ8JCABG) and ask away! We'll use those questions to help guide changes to this README. 🙂