@canonical/design-tokens 0.0.1

package/README.md

@@ -0,0 +1,42 @@
+# @canonical/design-tokens
+
+Design tokens for the Canonical design system. Token definitions follow the [DTCG Community Group](https://www.designtokens.org/tr/2025.10/format/) specification.
+
+## Installation
+
+```bash
+bun add @canonical/design-tokens
+```
+
+## Usage
+
+Import the CSS output in your application entry point:
+
+```css
+@import "@canonical/design-tokens/dist/tokens.css";
+```
+
+Tokens are available as CSS custom properties:
+
+```css
+.card {
+  background: var(--color-background-default);
+  padding: var(--spacing-medium);
+  border-radius: var(--radius-default);
+}
+```
+
+## Token Tiers
+
+| Tier | Path | Description |
+|------|------|-------------|
+| Primitive | `tokens/canonical/global/primitive/` | Raw values for colour, dimension, number, and typography. Not intended for direct use in application code. |
+| Semantic | `tokens/canonical/global/semantic/` | Aliased tokens referencing primitives. These encode design intent and are the tokens consumed by components. |
+
+## Building
+
+```bash
+bun run build
+```
+
+This runs the Terrazzo pipeline with `@canonical/terrazzo-plugin-css` and produces CSS files and a `tokens.json` artifact in `dist/`.

package/assets.ruleset.json

@@ -0,0 +1,19 @@
+{
+  "$schema": "https://raw.githubusercontent.com/canonical/pragma/refs/heads/main/packages/webarchitect/src/schema.json",
+  "name": "assets",
+  "extends": ["base"],
+  "package-license": {
+    "file": {
+      "name": "package.json",
+      "contains": {
+        "type": "object",
+        "properties": {
+          "license": {
+            "const": "LGPL-3.0"
+          }
+        },
+        "required": ["license"]
+      }
+    }
+  }
+}

package/package.json

@@ -0,0 +1,19 @@
+{
+  "name": "@canonical/design-tokens",
+  "version": "0.0.1",
+  "description": "Canonical design tokens (DTCG format) with CSS custom property output.",
+  "type": "module",
+  "license": "LGPL-3.0",
+  "scripts": {
+    "build": "tz build",
+    "build:all": "bun run build",
+    "check": "bun run check:webarchitect",
+    "check:webarchitect": "webarchitect assets"
+  },
+  "devDependencies": {
+    "@canonical/webarchitect": "^0.17.1",
+    "@canonical/terrazzo-plugin-css": "workspace:*",
+    "@terrazzo/cli": "2.0.0-beta.6",
+    "@terrazzo/parser": "2.0.0-beta.6"
+  }
+}

package/terrazzo.config.ts

@@ -0,0 +1,13 @@
+import { defineConfig } from "@terrazzo/cli";
+import { canonicalPlugin } from "@canonical/terrazzo-plugin-css";
+
+export default defineConfig({
+  tokens: ["./tokens/canonical/canonical.resolver.json"],
+  outDir: "./dist/",
+  lint: {
+    rules: {
+      "core/consistent-naming": ["warn", { format: "camelCase" }],
+    },
+  },
+  plugins: [canonicalPlugin()],
+});

package/tokens/canonical/canonical.resolver.json

@@ -0,0 +1,162 @@
+{
+  "$schema": "https://designtokens.org/schemas/2025.10/resolver.json",
+  "version": "2025.10",
+  "sets": {
+    "primitive": {
+      "description": "Base primitive tokens: color palette, dimensions, numbers, typography primitives.",
+      "sources": [
+        { "$ref": "global/primitive/color.tokens.json" },
+        { "$ref": "global/primitive/dimension.tokens.json" },
+        { "$ref": "global/primitive/number.tokens.json" },
+        { "$ref": "global/primitive/typography.tokens.json" }
+      ]
+    }
+  },
+  "modifiers": {
+    "breakpoint": {
+      "description": "Breakpoint modifier for responsive dimension tokens.",
+      "default": "small",
+      "contexts": {
+        "small": [{ "$ref": "global/semantic/dimension/small.tokens.json" }],
+        "medium": [{ "$ref": "global/semantic/dimension/medium.tokens.json" }],
+        "large": [{ "$ref": "global/semantic/dimension/large.tokens.json" }],
+        "xLarge": [{ "$ref": "global/semantic/dimension/xLarge.tokens.json" }]
+      }
+    },
+    "theme": {
+      "description": "Theme modifier for light/dark color tokens. Output uses light-dark() per DE015B section 2.E.a.",
+      "default": "light",
+      "contexts": {
+        "light": [{ "$ref": "global/semantic/color/light.tokens.json" }],
+        "dark": [{ "$ref": "global/semantic/color/dark.tokens.json" }]
+      }
+    },
+    "typography": {
+      "description": "Typography modifier with per-product contexts. Replaces three separate resolvers.",
+      "default": "global",
+      "contexts": {
+        "global": [
+          { "$ref": "global/semantic/modifier/typography/global.tokens.json" }
+        ],
+        "apps": [
+          { "$ref": "global/semantic/modifier/typography/global.tokens.json" },
+          { "$ref": "global/semantic/modifier/typography/apps.tokens.json" }
+        ],
+        "docs": [
+          { "$ref": "global/semantic/modifier/typography/global.tokens.json" },
+          { "$ref": "global/semantic/modifier/typography/docs.tokens.json" }
+        ],
+        "sites": [
+          { "$ref": "global/semantic/modifier/typography/global.tokens.json" },
+          { "$ref": "global/semantic/modifier/typography/sites.tokens.json" }
+        ]
+      }
+    },
+    "anticipation": {
+      "description": "Anticipation modifier family (WD433). Contexts: constructive, destructive, caution.",
+      "default": "none",
+      "contexts": {
+        "none": [],
+        "constructive": [
+          {
+            "$ref": "global/semantic/modifier/anticipation/constructive.tokens.json"
+          }
+        ],
+        "destructive": [
+          {
+            "$ref": "global/semantic/modifier/anticipation/destructive.tokens.json"
+          }
+        ],
+        "caution": [
+          {
+            "$ref": "global/semantic/modifier/anticipation/caution.tokens.json"
+          }
+        ]
+      }
+    },
+    "criticality": {
+      "description": "Criticality modifier family (WD433). Contexts: success, error, warning, information.",
+      "default": "none",
+      "contexts": {
+        "none": [],
+        "success": [
+          { "$ref": "global/semantic/modifier/criticality/success.tokens.json" }
+        ],
+        "error": [
+          { "$ref": "global/semantic/modifier/criticality/error.tokens.json" }
+        ],
+        "warning": [
+          { "$ref": "global/semantic/modifier/criticality/warning.tokens.json" }
+        ],
+        "information": [
+          {
+            "$ref": "global/semantic/modifier/criticality/information.tokens.json"
+          }
+        ]
+      }
+    },
+    "emphasis": {
+      "description": "Emphasis modifier family (WD433). Contexts: muted, highlighted, branded.",
+      "default": "none",
+      "contexts": {
+        "none": [],
+        "muted": [
+          { "$ref": "global/semantic/modifier/emphasis/muted.tokens.json" }
+        ],
+        "highlighted": [
+          {
+            "$ref": "global/semantic/modifier/emphasis/highlighted.tokens.json"
+          }
+        ],
+        "branded": [
+          { "$ref": "global/semantic/modifier/emphasis/branded.tokens.json" }
+        ]
+      }
+    },
+    "importance": {
+      "description": "Importance modifier family (WD433). Contexts: primary, secondary, tertiary. Placeholder bindings.",
+      "default": "none",
+      "contexts": {
+        "none": [],
+        "primary": [
+          { "$ref": "global/semantic/modifier/importance/primary.tokens.json" }
+        ],
+        "secondary": [
+          {
+            "$ref": "global/semantic/modifier/importance/secondary.tokens.json"
+          }
+        ],
+        "tertiary": [
+          { "$ref": "global/semantic/modifier/importance/tertiary.tokens.json" }
+        ]
+      }
+    },
+    "surface": {
+      "description": "Surface modifier for layer-aware token rebinding. Contexts: layer1, layer2, layer3. CSS output uses compound .surface selectors (depth-based compounding).",
+      "default": "none",
+      "contexts": {
+        "none": [],
+        "layer1": [
+          { "$ref": "global/semantic/modifier/surface/layer1.tokens.json" }
+        ],
+        "layer2": [
+          { "$ref": "global/semantic/modifier/surface/layer2.tokens.json" }
+        ],
+        "layer3": [
+          { "$ref": "global/semantic/modifier/surface/layer3.tokens.json" }
+        ]
+      }
+    }
+  },
+  "resolutionOrder": [
+    { "$ref": "#/sets/primitive" },
+    { "$ref": "#/modifiers/breakpoint" },
+    { "$ref": "#/modifiers/theme" },
+    { "$ref": "#/modifiers/typography" },
+    { "$ref": "#/modifiers/anticipation" },
+    { "$ref": "#/modifiers/criticality" },
+    { "$ref": "#/modifiers/emphasis" },
+    { "$ref": "#/modifiers/importance" },
+    { "$ref": "#/modifiers/surface" }
+  ]
+}