/choosing-charcoal-styling

name: choosing-charcoal-styling
description: Use before writing or editing any code that imports @charcoal-ui, and whenever a project's charcoal setup is unverified or incomplete. Decides between the CSS variables, Tailwind and styled-components routes, and names the setup steps that are silently missing in most projects.

Choosing a charcoal styling approach

`@charcoal-ui` is pixiv's design system. It ships tokens once and lets you consume them three different ways. Picking the wrong one — or picking right but skipping the opt-in — is the main source of failure.

The official docs are not readable by agents

Do not try to look this up on the web first.

• `https://charcoal-web.pixiv.design/` is a Storybook SPA. Fetching it returns a title and no content.
• The npm package pages return 403.
• `pages/` in the GitHub repo is a docsify site last updated 2023-03-22. It predates v4 and v6. **Its instructions are wrong** — it tells you `@charcoal-ui/react` needs a styled-components `ThemeProvider`, which stopped being true in v4.

Trust this skill and the package contents (`node_modules/@charcoal-ui/*`, or jsDelivr/unpkg) over search results.

Three layers, one choice

| Layer | What it is | Packages | Your choice? | | ------------- | --------------------------------- | ------------------------------------------------------------------- | ------------------------------ | | Constants | Design tokens | `@charcoal-ui/foundation`, `@charcoal-ui/theme` | No — everyone uses these | | **Utilities** | Turning tokens into CSS you write | `@charcoal-ui/tailwind-config`, `@charcoal-ui/styled`, or plain CSS | **Yes — here only** | | Components | Prebuilt UI (Button, Modal…) | `@charcoal-ui/react` | No — plain CSS, no alternative |

Two things people confuse:

• **"styled → pure CSS"** describes the _component layer's internals_. v4 removed styled-components from `@charcoal-ui/react`. You get no say in it.
• **"styled vs Tailwind"** is the _utility layer_ choice — how you style your own markup.

Using `@charcoal-ui/react` does not require styled-components or Tailwind. They are unrelated decisions.

Pick the utility

Do you use @charcoal-ui/react components?
  → Yes: install it and load the token CSS. No styling library needed.
  → Either way, continue below for your own markup.

How do you want to style your own markup?
  ├─ Tailwind already in the project  → setting-up-charcoal-tailwind
  ├─ Large existing styled-components codebase → setting-up-charcoal-styled
  └─ Anything else (plain CSS, CSS Modules, vanilla-extract)
                                       → setting-up-charcoal-css-variables

Default to `setting-up-charcoal-css-variables`. It has no extra dependency and works with any stack.

Design Token 2.0 is opt-in, and the default is silent

This is the single most common failure. Every route has an opt-in flag, and every route silently gives you the old generation — or nothing at all — if you skip it.

| Route | Opt-in | Skip it and you get | | ----------------- | -------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------ | | CSS variables | Load `@charcoal-ui/theme/css/v2/{light,dark}.css` **and** put `class="ch-token-v2"` on `<html>` or an ancestor | **No tokens at all** — components render with no color | | Tailwind | `unstableTokenV2: true` **plus** the same two steps above | Design Token 1.0 | | styled-components | not available | Design Token 1.0 only — the package has no v2 support |

No error, no warning. The page just looks wrong.

`.ch-token-v2` is not a CSS-variables-route detail. It gates the v2 variables themselves, so **every route that wants Design Token 2.0 needs it** — the Tailwind preset emits `var(--charcoal-color-*)` references but never defines them.

Is @charcoal-ui/styled deprecated?

Not formally — only `createTheme` carries `@deprecated`. But the package has **no Design Token 2.0 support** and receives no new features, while `@charcoal-ui/tailwind-config` keeps getting them. Treat it as a dead end you migrate off, not as a forbidden API.

Packages that _are_ formally deprecated: `@charcoal-ui/react-sandbox` (removal planned) and `@charcoal-ui/tailwind-diff` (announced as 廃止予定).

Common mistakes

| Mistake | Reality | | --------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------- | | Loading only `@charcoal-ui/react/dist/index.css` | That file uses `var(--charcoal-color-*)` but never defines them. You must also load `@charcoal-ui/theme/css/v2/{light,dark}.css`. | | Reading light.css's selector as `:root:not([data-theme])` | The real selector is `:root:not([data-theme]) .ch-token-v2`. Drop `.ch-token-v2` and nothing matches. | | Prescribing Tailwind to fix missing colors | Colors are not built by Tailwind. Static CSS ships in `@charcoal-ui/theme`. | | Wrapping the app in `ThemeProvider` for `<Button>` | `Button` imports its own CSS and needs no provider. Onl