@carbon/themes 11.81.0 → 11.82.0

package/src/dtcg/README.md

@@ -9,10 +9,8 @@ industry-standard format.
 
 ```
 dtcg/
-├── white.json              # White theme (light, high contrast)
-├── g10.json               # Gray 10 theme (light)
-├── g90.json               # Gray 90 theme (dark)
-├── g100.json              # Gray 100 theme (dark, high contrast)
+├── themes.json            # All four themes in one file (white, g10, g90, g100)
+├── color-palette.json     # Color palette aliases (generated from @carbon/colors)
 └── components/
     ├── button.json        # Button component tokens
     ├── tag.json           # Tag component tokens
@@ -21,6 +19,111 @@ dtcg/
     └── content-switcher.json  # Content switcher tokens
 ```
 
+## Token categories in each theme file
+
+`themes.json` is organised into top-level groups. When searching for a token,
+start with the group that matches the first segment of its name:
+
+| Top-level key | Token name prefix examples                                  |
+| ------------- | ----------------------------------------------------------- |
+| `ai`          | `ai-aura-*`, `ai-popover-*`, `ai-skeleton-*`                |
+| `background`  | `background`, `background-active`, `background-hover`       |
+| `border`      | `border-subtle-*`, `border-strong-*`, `border-tile-*`       |
+| `button`      | _(component tokens — see `components/button.json` instead)_ |
+| `field`       | `field-01`, `field-02`, `field-hover-01`                    |
+| `focus`       | `focus`, `focus-inset`, `focus-inverse`                     |
+| `icon`        | `icon-primary`, `icon-on-color`, `icon-disabled`            |
+| `layer`       | `layer-01`, `layer-active-01`, `layer-hover-01`             |
+| `link`        | `link-primary`, `link-visited`, `link-inverse`              |
+| `overlay`     | `overlay`                                                   |
+| `skeleton`    | `skeleton-background`, `skeleton-element`                   |
+| `support`     | `support-error`, `support-warning`, `support-success`       |
+| `text`        | `text-primary`, `text-on-color`, `text-disabled`            |
+
+> **Note:** Component tokens (`button`, `tag`, etc.) live in
+> `components/<name>.json`, **not** in `themes.json`.
+
+## Nested key → flat token name mapping
+
+Token names in Carbon use a hyphenated convention (e.g. `border-subtle-02`,
+`text-on-color-disabled`). In the DTCG JSON files these are represented as
+**nested objects**, where each hyphen-separated segment becomes a JSON key
+level:
+
+| Flat token name          | JSON path                            |
+| ------------------------ | ------------------------------------ |
+| `border-subtle-02`       | `border` → `subtle` → `02`           |
+| `text-on-color-disabled` | `text` → `on-color` → `disabled`     |
+| `layer-accent-active-03` | `layer` → `accent` → `active` → `03` |
+
+> **Tip for agents:** Do not `grep` for the full hyphenated name — it will not
+> match. Instead grep for the last segment (`"02"`, `"disabled"`) and navigate
+> up the JSON hierarchy to confirm the full path, or read the surrounding
+> context to resolve ambiguity when short keys like `"01"` or `"02"` appear in
+> multiple token groups.
+
+## Contextual layer tokens (`$layer-*` without numbers)
+
+In component styles (e.g. `$layer-accent`, `$layer-hover`, `$field`,
+`$border-subtle`), you will often see unnumbered tokens used. These are
+**dynamic layer-set tokens** defined in
+`packages/styles/scss/layer/_layer-sets.scss`.
+
+In DTCG JSON, tokens only exist as explicit numbered levels (`01`, `02`, `03`):
+
+- `layer.01` / `layer.02` / `layer.03`
+- `layer.accent.01` / `layer.accent.02` / `layer.accent.03`
+- `layer.accent.active.01` / `layer.accent.active.02` / `layer.accent.active.03`
+
+At runtime or inside a `<Layer>` component context, Carbon automatically
+resolves the unnumbered token (e.g. `$layer-accent`) to its corresponding
+numbered tier (`01`, `02`, or `03`) based on container nesting depth.
+
+## Dual-role nodes (tokens that are also groups)
+
+Some tokens are simultaneously a value **and** a group of related tokens. For
+example, `background` has its own per-theme value but also has children like
+`background-active` and `background-hover`. In `themes.json` these look like:
+
+```json
+"background": {
+  "$type": "color",
+  "$description": "…",
+  "$extensions": {
+    "carbon.themes": {
+      "white": "{white.default}", "g10": "{gray.10}",
+      "g90":   "{gray.90}",       "g100": "{gray.100}"
+    }
+  },
+  "active": {
+    "$type": "color",
+    "$extensions": { "carbon.themes": { "white": { "value": "{gray.50}", "alpha": 0.5 }, … } }
+  },
+  "hover": {
+    "$type": "color",
+    "$extensions": { "carbon.themes": { "white": { "value": "{gray.50}", "alpha": 0.12 }, … } }
+  }
+}
+```
+
+The flat names generated are `background`, `background-active`,
+`background-hover` — all siblings in the output even though they are
+parent/child in the source JSON.
+
+> **Tip for agents:** If you read a node and it has both a
+> `$extensions["carbon.themes"]` entry and non-`$` children, both the node
+> itself **and** every child are valid tokens. Do not assume a node with
+> children is only a group.
+
+## `carbon.themes` value aliases and `color-palette.json`
+
+The `value` field inside each `carbon.themes` entry uses curly-brace alias
+syntax referencing the color palette, e.g. `"{blue.60}"` or `"{gray.20}"`. These
+references are resolved during the build against
+`packages/themes/src/dtcg/color-palette.json`, which contains the full Carbon
+color ramp (`gray.10` … `gray.100`, `blue.10` … `blue.100`, etc.) with their hex
+values. If you need the actual hex for an alias, look it up in that file.
+
 ## Token Format
 
 All tokens follow the DTCG specification with a structured format using specific
