DOCSEARCHbyAlgolia
Submit Docs

Cobalt UI

website·Indexed 30 days ago

https://cobalt-ui.pages.dev

A tool that transforms Design Tokens Community Group (DTCG) format tokens into code via a CLI or Node.js API. It supports various integrations including CSS, Sass, Tailwind CSS, JavaScript, TypeScript, and Figma, and provides features for token linting, mode management, and custom plugin development.

Tokens
17.2K
Snippets
104
Records
143
Agent score
72%

What's inside Cobalt

  1. Overview of Cobalt and its goals

    Cobalt is a tool created to support the Design Tokens Community Group (DTCG) format. It provides a pluggable and extensible interface designed to generate code for any platform. Its primary goals are to fully support the DTCG format specification, ensure wide compatibility across platforms, and maintain a configurable architecture that allows users to develop custom plugins for specific output formats.

  2. Use DTCG format for design tokens in Cobalt UI

    Cobalt UI supports the DTCG (Design Tokens Community Group) format. Using this universal design token standard ensures the widest compatibility across different tools and prevents vendor lock-in.

  3. Install and configure the A11y linting plugin

    The @cobalt-ui/lint-a11y plugin allows you to lint your token schema for accessibility errors, specifically checking color and typography tokens for contrast compliance.
    npm i -D @cobalt-ui/lint-a11y
    // tokens.config.js
import a11y from "@cobalt-ui/lint-a11y";

/** @type {import("@cobalt-ui/core").Config} */
export default {
  tokens: "./tokens.json",
  outDir: "./tokens/",
  plugins: [a11y()],
  lint: {
    // checks
  },
};

  4. Apply number tokens to Typography and Gradients

    While number tokens lack units, they are specifically used in the following contexts:

    1. Typography: Used for lineHeight within a typography token, where the number serves as a shorthand for the em dimension.
    2. Gradients: Used to define color stops within a gradient token.

  5. Install the Cobalt CLI

    Install the Cobalt CLI as a development dependency in your project to begin transforming Design Token Community Group (DTCG) design tokens into code.
    npm i -D @cobalt-ui/cli

  6. Recommendations for color management in Cobalt UI

    When working with colors and gradients in Cobalt UI:

    1. Use OKLCH: Prefer the OKLCH color format over sRGB or hex. It is a future-proof standard that is more perceptually even and allows for better color manipulation.
    2. Use Culori: The Culori library is the preferred tool for parsing, generating, and manipulating colors due to its accuracy, speed, and support for tree-shaking.

  7. Configure WCAG2 color contrast checks with @cobalt-ui/lint-a11y

    Use the @cobalt-ui/lint-a11y plugin to run WCAG2 contrast checks on specific token pairs across different modes (e.g., light and dark).
    npm i -D @cobalt-ui/lint-a11y
    import a11y from "@cobalt-ui/lint-a11y";

/** @type {import("@cobalt-ui/core").Config} */
export default {
  plugins: [a11y()],
  lint: {
    rules: {
      "a11y/contrast": [
        "error",
        {
          checks: [
            {
              tokens: {
                foreground: "color.semantic.text",
                background: "color.semantic.bg",
                typography: "typography.body",
                modes: ["light", "dark"],
              },
              wcag2: "AAA",
            },
          ],
        },
      ],
    },
  },
};

  8. Create a custom Cobalt plugin

    A Cobalt plugin is a function that returns an object conforming to the Plugin interface. It allows developers to hook into the token processing lifecycle to modify configuration, lint tokens, or generate build output. Plugins are similar in design to Rollup or Vite plugins.
    import type { Plugin } from "@cobalt-ui/core";

export default function myPlugin(): Plugin {
  return {
    name: "my-plugin",
    config(config) {
      // read final user config
    },
    async build({ tokens, metadata, rawSchema }) {
      // plugin logic here
      return [
        {
          filename: "my-filename.json",
          contents: tokens,
        },
      ];
    },
  };
}

  9. Install and set up the Cobalt CSS plugin

    The @cobalt-ui/plugin-css plugin generates CSS variables from DTCG tokens for dynamic theming. It requires the Cobalt CLI to be installed.
    npm i -D @cobalt-ui/plugin-css
    // tokens.config.mjs
import pluginCSS from "@cobalt-ui/plugin-css"; 

/** @type {import("@cobalt-ui/core").Config} */
export default {
  tokens: "./tokens.json",
  outDir: "./tokens/",
  plugins: [pluginCSS()], 
};
    # Build the tokens
npx co build

  10. Determine when to use token modes

    Modes should be used for variations that are mutually exclusive (never used together on the same page).

    Recommended use cases (Do):

    • User preferences (text size, reduced motion, colorblind mode)
    • Device types (mobile vs. desktop)
    • Region or language
    • Product areas (marketing site vs. dashboard UI)

    Avoid using modes for (Don't):

    • Semantic colors (e.g., success, error)
    • Localized states (e.g., disabled, active)
    • Color shades or hues
    • Specific components (e.g., card, button)

  11. Install and configure @cobalt-ui/plugin-js

    The @cobalt-ui/plugin-js plugin generates JavaScript files with TypeScript declarations from DTCG tokens. It produces a .js file with accompanying .d.ts files, making it compatible with both JS and TS projects without additional configuration.
    npm i -D @cobalt-ui/plugin-js
    // tokens.config.mjs
import pluginJS from "@cobalt-ui/plugin-js"; 

/** @type {import("@cobalt-ui/core").Config} */
export default {
  tokens: "./tokens.json",
  outDir: "./tokens/",
  plugins: [
    pluginJS({
      js: true, // output JS (with TS types)? boolean or filename (default: true)
    }),
  ],
};
    # Build the tokens
npx co build

  12. Control utility class naming with token selectors

    The utility class name is derived from the token ID minus the matched selector. The last segment of the token ID is always preserved. For a token color.semantic.primary:

    • Selector ["color.semantic.primary"] $ ightarrow$ .bg-primary
    • Selector ["color.semantic.*"] $ ightarrow$ .bg-primary
    • Selector ["color.*"] $ ightarrow$ .bg-semantic-primary
    • Selector ["*"] $ ightarrow$ .bg-color-semantic-primary