@adobe/design-data-spec 1.3.0 → 1.5.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/conformance/invalid/SPEC-042/dataset.json +21 -0
- package/conformance/invalid/SPEC-042/expected-errors.json +15 -0
- package/conformance/invalid/SPEC-043/dataset.json +20 -0
- package/conformance/invalid/SPEC-043/expected-errors.json +15 -0
- package/fields/alignment.json +15 -0
- package/fields/colorFamily.json +15 -0
- package/fields/easing.json +15 -0
- package/fields/family.json +15 -0
- package/fields/motionRole.json +15 -0
- package/fields/scaleIndex.json +1 -1
- package/fields/style.json +15 -0
- package/fields/weight.json +15 -0
- package/package.json +1 -1
- package/rules/rules.yaml +40 -0
- package/schemas/manifest.schema.json +8 -1
- package/spec/taxonomy.md +135 -5
- package/spec/token-format.md +16 -0
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
{
|
|
2
|
+
"tokens": [
|
|
3
|
+
{
|
|
4
|
+
"$schema": "https://opensource.adobe.com/spectrum-design-data/schemas/token-types/font-weight.json",
|
|
5
|
+
"name": {
|
|
6
|
+
"property": "font-weight",
|
|
7
|
+
"colorFamily": "blue"
|
|
8
|
+
},
|
|
9
|
+
"value": "bold"
|
|
10
|
+
},
|
|
11
|
+
{
|
|
12
|
+
"$schema": "https://opensource.adobe.com/spectrum-design-data/schemas/token-types/color.json",
|
|
13
|
+
"name": {
|
|
14
|
+
"property": "color",
|
|
15
|
+
"weight": "bold"
|
|
16
|
+
},
|
|
17
|
+
"value": "#0265dc"
|
|
18
|
+
}
|
|
19
|
+
],
|
|
20
|
+
"components": []
|
|
21
|
+
}
|
|
@@ -0,0 +1,15 @@
|
|
|
1
|
+
{
|
|
2
|
+
"layer": 2,
|
|
3
|
+
"errors": [
|
|
4
|
+
{
|
|
5
|
+
"rule_id": "SPEC-042",
|
|
6
|
+
"severity": "warning",
|
|
7
|
+
"message_pattern": ".*colorFamily.*color-scoped.*font-weight.*"
|
|
8
|
+
},
|
|
9
|
+
{
|
|
10
|
+
"rule_id": "SPEC-042",
|
|
11
|
+
"severity": "warning",
|
|
12
|
+
"message_pattern": ".*weight.*typography-scoped.*color.*"
|
|
13
|
+
}
|
|
14
|
+
]
|
|
15
|
+
}
|
|
@@ -0,0 +1,20 @@
|
|
|
1
|
+
{
|
|
2
|
+
"tokens": [
|
|
3
|
+
{
|
|
4
|
+
"$schema": "https://opensource.adobe.com/spectrum-design-data/schemas/token-types/color.json",
|
|
5
|
+
"name": {
|
|
6
|
+
"property": "color",
|
|
7
|
+
"state": "hover"
|
|
8
|
+
},
|
|
9
|
+
"value": "#0265dc"
|
|
10
|
+
},
|
|
11
|
+
{
|
|
12
|
+
"$schema": "https://opensource.adobe.com/spectrum-design-data/schemas/token-types/font-weight.json",
|
|
13
|
+
"name": {
|
|
14
|
+
"property": "font-weight"
|
|
15
|
+
},
|
|
16
|
+
"value": "bold"
|
|
17
|
+
}
|
|
18
|
+
],
|
|
19
|
+
"components": []
|
|
20
|
+
}
|
|
@@ -0,0 +1,15 @@
|
|
|
1
|
+
{
|
|
2
|
+
"layer": 2,
|
|
3
|
+
"errors": [
|
|
4
|
+
{
|
|
5
|
+
"rule_id": "SPEC-043",
|
|
6
|
+
"severity": "warning",
|
|
7
|
+
"message_pattern": ".*color.*no domain-identifying field.*colorFamily.*"
|
|
8
|
+
},
|
|
9
|
+
{
|
|
10
|
+
"rule_id": "SPEC-043",
|
|
11
|
+
"severity": "warning",
|
|
12
|
+
"message_pattern": ".*typography.*no domain-identifying field.*family.*"
|
|
13
|
+
}
|
|
14
|
+
]
|
|
15
|
+
}
|
|
@@ -0,0 +1,15 @@
|
|
|
1
|
+
{
|
|
2
|
+
"$schema": "https://opensource.adobe.com/spectrum-design-data/schemas/v0/field.schema.json",
|
|
3
|
+
"specVersion": "1.0.0-draft",
|
|
4
|
+
"name": "alignment",
|
|
5
|
+
"description": "Horizontal alignment of a text-align token. Corresponds to the CSS text-align axis.",
|
|
6
|
+
"kind": "semantic",
|
|
7
|
+
"registry": "packages/design-system-registry/registry/alignments.json",
|
|
8
|
+
"validation": "advisory",
|
|
9
|
+
"serialization": {
|
|
10
|
+
"position": 25
|
|
11
|
+
},
|
|
12
|
+
"scope": "typography",
|
|
13
|
+
"required": false,
|
|
14
|
+
"valueType": "string"
|
|
15
|
+
}
|
|
@@ -0,0 +1,15 @@
|
|
|
1
|
+
{
|
|
2
|
+
"$schema": "https://opensource.adobe.com/spectrum-design-data/schemas/v0/field.schema.json",
|
|
3
|
+
"specVersion": "1.0.0-draft",
|
|
4
|
+
"name": "colorFamily",
|
|
5
|
+
"description": "Hue family of a color token (e.g. blue, gray, celery, accent). Used on color palette and semantic color tokens. Paired with scaleIndex for ramp tokens (e.g. colorFamily=blue + scaleIndex=100 → blue-100).",
|
|
6
|
+
"kind": "semantic",
|
|
7
|
+
"registry": "packages/design-system-registry/registry/color-families.json",
|
|
8
|
+
"validation": "advisory",
|
|
9
|
+
"serialization": {
|
|
10
|
+
"position": 17
|
|
11
|
+
},
|
|
12
|
+
"scope": "color",
|
|
13
|
+
"required": false,
|
|
14
|
+
"valueType": "string"
|
|
15
|
+
}
|
|
@@ -0,0 +1,15 @@
|
|
|
1
|
+
{
|
|
2
|
+
"$schema": "https://opensource.adobe.com/spectrum-design-data/schemas/v0/field.schema.json",
|
|
3
|
+
"specVersion": "1.0.0-draft",
|
|
4
|
+
"name": "easing",
|
|
5
|
+
"description": "Easing curve identifier for a motion token (e.g. ease-in, ease-out, standard). Registry is provisional until motion tokens are added to the foundation.",
|
|
6
|
+
"kind": "semantic",
|
|
7
|
+
"registry": "packages/design-system-registry/registry/easing-curves.json",
|
|
8
|
+
"validation": "advisory",
|
|
9
|
+
"serialization": {
|
|
10
|
+
"position": 22
|
|
11
|
+
},
|
|
12
|
+
"scope": "motion",
|
|
13
|
+
"required": false,
|
|
14
|
+
"valueType": "string"
|
|
15
|
+
}
|
|
@@ -0,0 +1,15 @@
|
|
|
1
|
+
{
|
|
2
|
+
"$schema": "https://opensource.adobe.com/spectrum-design-data/schemas/v0/field.schema.json",
|
|
3
|
+
"specVersion": "1.0.0-draft",
|
|
4
|
+
"name": "family",
|
|
5
|
+
"description": "Type family of a typography token (e.g. sans-serif, serif, cjk, code). Used to distinguish tokens that apply to different script or display contexts.",
|
|
6
|
+
"kind": "semantic",
|
|
7
|
+
"registry": "packages/design-system-registry/registry/typography-families.json",
|
|
8
|
+
"validation": "advisory",
|
|
9
|
+
"serialization": {
|
|
10
|
+
"position": 18
|
|
11
|
+
},
|
|
12
|
+
"scope": "typography",
|
|
13
|
+
"required": false,
|
|
14
|
+
"valueType": "string"
|
|
15
|
+
}
|
|
@@ -0,0 +1,15 @@
|
|
|
1
|
+
{
|
|
2
|
+
"$schema": "https://opensource.adobe.com/spectrum-design-data/schemas/v0/field.schema.json",
|
|
3
|
+
"specVersion": "1.0.0-draft",
|
|
4
|
+
"name": "motionRole",
|
|
5
|
+
"description": "Semantic role of a motion token — the interaction pattern it governs (e.g. enter, exit, transition, emphasis). Registry is provisional until motion tokens are added to the foundation.",
|
|
6
|
+
"kind": "semantic",
|
|
7
|
+
"registry": "packages/design-system-registry/registry/motion-roles.json",
|
|
8
|
+
"validation": "advisory",
|
|
9
|
+
"serialization": {
|
|
10
|
+
"position": 21
|
|
11
|
+
},
|
|
12
|
+
"scope": "motion",
|
|
13
|
+
"required": false,
|
|
14
|
+
"valueType": "string"
|
|
15
|
+
}
|
package/fields/scaleIndex.json
CHANGED
|
@@ -0,0 +1,15 @@
|
|
|
1
|
+
{
|
|
2
|
+
"$schema": "https://opensource.adobe.com/spectrum-design-data/schemas/v0/field.schema.json",
|
|
3
|
+
"specVersion": "1.0.0-draft",
|
|
4
|
+
"name": "style",
|
|
5
|
+
"description": "Typographic style of a typography token (e.g. italic, oblique). Corresponds to the CSS font-style axis. Normal style is omitted (default).",
|
|
6
|
+
"kind": "semantic",
|
|
7
|
+
"registry": "packages/design-system-registry/registry/typography-styles.json",
|
|
8
|
+
"validation": "advisory",
|
|
9
|
+
"serialization": {
|
|
10
|
+
"position": 20
|
|
11
|
+
},
|
|
12
|
+
"scope": "typography",
|
|
13
|
+
"required": false,
|
|
14
|
+
"valueType": "string"
|
|
15
|
+
}
|
|
@@ -0,0 +1,15 @@
|
|
|
1
|
+
{
|
|
2
|
+
"$schema": "https://opensource.adobe.com/spectrum-design-data/schemas/v0/field.schema.json",
|
|
3
|
+
"specVersion": "1.0.0-draft",
|
|
4
|
+
"name": "weight",
|
|
5
|
+
"description": "Typographic weight of a typography token (e.g. regular, bold, light, black). Corresponds to the CSS font-weight axis.",
|
|
6
|
+
"kind": "semantic",
|
|
7
|
+
"registry": "packages/design-system-registry/registry/typography-weights.json",
|
|
8
|
+
"validation": "advisory",
|
|
9
|
+
"serialization": {
|
|
10
|
+
"position": 19
|
|
11
|
+
},
|
|
12
|
+
"scope": "typography",
|
|
13
|
+
"required": false,
|
|
14
|
+
"valueType": "string"
|
|
15
|
+
}
|
package/package.json
CHANGED
package/rules/rules.yaml
CHANGED
|
@@ -436,3 +436,43 @@ rules:
|
|
|
436
436
|
message: "Token group '{base_name}' has no resolvable candidate under manifest mode-set restrictions ({restrictions})"
|
|
437
437
|
spec_ref: spec/mode-sets.md#platform-restrictions
|
|
438
438
|
introduced_in: "1.0.0-draft"
|
|
439
|
+
|
|
440
|
+
- id: SPEC-042
|
|
441
|
+
name: field-scope-violation
|
|
442
|
+
severity: warning
|
|
443
|
+
layer: 2
|
|
444
|
+
category: taxonomy
|
|
445
|
+
rfc: "#806"
|
|
446
|
+
assert: >
|
|
447
|
+
When a token's name object contains a domain-scoped field (e.g. `colorFamily`,
|
|
448
|
+
`weight`, `motionRole`), the token's effective domain schema MUST be compatible
|
|
449
|
+
with that field's scope. For alias tokens (`alias.json`), the rule follows the
|
|
450
|
+
`alias_target` chain to the terminal non-alias schema before checking domain
|
|
451
|
+
compatibility — a color alias may carry `colorFamily` when its target is a
|
|
452
|
+
color-domain token. Using a color-scoped field on a typography token, or a
|
|
453
|
+
typography-scoped field on a color token, is a taxonomy violation. The set of
|
|
454
|
+
domain-scoped fields and their valid schema URL suffixes is declared in the field
|
|
455
|
+
catalog under `packages/design-data-spec/fields/` via the `scope` property.
|
|
456
|
+
Tokens without a `$schema` are skipped (domain cannot be determined).
|
|
457
|
+
message: "name.{field} is a {scope}-scoped field but token schema '{effective_schema}' is not a {scope} token type"
|
|
458
|
+
spec_ref: spec/taxonomy.md#token-type-taxonomies
|
|
459
|
+
introduced_in: "1.0.0-draft"
|
|
460
|
+
|
|
461
|
+
- id: SPEC-043
|
|
462
|
+
name: domain-required-fields
|
|
463
|
+
severity: warning
|
|
464
|
+
layer: 2
|
|
465
|
+
category: taxonomy
|
|
466
|
+
rfc: "#806"
|
|
467
|
+
assert: >
|
|
468
|
+
Tokens in a known domain SHOULD include at least one domain-identifying field in
|
|
469
|
+
their name object so tooling can group, sort, and validate them correctly.
|
|
470
|
+
Color tokens (schema: color.json, color-set.json) SHOULD have `colorFamily` or
|
|
471
|
+
`scaleIndex`. Typography tokens (schema: font-*.json, typography.json) SHOULD have
|
|
472
|
+
`family`, `weight`, or `style`. Motion tokens (schema: duration.json, motion.json)
|
|
473
|
+
SHOULD have `motionRole` or `easing`. String-named tokens and tokens without `$schema`
|
|
474
|
+
are skipped. Advisory severity: the existing corpus has not yet migrated to structured
|
|
475
|
+
name objects; this rule tracks progress rather than blocking.
|
|
476
|
+
message: "{domain} token has a name object but no domain-identifying field — add at least one of: {required_fields}"
|
|
477
|
+
spec_ref: spec/taxonomy.md#token-type-taxonomies
|
|
478
|
+
introduced_in: "1.0.0-draft"
|
package/spec/taxonomy.md
CHANGED
|
@@ -46,13 +46,17 @@ The taxonomy is designed with three guiding principles:
|
|
|
46
46
|
2. **Agnostic (with compromises)** — Platform-agnostic terms are used except when platforms have specific terms for the same concept. In those cases, the most common or clear term is used.
|
|
47
47
|
3. **Verified** — Multiple existing components must be rebuildable using the taxonomy system, and consumers must find them reasonably understandable or learnable.
|
|
48
48
|
|
|
49
|
-
##
|
|
49
|
+
## Token-type taxonomies
|
|
50
50
|
|
|
51
|
-
Concept categories for name-object fields are declared in the design system's **field catalog** — a set of field declarations in the `fields/` directory, each conforming to [`field.schema.json`](../schemas/field.schema.json). Each declaration specifies the field name, vocabulary registry, validation severity,
|
|
51
|
+
Concept categories for name-object fields are declared in the design system's **field catalog** — a set of field declarations in the `fields/` directory, each conforming to [`field.schema.json`](../schemas/field.schema.json). Each declaration specifies the field name, vocabulary registry, validation severity, default serialization position, and an optional **scope** that restricts the field to a specific token type.
|
|
52
52
|
|
|
53
53
|
**NORMATIVE:** The field catalog is the authoritative source for what fields exist on the name object. Tools, validators, and serializers **SHOULD** read the catalog rather than hardcoding field knowledge.
|
|
54
54
|
|
|
55
|
-
|
|
55
|
+
**NORMATIVE:** A field with a non-null `scope` declaration **MUST** only appear on tokens of that type. Using a scoped field on a mismatched token type triggers rule SPEC-042 (`field-scope-violation`, warning).
|
|
56
|
+
|
|
57
|
+
### Semantic / layout token taxonomy
|
|
58
|
+
|
|
59
|
+
The following concept categories are defined in Spectrum's foundation field catalog for semantic and layout tokens (`scope: null` — universal), ordered by default serialization position. This ordering is the **default serialization order** for legacy format output; it is not a conformance requirement for stored name objects.
|
|
56
60
|
|
|
57
61
|
**NORMATIVE:** Each category listed below corresponds to a field on the token [name object](token-format.md). Tokens **MAY** use any subset of these fields. Exception: `property` is REQUIRED on every name object — see [token-format.md](token-format.md#name-object).
|
|
58
62
|
|
|
@@ -77,7 +81,95 @@ Additional categories for variant and state are inherited from the existing name
|
|
|
77
81
|
| Variant | `variant` | Variant within a component (e.g. accent, negative, primary). |
|
|
78
82
|
| State | `state` | Interactive or semantic state (e.g. hover, focus, disabled). |
|
|
79
83
|
|
|
80
|
-
|
|
84
|
+
### Color token taxonomy
|
|
85
|
+
|
|
86
|
+
Color tokens describe palette entries and semantic color assignments. Their name objects use `scope: "color"` fields alongside the universal `property` and `state` fields.
|
|
87
|
+
|
|
88
|
+
**NORMATIVE:** Color tokens SHOULD include `colorFamily`, `scaleIndex`, or both to allow tooling to group and sort palette entries. Tokens missing both are flagged by rule SPEC-043 (`domain-required-fields`, warning).
|
|
89
|
+
|
|
90
|
+
| Category | Name object field | Answers | Description |
|
|
91
|
+
| ------------ | ----------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
92
|
+
| Color Family | `colorFamily` | What? | Hue family of the color (e.g. `blue`, `gray`, `celery`, `transparent-black`). Values come from [`color-families.json`](../../packages/design-system-registry/registry/color-families.json). |
|
|
93
|
+
| Ramp Index | `scaleIndex` | Which? | Numeric perceptual ramp step (e.g. `100`, `400`, `900`, `1600`). Shared with layout tokens; see [scaleIndex field declaration](../fields/scaleIndex.json). Not scope-restricted. |
|
|
94
|
+
|
|
95
|
+
**Default serialization order for color tokens:**
|
|
96
|
+
|
|
97
|
+
```
|
|
98
|
+
{variant}-{colorFamily}-{scaleIndex}
|
|
99
|
+
```
|
|
100
|
+
|
|
101
|
+
Example: `colorFamily=blue` + `scaleIndex=100` → `blue-100`.
|
|
102
|
+
|
|
103
|
+
### Typography token taxonomy
|
|
104
|
+
|
|
105
|
+
Typography tokens describe typeface attributes: family, weight, style, and numeric scale. Their name objects use `scope: "typography"` fields alongside the universal `property` field.
|
|
106
|
+
|
|
107
|
+
**NORMATIVE:** Typography tokens SHOULD include at least one of `family`, `weight`, or `style`. Tokens missing all three are flagged by rule SPEC-043 (`domain-required-fields`, warning).
|
|
108
|
+
|
|
109
|
+
| Category | Name object field | Answers | Description |
|
|
110
|
+
| --------- | ----------------- | ------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
111
|
+
| Family | `family` | What? | Type family of the token (e.g. `sans-serif`, `serif`, `cjk`, `code`). Values come from [`typography-families.json`](../../packages/design-system-registry/registry/typography-families.json). |
|
|
112
|
+
| Weight | `weight` | How? | Typographic weight (e.g. `regular`, `bold`, `light`, `black`). Values come from [`typography-weights.json`](../../packages/design-system-registry/registry/typography-weights.json). |
|
|
113
|
+
| Style | `style` | How? | Typographic style (e.g. `italic`, `oblique`, `normal`). Include `normal` when the token explicitly declares a normal style (e.g. a reset). Values come from [`typography-styles.json`](../../packages/design-system-registry/registry/typography-styles.json). |
|
|
114
|
+
| Alignment | `alignment` | How? | Horizontal text-alignment direction (e.g. `start`, `center`, `end`). Corresponds to the CSS `text-align` axis. Values come from [`alignments.json`](../../packages/design-system-registry/registry/alignments.json). |
|
|
115
|
+
| Scale | `scaleIndex` | Which? | Numeric size scale step (e.g. `75`, `100`, `200`). Shared with other token types; not scope-restricted. |
|
|
116
|
+
|
|
117
|
+
**Default serialization order for typography tokens:**
|
|
118
|
+
|
|
119
|
+
```
|
|
120
|
+
{family}-{weight}-{style}-{scaleIndex}
|
|
121
|
+
```
|
|
122
|
+
|
|
123
|
+
Example: `family=sans-serif` + `weight=bold` → `sans-serif-bold`. `family=sans-serif` + `style=italic` + `scaleIndex=100` → `sans-serif-italic-100`.
|
|
124
|
+
|
|
125
|
+
### Motion token taxonomy
|
|
126
|
+
|
|
127
|
+
Motion tokens describe timing, easing, and animation role for UI animation. Their name objects use `scope: "motion"` fields alongside the universal `property` field.
|
|
128
|
+
|
|
129
|
+
**NOTE:** No motion tokens exist in the foundation dataset at the time of this writing. This taxonomy is normative but the registry values for `motionRole` and `easing` are provisional — they will be refined when motion tokens are added to the foundation. Validators emit SPEC-043 at warning severity so provisional tokens are not blocked.
|
|
130
|
+
|
|
131
|
+
**NORMATIVE:** Motion tokens SHOULD include `motionRole` or `easing`. Tokens missing both are flagged by rule SPEC-043 (`domain-required-fields`, warning).
|
|
132
|
+
|
|
133
|
+
| Category | Name object field | Answers | Description |
|
|
134
|
+
| ----------- | ----------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
|
|
135
|
+
| Motion Role | `motionRole` | What? | Semantic role of the animation (e.g. `enter`, `exit`, `transition`, `emphasis`). Values come from [`motion-roles.json`](../../packages/design-system-registry/registry/motion-roles.json). |
|
|
136
|
+
| Easing | `easing` | How? | Easing curve identifier (e.g. `ease-in`, `ease-out`, `standard`). Values come from [`easing-curves.json`](../../packages/design-system-registry/registry/easing-curves.json). |
|
|
137
|
+
| Duration | `scaleIndex` | Which? | Numeric duration bucket index (e.g. `100` for 100ms, `200` for 200ms). Shared with other token types; not scope-restricted. |
|
|
138
|
+
|
|
139
|
+
**Default serialization order for motion tokens:**
|
|
140
|
+
|
|
141
|
+
```
|
|
142
|
+
{motionRole}-{easing}-{scaleIndex}
|
|
143
|
+
```
|
|
144
|
+
|
|
145
|
+
Example: `motionRole=enter` + `easing=ease-out` → `enter-ease-out`. `motionRole=transition` + `scaleIndex=100` → `transition-100`.
|
|
146
|
+
|
|
147
|
+
### Alias / semantic token name objects
|
|
148
|
+
|
|
149
|
+
Alias tokens (`$schema: …/alias.json`) MAY carry name objects using the same field vocabulary
|
|
150
|
+
as their target domain. A color alias carrying `colorFamily` is valid when its alias chain
|
|
151
|
+
resolves to a color-domain schema (`color.json`, `color-set.json`).
|
|
152
|
+
|
|
153
|
+
**NORMATIVE:** SPEC-042 (`field-scope-violation`) evaluates alias tokens by following the
|
|
154
|
+
`alias_target` chain to the terminal non-alias schema, then checking that schema against the
|
|
155
|
+
field's domain. This is the **alias-target-domain** rule: the alias *inherits* its domain
|
|
156
|
+
from what it ultimately resolves to.
|
|
157
|
+
|
|
158
|
+
**Examples:**
|
|
159
|
+
|
|
160
|
+
```json
|
|
161
|
+
// icon-color-blue-primary-default ($schema=alias.json, $ref → icon-color-blue-100 which is color-set.json)
|
|
162
|
+
// Valid: colorFamily allowed because target resolves to color domain.
|
|
163
|
+
{ "property": "icon-color", "colorFamily": "blue", "variant": "primary" }
|
|
164
|
+
|
|
165
|
+
// icon-color-primary-default ($schema=alias.json, $ref → icon-color-blue-primary-default)
|
|
166
|
+
// Valid: no domain-scoped fields used — variant and state are universal.
|
|
167
|
+
{ "property": "icon-color", "variant": "primary" }
|
|
168
|
+
```
|
|
169
|
+
|
|
170
|
+
**What stays deferred:** alias tokens referencing the same target but carrying modifiers that
|
|
171
|
+
have no current field (e.g. `inverse`, `emphasized`, `subtle`, `subdued`) remain unclassified
|
|
172
|
+
until a color-modifier RFC defines those fields.
|
|
81
173
|
|
|
82
174
|
### Structure vs. component — when does the line move?
|
|
83
175
|
|
|
@@ -177,9 +269,47 @@ The taxonomy and terms are built to scale as new concepts and terms are identifi
|
|
|
177
269
|
|
|
178
270
|
* New concept categories **MAY** be added by creating a new field declaration file in the field catalog — no spec version change is required for the mechanism itself.
|
|
179
271
|
* New terms **MAY** be added to the vocabulary registry without spec version changes.
|
|
180
|
-
* New token type taxonomies
|
|
272
|
+
* New token type taxonomies **MAY** be added by creating scoped field declarations (non-null `scope`) and a corresponding registry section in taxonomy.md. Color, typography, and motion taxonomies are defined above.
|
|
181
273
|
* Platform manifests **MAY** extend the vocabulary with platform-specific terms and formatting.
|
|
182
274
|
|
|
275
|
+
## Where `name` objects live
|
|
276
|
+
|
|
277
|
+
Token taxonomy data is **decoupled** from the published `@adobe/spectrum-tokens`
|
|
278
|
+
package to avoid bumping the tokens version on every taxonomy change.
|
|
279
|
+
|
|
280
|
+
| Artifact | Location | Description |
|
|
281
|
+
| ----------------- | ----------------------------------- | -------------------------------------------------------------------------------- |
|
|
282
|
+
| Token source data | `packages/tokens/src/*.json` | `$schema`, `value`, `uuid`, `sets`, … — no `name` field |
|
|
283
|
+
| Taxonomy sidecar | `packages/token-names/names/*.json` | `{ "<slug>": { property, colorFamily, … }, … }` — one file per token source file |
|
|
284
|
+
| Field definitions | `packages/design-data-spec/fields/` | Authoritative field catalog with scope and type |
|
|
285
|
+
|
|
286
|
+
The sidecar package (`@adobe/token-names`) is **private** (not published to npm).
|
|
287
|
+
Its delivery format for downstream consumers is TBD.
|
|
288
|
+
|
|
289
|
+
### SDK validator integration
|
|
290
|
+
|
|
291
|
+
Pass `--names-dir packages/token-names/names/` to the `design-data validate` CLI
|
|
292
|
+
to merge sidecar names into the token graph at ingest. All relational rules
|
|
293
|
+
(SPEC-042, SPEC-043, SPEC-018…022, cascade, diff, query) continue to read
|
|
294
|
+
`record.raw["name"]` as if the field were inline:
|
|
295
|
+
|
|
296
|
+
```bash
|
|
297
|
+
cargo run --bin design-data -- validate packages/tokens/src/ \
|
|
298
|
+
--names-dir packages/token-names/names/
|
|
299
|
+
```
|
|
300
|
+
|
|
301
|
+
Validation without `--names-dir` is a valid fail-open configuration (name-scope
|
|
302
|
+
rules are silent); CI always supplies the flag.
|
|
303
|
+
|
|
304
|
+
### Regenerating name data
|
|
305
|
+
|
|
306
|
+
```bash
|
|
307
|
+
node tools/token-corpus-migrate/src/cli.js \
|
|
308
|
+
--root packages/tokens/src \
|
|
309
|
+
--names-out packages/token-names/names \
|
|
310
|
+
--write
|
|
311
|
+
```
|
|
312
|
+
|
|
183
313
|
## References
|
|
184
314
|
|
|
185
315
|
* [#806 — Token Taxonomy, Vocabulary, and Formatting](https://github.com/adobe/spectrum-design-data/discussions/806)
|
package/spec/token-format.md
CHANGED
|
@@ -51,6 +51,10 @@ Fields are divided into **semantic fields** (identity, structure, intent) and **
|
|
|
51
51
|
|
|
52
52
|
#### Semantic fields
|
|
53
53
|
|
|
54
|
+
The table below lists all semantic fields. Fields marked with a scope are domain-restricted — see [Taxonomy — Token-type taxonomies](taxonomy.md#token-type-taxonomies) for the normative per-domain field rules and serialization orders. Validators enforce scope restrictions via rule SPEC-042.
|
|
55
|
+
|
|
56
|
+
**Universal semantic fields** (`scope: null` — apply to all token types):
|
|
57
|
+
|
|
54
58
|
| Field | Status | Taxonomy category | Description |
|
|
55
59
|
| -------------- | -------- | ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
|
|
56
60
|
| `property` | REQUIRED | Property | The stylistic attribute being defined (e.g. `color`, `width`, `padding`, `gap`). |
|
|
@@ -66,6 +70,18 @@ Fields are divided into **semantic fields** (identity, structure, intent) and **
|
|
|
66
70
|
| `size` | OPTIONAL | Size | Relative t-shirt sizing for relationships across tokens (e.g. `small`, `medium`, `large`). |
|
|
67
71
|
| `density` | OPTIONAL | Density | Space within or around component parts (e.g. `spacious`, `compact`). |
|
|
68
72
|
| `shape` | OPTIONAL | Shape | Relative to overall component shape (e.g. `uniform`). |
|
|
73
|
+
| `scaleIndex` | OPTIONAL | — | Numeric scale index appended at the end of the serialized name (e.g. `100`, `200`, `900`). Used by color palette, spacing, font-size, and motion duration tokens. |
|
|
74
|
+
|
|
75
|
+
**Domain-scoped semantic fields** (only valid on the indicated token type):
|
|
76
|
+
|
|
77
|
+
| Field | Status | Scope | Description |
|
|
78
|
+
| ------------- | -------- | ------------ | ------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
79
|
+
| `colorFamily` | OPTIONAL | `color` | Hue family of the color (e.g. `blue`, `gray`, `cyan`). See [Taxonomy — Color token taxonomy](taxonomy.md#color-token-taxonomy). |
|
|
80
|
+
| `family` | OPTIONAL | `typography` | Type family (e.g. `sans-serif`, `serif`, `cjk`, `code`). See [Taxonomy — Typography token taxonomy](taxonomy.md#typography-token-taxonomy). |
|
|
81
|
+
| `weight` | OPTIONAL | `typography` | Typographic weight (e.g. `regular`, `bold`, `light`). See [Taxonomy — Typography token taxonomy](taxonomy.md#typography-token-taxonomy). |
|
|
82
|
+
| `style` | OPTIONAL | `typography` | Typographic style when non-default (e.g. `italic`). See [Taxonomy — Typography token taxonomy](taxonomy.md#typography-token-taxonomy). |
|
|
83
|
+
| `motionRole` | OPTIONAL | `motion` | Semantic animation role (e.g. `enter`, `exit`, `transition`). See [Taxonomy — Motion token taxonomy](taxonomy.md#motion-token-taxonomy). |
|
|
84
|
+
| `easing` | OPTIONAL | `motion` | Easing curve identifier (e.g. `ease-out`, `standard`). See [Taxonomy — Motion token taxonomy](taxonomy.md#motion-token-taxonomy). |
|
|
69
85
|
|
|
70
86
|
#### Mode-set fields
|
|
71
87
|
|