@@ -47,86 +150,108 @@ keys:
 #### Optional Keys
 
 - **`$extensions`** - Custom metadata and vendor-specific information. Carbon
-  uses this for:
+  uses two namespaces — see the dedicated sections below for full details.
 
-  - **`carbon.themes`** - Theme-specific values for component tokens:
-    ```json
-    "$extensions": {
-      "carbon.themes": {
-        "white": "{blue.60}",
-        "g10": "{blue.60}",
-        "g90": "{blue.60}",
-        "g100": "{blue.60}"
-      }
-    }
-    ```
-  - **`org.carbon`** - Carbon-specific metadata like alpha modifiers:
-    ```json
-    "$extensions": {
-      "org.carbon": {
-        "alphaModifier": 0.5,
-        "color-scheme": "light"
-      }
-    }
-    ```
+## Semi-transparent tokens — the `alpha` field
 
-### Example: Theme Token
+Some tokens are a base color with an opacity applied. In `themes.json` the
+opacity is expressed as an `alpha` field co-located with `value` inside the
+per-theme entry:
 
 ```json
-{
-  "$schema": "https://tr.designtokens.org/format/",
-  "$description": "White theme - Light theme with high contrast",
-  "background": {
-    "$type": "color",
-    "$value": "{white.default}",
-    "$description": "Default page background color. Use as the base surface for the entire application."
-  },
-  "background-hover": {
+"background": {
+  "hover": {
     "$type": "color",
-    "$value": "{gray.50}",
-    "$description": "Background color for hover state. Use when user hovers over interactive elements.",
+    "$description": "Background color for hover state.",
     "$extensions": {
-      "org.carbon": {
-        "alphaModifier": 0.12
+      "carbon.themes": {
+        "white": { "value": "{gray.50}", "alpha": 0.12 },
+        "g10":   { "value": "{gray.50}", "alpha": 0.12 },
+        "g90":   { "value": "{gray.50}", "alpha": 0.16 },
+        "g100":  { "value": "{gray.50}", "alpha": 0.16 }
       }
     }
   }
 }
 ```
 
