Skip to content

Commit

Permalink
Standardize on “Design Tokens Format Module” (DTFM) naming
Browse files Browse the repository at this point in the history
  • Loading branch information
@drwpow
drwpow committed Oct 23, 2023
1 parent c8fd570 commit 61d63c7
Show file tree
Hide file tree
Showing 26 changed files with 71 additions and 59 deletions.
2 changes: 1 addition & 1 deletion README.md
View file
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
# Cobalt

Design token tooling compatible with the [W3C Design Tokens specification](https://design-tokens.github.io/community-group/format/). Cobalt can:
Design token tooling compatible with the [Design Tokens Format Module](https://design-tokens.github.io/community-group/format/). Cobalt can:

- Parse and validate any valid `tokens.json` file
- Generate Sass, CSS, TypeScript, and more from `tokens.json`
Expand Down
2 changes: 1 addition & 1 deletion docs/src/components/Head.astro
View file
Original file line number Diff line number Diff line change
Expand Up @@ -10,4 +10,4 @@ const {title = 'Cobalt design tokens'} = Astro.props;
<link rel="apple-touch-icon" type="image/png" sizes="128x128" href="/favicon-128.png" />
<link rel="apple-touch-icon" type="image/png" sizes="512x512" href="/favicon-512.png" />
<title>{title}</title>
<meta type="description" content="Cobalt is open-source tooling for the W3C Design Tokens community spec. Load your design tokens in any website or app using code. Support light and dark mode easily." />
<meta type="description" content="Cobalt is open-source tooling for the Design Tokens Format Module. Load your design tokens in any website or app using code. Support light and dark mode easily." />
8 changes: 7 additions & 1 deletion docs/src/pages/docs/getting-started/index.astro
View file
Original file line number Diff line number Diff line change
Expand Up @@ -41,7 +41,13 @@ const title = 'Getting Started';
Converting your tokens to JSON is a manual process of grabbing values from your design files and formatting the JSON yourself. There’s not a great UI for this yet, but <strong>the Cobalt team is developing one currently</strong>.
</p>

<aside class="callout"><p>✨ Cobalt can now convert some Style Dictionary files into the W3C format (<a href="/docs/guides/style-dictionary">docs</a>)</p></aside>
<aside class="callout">
<p>
✨ Cobalt can now convert some Style Dictionary files into the <a href="https://design-tokens.github.io/community-group/format/" target="_blank" rel="noopener noreferrer">Design Tokens Format Module</a> format (<a
href="/docs/guides/style-dictionary">docs</a
>)
</p>
</aside>

<p>Save these all to a <code>tokens.json</code> file (or <code>tokens.yaml</code>, if you prefer YAML) like so:</p>

Expand Down
4 changes: 2 additions & 2 deletions docs/src/pages/docs/guides/design-tokens.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -36,10 +36,10 @@ Though there is <a href="https://designtokens.org" target="_blank" rel="noopener
allowfullscreen></iframe>
</div>

Cobalt uses this new W3C community standard in the hopes that it will become a common/universal way of expressing design tokens. To get started, you can view either:
Cobalt uses the <a href="https://designtokens.org" target="_blank" rel="noopener noreferrer">Design Tokens Format Module</a> standard in the hopes that it will become a common/universal way of expressing design tokens. To get started, you can view either:

- [Cobalt’s guide to writing tokens](/docs/tokens), or
- [The W3C Design Tokens specification itself](https://design-tokens.github.io/community-group/format/)
- [Design Token Format Module spec](https://design-tokens.github.io/community-group/format/)

Other competing formats include, but aren’t limited to:

Expand Down
8 changes: 4 additions & 4 deletions docs/src/pages/docs/integrations/custom-plugins.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -9,14 +9,14 @@ Creating your own Cobalt plugins is easy if you’re comfortable with JavaScript

## Why use Cobalt?

Cobalt was created to deal with the following difficulties of the W3C Design Tokens spec:
Cobalt was created to deal with the following difficulties of the Design Tokens Format Module (DTFM) spec:

1. **Validation**: Cobalt errs on schema violations
2. **Normalization**: The W3C Design Tokens spec allows for much flexibility, which means many unexpected values
2. **Normalization**: The DTFM spec allows for much flexibility, which means many unexpected values
3. **Aliasing**: Cobalt resolves aliases (including _aliases of aliases of aliases!_) for you
4. **Traversal**: A deeply-nested object is converted into a flat array for easy iteration
5. **Modes** Cobalt extends the design tokens format with powerful [modes](/docs/tokens#modes)
6. **Figma syncing** Update your design tokens with Figma easily
5. **Modes** Cobalt extends the DTFM with powerful [modes](/docs/tokens#modes)
6. **Figma syncing** Update your DTFM tokens with Figma easily

## Basic structure

Expand Down
12 changes: 6 additions & 6 deletions docs/src/pages/docs/integrations/style-dictionary.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -5,7 +5,7 @@ layout: ../../../layouts/docs.astro

# Style Dictionary

You can migrate your <a href="https://amzn.github.io/style-dictionary" target="_blank" rel="noopener noreferrer">Style Dictionary</a> tokens to the W3C format by running the following command (granted you have [the CLI installed](/docs/reference/cli)):
You can migrate your <a href="https://amzn.github.io/style-dictionary" target="_blank" rel="noopener noreferrer">Style Dictionary</a> tokens to the Design Tokens Format Module (DTFM) standard by running the following command (granted you have [the CLI installed](/docs/reference/cli)):

```bash
npx co convert style-dictionary-tokens.json --out tokens.json
Expand All @@ -14,16 +14,16 @@ npx co convert style-dictionary-tokens.json --out tokens.json
<div class="callout" role="note">

⚠️ **Warning**
This is **NOT** meant to be a comprehensive conversion. The W3C format is not 1:1 compatible with Style Dictionary. This will not import your transformations, and it will probably make mistakes, and miss tokens. This is only meant for **migrating** to the W3C format permanently, and is meant to save you some work by giving you a starting point you’ll have to clean up afterward.
This is **NOT** meant to be a comprehensive conversion. The DTFM standard is not 1:1 compatible with Style Dictionary. This will not import your transformations, and it will probably make mistakes, and miss tokens. This is only meant for **migrating** to the DTFM standard permanently, and is meant to save you some work by giving you a starting point you’ll have to clean up afterward.

After running `npx co convert` it’s not recommended to keep using the Style Dictionary format.

</div>

## Why convert to W3C Design Tokens?
## Why convert to DTFM?

While Style Dictionary is a powerful and flexible tool, it also requires more configuration and maintenance than the W3C Design Token format does. For example, Style Dictionary requires you place all your colors underneath a top-level `color` group. If you want to reference colors elsewhere, you’ll have to configure all your transformers to look for them. The same applies for `size` and `time` tokens.
While Style Dictionary is a powerful and flexible tool, it also requires more configuration and maintenance than the Design Tokens Format Module does. For example, Style Dictionary requires you place all your colors underneath a top-level `color` group. If you want to reference colors elsewhere, you’ll have to configure all your transformers to look for them. The same applies for `size` and `time` tokens.

Further, Style Dictionary is missing more advanced features like `gradient`, `typography`, and `shadow` tokens from the W3C spec, to name a few.
Further, Style Dictionary is missing more advanced features like `gradient`, `typography`, and `shadow` tokens from the DTFM spec, to name a few.

While Style Dictionary was a significant trailblazer in managing design tokens and was the first mature library to accomplish this elegantly, the W3C spec is being actively designed to make up for Style Dictionary’s shortcomings. The new W3C spec is arguably more influenced by Style Dictionary than any other tool, and takes into account Style Dictionary’s way of doing things. W3C is meant to replace the Style Dictionary format eventually.
While Style Dictionary was a significant trailblazer in managing design tokens and was the first mature library to accomplish this elegantly, the DTFM spec is being actively designed to make up for Style Dictionary’s shortcomings. The new DTFM spec is arguably more influenced by Style Dictionary than any other tool, and takes into account Style Dictionary’s way of doing things. DTFM is meant to replace the Style Dictionary format eventually.
2 changes: 1 addition & 1 deletion docs/src/pages/docs/integrations/tailwind.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -5,7 +5,7 @@ layout: ../../../layouts/docs.astro

# Tailwind

Cobalt’s Tailwind plugin lets you use your W3C Design Token Community Group tokens seamlessly in any Tailwind project by building your own custom [preset](https://tailwindcss.com/docs/presets). To start, install the Tailwind plugin and CLI:
Cobalt’s Tailwind plugin lets you use your [Design Tokens Format Module](https://designtokens.org) tokens seamlessly in any Tailwind project by building your own custom [preset](https://tailwindcss.com/docs/presets). To start, install the Tailwind plugin and CLI:

```bash
npm install -D @cobalut-ui/plugin-tailwind @cobalt-ui/cli
Expand Down
34 changes: 17 additions & 17 deletions docs/src/pages/docs/integrations/tokens-studio.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -7,7 +7,7 @@ layout: ../../../layouts/docs.astro

![Tokens Studio for Figma](/images/tokens-studio-for-figma.png)

[Tokens Studio for Figma](https://tokens.studio/) is a free plugin that makes managing design tokens in Figma easy ([docs](https://docs.tokens.studio/)). While it doesn’t use the W3C Design Tokens format like Cobalt does, Cobalt supports most of Tokens Studio’s format.
[Tokens Studio for Figma](https://tokens.studio/) is a free plugin that makes managing design tokens in Figma easy ([docs](https://docs.tokens.studio/)). While it doesn’t use the [Design Tokens Format Module](https://designtokens.org) (DTFM) like Cobalt does, Cobalt supports most of Tokens Studio’s format.

To use Tokens Studio, first export a `tokens.json` file using [any of the approved sync methods](https://docs.tokens.studio/sync/sync). Then use Cobalt as you would normally:

Expand All @@ -24,21 +24,21 @@ export default {

## Compatibility

| Token Studio Token | Supported | Notes |
| :-------------------------------------------------------------------------------- | :-------: | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| [Sizing](https://docs.tokens.studio/available-tokens/sizing-tokens) | ✅ | Converted to [Dimension](/docs/tokens/#dimension). |
| [Spacing](https://docs.tokens.studio/available-tokens/spacing-tokens) | ✅ | Converted to [Dimension](/docs/tokens/#dimension). |
| [Color](https://docs.tokens.studio/available-tokens/color-tokens) | ✅ | Flat colors are kept as [Color](/docs/tokens/#color) while gradients are converted to [Gradient](/docs/tokens/#gradient). Modifiers aren’t supported. |
| [Border radius](https://docs.tokens.studio/available-tokens/border-radius-tokens) | ✅ | Converted to [Dimension](/docs/tokens/#dimension). Multiple values are expanded into 4 tokens (`*TopLeft`, `*TopRight`, `*BottomLeft`, `*BottomRight`). |
| [Border width](https://docs.tokens.studio/available-tokens/border-width-tokens) | ✅ | Converted to [Dimension](/docs/tokens/#dimension). |
| [Shadow](https://docs.tokens.studio/available-tokens/shadow-tokens) | ✅ | Basically equivalent to [Shadow](/docs/tokens/#shadow). |
| [Opacity](https://docs.tokens.studio/available-tokens/opacity-tokens) | ✅ | Converted to [Number](/docs/tokens/#number) |
| [Typography](https://docs.tokens.studio/available-tokens/typography-tokens) | ✅ | Basically equivalent to [Typography](/docs/tokens/#typography). **Text decoration** and **Text Case** must be flattened as there is no W3C Design Token spec equivalent. |
| [Asset](https://docs.tokens.studio/available-tokens/asset-tokens) | ❌ | TODO. Cobalt supports [Link](/docs/tokens/#link), which should be an equivalent. |
| [Composition](https://docs.tokens.studio/available-tokens/composition-tokens) | ❌ | Unsupported because this is a paid feature. |
| [Dimension](https://docs.tokens.studio/available-tokens/dimension-tokens) | ✅ | Direct equivalent to [Dimension](/docs/tokens/#dimension). |
| [Border](https://docs.tokens.studio/available-tokens/border-tokens) | ✅ | Direct equivalent to [Border](/docs/tokens/#border). |

Note that **Duration** and **Cubic Bezier** aren’t supported by Tokens Studio (because Figma currently doesn’t support animations). So to use those types you’ll need to convert your tokens into the W3C Design Token format.
| Token Studio Token | Supported | Notes |
| :-------------------------------------------------------------------------------- | :-------: | :----------------------------------------------------------------------------------------------------------------------------------------------------------- |
| [Sizing](https://docs.tokens.studio/available-tokens/sizing-tokens) | ✅ | Converted to [Dimension](/docs/tokens/#dimension). |
| [Spacing](https://docs.tokens.studio/available-tokens/spacing-tokens) | ✅ | Converted to [Dimension](/docs/tokens/#dimension). |
| [Color](https://docs.tokens.studio/available-tokens/color-tokens) | ✅ | Flat colors are kept as [Color](/docs/tokens/#color) while gradients are converted to [Gradient](/docs/tokens/#gradient). Modifiers aren’t supported. |
| [Border radius](https://docs.tokens.studio/available-tokens/border-radius-tokens) | ✅ | Converted to [Dimension](/docs/tokens/#dimension). Multiple values are expanded into 4 tokens (`*TopLeft`, `*TopRight`, `*BottomLeft`, `*BottomRight`). |
| [Border width](https://docs.tokens.studio/available-tokens/border-width-tokens) | ✅ | Converted to [Dimension](/docs/tokens/#dimension). |
| [Shadow](https://docs.tokens.studio/available-tokens/shadow-tokens) | ✅ | Basically equivalent to [Shadow](/docs/tokens/#shadow). |
| [Opacity](https://docs.tokens.studio/available-tokens/opacity-tokens) | ✅ | Converted to [Number](/docs/tokens/#number) |
| [Typography](https://docs.tokens.studio/available-tokens/typography-tokens) | ✅ | Basically equivalent to [Typography](/docs/tokens/#typography). **Text decoration** and **Text Case** must be flattened as there is no DTFM spec equivalent. |
| [Asset](https://docs.tokens.studio/available-tokens/asset-tokens) | ❌ | TODO. Cobalt supports [Link](/docs/tokens/#link), which should be an equivalent. |
| [Composition](https://docs.tokens.studio/available-tokens/composition-tokens) | ❌ | Unsupported because this is a paid feature. |
| [Dimension](https://docs.tokens.studio/available-tokens/dimension-tokens) | ✅ | Direct equivalent to [Dimension](/docs/tokens/#dimension). |
| [Border](https://docs.tokens.studio/available-tokens/border-tokens) | ✅ | Direct equivalent to [Border](/docs/tokens/#border). |

Note that **Duration** and **Cubic Bezier** aren’t supported by Tokens Studio (because Figma currently doesn’t support animations). So to use those types you’ll need to convert your tokens into DTFM.

Though Cobalt preserves your [Token Sets](https://docs.tokens.studio/themes/token-sets), which means most aliases will work, Token Studio’s [Advanced Themes](https://docs.tokens.studio/themes/themes-pro) is a paid feature and is therefore not supported. Though you could manually upconvert Token Studio themes to [modes](http://localhost:3000/docs/tokens/#modes).
4 changes: 2 additions & 2 deletions docs/src/pages/docs/reference/about.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -7,7 +7,7 @@ layout: ../../../layouts/docs.astro

## Project Goals

1. Support the complete and full [W3C Design Tokens CG spec](https://design-tokens.github.io/community-group/format)
1. Support the complete and full [Design Tokens Format Module](https://design-tokens.github.io/community-group/format) spec
2. Support a pluggable and configurable architecture, enabling users and the community to write their own plugins to generate any format
3. Make syncing from Figma easy and automatable ([docs](/docs/integrations/tokens-studio))

Expand All @@ -16,7 +16,7 @@ layout: ../../../layouts/docs.astro
The name **Cobalt** has three meanings:

1. Cobalt [the element](https://en.wikipedia.org/wiki/Cobalt) is a nod to design tokens being the “atoms” of your design system<br />
_Fun fact: the crystalline structure of Cobalt is hexagonal_
_Fun fact: the animated token icons on this docs site are a nod to Cobalt’s hexagonal atomic structure_
2. Cobalt [the pigment](https://artsartistsartwork.com/history-of-the-colour-blue-in-art/) is a nod to blue being the last missing color in art history, just as design tokens are the last missing piece of design systems<br />
_Fun fact: Van Gogh once said “Cobalt is a divine colour and there is nothing so beautiful for putting atmosphere around things”_
3. Cobalt the color is a nod to [blueprints](https://en.wikipedia.org/wiki/Blueprint)<br />
Expand Down
Loading

0 comments on commit 61d63c7

Please sign in to comment.