@adobe/design-data-spec 0.10.0 → 0.11.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/rules/rules.yaml +17 -0
- package/spec/index.md +13 -11
- package/spec/registry.md +93 -0
package/package.json
CHANGED
package/rules/rules.yaml
CHANGED
|
@@ -304,3 +304,20 @@ rules:
|
|
|
304
304
|
message: "Token '{entity}' override changes value type from '{foundationType}' to '{overrideType}' — overrides MUST NOT change the resolved token's value type"
|
|
305
305
|
spec_ref: spec/cascade.md
|
|
306
306
|
introduced_in: "1.0.0-draft"
|
|
307
|
+
|
|
308
|
+
- id: SPEC-033
|
|
309
|
+
name: registry-id-cross-namespace-allowed
|
|
310
|
+
severity: error
|
|
311
|
+
category: registry
|
|
312
|
+
# Meta-rule: constrains validator behavior, not data shape. No SDK implementation exists;
|
|
313
|
+
# this entry documents a MUST constraint for external validator implementors. The error
|
|
314
|
+
# severity correctly signals "MUST" — a validator that incorrectly rejects valid
|
|
315
|
+
# cross-registry IDs is non-conforming. No conformance fixture is required because the
|
|
316
|
+
# SDK never emits this diagnostic; the rule is enforced by spec prose alone.
|
|
317
|
+
assert: >
|
|
318
|
+
A validator MUST NOT flag a registry ID as invalid solely because that same ID appears in
|
|
319
|
+
a different registry. Registry IDs are scoped to their registry; cross-registry overlap is
|
|
320
|
+
intentional when the same word is a valid term in each registry's distinct validation context.
|
|
321
|
+
message: "Registry ID '{id}' appears in multiple registries — this is permitted; do not reject on cross-registry overlap alone"
|
|
322
|
+
spec_ref: spec/registry.md#id-scoping
|
|
323
|
+
introduced_in: "1.0.0-draft"
|
package/spec/index.md
CHANGED
|
@@ -11,19 +11,20 @@ The specification defines:
|
|
|
11
11
|
|
|
12
12
|
1. **Token format** — structured token identity (`name`), literal `value` or alias `$ref`, and lifecycle metadata ([Token format](token-format.md)).
|
|
13
13
|
2. **Taxonomy** — concept categories, token term vocabulary, formatting style, and the distinction between component anatomy and token objects ([Taxonomy](taxonomy.md)).
|
|
14
|
-
3. **
|
|
14
|
+
3. **Registry** — named value collections that supply allowed vocabulary for token name fields and component metadata; three-registry boundary (anatomy-terms, token-objects, categories) and packaging strategy ([Registry](registry.md)).
|
|
15
|
+
4. **Component format** — component declaration shape: API options, named content slots, anatomy parts, state model, and cross-reference validation rules ([Component format](component-format.md)).
|
|
15
16
|
* **Anatomy format** — anatomy part declaration shape: field constraints, canonical anatomy vocabulary, and cross-reference rules for token `anatomy` field values ([Anatomy format](anatomy-format.md)).
|
|
16
17
|
* **State model** — state declaration shape: trigger semantics, precedence and resolution algorithm, canonical state vocabulary, and cross-reference rules for token `state` field values ([State model](state-model.md)).
|
|
17
|
-
|
|
18
|
-
|
|
19
|
-
|
|
20
|
-
|
|
21
|
-
|
|
22
|
-
|
|
23
|
-
|
|
24
|
-
|
|
25
|
-
|
|
26
|
-
|
|
18
|
+
5. **Cascade and resolution** — layered data (foundation, platform, product), specificity, and how a context picks a winning value ([Cascade](cascade.md)).
|
|
19
|
+
6. **Mode Sets** — declared modes, defaults, and coverage expectations ([Mode Sets](mode-sets.md)).
|
|
20
|
+
7. **Platform manifest** — how a platform repo pins foundation data, filters tokens, and applies typed overrides ([Manifest](manifest.md)).
|
|
21
|
+
8. **Semantic diff** — change taxonomy, token identity rules, and property-level change tracking for comparing dataset versions ([Diff](diff.md)).
|
|
22
|
+
9. **Query notation** — filter syntax for selecting tokens by structured fields ([Query](query.md)).
|
|
23
|
+
10. **Accessibility** — component accessibility vocabulary: semantic role, interaction and keyboard intents, focus behavior, WCAG criteria, and state-level AT fields ([Accessibility](accessibility.md)).
|
|
24
|
+
* **Accessibility adapters** — informative platform adapter contracts: Web/ARIA, iOS UIAccessibility, Android AccessibilityNodeInfo, and voice/multimodal ([Accessibility adapters](accessibility-adapters.md)).
|
|
25
|
+
11. **Document blocks** — typed prose blocks attachable to tokens, components, and anatomy parts; makes design guidance machine-readable and agent-queryable ([Document blocks](document-blocks.md)).
|
|
26
|
+
12. **Agent-readable surface** — operations and transport contracts (CLI, MCP server, Agent Skill) for AI agents consuming spec-conformant design data; covers session primer, token resolution, validation, query, and component description ([Agent-readable surface](agent-surface.md)).
|
|
27
|
+
13. **Evolution** — deprecation lifecycle, migration windows, change classification, and legacy format contract ([Evolution](evolution.md)).
|
|
27
28
|
|
|
28
29
|
## Conformance
|
|
29
30
|
|
|
@@ -61,6 +62,7 @@ Full governance (compatibility tiers, migration, CLI `--spec-version`) is discus
|
|
|
61
62
|
| --------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------- |
|
|
62
63
|
| [Token format](token-format.md) | Token `name`, `value` / `$ref`, value types, lifecycle metadata. |
|
|
63
64
|
| [Taxonomy](taxonomy.md) | Concept categories, vocabulary, formatting, anatomy vs objects. |
|
|
65
|
+
| [Registry](registry.md) | Named value collections for vocabulary validation; three-registry boundary (anatomy, token objects, categories) and packaging. |
|
|
64
66
|
| [Component format](component-format.md) | Component declaration: options, slots, anatomy (→ anatomy-format.md), states (→ state-model.md), lifecycle. |
|
|
65
67
|
| [Anatomy format](anatomy-format.md) | Anatomy part declarations: field constraints, canonical vocabulary, SPEC-020/SPEC-023/SPEC-024/SPEC-025. |
|
|
66
68
|
| [State model](state-model.md) | State declarations: trigger semantics, precedence algorithm, canonical vocabulary, SPEC-022/SPEC-026. |
|
package/spec/registry.md
ADDED
|
@@ -0,0 +1,93 @@
|
|
|
1
|
+
# Registry
|
|
2
|
+
|
|
3
|
+
**Spec version:** `1.0.0-draft` (see [Overview](index.md))
|
|
4
|
+
|
|
5
|
+
This document defines the **design system registry**: the set of named value collections that supply allowed vocabulary for token name fields and component metadata. It describes which registries exist, what each one validates, and the packaging strategy for the current release.
|
|
6
|
+
|
|
7
|
+
## What a registry is
|
|
8
|
+
|
|
9
|
+
A **registry** is a JSON file in `@adobe/design-system-registry` that declares an ordered list of named values. Each value has at minimum an `id` (the canonical string used in token names and component files) and a `label` (a human-readable display name). Values **MAY** carry additional fields such as `description`, `aliases`, `deprecated`, and `usedIn`.
|
|
10
|
+
|
|
11
|
+
Registries are the authoritative source of truth for vocabulary validation. A validator SHOULD flag token field values that are not present in the corresponding registry (typically as a warning, not an error — see field declarations in the field catalog).
|
|
12
|
+
|
|
13
|
+
## Packaging strategy
|
|
14
|
+
|
|
15
|
+
All registries ship as a **single package**: `@adobe/design-system-registry`. The three semantically distinct registries described below are separate JSON files within that package. Independent sub-package splits are explicitly deferred.
|
|
16
|
+
|
|
17
|
+
**Rationale:** No external consumers currently require independent semver versioning of individual registries. A single package is cheaper to maintain, simpler to consume, and avoids the proliferation of tiny packages with coordinated versioning overhead. If independent versioning needs emerge in a future release, the split can be done with a standard deprecation window per [Evolution](evolution.md).
|
|
18
|
+
|
|
19
|
+
## Registries
|
|
20
|
+
|
|
21
|
+
### Component anatomy (`anatomy-terms.json`)
|
|
22
|
+
|
|
23
|
+
Validates the `anatomy` field on token name objects and the `id` field on anatomy part declarations in component schemas.
|
|
24
|
+
|
|
25
|
+
**What it contains:** Visible, named parts of components as defined in component specification diagrams — the elements called out when designers annotate a component. Examples: `label`, `icon`, `track`, `handle`, `thumbnail`, `drag-icon`.
|
|
26
|
+
|
|
27
|
+
Anatomy terms fall into three tiers:
|
|
28
|
+
|
|
29
|
+
| Tier | Description | Examples |
|
|
30
|
+
| ------------------ | -------------------------------------- | ------------------------------------------------------ |
|
|
31
|
+
| Primitive | Reusable across many components | `icon`, `label`, `track`, `handle`, `divider`, `title` |
|
|
32
|
+
| Composite | Another component used as a named part | `checkbox`, `close-button`, `popover`, `avatar` |
|
|
33
|
+
| Component-specific | Unique to one component | `loupe`, `gripper`, `hold-icon` |
|
|
34
|
+
|
|
35
|
+
**File:** `packages/design-system-registry/registry/anatomy-terms.json`\
|
|
36
|
+
**Validated by:** SPEC-020, SPEC-023, SPEC-024, SPEC-025\
|
|
37
|
+
**See also:** [Taxonomy — Component anatomy vs. token objects](taxonomy.md#component-anatomy-vs-token-objects), [Anatomy format](anatomy-format.md)
|
|
38
|
+
|
|
39
|
+
### Token objects (`token-objects.json`)
|
|
40
|
+
|
|
41
|
+
Validates the `object` field on token name objects.
|
|
42
|
+
|
|
43
|
+
**What it contains:** Abstract styling surfaces that describe *where* a visual property is applied. Token objects are not anatomy — they are not visible named parts of a component; they are targets for visual properties that exist on any element regardless of its type.
|
|
44
|
+
|
|
45
|
+
| ID | Description |
|
|
46
|
+
| ------------ | ----------------------------------------------------- |
|
|
47
|
+
| `background` | Background surface or fill |
|
|
48
|
+
| `border` | Border or outline |
|
|
49
|
+
| `edge` | Outer boundary (used in spacing tokens) |
|
|
50
|
+
| `visual` | Visible graphic element area (may be inset from edge) |
|
|
51
|
+
| `content` | Main content area |
|
|
52
|
+
|
|
53
|
+
**File:** `packages/design-system-registry/registry/token-objects.json`\
|
|
54
|
+
**Validated by:** SPEC-009 (advisory — `name.object` field values SHOULD match the token-objects registry)\
|
|
55
|
+
**See also:** [Taxonomy — Token objects (styling surfaces)](taxonomy.md#token-objects-styling-surfaces)
|
|
56
|
+
|
|
57
|
+
### Component categories (`categories.json`)
|
|
58
|
+
|
|
59
|
+
Validates the `category` field on component declarations.
|
|
60
|
+
|
|
61
|
+
**What it contains:** Top-level categories for organizing components by purpose and interaction type. Used for documentation navigation and tooling filters.
|
|
62
|
+
|
|
63
|
+
**File:** `packages/design-system-registry/registry/categories.json`\
|
|
64
|
+
**Validated by:** gap — no dedicated SPEC rule yet; component `category` field validation against this registry is untracked. A future rule SHOULD enforce advisory validation here.\
|
|
65
|
+
**See also:** [Component format](component-format.md)
|
|
66
|
+
|
|
67
|
+
## ID scoping
|
|
68
|
+
|
|
69
|
+
Registry IDs are scoped to their registry. The same ID **MAY** appear in multiple registries when the same word is a valid term in each registry's distinct validation context. For example, `actions` is a legitimate anatomy term (a group of action controls within a list item) and also a component category — these are unrelated concepts that happen to share a label.
|
|
70
|
+
|
|
71
|
+
**NORMATIVE (SPEC-033):** Cross-registry ID overlap is not an error. Validators MUST NOT flag an ID as invalid solely because it appears in another registry.
|
|
72
|
+
|
|
73
|
+
## Other registries in the package
|
|
74
|
+
|
|
75
|
+
The following registries exist in `@adobe/design-system-registry` but are not part of the three-registry boundary defined above. They validate other token name fields and component metadata fields:
|
|
76
|
+
|
|
77
|
+
| Registry | File | Validates |
|
|
78
|
+
| ----------------- | ------------------------ | ------------------------------------ |
|
|
79
|
+
| Sizes | `sizes.json` | `name.size` field |
|
|
80
|
+
| States | `states.json` | `name.state` field |
|
|
81
|
+
| Variants | `variants.json` | `name.variant` field |
|
|
82
|
+
| Structures | `structures.json` | `name.structure` field |
|
|
83
|
+
| Substructures | `substructures.json` | `name.substructure` field |
|
|
84
|
+
| Orientations | `orientations.json` | `name.orientation` field |
|
|
85
|
+
| Positions | `positions.json` | `name.position` field |
|
|
86
|
+
| Densities | `densities.json` | `name.density` field |
|
|
87
|
+
| Shapes | `shapes.json` | `name.shape` field |
|
|
88
|
+
| Scale values | `scale-values.json` | Numeric scale vocabulary |
|
|
89
|
+
| Platforms | `platforms.json` | Platform identifiers in manifests |
|
|
90
|
+
| Components | `components.json` | Component identifiers in token names |
|
|
91
|
+
| Navigation terms | `navigation-terms.json` | Navigation vocabulary |
|
|
92
|
+
| Token terminology | `token-terminology.json` | Human-readable token concept labels |
|
|
93
|
+
| Glossary | `glossary.json` | Design system glossary |
|