-### Example: Component Token
+During the build the `carbon/alpha-modifier` Style Dictionary transform resolves
+`{gray.50}` to its hex (`#8d8d8d`) and then emits `rgba(141, 141, 141, 0.12)`.
+
+> **Reading the source:** When a `carbon.themes` entry is an object, the `value`
+> field alone does **not** tell you the final color. The real output is
+> `rgba(<palette hex at value>, <alpha>)`. Check `color-palette.json` for the
+> hex, then apply `alpha` mentally.
+
+> **`alpha: 0`** means fully transparent (`rgba(…, 0)`). Used for gradient "fade
+> to transparent" endpoints (e.g. `ai-aura-end`).
+
+> **Note for component token files:** `components/*.json` still use the legacy
+> `$extensions["org.carbon"].alphaModifiers` map (plural, keyed by theme) rather
+> than the co-located `alpha` field. The build preprocessor accepts both forms.
+
+## `$extensions["carbon.themes"]` — the unified per-theme format
+
+Both theme tokens (`themes.json`) and component tokens (`components/*.json`)
+store per-theme values under the same `$extensions["carbon.themes"]` key. Each
+entry for a theme is either:
+
+- **A bare string** (palette alias or hex) when there is no alpha modifier:
+  ```json
+  "white": "{gray.10}"
+  ```
+- **An object `{ value, alpha }`** when an opacity modifier is needed:
+  ```json
+  "white": { "value": "{gray.50}", "alpha": 0.12 }
+  ```
+
+Example token from `themes.json`:
 
 ```json
-{
-  "$schema": "https://tr.designtokens.org/format/",
-  "$description": "Button component color tokens",
-  "button": {
-    "primary": {
-      "$type": "color",
-      "$description": "Background color for primary buttons in default state.",
-      "$extensions": {
-        "carbon.themes": {
-          "white": "{blue.60}",
-          "g10": "{blue.60}",
-          "g90": "{blue.60}",
-          "g100": "{blue.60}"
-        }
+"background": {
+  "hover": {
+    "$type": "color",
+    "$description": "Background color for hover state.",
+    "$extensions": {
+      "carbon.themes": {
+        "white": { "value": "{gray.50}", "alpha": 0.12 },
+        "g10":   { "value": "{gray.50}", "alpha": 0.12 },
+        "g90":   { "value": "{gray.50}", "alpha": 0.16 },
+        "g100":  { "value": "{gray.50}", "alpha": 0.16 }
       }
     }
   }
 }
 ```
 
+The `carbon/component-tokens` preprocessor understands both entry shapes and
+expands them into per-theme leaf tokens before Style Dictionary processes them.
+
+### Comparison: theme tokens vs. component tokens
+
+|               | Theme token (`themes.json`)                                           | Component token (`components/button.json`)                                 |
+| ------------- | --------------------------------------------------------------------- | -------------------------------------------------------------------------- |
+| File scope    | All four themes                                                       | All four themes                                                            |
+| Value field   | `$extensions["carbon.themes"]["<theme>"]` (string or `{value,alpha}`) | `$extensions["carbon.themes"]["<theme>"]` (string)                         |
+| Alpha opacity | Co-located: `{ "value": "…", "alpha": 0.12 }`                         | Separate: `$extensions["org.carbon"].alphaModifiers.<theme>` (note plural) |
+| Grepping      | Navigate nested keys                                                  | Same nesting rules apply                                                   |
+
+> **Note:** Component files still use the legacy `org.carbon.alphaModifiers` map
+> for backwards compatibility. Both forms are accepted by the preprocessor.
+
+> **Reading theme token values:** Navigate to the nested key in `themes.json`,
+> then read the value for the theme you care about from `carbon.themes`.
+
 ## Theme Tokens
 
-All four Carbon themes are available in DTCG format:
+All four Carbon themes are consolidated into `themes.json`:
 
-- **white.json** - White theme (light, high contrast)
-- **g10.json** - Gray 10 theme (light)
-- **g90.json** - Gray 90 theme (dark)
-- **g100.json** - Gray 100 theme (dark, high contrast)
+- **white** — Light theme, high contrast for optimal readability
+- **g10** — Gray 10 light theme, subtle contrast for data-dense interfaces
+- **g90** — Gray 90 dark theme
+- **g100** — Gray 100 dark theme, high contrast
 
-Each theme file contains 250+ tokens organized into categories:
+The file contains 250+ tokens organised into categories:
 
 - **Color tokens**: Background, layer, field, border, text, link, icon, support
   colors
@@ -172,7 +297,7 @@ Manual validation can be performed using any JSON Schema validator:
 
 ```bash
 # Using ajv-cli
-ajv validate -s https://tr.designtokens.org/format/schema.json -d white.json
+ajv validate -s https://tr.designtokens.org/format/schema.json -d themes.json
 ```
 
 ## Contributing
@@ -185,7 +310,8 @@ When adding or modifying tokens:
    `$description`
 3. **Use appropriate types** - Set correct `$type` values (color, dimension,
    etc.)
-4. **Add theme-specific values** - Use `$extensions.carbon.themes` for component
+4. **Add theme-specific values** - Edit `themes.json` for theme tokens; use
+   `$extensions["carbon.themes"]` in `components/<name>.json` for component
    tokens
 5. **Validate your changes** - Run `yarn build` to validate against DTCG schema
 6. **Test generated output** - Verify SCSS generation works correctly