@adobe/design-data-spec 0.6.0 → 0.7.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/package.json +1 -1
- package/schemas/product-context.schema.json +95 -0
- package/schemas/token.schema.json +8 -0
- package/spec/agent-surface.md +15 -11
- package/spec/cascade.md +5 -5
- package/spec/index.md +1 -0
- package/spec/manifest.md +4 -0
- package/spec/product-context.md +120 -0
- package/spec/token-format.md +10 -9
package/package.json
CHANGED
|
@@ -0,0 +1,95 @@
|
|
|
1
|
+
{
|
|
2
|
+
"$schema": "https://json-schema.org/draft/2020-12/schema",
|
|
3
|
+
"$id": "https://opensource.adobe.com/spectrum-design-data/schemas/v0/product-context.schema.json",
|
|
4
|
+
"title": "Product context document",
|
|
5
|
+
"description": "Layer 3 — product-layer record of rationale, overrides, and extensions. See spec/product-context.md.",
|
|
6
|
+
"type": "object",
|
|
7
|
+
"required": ["specVersion", "layer"],
|
|
8
|
+
"properties": {
|
|
9
|
+
"specVersion": {
|
|
10
|
+
"const": "1.0.0-draft"
|
|
11
|
+
},
|
|
12
|
+
"layer": {
|
|
13
|
+
"const": "product"
|
|
14
|
+
},
|
|
15
|
+
"rationale": {
|
|
16
|
+
"type": "string",
|
|
17
|
+
"description": "Why this product-layer working copy exists (e.g. feature name, project, team)."
|
|
18
|
+
},
|
|
19
|
+
"createdBy": {
|
|
20
|
+
"type": "object",
|
|
21
|
+
"description": "Tool or agent attribution.",
|
|
22
|
+
"properties": {
|
|
23
|
+
"type": {
|
|
24
|
+
"type": "string",
|
|
25
|
+
"enum": ["agent", "human"]
|
|
26
|
+
},
|
|
27
|
+
"tool": {
|
|
28
|
+
"type": "string",
|
|
29
|
+
"description": "Tool name (e.g. 'design-data', 'figma-plugin', 'manual')."
|
|
30
|
+
},
|
|
31
|
+
"model": {
|
|
32
|
+
"type": "string",
|
|
33
|
+
"description": "Model identifier when type is 'agent'."
|
|
34
|
+
}
|
|
35
|
+
},
|
|
36
|
+
"additionalProperties": false
|
|
37
|
+
},
|
|
38
|
+
"createdAt": {
|
|
39
|
+
"type": "string",
|
|
40
|
+
"format": "date-time",
|
|
41
|
+
"description": "ISO 8601 datetime when the document was first created."
|
|
42
|
+
},
|
|
43
|
+
"overrides": {
|
|
44
|
+
"type": "array",
|
|
45
|
+
"description": "Overrides of foundation or platform tokens.",
|
|
46
|
+
"items": {
|
|
47
|
+
"$ref": "#/$defs/override"
|
|
48
|
+
}
|
|
49
|
+
},
|
|
50
|
+
"extensions": {
|
|
51
|
+
"type": "object",
|
|
52
|
+
"description": "Net-new tokens and components added at this layer.",
|
|
53
|
+
"properties": {
|
|
54
|
+
"tokens": {
|
|
55
|
+
"type": "array",
|
|
56
|
+
"description": "New token objects. Each item MUST conform to token.schema.json.",
|
|
57
|
+
"items": {
|
|
58
|
+
"type": "object"
|
|
59
|
+
}
|
|
60
|
+
},
|
|
61
|
+
"components": {
|
|
62
|
+
"type": "array",
|
|
63
|
+
"description": "New component objects. Each item MUST conform to component.schema.json.",
|
|
64
|
+
"items": {
|
|
65
|
+
"type": "object"
|
|
66
|
+
}
|
|
67
|
+
}
|
|
68
|
+
},
|
|
69
|
+
"additionalProperties": false
|
|
70
|
+
}
|
|
71
|
+
},
|
|
72
|
+
"additionalProperties": false,
|
|
73
|
+
"$defs": {
|
|
74
|
+
"override": {
|
|
75
|
+
"type": "object",
|
|
76
|
+
"required": ["uuid", "value"],
|
|
77
|
+
"description": "A product-layer value override of an existing token.",
|
|
78
|
+
"properties": {
|
|
79
|
+
"uuid": {
|
|
80
|
+
"type": "string",
|
|
81
|
+
"format": "uuid",
|
|
82
|
+
"description": "UUID of the token being overridden. MUST match a token in the merged cascade."
|
|
83
|
+
},
|
|
84
|
+
"value": {
|
|
85
|
+
"description": "The overriding value. MUST be type-compatible with the original token value type."
|
|
86
|
+
},
|
|
87
|
+
"rationale": {
|
|
88
|
+
"type": "string",
|
|
89
|
+
"description": "Why this specific value was chosen."
|
|
90
|
+
}
|
|
91
|
+
},
|
|
92
|
+
"additionalProperties": false
|
|
93
|
+
}
|
|
94
|
+
}
|
|
95
|
+
}
|
|
@@ -172,6 +172,10 @@
|
|
|
172
172
|
"type": "string",
|
|
173
173
|
"description": "Plain text describing the token's purpose (aligns with DTCG $description)."
|
|
174
174
|
},
|
|
175
|
+
"rationale": {
|
|
176
|
+
"type": "string",
|
|
177
|
+
"description": "Why this token has its current value. Intended for product-layer authoring context; see spec/product-context.md."
|
|
178
|
+
},
|
|
175
179
|
"componentBindings": {
|
|
176
180
|
"type": "array",
|
|
177
181
|
"items": { "$ref": "#/$defs/componentBinding" },
|
|
@@ -246,6 +250,10 @@
|
|
|
246
250
|
"type": "string",
|
|
247
251
|
"description": "Plain text describing the token's purpose (aligns with DTCG $description)."
|
|
248
252
|
},
|
|
253
|
+
"rationale": {
|
|
254
|
+
"type": "string",
|
|
255
|
+
"description": "Why this token has its current value. Intended for product-layer authoring context; see spec/product-context.md."
|
|
256
|
+
},
|
|
249
257
|
"componentBindings": {
|
|
250
258
|
"type": "array",
|
|
251
259
|
"items": { "$ref": "#/$defs/componentBinding" },
|
package/spec/agent-surface.md
CHANGED
|
@@ -25,17 +25,21 @@ The surface targets three consumer shapes:
|
|
|
25
25
|
|
|
26
26
|
**NORMATIVE:** A conforming implementation MUST expose the following operations. Transport-specific naming (CLI subcommand vs MCP tool name vs skill action) MAY differ; the semantics MUST NOT.
|
|
27
27
|
|
|
28
|
-
| Operation | Reads | Returns | Backed by
|
|
29
|
-
| -------------------- | ------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
30
|
-
| `resolve_token` | property + dimension context | winning token (literal or resolved alias) with file/UUID/specificity | `cascade::resolve`
|
|
31
|
-
| `query_tokens` | filter expression (see [Query](query.md)) | matching token list | `query::filter`
|
|
32
|
-
| `validate_usage` | candidate token document or fragment | `ValidationReport` (Layer 1 + Layer 2 diagnostics) | `validate::validate_*`
|
|
33
|
-
| `describe_component` | component identifier | component contract (anatomy, options, states, tokenBindings); see [#832](https://github.com/adobe/spectrum-design-data/discussions/832) and [Phase 6.7](#describe_component-return-shape) | (Phase 6 contract)
|
|
34
|
-
| `suggest_token` | natural-language intent + optional property hint | ranked candidate tokens with rationale (RECOMMENDED, not NORMATIVE in v1) | registry + query
|
|
35
|
-
| `get_guidance` | token UUID, component identifier, or anatomy reference | attached document blocks (Phase 9 / RFC-D); falls back to empty list pre-RFC-D | document blocks
|
|
36
|
-
| `diff_datasets` | two dataset roots | `DiffReport` per [Diff](diff.md) | `diff::semantic_diff`
|
|
37
|
-
|
|
38
|
-
|
|
28
|
+
| Operation | Reads | Returns | Backed by |
|
|
29
|
+
| -------------------- | ------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------- |
|
|
30
|
+
| `resolve_token` | property + dimension context | winning token (literal or resolved alias) with file/UUID/specificity | `cascade::resolve` |
|
|
31
|
+
| `query_tokens` | filter expression (see [Query](query.md)) | matching token list | `query::filter` |
|
|
32
|
+
| `validate_usage` | candidate token document or fragment | `ValidationReport` (Layer 1 + Layer 2 diagnostics) | `validate::validate_*` |
|
|
33
|
+
| `describe_component` | component identifier | component contract (anatomy, options, states, tokenBindings); see [#832](https://github.com/adobe/spectrum-design-data/discussions/832) and [Phase 6.7](#describe_component-return-shape) | (Phase 6 contract) |
|
|
34
|
+
| `suggest_token` | natural-language intent + optional property hint | ranked candidate tokens with rationale (RECOMMENDED, not NORMATIVE in v1) | registry + query |
|
|
35
|
+
| `get_guidance` | token UUID, component identifier, or anatomy reference | attached document blocks (Phase 9 / RFC-D); falls back to empty list pre-RFC-D | document blocks |
|
|
36
|
+
| `diff_datasets` | two dataset roots | `DiffReport` per [Diff](diff.md) | `diff::semantic_diff` |
|
|
37
|
+
| `write_token` | token object + optional rationale string | updated product-layer token file + `product-context.json` (RECOMMENDED, not NORMATIVE in v1) | `write::write_token` (Phase 8.x, not yet implemented) |
|
|
38
|
+
| `write_component` | component object + optional rationale string | updated product-layer component file + `product-context.json` (RECOMMENDED, not NORMATIVE in v1) | `write::write_component` (Phase 8.x, not yet implemented) |
|
|
39
|
+
|
|
40
|
+
**NORMATIVE:** `validate_usage`, `resolve_token`, `query_tokens`, and `diff_datasets` MUST be implemented in a conforming agent surface. `suggest_token`, `get_guidance`, `write_token`, and `write_component` are RECOMMENDED. `describe_component` becomes NORMATIVE once [#832](https://github.com/adobe/spectrum-design-data/discussions/832) reaches implemented status.
|
|
41
|
+
|
|
42
|
+
**RECOMMENDED:** When `write_token` or `write_component` is invoked, the implementation SHOULD capture a `rationale` argument from the agent session context and record it in both the token's inline `rationale` field and the product context document's `overrides[].rationale` or `extensions.tokens[].rationale`. See [Product context — Agent capture behavior](product-context.md#agent-capture-behavior).
|
|
39
43
|
|
|
40
44
|
## Session primer
|
|
41
45
|
|
package/spec/cascade.md
CHANGED
|
@@ -8,11 +8,11 @@ This document defines the **cascade model**: three **layers**, **semantic specif
|
|
|
8
8
|
|
|
9
9
|
Design data is organized in three layers, ordered from lowest to highest precedence when values conflict:
|
|
10
10
|
|
|
11
|
-
| Layer | Name | Description
|
|
12
|
-
| ----- | -------------- |
|
|
13
|
-
| 1 | **Foundation** | Canonical design system data (e.g. Spectrum foundation).
|
|
14
|
-
| 2 | **Platform** | Platform-specific adjustments; **MUST** remain type-compatible with foundation.
|
|
15
|
-
| 3 | **Product** | Product-specific overrides; **MUST** remain type-compatible with the resolved lower layers. |
|
|
11
|
+
| Layer | Name | Description |
|
|
12
|
+
| ----- | -------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
13
|
+
| 1 | **Foundation** | Canonical design system data (e.g. Spectrum foundation). |
|
|
14
|
+
| 2 | **Platform** | Platform-specific adjustments; **MUST** remain type-compatible with foundation. |
|
|
15
|
+
| 3 | **Product** | Product-specific overrides; **MUST** remain type-compatible with the resolved lower layers. A product-layer working copy **SHOULD** include a `product-context.json` document recording its rationale and overrides. See [Product context](product-context.md). |
|
|
16
16
|
|
|
17
17
|
**NORMATIVE:** When two candidates match the same context, the candidate from the **higher** layer (larger number above) **MUST** win.
|
|
18
18
|
|
package/spec/index.md
CHANGED
|
@@ -63,6 +63,7 @@ Full governance (compatibility tiers, migration, CLI `--spec-version`) is discus
|
|
|
63
63
|
| [Cascade](cascade.md) | Layers, specificity, resolution algorithm. |
|
|
64
64
|
| [Dimensions](dimensions.md) | Dimension declarations, built-in dimensions, coverage. |
|
|
65
65
|
| [Manifest](manifest.md) | Platform manifest fields and validation expectations. |
|
|
66
|
+
| [Product context](product-context.md) | Product-layer context document: rationale, overrides, and extensions. |
|
|
66
67
|
| [Diff](diff.md) | Semantic diff change taxonomy, token identity, property changes. |
|
|
67
68
|
| [Query](query.md) | Filter notation for selecting tokens by structured fields. |
|
|
68
69
|
| [Evolution](evolution.md) | Deprecation lifecycle, migration windows, change classification. |
|
package/spec/manifest.md
CHANGED
|
@@ -65,6 +65,10 @@ A platform **MAY** declare formatting rules that control how structured name obj
|
|
|
65
65
|
|
|
66
66
|
**OPTIONAL:** Workflows **MAY** open upgrade PRs when `foundationVersion` lags the latest release; details are out of scope for this document (see [#715](https://github.com/adobe/spectrum-design-data/discussions/715)).
|
|
67
67
|
|
|
68
|
+
## Relationship to product context
|
|
69
|
+
|
|
70
|
+
The platform manifest is the Layer 2 context document. For Layer 3 (product-layer) context — rationale, overrides, and extensions specific to a product team's working copy — see [Product context](product-context.md).
|
|
71
|
+
|
|
68
72
|
## References
|
|
69
73
|
|
|
70
74
|
* [#715 — Distributed Design Data Architecture](https://github.com/adobe/spectrum-design-data/discussions/715)
|
|
@@ -0,0 +1,120 @@
|
|
|
1
|
+
# Product context
|
|
2
|
+
|
|
3
|
+
**Spec version:** `1.0.0-draft` (see [Overview](index.md))
|
|
4
|
+
|
|
5
|
+
This document defines the **product context document**: a machine-readable record that a product-layer working copy keeps alongside its token and component files. It preserves the rationale behind the working copy's existence and records the intent of each override and extension it introduces.
|
|
6
|
+
|
|
7
|
+
## Purpose
|
|
8
|
+
|
|
9
|
+
The cascade model defines three layers (Foundation → Platform → Product; see [Cascade](cascade.md)). The Platform layer has a context document — the [manifest](manifest.md) — that declares its relationship to the foundation. The Product layer has no equivalent until this document.
|
|
10
|
+
|
|
11
|
+
When a designer or engineer overrides a token or adds a component at the product layer, the intent behind those changes is currently lost. The product context document preserves that context as a machine-readable, human-editable file that travels with the product-layer dataset and can be consumed by agent tools.
|
|
12
|
+
|
|
13
|
+
## Document
|
|
14
|
+
|
|
15
|
+
A product context document **MUST** conform to [`product-context.schema.json`](../schemas/product-context.schema.json) (canonical `$id`: `https://opensource.adobe.com/spectrum-design-data/schemas/v0/product-context.schema.json`).
|
|
16
|
+
|
|
17
|
+
**RECOMMENDED:** A product-layer working copy **SHOULD** include a `product-context.json` file whenever it contains overrides or extensions.
|
|
18
|
+
|
|
19
|
+
## Required fields
|
|
20
|
+
|
|
21
|
+
| Field | Type | Description |
|
|
22
|
+
| ------------- | ------ | ------------------------------------------------------------- |
|
|
23
|
+
| `specVersion` | string | **MUST** be `1.0.0-draft` for documents targeting this draft. |
|
|
24
|
+
| `layer` | string | **MUST** be `"product"`. |
|
|
25
|
+
|
|
26
|
+
## Optional fields
|
|
27
|
+
|
|
28
|
+
| Field | Type | Description |
|
|
29
|
+
| ------------ | ------ | --------------------------------------------------------------------------------------------------------------------------------- |
|
|
30
|
+
| `rationale` | string | Why this product-layer working copy exists (e.g. feature name, project, team). |
|
|
31
|
+
| `createdBy` | object | Tool or agent attribution (see [createdBy shape](#createdby-shape)). |
|
|
32
|
+
| `createdAt` | string | ISO 8601 datetime when the document was **first** created. Implementations SHOULD NOT overwrite this field on subsequent updates. |
|
|
33
|
+
| `overrides` | array | Overrides of foundation or platform tokens (see [overrides](#overrides)). |
|
|
34
|
+
| `extensions` | object | Net-new tokens and components added at this layer (see [extensions](#extensions)). |
|
|
35
|
+
|
|
36
|
+
### `createdBy` shape
|
|
37
|
+
|
|
38
|
+
| Field | Type | Description |
|
|
39
|
+
| ------- | ------ | ----------------------------------------------------------------------- |
|
|
40
|
+
| `type` | string | `"agent"` or `"human"`. |
|
|
41
|
+
| `tool` | string | Tool name (e.g. `"design-data"`, `"figma-plugin"`, `"manual"`). |
|
|
42
|
+
| `model` | string | Model identifier when `type` is `"agent"` (e.g. `"claude-sonnet-4-6"`). |
|
|
43
|
+
|
|
44
|
+
### `overrides`
|
|
45
|
+
|
|
46
|
+
Each entry in `overrides` is an object that records a product-layer value override of an existing token:
|
|
47
|
+
|
|
48
|
+
| Field | Required | Type | Description |
|
|
49
|
+
| ----------- | -------- | ------ | ------------------------------------------------------------------------------------- |
|
|
50
|
+
| `uuid` | yes | string | UUID of the token being overridden. **MUST** match a token in the merged cascade. |
|
|
51
|
+
| `value` | yes | any | The overriding value. **MUST** be type-compatible with the original token value type. |
|
|
52
|
+
| `rationale` | no | string | Why this specific value was chosen. |
|
|
53
|
+
|
|
54
|
+
### `extensions`
|
|
55
|
+
|
|
56
|
+
The `extensions` object contains net-new tokens and components that do not exist in the foundation or platform layers:
|
|
57
|
+
|
|
58
|
+
| Field | Type | Description |
|
|
59
|
+
| ------------ | ----- | -------------------------------------------------------------------------------------------------------------------------------- |
|
|
60
|
+
| `tokens` | array | Token objects conforming to [`token.schema.json`](../schemas/token.schema.json). Each token **MAY** include a `rationale` field. |
|
|
61
|
+
| `components` | array | Component objects conforming to [`component.schema.json`](../schemas/component.schema.json). |
|
|
62
|
+
|
|
63
|
+
## Example
|
|
64
|
+
|
|
65
|
+
```json
|
|
66
|
+
{
|
|
67
|
+
"specVersion": "1.0.0-draft",
|
|
68
|
+
"layer": "product",
|
|
69
|
+
"rationale": "Checkout flow redesign — Q3 2026.",
|
|
70
|
+
"createdBy": {
|
|
71
|
+
"type": "agent",
|
|
72
|
+
"tool": "design-data",
|
|
73
|
+
"model": "claude-sonnet-4-6"
|
|
74
|
+
},
|
|
75
|
+
"createdAt": "2026-05-13T14:30:00Z",
|
|
76
|
+
"overrides": [
|
|
77
|
+
{
|
|
78
|
+
"uuid": "aaaaaaaa-0001-4000-8000-000000000001",
|
|
79
|
+
"value": "#f8f8f8",
|
|
80
|
+
"rationale": "Off-white card background to distinguish from pure-white page without elevation shadow."
|
|
81
|
+
}
|
|
82
|
+
],
|
|
83
|
+
"extensions": {
|
|
84
|
+
"tokens": [
|
|
85
|
+
{
|
|
86
|
+
"name": { "component": "checkout-summary", "property": "background-color" },
|
|
87
|
+
"value": "#f0f0f0",
|
|
88
|
+
"rationale": "Nested surface; lighter to create hierarchy without adding a border.",
|
|
89
|
+
"uuid": "bbbbbbbb-0002-4000-8000-000000000002"
|
|
90
|
+
}
|
|
91
|
+
]
|
|
92
|
+
}
|
|
93
|
+
}
|
|
94
|
+
```
|
|
95
|
+
|
|
96
|
+
## Agent capture behavior
|
|
97
|
+
|
|
98
|
+
**RECOMMENDED:** Agent tools that create or modify product-layer tokens (`write_token`, `write_component`) **SHOULD** capture a `rationale` from session context and record it in:
|
|
99
|
+
|
|
100
|
+
1. The token's inline `rationale` field (see [Token format — rationale](token-format.md#lifecycle-and-metadata)).
|
|
101
|
+
2. The product context document's `overrides[].rationale` (for overrides) or `extensions.tokens[].rationale` (for new tokens).
|
|
102
|
+
|
|
103
|
+
This makes the product context document self-maintaining during agent-assisted authoring sessions.
|
|
104
|
+
|
|
105
|
+
## Relationship to platform manifest
|
|
106
|
+
|
|
107
|
+
The platform manifest (Layer 2) declares which foundation tokens a platform includes, excludes, or overrides at a structural level. The product context document (Layer 3) records the *intent* behind a product team's specific value choices. The two documents are complementary and independent.
|
|
108
|
+
|
|
109
|
+
| Document | Layer | Primary audience | Records |
|
|
110
|
+
| ---------------------- | ----- | ----------------------------------- | -------------------------------------- |
|
|
111
|
+
| `manifest.json` | 2 | Platform engineers | Version pins, filters, typed overrides |
|
|
112
|
+
| `product-context.json` | 3 | Product designers/engineers, agents | Rationale for overrides and extensions |
|
|
113
|
+
|
|
114
|
+
## References
|
|
115
|
+
|
|
116
|
+
* [Cascade — Layers](cascade.md#layers)
|
|
117
|
+
* [Platform manifest](manifest.md)
|
|
118
|
+
* [Token format — rationale field](token-format.md#lifecycle-and-metadata)
|
|
119
|
+
* [Agent-readable surface — write operations](agent-surface.md#tool-catalog)
|
|
120
|
+
* [#847 — Phase 8.x: Product context document](https://github.com/adobe/spectrum-design-data/issues/847)
|
package/spec/token-format.md
CHANGED
|
@@ -92,15 +92,16 @@ When **`value`** is present, it **MUST** conform to the declared value type for
|
|
|
92
92
|
|
|
93
93
|
The following OPTIONAL fields implement the token lifecycle model described in [#623](https://github.com/adobe/spectrum-design-data/discussions/623) and the evolution policy in [Evolution](evolution.md). Inspired by Swift's `@available` attribute, Kotlin's `@Deprecated`, and OpenAPI 3.3's deprecation model.
|
|
94
94
|
|
|
95
|
-
| Field | Type | Description
|
|
96
|
-
| -------------------- | --------------------------------------- |
|
|
97
|
-
| `uuid` | string (UUID) | Stable unique id for rename tracking and diffs.
|
|
98
|
-
| `introduced` | string (version) | Spec version when the token was first added (e.g. `"1.0.0"`).
|
|
99
|
-
| `deprecated` | string (version) | Spec version when the token was deprecated (e.g. `"3.2.0"`). Truthy = deprecated.
|
|
100
|
-
| `deprecated_comment` | string | Human-readable deprecation explanation and migration guidance.
|
|
101
|
-
| `replaced_by` | string (UUID) or array of string (UUID) | UUID(s) of the replacement token(s). Single string for 1:1 replacement; array for one-to-many splits.
|
|
102
|
-
| `plannedRemoval` | string (version) | Spec version when the token will be removed. If omitted, defaults to the next major version after `deprecated`.
|
|
103
|
-
| `private` | boolean | Not part of public API surface.
|
|
95
|
+
| Field | Type | Description |
|
|
96
|
+
| -------------------- | --------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------ |
|
|
97
|
+
| `uuid` | string (UUID) | Stable unique id for rename tracking and diffs. |
|
|
98
|
+
| `introduced` | string (version) | Spec version when the token was first added (e.g. `"1.0.0"`). |
|
|
99
|
+
| `deprecated` | string (version) | Spec version when the token was deprecated (e.g. `"3.2.0"`). Truthy = deprecated. |
|
|
100
|
+
| `deprecated_comment` | string | Human-readable deprecation explanation and migration guidance. |
|
|
101
|
+
| `replaced_by` | string (UUID) or array of string (UUID) | UUID(s) of the replacement token(s). Single string for 1:1 replacement; array for one-to-many splits. |
|
|
102
|
+
| `plannedRemoval` | string (version) | Spec version when the token will be removed. If omitted, defaults to the next major version after `deprecated`. |
|
|
103
|
+
| `private` | boolean | Not part of public API surface. |
|
|
104
|
+
| `rationale` | string | Why this token has its current value. Intended for product-layer authoring context; see [Product context](product-context.md). |
|
|
104
105
|
|
|
105
106
|
#### Lifecycle example
|
|
106
107
|
|