@kong/design-tokens 2.0.1 → 2.0.2-pr.666.012f8f0.0

package/README.md

@@ -2,18 +2,26 @@
 
 Kong Design Tokens for Konnect, via [Style Dictionary](https://github.com/amzn/style-dictionary).
 
+- [Token Tiers](#token-tiers)
+  - [Semantic tokens](#semantic-tokens)
+  - [Component tokens — names only, value-less](#component-tokens--names-only-value-less)
+  - [Themeable token list](#themeable-token-list)
+- [Themes](#themes)
 - [Tokens](#tokens)
   - [Token Formats](#token-formats)
   - [SCSS](#scss)
-  - [LESS](#less)
   - [CSS Custom Properties](#css-custom-properties)
   - [JavaScript](#javascript)
 - [Usage](#usage)
   - [Installation](#installation)
   - [Standalone components](#standalone-components)
   - [Host applications](#host-applications)
+  - [Kongponents](#kongponents)
 - [Updating Tokens & Local Development](#updating-tokens--local-development)
+  - [Directory structure](#directory-structure)
   - [Token Requirements](#token-requirements)
+  - [Creating a new theme](#creating-a-new-theme)
+  - [Theme `$description` authoring rules](#theme-description-authoring-rules)
   - [Development Sandbox](#development-sandbox)
   - [Lint and fix](#lint-and-fix)
   - [Build for production](#build-for-production)
@@ -22,9 +30,96 @@ Kong Design Tokens for Konnect, via [Style Dictionary](https://github.com/amzn/s
   - [Approvals](#approvals)
   - [Package Publishing](#package-publishing)
 
-## Tokens
+## Token Tiers
+
+The `@kong/design-tokens` package uses a two-tier exported token taxonomy.
+
+| Tier | Source directory | Examples | Exported as |
+|------|-----------------|----------|-------------|
+| **Semantic** | `tokens/source/**` | `--kui-color-background-primary`, `--kui-space-40`, `--kui-border-radius-30`, `--kui-method-color-background-get` | CSS custom properties, SCSS variables, JS constants |
+| **Component** | `tokens/components/**` | `--kui-button-border-radius-medium`, `--kui-button-color-background-primary`, `--kui-button-shadow-focus` | Included in `KUI_THEMEABLE_TOKENS` — **no CSS value** |
+
+> **Alias tokens** (`themes/<name>/<name>.alias.color.json`, one per theme) form a third internal
+> category. They hold the raw palette values (hex colors) that semantic and component tokens
+> reference. They are **never exported** — they exist only so Style Dictionary can resolve
+> `{color.alias.blue.100}` references at build time.
+
+### Semantic tokens
+
+Everything in `tokens/source/` is a semantic token — it has a concrete value and is exported to all formats (CSS, SCSS, JS). This includes:
+
+- **Scale tokens** — `--kui-color-*`, `--kui-space-*`, `--kui-border-radius-*`, `--kui-shadow-*`, `--kui-font-*`, etc. Named after the design dimension they represent.
+- **Concept tokens** — `--kui-method-*`, `--kui-status-*`, `--kui-navigation-*`, `--kui-icon-*`. Named after a cross-cutting UI concept (HTTP methods, status codes, navigation chrome, icons) rather than a design dimension. Each family lives in its own folder under `tokens/source/` (`method/`, `status/`, `navigation/`, `icon/`), following the same pattern as the scale folders. They are plain semantic tokens, valued and exported exactly like scale tokens. **These are not component tokens** even though they're used inside components.
+
+> **IMPORTANT — `primary` and `accent` colors must be overridden in the Dev Portal**
+>
+> The `primary` tokens (`--kui-color-background-primary`, `--kui-color-text-primary`, `--kui-color-border-primary`) and the `accent` tokens (`--kui-color-background-accent`, `--kui-color-text-accent`, `--kui-color-border-accent`) — plus any future brand-derived color used the same way — ship a **Kong-branded default value**. The Kong Konnect **Dev Portal** (`kong-konnect/portal`) renders **customer-branded** UIs, where each customer configures their own brand/theme color.
+>
+> Because these tokens carry a default, that default will **leak Kong's brand color into the customer's portal** unless the portal overrides it. Therefore, whenever a `primary`- or `accent`-like brand color token is **added, renamed, or its default value changes**, the `kong-konnect/portal` customization plugin **must** be updated to override the token with the portal's configured theme color variants so the design-tokens default never reaches the rendered Dev Portal.
+
+### Component tokens — names only, value-less
+
+Component tokens (`--kui-button-*`, `--kui-card-*`, `--kui-input-*`, `--kui-badge-*`, …) live in `tokens/components/` and are **declared without any CSS value** — they are purely override slots. Every Kongponents component uses them in a `var()` fallback chain:
+
+```scss
+border-radius: var(--kui-button-border-radius-medium, var(--kui-border-radius-30, $kui-border-radius-30));
+//                 ↑ component token (empty by default)   ↑ semantic fallback        ↑ SCSS literal
+```
+
+When a theme writes `--kui-button-border-radius-medium: 999px`, only buttons go pill-shaped. Inputs and other components keep their semantic default. When no theme writes the token, `var()` falls through to the semantic default — **byte-identical to the un-themed render**.
+
+### Themeable token list
+
+The `./tokens/themeable-tokens` subpath exports `KUI_THEMEABLE_TOKENS` — a typed `readonly` tuple of every `--kui-*` custom property name that a theme may meaningfully override. It combines both semantic tokens and value-less component tokens.
+
+```ts
+import { KUI_THEMEABLE_TOKENS } from '@kong/design-tokens/tokens/themeable-tokens'
+
+// Each entry is a `{ name, description, category, value }` record.
+// Derive a union type of all valid theme keys from their `name`s:
+type ThemeToken = typeof KUI_THEMEABLE_TOKENS[number]['name']
+```
+
+## Themes
 
-All design tokens **must** be placed inside of the `packages/design-tokens/tokens/` directory in one of two sub-directories.
+Pre-built theme CSS files activate a complete set of token overrides via a `data-kui-theme` attribute on any element. Load a theme CSS file and then set the attribute on the root element (or any subtree element):
+
+```html
+<!-- In your HTML template or equivalent -->
+<html data-kui-theme="electric-lime-day">
+```
+
+```ts
+// Load the theme CSS — webpack/Vite will bundle it
+import '@kong/design-tokens/themes/electric-lime-day.css'
+
+// Switch the active theme at runtime
+document.documentElement.setAttribute('data-kui-theme', 'electric-lime-night')
+```
+
+Available themes: `classic-day`, `classic-night`, `electric-lime-day`, `electric-lime-night`.
+`classic-day` is the default look (identical to the unthemed `:root` exports); `classic-night` is its dark counterpart.
+
+Each theme CSS file uses `@layer kui.theme { [data-kui-theme="name"] { ... } }`. This means customer `:root {}` overrides (which are **unlayered**) beat the theme automatically — no `!important` or special selectors needed.
+
+To respond to the system dark-mode preference, listen to the `prefers-color-scheme` media query in JS:
+
+```ts
+const mq = window.matchMedia('(prefers-color-scheme: dark)')
+const applyColorScheme = (dark: boolean) =>
+  document.documentElement.setAttribute('data-kui-theme', dark ? 'electric-lime-night' : 'electric-lime-day')
+
+applyColorScheme(mq.matches)
+mq.addEventListener('change', e => applyColorScheme(e.matches))
+```
+
+You can also import the theme objects as JavaScript for runtime composition or for use with Kongponents' `applyTheme` / `defineKongponentsTheme`:
+
+```ts
+import { electricLimeDay, electricLimeNight, classicDay, classicNight } from '@kong/design-tokens/themes'
+```
+
+## Tokens
 
 [View the lists of available tokens here](TOKENS.md), or keep reading for more information.
 
@@ -33,7 +128,6 @@ All design tokens **must** be placed inside of the `packages/design-tokens/token
 The `@kong/design-tokens` package exports tokens in multiple formats:
 
 - [SCSS](#scss)
-- [LESS](#less)
 - [CSS Custom Properties](#css-custom-properties)
 - [JavaScript](#javascript) (ESM, CJS, and JSON), along with corresponding TypeScript types
 
@@ -89,14 +183,6 @@ $tokens-map: (
 );
 ```
 
-### LESS
-
-#### LESS Variables
-
-LESS variables can be utilized in your project's LESS files or in-component style blocks (this assumes your app is already configured to compile LESS).
-
-To use the LESS variables, you need to import them into your component or app stylesheet so they are available throughout your project via the export from `@kong/design-tokens/tokens/less/variables.less`.
-
 ### CSS Custom Properties
 
 You may scope your CSS variable overrides inside the `:root` selector as shown here, or inside any other valid CSS selector.
@@ -249,6 +335,55 @@ Typically, a host application should only utilize the SCSS and/or JavaScript var
 </style>
 ```
 
+#### Kongponents
+
+[Kongponents](https://kongponents.konghq.com) ships its own `defineKongponentsTheme` helper that validates a theme object against the full typed token surface at authoring time. To use a pre-built design-tokens theme in Kongponents, wrap it with `defineKongponentsTheme`:
+
+```ts
+// my-app-theme.ts
+import { electricLimeDay } from '@kong/design-tokens/themes'
+import { defineKongponentsTheme } from '@kong/kongponents'
+
+export const myTheme = defineKongponentsTheme({
+  ...electricLimeDay,           // spread the base theme
+  '--kui-button-border-radius-medium': '999px',  // then override specific tokens
+})
+```
+
+Register the theme at app startup via the Kongponents plugin:
+
+```ts
+// main.ts
+import { createApp } from 'vue'
+import Kongponents from '@kong/kongponents'
+import { myTheme } from './my-app-theme'
+import App from './App.vue'
+
+createApp(App)
+  .use(Kongponents, { theme: myTheme })
+  .mount('#app')
+```
+
+Or apply a theme to a specific subtree at runtime using `KThemeProvider`:
+
+```vue
+<template>
+  <KThemeProvider :theme="myTheme">
+    <!-- everything here renders with myTheme active -->
+  </KThemeProvider>
+</template>
+```
+
+For per-tenant runtime composition (e.g. theme values fetched from an API), use `applyTheme` from `@kong/kongponents`:
+
+```ts
+import { applyTheme } from '@kong/kongponents'
+import { electricLimeDay } from '@kong/design-tokens/themes'
+
+// Merge the base theme with tenant-specific overrides, then apply to :root
+applyTheme({ ...electricLimeDay, ...tenantOverrides })
+```
+
 #### Server-Side Rendering (SSR)
 
 If your host application utilizes SSR, you may need to resolve aliases to the package exports.
@@ -276,22 +411,25 @@ To get started, install the package dependencies from the repo root:
 pnpm install
 ```
 
-### Token Requirements
+### Directory structure
 
-- Tokens **must** be defined in the corresponding JSON files within the `packages/design-tokens/tokens/` directory in one of two sub-directories:
+The package is organized around three top-level source directories:
 
-    Directory | Description
-    ---------|----------
-    `/tokens/alias` | The `alias` directory **must** only contain alias values that point directly to a raw CSS value. Any tokens defined within the `alias` directory **will not** be exposed in the package exports. Tokens defined in the `/tokens/alias/` directory can be utilized/referenced within the `/tokens/source/` files; however, these tokens will **NOT** be exported in the build files.
-    `/tokens/source` | The `source` directory contains all tokens that **will be** available for consumption from the package exports.
+| Directory | Purpose |
+|-----------|---------|
+| `tokens/source/` | **Semantic tokens** exported to `custom-properties.css`, SCSS, and JS. Each token family is its own subdirectory: `color/`, `space/`, `shadow/`, `font/`, `border/`, `animation/`, `breakpoint/`, `letter-spacing/`, `line-height/`, plus the concept-named families `method/`, `status/`, `navigation/`, and `icon/` (HTTP methods, status codes, navigation chrome, icons). |
+| `tokens/components/` | **Component tokens** — name-only override slots for Kongponents components (`button/`, `card/`, `input/`, `badge/`, …). All `$value` fields must be `""`. Included in `KUI_THEMEABLE_TOKENS` — no CSS, no SCSS/JS values emitted. |
+| `themes/` | **Named theme override sets**, one directory per theme (`themes/<name>/`), each holding two co-located files: `<name>.theme.json` (the token values that activate for `[data-kui-theme="<name>"]`) and `<name>.alias.color.json` (that theme's color palette — the **internal alias tokens**, never exported, that `<name>.theme.json`'s `{color.alias.*}` references resolve against). Both filenames are required and enforced by the build and tests. `themes/_manifest.alias.color.json` is the names-only contract every palette must match. |
+
+### Token Requirements
 
 - Token keys **must** be lowercase, snake_case, and defined in normal alphabetical order (rules enforced by the eslint config)
-- The `category` of each token should be its own directory (e.g. `tokens/color/`)
-- Each `type` of token should be a file in the `category` directory, named `{type}.json` (e.g. `tokens/color/background.json`)
-- If there is only a single `type` of token within a `category`, you **should** name the file `index.json` (e.g. `tokens/line-height/index.json`)
-- Component tokens **must** be defined within the `/tokens/source/components/` directory. All tokens for a component should be defined in a single JSON file, `{component-name}.json`, with the name of the component as the top-level property in the file.
-- Token aliases (e.g. color aliases) **must not** be exposed/exported from the package exports
+- The `category` of each token should be its own directory (e.g. `tokens/source/color/`)
+- Each `type` of token should be a file in the `category` directory, named `{type}.json` (e.g. `tokens/source/color/background.json`)
+- If there is only a single `type` of token within a `category`, you **should** name the file `index.json` (e.g. `tokens/source/line-height/index.json`)
+- Alias tokens (`themes/<name>/<name>.alias.color.json`) **must not** be exposed/exported from the package exports
 - Tokens at the "root" of their structure **must** be defined with a key of `"_"` to allow for nested child tokens.
+- Component tokens in `tokens/components/` **must always have `$value: ""`** — they are name-only slots with no CSS value. A non-empty `$value` is a build violation caught by the test suite.
 
     <details>
 
@@ -302,17 +440,17 @@ pnpm install
       "color": {
         "text": {
           "_": {
-            "comment": "blue-100",
-            "value": "{color.alias.blue.100}"
+            "$description": "Default text color.",
+            "$value": "{color.alias.blue.100}"
           },
           "neutral": {
             "_": {
-              "comment": "gray-100",
-              "value": "{color.alias.gray.60}"
+              "$description": "Neutral text color.",
+              "$value": "{color.alias.gray.60}"
             },
             "strong": {
-              "comment": "gray-70",
-              "value": "{color.alias.gray.70}"
+              "$description": "Strong neutral text color.",
+              "$value": "{color.alias.gray.70}"
             }
           }
         }
@@ -329,6 +467,90 @@ pnpm install
 
     </details>
 
+### Creating a new theme
+
+A new theme is scaffolded **directly from the canonical token tree** — not copied from an existing
+theme. `pnpm theme:scaffold <name>` generates `themes/<name>/<name>.theme.json` and
+`themes/<name>/<name>.alias.color.json`:
+
+- Every **semantic** token (`tokens/source/**`) is seeded with its real default `{color.alias.*}`
+  mapping — a safe, sensible starting point.
+- Every **component** token (`tokens/components/**`) is seeded as an **empty slot** (`$value: ""`)
+  for you to fill deliberately — a component token's value is a genuine design decision (e.g. an
+  alert's danger background is a light tint, not the strong semantic danger color) and can't be
+  safely defaulted.
+- The **palette** is seeded from `classic-day`'s real neutral values, so the theme builds and
+  renders immediately, rather than from a placeholder.
+
+The result is **exhaustive by construction** — it contains exactly `KUI_THEMEABLE_TOKENS`, with no
+comparison against any other theme required. (For a **semantic-only** theme instead — every
+semantic token, **zero** component tokens, like `classic-day`/`classic-night` — scaffold normally,
+then delete the component-token entries and add the theme's name to `SEMANTIC_ONLY_THEMES` in
+`platforms/themes.mjs`.)
+
+```sh
+pnpm theme:scaffold my-brand
+# Fill in real palette values (themes/my-brand/my-brand.alias.color.json) and component
+# tokens (themes/my-brand/my-brand.theme.json) to taste.
+pnpm themes:unfilled my-brand   # reports empty component slots and palette families still
+                                # unchanged from the classic-day seed
+pnpm build:tokens && pnpm test  # the drift and off-source guards confirm completeness
+```
+
+The build auto-discovers any `themes/<name>/<name>.theme.json` — no code change needed. A theme
+directory whose `<name>.theme.json` is missing is a hard build error (and fails `pnpm test`), as is
+an alias-referencing theme with no matching `<name>.alias.color.json` palette (no silent fallback).
+See [`ALIAS-COLOR-MAPPING-GUIDE.md`](./docs/ALIAS-COLOR-MAPPING-GUIDE.md) §6, "Adding a future theme".
+
+**Keeping every theme in sync as the token set grows.** Adding a token to `tokens/source/**` or
+`tokens/components/**` doesn't require hand-editing every theme file — run `pnpm themes:sync` to
+add the new token to every theme (semantic tokens get their source default; component tokens get
+an empty slot to fill), or `pnpm themes:unfilled <name>` to check what any one theme still needs.
+
+> **Note — theme-creation skill dependency.** The `theme-creation` skill in
+> `packages/skills/theme-creation/` automates this flow end-to-end (scaffolding, matching a
+> source's look, previewing against Kongponents). It calls this package's `theme:scaffold` /
+> `themes:sync` / `themes:unfilled` commands directly rather than duplicating their logic, so
+> renaming or restructuring those commands (`scripts/theme-scaffold.mjs`, `scripts/themes-sync.mjs`,
+> `scripts/themes-unfilled.mjs`) only needs updating in one place — the skill won't silently drift
+> out of sync with them.
+
+### Theme `$description` authoring rules
+
+Every token entry in a theme JSON file may carry an optional `$description` field. When present, it must follow these rules:
+
+- **Match the semantic token's description** — copy the text from the corresponding token in `tokens/source/`. Do not invent a different description for the same concept.
+- **Never reference a CSS value** — descriptions must be value-agnostic. The description explains *what* the token controls, not *what value* it currently holds.
+
+| ❌ Avoid | ✅ Use instead |
+|---|---|
+| `"2px border radius."` | _(omit — scale tokens are self-documenting by name)_ |
+| `"Background color for containers (white)."` | `"Default background color for containers."` |
+| `"Border color for danger actions or messages (red.60)."` | `"Border color for danger actions or messages."` |
+| `"0px 0px 0px 1px blue.60 inset"` | `"Primary state inset border shadow."` |
+
+**When to omit `$description` entirely:** pure scale tokens (`--kui-space-*`, `--kui-border-radius-0` through `-50`, `--kui-border-width-*`, `--kui-icon-size-*`, `--kui-line-height-*`, `--kui-letter-spacing-*`) are self-documenting — their token names carry all the meaning. Leave `$description` off these entries.
+
+**Component tokens may appear in theme files with `$description`.** A theme may set any component token (`--kui-button-*`, `--kui-card-*`, etc.) to provide per-component customization that diverges from the semantic fallback. Use the same description as the component token's source definition in `tokens/components/`.
+
+```json
+// ✅ Correct — description matches source definition
+"kui-button-border-radius-medium": {
+  "$description": "Medium button border radius.",
+  "$value": "999px"
+}
+```
+
+**A theme file must define its full token set, not just the tokens it changes.** An exhaustive
+theme must contain exactly `KUI_THEMEABLE_TOKENS` (every semantic *and* component token); a
+semantic-only theme (`SEMANTIC_ONLY_THEMES`) must contain every semantic token and zero component
+tokens — nothing may be missing, even if its value is identical to another theme's. The
+`[data-kui-theme]` CSS cascade / `var()` fallback behavior governs runtime behavior for *component*
+tokens that are legitimately absent from a semantic-only theme (they fall through to the semantic
+layer) — it does not mean a theme file itself may omit tokens whose value happens not to differ.
+`pnpm theme:scaffold` and `pnpm themes:sync` handle this for you: every scaffolded or synced theme
+already contains its full required set.
+
 ### Development Sandbox
 
 This package includes a Vue sandbox (see the `sandbox/` directory) to allow you to experiment with consuming tokens.
@@ -345,7 +567,7 @@ Or from within this package directory:
 pnpm sandbox
 ```
 
-This command will simultaneously start the Vite dev server and initialize a watcher on the `tokens/` directory. If any files in the `tokens/` directory are modified, the sandbox will automatically run the build command to update the tokens and then restart the Vite dev server (simulating hot module reload).
+This command simultaneously starts the Vite dev server and watches both the `tokens/` and `themes/` directories. Changes to either trigger a rebuild and restart the Vite dev server.
 
 Updating any files within the sandbox itself will also trigger hot module reload as expected.
 
@@ -399,7 +621,7 @@ For example, if I want to add a new `my-feature` folder, I'd update the `exports
 
 1. Ensure you are on the `main` branch, then pull down the latest code by running `git checkout main && git pull origin main`
 2. Checkout a new branch for your changes with `git checkout -b {type}/{jira-ticket}-{description}` — as an example, `git checkout feat/khcp-1234-add-color-tokens`
-3. Add/edit the tokens in the `packages/design-tokens/tokens/` directory as needed, ensuring to adhere to the [Token Requirements](#token-requirements)
+3. Add/edit the tokens in the `tokens/` or `themes/` directory as needed, ensuring to adhere to the [Token Requirements](#token-requirements)
 4. Before committing your changes, locally run `pnpm lint` to ensure you do not have any linting errors. If you have errors, you can try running `pnpm lint:fix` to resolve
 5. Commit your changes, adhering to [Conventional Commits](#committing-changes). To make this easier, you're encouraged to run `pnpm commit` from the repo root to help build your commit message
 6. Push your branch up to the remote with `git push origin {branch-name}`