@adobe/design-data-spec 0.9.0 → 0.10.0

package/spec/token-format.md

@@ -35,7 +35,7 @@ A token's `name` field **MAY** be a non-empty plain string instead of a name obj
 
 **NORMATIVE:** String-named tokens **MUST** trigger rule SPEC-017 (severity: `warning`, category: `tech-debt`). The warning surfaces the token as tracked debt requiring future remediation.
 
-**NORMATIVE:** String-named tokens **MUST NOT** participate in name-object cascade dimension matching, specificity calculation, or registry vocabulary checks (SPEC-009 does not apply).
+**NORMATIVE:** String-named tokens **MUST NOT** participate in name-object cascade mode-set matching, specificity calculation, or registry vocabulary checks (SPEC-009 does not apply).
 
 **RECOMMENDED:** Authors **SHOULD** treat string names as a temporary escape hatch and track a remediation plan. Each string-named token **SHOULD** eventually be given a structured name object, at which point SPEC-017 no longer fires.
 
@@ -45,9 +45,9 @@ The **name object** identifies the token in a structured way. Implementations us
 
 **NORMATIVE fields** (all string unless noted):
 
-The set of available name-object fields is declared in the design system's **field catalog** (`fields/` directory). Each field declaration conforms to [`field.schema.json`](../schemas/field.schema.json) and specifies its kind (`semantic` or `dimension`), vocabulary registry, validation severity, and default serialization position. See [Taxonomy](taxonomy.md) for the full concept category hierarchy, component anatomy vs. token objects, and serialization rules.
+The set of available name-object fields is declared in the design system's **field catalog** (`fields/` directory). Each field declaration conforms to [`field.schema.json`](../schemas/field.schema.json) and specifies its kind (`semantic` or `mode-set`), vocabulary registry, validation severity, and default serialization position. See [Taxonomy](taxonomy.md) for the full concept category hierarchy, component anatomy vs. token objects, and serialization rules.
 
-Fields are divided into **semantic fields** (identity, structure, intent) and **dimension fields** (axes of variation for cascade resolution). The tables below list Spectrum's foundation-standard fields as declared in the catalog.
+Fields are divided into **semantic fields** (identity, structure, intent) and **mode-set fields** (axes of variation for cascade resolution). The tables below list Spectrum's foundation-standard fields as declared in the catalog.
 
 #### Semantic fields
 
@@ -67,16 +67,16 @@ Fields are divided into **semantic fields** (identity, structure, intent) and **
 | `density`      | OPTIONAL | Density           | Space within or around component parts (e.g. `spacious`, `compact`).                                                                                                     |
 | `shape`        | OPTIONAL | Shape             | Relative to overall component shape (e.g. `uniform`).                                                                                                                    |
 
-#### Dimension fields
+#### Mode-set fields
 
-| Field           | Status   | Description                                                                                     |
-| --------------- | -------- | ----------------------------------------------------------------------------------------------- |
-| `colorScheme`   | OPTIONAL | Dimension: light / dark / wireframe / etc.                                                      |
-| `scale`         | OPTIONAL | Dimension: platform density scale (e.g. `desktop`, `mobile`). Distinct from semantic `size`.    |
-| `contrast`      | OPTIONAL | Dimension: contrast level (e.g. `regular`, `high`).                                             |
-| Additional keys | OPTIONAL | Other dimensions declared in the dataset’s dimension catalog (see [Dimensions](dimensions.md)). |
+| Field           | Status   | Description                                                                                 |
+| --------------- | -------- | ------------------------------------------------------------------------------------------- |
+| `colorScheme`   | OPTIONAL | Mode set: light / dark / wireframe / etc.                                                   |
+| `scale`         | OPTIONAL | Mode set: platform density scale (e.g. `desktop`, `mobile`). Distinct from semantic `size`. |
+| `contrast`      | OPTIONAL | Mode set: contrast level (e.g. `regular`, `high`).                                          |
+| Additional keys | OPTIONAL | Other mode sets declared in the dataset’s mode set catalog (see [Mode Sets](mode-sets.md)). |
 
