@carbon/layout 11.59.0-rc.0 → 11.60.0-rc.0

package/src/dtcg/README.md

@@ -0,0 +1,266 @@
+# Layout Tokens (DTCG Format)
+
+This directory contains `@carbon/layout` design tokens in the
+[Design Tokens Community Group (DTCG)](https://tr.designtokens.org/format/)
+format.
+
+## File
+
+```
+dtcg/
+└── layout.json    # All layout tokens organised into DTCG groups
+```
+
+Tokens are grouped using **native DTCG token groups**. Each top-level key in the
+JSON (e.g. `"spacing"`, `"border-radius"`) is a group, and the tokens live
+inside it:
+
+```json
+{
+  "spacing": {
+    "$description": "Spacing scale based on the 8px mini-unit grid.",
+    "spacing-05": {
+      "$type": "dimension",
+      "$value": 2,
+      "$extensions": { "carbon.layout": { "converter": "miniUnits" } }
+    }
+  }
+}
+```
+
+The group name is the **authoritative category** for a token. The Style
+Dictionary pipeline reads `token.path[0]` (the group key) to decide which
+generated file the token belongs to — no name-prefix inference, no hidden
+ordering rules.
+
+## Token Format
+
+All tokens follow the DTCG specification. Every token has `$type`, `$value`, and
+`$description`. Some tokens carry a `carbon.layout` extension that describes how
+the value was derived.
+
+### Keys
+
+| Key            | Required | Description                                         |
+| -------------- | -------- | --------------------------------------------------- |
+| `$type`        | ✅       | Always `"dimension"` for layout tokens              |
+| `$value`       | ✅       | The token value — see **Authoring values** below    |
+| `$description` | ✅       | Human-readable description of purpose and usage     |
+| `$extensions`  | —        | Carbon-specific metadata — see **Extensions** below |
+
+---
+
+## Authoring values
+
+The `$value` field has two modes depending on whether `$extensions` is present.
+
+### Without extensions — resolved CSS value
+
+When no `carbon.layout` extension is present, `$value` must be a **fully
+resolved CSS value** including its unit. The build pipeline uses it as-is.
+
+```json
+"fluid-spacing-02": {
+  "$type": "dimension",
+  "$value": "2vw",
+  "$description": "Fluid spacing token — 2vw."
+}
+```
+
+Valid units: `rem`, `px`, `vw`, `vh`, `%`, or `0` (unitless zero).
+
+### With extensions — raw numeric input + converter
+
+When `carbon.layout.converter` is present, `$value` is the **raw numeric input**
+to that converter function. The build pipeline resolves it to the final CSS
+value. Do **not** include a unit in `$value` in this case.
+
+```json
+"spacing-05": {
+  "$type": "dimension",
+  "$value": 2,
+  "$description": "Spacing token — 16px.",
+  "$extensions": {
+    "carbon.layout": {
+      "converter": "miniUnits"
+    }
+  }
+}
+```
+
+---
+
+## Extensions — `carbon.layout`
+
+### `converter`
+
+Declares how to convert the raw `$value` number to a CSS value.
+
+| `converter`   | Input           | Formula                  | Example           |
+| ------------- | --------------- | ------------------------ | ----------------- |
+| `"miniUnits"` | Grid step count | `steps × 8px ÷ 16 = rem` | `2` → `"1rem"`    |
+| `"rem"`       | Pixel value     | `px ÷ 16 = rem`          | `4` → `"0.25rem"` |
+
+**`miniUnits`** — Carbon's 8px base grid. Pass the number of grid steps. Use
+this for spacing, container, and layout-scale tokens.
+
+```json
+"spacing-07": {
+  "$type": "dimension",
+  "$value": 4,
+  "$description": "Spacing token — 32px.",
+  "$extensions": {
+    "carbon.layout": {
+      "converter": "miniUnits"
+    }
+  }
+}
+```
+
+**`rem`** — Direct pixel-to-rem conversion. Pass the value in pixels. Use this
+for border-radius tokens and any token defined by an explicit px measurement
+rather than a grid step.
+
+```json
+"border-radius-04": {
+  "$type": "dimension",
+  "$value": 4,
+  "$description": "Border radius token — 4px.",
+  "$extensions": {
+    "carbon.layout": {
+      "converter": "rem"
+    }
+  }
+}
+```
+
+### `deprecated`
+
+Marks a token as deprecated. Set to `true` alongside any other extension keys.
+Tools and codemods can read this flag to warn consumers.
+
+```json
+"layout-01": {
+  "$type": "dimension",
+  "$value": 2,
+  "$description": "Deprecated. Replaced by spacing scale. Do not use in new work.",
+  "$extensions": {
+    "carbon.layout": {
+      "converter": "miniUnits",
+      "deprecated": true
+    }
+  }
+}
+```
+
+---
+
+## Token naming and generated file routing
+
+Token names in `layout.json` use **kebab-case**. Routing to a generated Sass
+file is determined by the **DTCG group** the token belongs to — `token.path[0]`
+in Style Dictionary terms. There is no name-prefix inference.
+
+| DTCG group key  | Generated Sass file                  | Sass map variable           |
+| --------------- | ------------------------------------ | --------------------------- |
+| `spacing`       | `scss/generated/_spacing.scss`       | `$spacing`                  |
+| `fluid-spacing` | `scss/generated/_fluid-spacing.scss` | `$fluid-spacing`            |
+| `container`     | `scss/generated/_container.scss`     | `$container`                |
+| `icon-size`     | `scss/generated/_icon-size.scss`     | `$icon-size`                |
+| `border-radius` | `scss/generated/_border-radius.scss` | `$border-radius`            |
+| `layout`        | `scss/generated/_layout.scss`        | `$layout`                   |
+| `size`          | `scss/generated/_size.scss`          | _(no map — bare variables)_ |
+
+The JS export name is the camelCase version of the token's own key: `spacing-05`
+→ `spacing05`, `border-radius-04` → `borderRadius04`, `fluid-spacing-02` →
+`fluidSpacing02`.
+
+### Adding a token to an existing category
+
+Place the token inside the correct group object — it will automatically be
+included in the right file on the next build. For example, to add a new spacing
+step:
+
+```json
+"spacing": {
+  "spacing-14": {
+    "$type": "dimension",
+    "$value": 24,
+    "$description": "Spacing token — 192px.",
+    "$extensions": {
+      "carbon.layout": {
+        "converter": "miniUnits"
+      }
+    }
+  }
+}
+```
+
+This will add `$spacing-14: 12rem !default;` to `_spacing.scss` and
+`export const spacing14 = '12rem';` to `layout-tokens.js`.
+
+### Adding a token in a new category
+
+If your token does not match any existing prefix (e.g. `gap-*`), you need to
+also update the Style Dictionary pipeline:
+
+1. Add your token to `layout.json` with the appropriate name prefix.
+2. Add a new format function in
+   [`style-dictionary/formats/scss-layout.js`](../style-dictionary/formats/scss-layout.js):
+   ```js
+   function formatGap({ dictionary }) {
+     const tokens = tokensForGroup(dictionary, 'gap-');
+     return buildStandardFile(tokens, 'gap', BANNER_2023);
+   }
+   ```
+3. Export it from the `module.exports` array at the bottom of that file.
+4. Register the new output file in
+   [`style-dictionary/sd.config.js`](../style-dictionary/sd.config.js) under the
+   `scss` platform's `files` array:
+   ```js
+   { destination: '_gap.scss', format: 'carbon/scss-gap' }
+   ```
+5. Forward the new file from the appropriate `scss/_*.scss` entry point (or
+   create a new one and forward it from `index.scss`).
+
+---
+
+## Adding a new token
+
+1. Add an entry to `layout.json` following the examples above.
+2. Choose the right name prefix (see table above).
+3. Choose the right `$value` and `converter`:
+   - Grid-aligned value? Use `converter: "miniUnits"` and pass the step count.
+   - Explicit pixel value? Use `converter: "rem"` and pass the px number.
+   - Non-rem unit (e.g. `vw`, `px`)? Omit extensions and write the full CSS
+     value directly in `$value`.
+4. Run the build to regenerate SCSS and JS outputs:
+   ```bash
+   cd packages/layout
+   yarn build:dtcg
+   ```
+5. Verify the resolved value in `js/generated/layout-tokens.js` and the correct
+   `scss/generated/_*.scss` file.
+
+---
+
+## Build pipeline
+
+```
+src/dtcg/layout.json          ← you edit this
+        │
+        ▼  yarn build:dtcg
+        │  (style-dictionary/sd.config.js)
+        │
+        ├── scss/generated/*.scss                (Sass variables + maps, one file per token group)
+        └── js/generated/layout-tokens.{js,d.ts} (ES module + types)
+                │
+                ▼
+        src/index.ts  re-exports all tokens
+```
+
+The SD pipeline in
+[`style-dictionary/sd.config.js`](../style-dictionary/sd.config.js) reads the
+`carbon.layout.converter` extension and resolves `$value` before emitting. The
+generated files always contain **resolved CSS values** regardless of how the
+token was authored.

package/src/dtcg/layout.json

@@ -0,0 +1,432 @@
+{
+  "$schema": "https://tr.designtokens.org/format/",
+  "$description": "Layout tokens for Carbon Design System — spacing, container, icon size, fluid spacing, size, border-radius, and deprecated layout scale.",
+  "spacing": {
+    "$description": "Spacing scale based on the 8px mini-unit grid.",
+    "spacing-01": {
+      "$type": "dimension",
+      "$value": 0.25,
+      "$description": "Spacing token — 2px. Use for the smallest internal padding or gaps between tightly-packed elements.",
+      "$extensions": {
+        "carbon.layout": {
+          "converter": "miniUnits"
+        }
+      }
+    },
+    "spacing-02": {
+      "$type": "dimension",
+      "$value": 0.5,
+      "$description": "Spacing token — 4px. Use for compact padding within dense components.",
+      "$extensions": {
+        "carbon.layout": {
+          "converter": "miniUnits"
+        }
+      }
+    },
+    "spacing-03": {
+      "$type": "dimension",
+      "$value": 1,
+      "$description": "Spacing token — 8px. Default small spacing unit for inset padding and icon gaps.",
+      "$extensions": {
+        "carbon.layout": {
+          "converter": "miniUnits"
+        }
+      }
+    },
+    "spacing-04": {
+      "$type": "dimension",
+      "$value": 1.5,
+      "$description": "Spacing token — 12px. Use for comfortable inset padding in small components.",
+      "$extensions": {
+        "carbon.layout": {
+          "converter": "miniUnits"
+        }
+      }
+    },
+    "spacing-05": {
+      "$type": "dimension",
+      "$value": 2,
+      "$description": "Spacing token — 16px. Standard spacing unit; use for typical component padding and gutters.",
+      "$extensions": {
+        "carbon.layout": {
+          "converter": "miniUnits"
+        }
+      }
+    },
+    "spacing-06": {
+      "$type": "dimension",
+      "$value": 3,
+      "$description": "Spacing token — 24px. Use for section padding and medium gaps between components.",
+      "$extensions": {
+        "carbon.layout": {
+          "converter": "miniUnits"
+        }
+      }
+    },
+    "spacing-07": {
+      "$type": "dimension",
+      "$value": 4,
+      "$description": "Spacing token — 32px. Use for group separation and larger layout gaps.",
+      "$extensions": {
+        "carbon.layout": {
+          "converter": "miniUnits"
+        }
+      }
+    },
+    "spacing-08": {
+      "$type": "dimension",
+      "$value": 5,
+      "$description": "Spacing token — 40px. Use for generous padding between distinct sections.",
+      "$extensions": {
+        "carbon.layout": {
+          "converter": "miniUnits"
+        }
+      }
+    },
+    "spacing-09": {
+      "$type": "dimension",
+      "$value": 6,
+      "$description": "Spacing token — 48px. Use for large vertical rhythm and section separation.",
+      "$extensions": {
+        "carbon.layout": {
+          "converter": "miniUnits"
+        }
+      }
+    },
+    "spacing-10": {
+      "$type": "dimension",
+      "$value": 8,
+      "$description": "Spacing token — 64px. Use for major page section gaps.",
+      "$extensions": {
+        "carbon.layout": {
+          "converter": "miniUnits"
+        }
+      }
+    },
+    "spacing-11": {
+      "$type": "dimension",
+      "$value": 10,
+      "$description": "Spacing token — 80px. Use for hero and large feature-area spacing.",
+      "$extensions": {
+        "carbon.layout": {
+          "converter": "miniUnits"
+        }
+      }
+    },
+    "spacing-12": {
+      "$type": "dimension",
+      "$value": 12,
+      "$description": "Spacing token — 96px. Use for very large layout separations.",
+      "$extensions": {
+        "carbon.layout": {
+          "converter": "miniUnits"
+        }
+      }
+    },
+    "spacing-13": {
+      "$type": "dimension",
+      "$value": 20,
+      "$description": "Spacing token — 160px. Use for the largest page-level spacing needs.",
+      "$extensions": {
+        "carbon.layout": {
+          "converter": "miniUnits"
+        }
+      }
+    }
+  },
+  "fluid-spacing": {
+    "$description": "Viewport-relative fluid spacing tokens.",
+    "fluid-spacing-01": {
+      "$type": "dimension",
+      "$value": "0",
+      "$description": "Fluid spacing token — 0. Use when no fluid spacing is required."
+    },
+    "fluid-spacing-02": {
+      "$type": "dimension",
+      "$value": "2vw",
+      "$description": "Fluid spacing token — 2vw. Use for viewport-proportional small spacing in fluid layouts."
+    },
+    "fluid-spacing-03": {
+      "$type": "dimension",
+      "$value": "5vw",
+      "$description": "Fluid spacing token — 5vw. Use for medium fluid spacing that scales with the viewport."
+    },
+    "fluid-spacing-04": {
+      "$type": "dimension",
+      "$value": "10vw",
+      "$description": "Fluid spacing token — 10vw. Use for large fluid spacing in full-bleed or hero sections."
+    }
+  },
+  "container": {
+    "$description": "Interactive element container height tokens.",
+    "container-01": {
+      "$type": "dimension",
+      "$value": 3,
+      "$description": "Container height token — 24px. Minimum interactive target height for compact UI elements.",
+      "$extensions": {
+        "carbon.layout": {
+          "converter": "miniUnits"
+        }
+      }
+    },
+    "container-02": {
+      "$type": "dimension",
+      "$value": 4,
+      "$description": "Container height token — 32px. Small interactive element height.",
+      "$extensions": {
+        "carbon.layout": {
+          "converter": "miniUnits"
+        }
+      }
+    },
+    "container-03": {
+      "$type": "dimension",
+      "$value": 5,
+      "$description": "Container height token — 40px. Default interactive element height.",
+      "$extensions": {
+        "carbon.layout": {
+          "converter": "miniUnits"
+        }
+      }
+    },
+    "container-04": {
+      "$type": "dimension",
+      "$value": 6,
+      "$description": "Container height token — 48px. Large interactive element height.",
+      "$extensions": {
+        "carbon.layout": {
+          "converter": "miniUnits"
+        }
+      }
+    },
+    "container-05": {
+      "$type": "dimension",
+      "$value": 8,
+      "$description": "Container height token — 64px. Extra-large interactive element height.",
+      "$extensions": {
+        "carbon.layout": {
+          "converter": "miniUnits"
+        }
+      }
+    }
+  },
+  "size": {
+    "$description": "Named component size tokens (xs–2xl).",
+    "size-xs": {
+      "$type": "dimension",
+      "$value": 24,
+      "$description": "Component size token — XSmall, 24px. Use for the smallest component variant.",
+      "$extensions": {
+        "carbon.layout": {
+          "converter": "rem"
+        }
+      }
+    },
+    "size-sm": {
+      "$type": "dimension",
+      "$value": 32,
+      "$description": "Component size token — Small, 32px.",
+      "$extensions": {
+        "carbon.layout": {
+          "converter": "rem"
+        }
+      }
+    },
+    "size-md": {
+      "$type": "dimension",
+      "$value": 40,
+      "$description": "Component size token — Medium, 40px. Default component size.",
+      "$extensions": {
+        "carbon.layout": {
+          "converter": "rem"
+        }
+      }
+    },
+    "size-lg": {
+      "$type": "dimension",
+      "$value": 48,
+      "$description": "Component size token — Large, 48px.",
+      "$extensions": {
+        "carbon.layout": {
+          "converter": "rem"
+        }
+      }
+    },
+    "size-xl": {
+      "$type": "dimension",
+      "$value": 64,
+      "$description": "Component size token — XLarge, 64px.",
+      "$extensions": {
+        "carbon.layout": {
+          "converter": "rem"
+        }
+      }
+    },
+    "size-2xl": {
+      "$type": "dimension",
+      "$value": 80,
+      "$description": "Component size token — 2XLarge, 80px.",
+      "$extensions": {
+        "carbon.layout": {
+          "converter": "rem"
+        }
+      }
+    }
+  },
+  "icon-size": {
+    "$description": "Icon size tokens.",
+    "icon-size-01": {
+      "$type": "dimension",
+      "$value": "1rem",
+      "$description": "Icon size token — 16px. Standard icon size for inline and UI icons."
+    },
+    "icon-size-02": {
+      "$type": "dimension",
+      "$value": "1.25rem",
+      "$description": "Icon size token — 20px. Use for slightly larger icons that need more visual weight."
+    }
+  },
+  "border-radius": {
+    "$description": "Border radius tokens for component rounding.",
+    "border-radius-00": {
+      "$type": "dimension",
+      "$value": "0px",
+      "$description": "Border radius token — 0. No rounding; use for sharp-cornered elements."
+    },
+    "border-radius-02": {
+      "$type": "dimension",
+      "$value": 2,
+      "$description": "Border radius token — 2px. Subtle rounding for small components like tags and badges.",
+      "$extensions": {
+        "carbon.layout": {
+          "converter": "rem"
+        }
+      }
+    },
+    "border-radius-04": {
+      "$type": "dimension",
+      "$value": 4,
+      "$description": "Border radius token — 4px. Default rounding for inputs, cards, and general components.",
+      "$extensions": {
+        "carbon.layout": {
+          "converter": "rem"
+        }
+      }
+    },
+    "border-radius-08": {
+      "$type": "dimension",
+      "$value": 8,
+      "$description": "Border radius token — 8px. Moderate rounding for panels, modals, and containers.",
+      "$extensions": {
+        "carbon.layout": {
+          "converter": "rem"
+        }
+      }
+    },
+    "border-radius-16": {
+      "$type": "dimension",
+      "$value": 16,
+      "$description": "Border radius token — 16px. Strong rounding for large cards or featured containers.",
+      "$extensions": {
+        "carbon.layout": {
+          "converter": "rem"
+        }
+      }
+    },
+    "border-radius-24": {
+      "$type": "dimension",
+      "$value": 24,
+      "$description": "Border radius token — 24px. Very rounded corners for pill-adjacent components.",
+      "$extensions": {
+        "carbon.layout": {
+          "converter": "rem"
+        }
+      }
+    },
+    "border-radius-max": {
+      "$type": "dimension",
+      "$value": "999999px",
+      "$description": "Border radius token — pill/fully rounded. Use for pill buttons, chips, and circular elements."
+    }
+  },
+  "layout": {
+    "$description": "Deprecated layout scale tokens. Replaced by the spacing scale — do not use in new work.",
+    "layout-01": {
+      "$type": "dimension",
+      "$value": 2,
+      "$description": "Deprecated layout token — 16px. Replaced by spacing scale. Do not use in new work.",
+      "$extensions": {
+        "carbon.layout": {
+          "converter": "miniUnits",
+          "deprecated": true
+        }
+      }
+    },
+    "layout-02": {
+      "$type": "dimension",
+      "$value": 3,
+      "$description": "Deprecated layout token — 24px. Replaced by spacing scale. Do not use in new work.",
+      "$extensions": {
+        "carbon.layout": {
+          "converter": "miniUnits",
+          "deprecated": true
+        }
+      }
+    },
+    "layout-03": {
+      "$type": "dimension",
+      "$value": 4,
+      "$description": "Deprecated layout token — 32px. Replaced by spacing scale. Do not use in new work.",
+      "$extensions": {
+        "carbon.layout": {
+          "converter": "miniUnits",
+          "deprecated": true
+        }
+      }
+    },
+    "layout-04": {
+      "$type": "dimension",
+      "$value": 6,
+      "$description": "Deprecated layout token — 48px. Replaced by spacing scale. Do not use in new work.",
+      "$extensions": {
+        "carbon.layout": {
+          "converter": "miniUnits",
+          "deprecated": true
+        }
+      }
+    },
+    "layout-05": {
+      "$type": "dimension",
+      "$value": 8,
+      "$description": "Deprecated layout token — 64px. Replaced by spacing scale. Do not use in new work.",
+      "$extensions": {
+        "carbon.layout": {
+          "converter": "miniUnits",
+          "deprecated": true
+        }
+      }
+    },
+    "layout-06": {
+      "$type": "dimension",
+      "$value": 12,
+      "$description": "Deprecated layout token — 96px. Replaced by spacing scale. Do not use in new work.",
+      "$extensions": {
+        "carbon.layout": {
+          "converter": "miniUnits",
+          "deprecated": true
+        }
+      }
+    },
+    "layout-07": {
+      "$type": "dimension",
+      "$value": 20,
+      "$description": "Deprecated layout token — 160px. Replaced by spacing scale. Do not use in new work.",
+      "$extensions": {
+        "carbon.layout": {
+          "converter": "miniUnits",
+          "deprecated": true
+        }
+      }
+    }
+  }
+}