-**NORMATIVE:** Each field is validated according to the `validation` severity declared in its field declaration. Semantic fields typically use **advisory** severity (warning); dimension fields use **strict** severity (error). See [Taxonomy — Name object field categories](taxonomy.md#name-object-field-categories).
+**NORMATIVE:** Each field is validated according to the `validation` severity declared in its field declaration. Semantic fields typically use **advisory** severity (warning); mode-set fields use **strict** severity (error). See [Taxonomy — Name object field categories](taxonomy.md#name-object-field-categories).
 
 **RECOMMENDED:** Name objects use a consistent key ordering in authored files for diffs; this is not a conformance requirement. Concept ordering for serialized names is defined in [Taxonomy — Default serialization](taxonomy.md#default-serialization-legacy-format).
 
@@ -249,7 +249,7 @@ The current `@adobe/spectrum-tokens` JSON uses **sets** (`color-set`, `scale-set
 | ------------------- | -------------------------------------------------------------------------- | -------------------------------------------------------------------------- |
 | Identity field      | `id`                                                                       | `uuid`                                                                     |
 | Name model          | `name.original` (string) + `name.structure` (nested object)                | Flat fields directly on `name` (`property`, `component`, `colorScheme`, …) |
-| Complexity tracking | `name.semanticComplexity` (stored on token)                                | Computed at validation time from dimension declarations                    |
+| Complexity tracking | `name.semanticComplexity` (stored on token)                                | Computed at validation time from mode set declarations                     |
 
 **NORMATIVE:** The flat `name` object defined in this spec is the authoritative serialization format. RFC [#646](https://github.com/adobe/spectrum-design-data/issues/646)'s `name.structure` / `name.original` shape is not a conformance target; it remains a useful reference for the analytical model that informed this design.
 

package/spec/dimensions.md

@@ -1,64 +0,0 @@
-# Dimensions
-
-**Spec version:** `1.0.0-draft` (see [Overview](index.md))
-
-This document defines how **dimensions** (modes such as color scheme, scale, contrast) are **declared**, assigned **defaults**, and validated for **coverage**.
-
-## Dimension declaration
-
-A **dimension declaration** is a JSON object describing one axis of variation. It **MUST** conform to [`dimension.schema.json`](../schemas/dimension.schema.json) (canonical `$id`: `https://opensource.adobe.com/spectrum-design-data/schemas/v0/dimension.schema.json`).
-
-### Required fields
-
-| Field     | Description                                               |
-| --------- | --------------------------------------------------------- |
-| `name`    | Stable identifier for the dimension (e.g. `colorScheme`). |
-| `modes`   | Array of allowed mode values (strings).                   |
-| `default` | Default mode; **MUST** be a member of `modes`.            |
-
-### Optional fields
-
-| Field         | Description                          |
-| ------------- | ------------------------------------ |
-| `description` | Human-readable documentation.        |
-| `coverage`    | Rules for mode coverage (see below). |
-
-## Built-in dimensions
-
-These dimensions are declared in the `dimensions/` catalog (see [Dimension catalog](#dimension-catalog)) and **SHOULD** be used consistently across Spectrum-compatible datasets:
-
-| `name`        | `modes`                      | `default` | Notes                                                                             |
-| ------------- | ---------------------------- | --------- | --------------------------------------------------------------------------------- |
-| `colorScheme` | `light`, `dark`, `wireframe` | `light`   | Theme / appearance.                                                               |
-| `scale`       | `desktop`, `mobile`          | `desktop` | Density scale. Legacy names; desktop = medium, mobile = large in W3C terminology. |
-| `contrast`    | `regular`, `high`            | `regular` | Accessibility contrast level.                                                     |
-
-## Dimension catalog
-
-The Spectrum foundation publishes dimension declarations as JSON files under `packages/design-data-spec/dimensions/`. Each file conforms to [`dimension.schema.json`](../schemas/dimension.schema.json).
-
-**NORMATIVE:** Tooling (validators, resolution engine) **MUST** load dimension declarations from the dataset’s dimension catalog before performing specificity calculations or coverage validation.
-
-**RECOMMENDED:** The catalog directory is named `dimensions/` and is co-located with the dataset’s spec package or manifest.
-
-## Optional dimensions
-
-Additional dimensions (e.g. `language`, `motion`) **MAY** be declared in a dataset’s dimension catalog. Token name objects **MAY** include keys matching declared dimension names.
-
-## Defaults and specificity
-
-**NORMATIVE:** A token name object **omitting** a dimension field implies the token applies under the dimension’s **`default`** mode for specificity and matching purposes unless the spec for that dimension states otherwise.
-
-**NORMATIVE:** Only **non-default** dimension fields on the name object increase **semantic specificity** (see [Cascade](cascade.md)).
-
-## Coverage validation
-
-**RECOMMENDED:** If a dimension’s `coverage` requires **peer modes** (e.g. defining `dark` requires `light`), validators implement rule **`SPEC-005`** (see `rules/rules.yaml`).
-
-**RECOMMENDED:** Explicit **combination** tokens are used for rare cross-dimensional cases instead of inferring Cartesian products.
-
-## References
-
-* [#646 — Token Schema Structure and Validation System](https://github.com/adobe/spectrum-design-data/discussions/646)
-* [#714 — Design Data Specification](https://github.com/adobe/spectrum-design-data/discussions/714)
-* [#746 — Phase 2: Dimension declarations (machine-readable)](https://github.com/adobe/spectrum-design-data/issues/746)

package/src/canonical.js

@@ -1,61 +0,0 @@
-/*
-Copyright 2026 Adobe. All rights reserved.
-This file is licensed to you under the Apache License, Version 2.0 (the "License");
-you may not use this file except in compliance with the License. You may obtain a copy
-of the License at http://www.apache.org/licenses/LICENSE-2.0
-
-Unless required by applicable law or agreed to in writing, software distributed under
-the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR REPRESENTATIONS
-OF ANY KIND, either express or implied. See the License for the specific language
-governing permissions and limitations under the License.
-*/
-
-// Canonical vocabulary sets derived from spec chapters.
-// Sources: spec/component-format.md, spec/anatomy-format.md, spec/state-model.md
-
-export const CANONICAL_SLOTS = new Set([
-  "default",
-  "icon",
-  "label",
-  "help-text",
-  "negative-help-text",
-  "action",
-  "heading",
-  "description",
-  "hero",
-  "footer",
-  "tooltip",
-]);
-
-export const CANONICAL_ANATOMY_PARTS = new Set([
-  "body",
-  "checkmark",
-  "disclosure-triangle",
-  "field",
-  "handle",
-  "header",
-  "icon",
-  "label",
-  "picker",
-  "progress-bar",
-  "swatch",
-  "thumbnail",
-  "track",
-  "value",
-]);
-
-export const CANONICAL_STATES = new Set([
-  "default",
-  "hover",
-  "focus",
-  "focus-visible",
-  "active",
-  "pressed",
-  "selected",
-  "indeterminate",
-  "disabled",
-  "read-only",
-  "invalid",
-  "valid",
-  "dragging",
-]);

package/src/validate.js

@@ -1,190 +0,0 @@
-/*
-Copyright 2026 Adobe. All rights reserved.
-This file is licensed to you under the Apache License, Version 2.0 (the "License");
-you may not use this file except in compliance with the License. You may obtain a copy
-of the License at http://www.apache.org/licenses/LICENSE-2.0
-
-Unless required by applicable law or agreed to in writing, software distributed under
-the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR REPRESENTATIONS
-OF ANY KIND, either express or implied. See the License for the specific language
-governing permissions and limitations under the License.
-*/
-
-/**
- * Layer 2 cross-reference validator for design-data-spec.
- *
- * Implements SPEC-018 through SPEC-027: semantic rules that validate token
- * name-object fields against component declarations, validate component
- * declarations internally, and validate tokenBindings references.
- *
- * @see spec/component-format.md#spec-rules
- * @see spec/anatomy-format.md#spec-rules
- * @see spec/state-model.md#spec-rules
- */
-
-import {
-  CANONICAL_SLOTS,
-  CANONICAL_ANATOMY_PARTS,
-  CANONICAL_STATES,
-} from "./canonical.js";
-
-/**
- * @typedef {{ ruleId: string, severity: 'error'|'warning', message: string, tokenName?: string, componentName?: string }} Diagnostic
- * @typedef {{ name: string|object, [key: string]: unknown }} Token
- * @typedef {{ name: string, options?: object, anatomy?: Array<{name:string,description?:string}>, slots?: Array<{name:string,description?:string}>, states?: Array<{name:string,trigger?:string,precedence?:number,layered?:boolean,description?:string}> }} ComponentDeclaration
- * @typedef {{ tokens?: Token[], components?: ComponentDeclaration[] }} Dataset
- */
-
-/**
- * Validate a dataset for SPEC-018 through SPEC-024 compliance.
- *
- * @param {Dataset} dataset
- * @returns {Diagnostic[]}
- */
-export function validateDataset(dataset) {
-  const tokens = dataset.tokens ?? [];
-  const components = dataset.components ?? [];
-
-  // Build component lookup map keyed by name.
-  const componentMap = new Map(components.map((c) => [c.name, c]));
-
-  const diagnostics = [];
-
-  // --- Token cross-reference rules ---
-  for (const token of tokens) {
-    const name = token.name;
-    // String names (SPEC-017 escape hatch) skip cross-reference checks.
-    if (typeof name !== "object" || name === null) continue;
-
-    const tokenLabel = JSON.stringify(name);
-
-    if (name.component != null) {
-      // SPEC-018: component name must be declared
-      if (!componentMap.has(name.component)) {
-        diagnostics.push({
-          ruleId: "SPEC-018",
-          severity: "error",
-          message: `Token '${tokenLabel}' references undeclared component '${name.component}'`,
-          tokenName: tokenLabel,
-        });
-        // Can't validate further fields without a component declaration.
-        continue;
-      }
-
-      const component = componentMap.get(name.component);
-
-      // SPEC-019: variant must be in component's variant option enum
-      if (name.variant != null) {
-        const variantEnum = component.options?.variant?.enum;
-        if (Array.isArray(variantEnum) && !variantEnum.includes(name.variant)) {
-          diagnostics.push({
-            ruleId: "SPEC-019",
-            severity: "error",
-            message: `Token '${tokenLabel}' has variant '${name.variant}' which is not declared on component '${name.component}'`,
-            tokenName: tokenLabel,
-            componentName: name.component,
-          });
-        }
-      }
-
-      // SPEC-020: anatomy must match a declared anatomy part name
-      if (name.anatomy != null) {
-        const declaredParts = new Set(
-          (component.anatomy ?? []).map((p) => p.name),
-        );
-        if (declaredParts.size > 0 && !declaredParts.has(name.anatomy)) {
-          diagnostics.push({
-            ruleId: "SPEC-020",
-            severity: "error",
-            message: `Token '${tokenLabel}' references undeclared anatomy part '${name.anatomy}' on component '${name.component}'`,
-            tokenName: tokenLabel,
-            componentName: name.component,
-          });
-        }
-      }
-
-      // SPEC-022: state must match a declared state name (only when states are declared)
-      if (name.state != null) {
-        const declaredStates = new Set(
-          (component.states ?? []).map((s) => s.name),
-        );
-        if (declaredStates.size > 0 && !declaredStates.has(name.state)) {
-          diagnostics.push({
-            ruleId: "SPEC-022",
-            severity: "error",
-            message: `Token '${tokenLabel}' references undeclared state '${name.state}' on component '${name.component}'`,
-            tokenName: tokenLabel,
-            componentName: name.component,
-          });
-        }
-      }
-    }
-  }
-
-  // --- Component declaration internal rules ---
-  for (const component of components) {
-    const cName = component.name;
-
-    // SPEC-021: custom slot names should have descriptions
-    for (const slot of component.slots ?? []) {
-      if (!CANONICAL_SLOTS.has(slot.name) && !slot.description) {
-        diagnostics.push({
-          ruleId: "SPEC-021",
-          severity: "warning",
-          message: `Component '${cName}' has custom slot '${slot.name}' with no description — add a description or use a canonical slot name`,
-          componentName: cName,
-        });
-      }
-    }
-
-    // SPEC-023: custom anatomy part names should have descriptions
-    for (const part of component.anatomy ?? []) {
-      if (!CANONICAL_ANATOMY_PARTS.has(part.name) && !part.description) {
-        diagnostics.push({
-          ruleId: "SPEC-023",
-          severity: "warning",
-          message: `Component '${cName}' has custom anatomy part '${part.name}' with no description`,
-          componentName: cName,
-        });
-      }
-    }
-
-    // SPEC-024: custom state names should have descriptions
-    for (const state of component.states ?? []) {
-      if (!CANONICAL_STATES.has(state.name) && !state.description) {
-        diagnostics.push({
-          ruleId: "SPEC-024",
-          severity: "warning",
-          message: `Component '${cName}' has custom state '${state.name}' with no description`,
-          componentName: cName,
-        });
-      }
-    }
-  }
-
-  // --- Token binding rules ---
-
-  // SPEC-027: each tokenBindings[].token must resolve to a known token name.
-  // String-named tokens are matched directly. Name-object tokens are skipped
-  // here because tokenBindings always reference tokens by their string name.
-  const tokenNameSet = new Set(
-    tokens
-      .map((t) => (typeof t.name === "string" ? t.name : null))
-      .filter(Boolean),
-  );
-
-  for (const component of components) {
-    for (const binding of component.tokenBindings ?? []) {
-      if (!tokenNameSet.has(binding.token)) {
-        diagnostics.push({
-          ruleId: "SPEC-027",
-          severity: "error",
-          message: `Component '${component.name}' tokenBindings references unknown token '${binding.token}'`,
-          componentName: component.name,
-        });
-      }
-    }
-  }
-
-  return diagnostics;
-}