@adobe/design-system-registry 3.2.0 → 5.0.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/CHANGELOG.md +39 -0
- package/index.js +39 -139
- package/moon.yml +2 -29
- package/package.json +5 -34
- package/AUTHORING.md +0 -290
- package/PLATFORM_EXTENSIONS.md +0 -315
- package/ava.config.js +0 -21
- package/registry/alignments.json +0 -22
- package/registry/anatomy-terms.json +0 -739
- package/registry/categories.json +0 -55
- package/registry/color-families.json +0 -177
- package/registry/components.json +0 -277
- package/registry/densities.json +0 -17
- package/registry/easing-curves.json +0 -42
- package/registry/glossary.json +0 -181
- package/registry/motion-roles.json +0 -32
- package/registry/navigation-terms.json +0 -241
- package/registry/orientations.json +0 -17
- package/registry/platform-extensions/ios-states.json +0 -59
- package/registry/platform-extensions/web-components-states.json +0 -58
- package/registry/platforms.json +0 -37
- package/registry/positions.json +0 -32
- package/registry/property-terms.json +0 -192
- package/registry/scale-values.json +0 -126
- package/registry/shapes.json +0 -12
- package/registry/sizes.json +0 -71
- package/registry/states.json +0 -184
- package/registry/structures.json +0 -27
- package/registry/substructures.json +0 -12
- package/registry/token-objects.json +0 -32
- package/registry/token-terminology.json +0 -925
- package/registry/typography-families.json +0 -27
- package/registry/typography-styles.json +0 -22
- package/registry/typography-weights.json +0 -37
- package/registry/variants.json +0 -282
- package/schemas/platform-extension.json +0 -79
- package/schemas/registry-value.json +0 -230
- package/scripts/validate-registry.js +0 -134
- package/test/registry.test.js +0 -417
package/CHANGELOG.md
CHANGED
|
@@ -1,5 +1,44 @@
|
|
|
1
1
|
# @adobe/design-system-registry
|
|
2
2
|
|
|
3
|
+
## 5.0.0
|
|
4
|
+
|
|
5
|
+
### Major Changes
|
|
6
|
+
|
|
7
|
+
- [#1113](https://github.com/adobe/spectrum-design-data/pull/1113) [`e23264e`](https://github.com/adobe/spectrum-design-data/commit/e23264e681c56077b5582bf019123b941862779a) Thanks [@GarthDB](https://github.com/GarthDB)! - Move Spectrum registry vocabulary into spectrum-design-data; deprecate design-system-registry.
|
|
8
|
+
- **@adobe/spectrum-design-data**: gains `registry/` (27 vocabulary files) with
|
|
9
|
+
subpath exports (`./registry/*.json`); now the single source of truth for all Spectrum data.
|
|
10
|
+
- **@adobe/design-system-registry**: reduced to a compatibility shim. Migrate imports to
|
|
11
|
+
`@adobe/spectrum-design-data` — this shim will be removed in a future major version.
|
|
12
|
+
- **@adobe/design-data-spec**: gains `registry-value.json` and `platform-extension.json`
|
|
13
|
+
schema exports; `manifest.schema.json` `conceptOrder` enum relaxed to open `string` type
|
|
14
|
+
(no longer hardcodes Spectrum's field names — configurable per field catalog).
|
|
15
|
+
|
|
16
|
+
### Patch Changes
|
|
17
|
+
|
|
18
|
+
- Updated dependencies [[`073c22a`](https://github.com/adobe/spectrum-design-data/commit/073c22a75c27fbb44eb57eb6cb7311e294066d76), [`e23264e`](https://github.com/adobe/spectrum-design-data/commit/e23264e681c56077b5582bf019123b941862779a), [`e23264e`](https://github.com/adobe/spectrum-design-data/commit/e23264e681c56077b5582bf019123b941862779a), [`e23264e`](https://github.com/adobe/spectrum-design-data/commit/e23264e681c56077b5582bf019123b941862779a)]:
|
|
19
|
+
- @adobe/spectrum-design-data@0.2.0
|
|
20
|
+
|
|
21
|
+
## 3.3.0
|
|
22
|
+
|
|
23
|
+
### Minor Changes
|
|
24
|
+
|
|
25
|
+
- [#977](https://github.com/adobe/spectrum-design-data/pull/977) [`526d2de`](https://github.com/adobe/spectrum-design-data/commit/526d2de363788c1e916a1ed6426e14600d84fd73) Thanks [@GarthDB](https://github.com/GarthDB)! - Classify line-height multiplier and CJK line-height multiplier tokens.
|
|
26
|
+
- **registry/property-terms.json**: add `line-height-multiplier` term (unitless ratio,
|
|
27
|
+
distinct from absolute px line-height paired with a font-size tier).
|
|
28
|
+
- **sdk/validate/rules/mod.rs**: add `multiplier.json` to typography `DOMAIN_SCHEMAS`
|
|
29
|
+
so the `family` field is permitted on CJK multiplier tokens (SPEC-042).
|
|
30
|
+
- **sdk/validate/rules/spec043.rs**: extend typography domain-required-fields check to
|
|
31
|
+
accept `scaleIndex` and `structure` alongside `family`/`weight`/`style`.
|
|
32
|
+
- **token-names/names/typography.json**: sidecar entries for all 4 tokens.
|
|
33
|
+
- Reduces SPEC-017 warning count by 4.
|
|
34
|
+
|
|
35
|
+
- [#977](https://github.com/adobe/spectrum-design-data/pull/977) [`526d2de`](https://github.com/adobe/spectrum-design-data/commit/526d2de363788c1e916a1ed6426e14600d84fd73) Thanks [@GarthDB](https://github.com/GarthDB)! - Classify 5 margin multiplier tokens; add margin property-terms and typography structures.
|
|
36
|
+
- **registry/property-terms.json**: add `margin`, `margin-top`, `margin-bottom`.
|
|
37
|
+
- **registry/structures.json**: add `body`, `detail`, `heading` typography-scale structures.
|
|
38
|
+
- **token-names/names/typography.json**: sidecar entries for all 5 tokens using
|
|
39
|
+
`{ structure, property }` shape.
|
|
40
|
+
- Reduces SPEC-017 (`string-name-tech-debt`) warning count by 5.
|
|
41
|
+
|
|
3
42
|
## 3.2.0
|
|
4
43
|
|
|
5
44
|
### Minor Changes
|
package/index.js
CHANGED
|
@@ -1,5 +1,5 @@
|
|
|
1
1
|
/*
|
|
2
|
-
Copyright
|
|
2
|
+
Copyright 2026 Adobe. All rights reserved.
|
|
3
3
|
This file is licensed to you under the Apache License, Version 2.0 (the "License");
|
|
4
4
|
you may not use this file except in compliance with the License. You may obtain a copy
|
|
5
5
|
of the License at http://www.apache.org/licenses/LICENSE-2.0
|
|
@@ -10,170 +10,83 @@ OF ANY KIND, either express or implied. See the License for the specific languag
|
|
|
10
10
|
governing permissions and limitations under the License.
|
|
11
11
|
*/
|
|
12
12
|
|
|
13
|
+
/**
|
|
14
|
+
* @deprecated This package is deprecated. The registry data and API have moved to
|
|
15
|
+
* @adobe/spectrum-design-data. Update your imports:
|
|
16
|
+
*
|
|
17
|
+
* import { sizes, getValues } from "@adobe/spectrum-design-data";
|
|
18
|
+
* import sizesJson from "@adobe/spectrum-design-data/registry/sizes.json" with { type: "json" };
|
|
19
|
+
*
|
|
20
|
+
* This shim will be removed in a future major version.
|
|
21
|
+
*/
|
|
22
|
+
|
|
13
23
|
import { readFileSync, readdirSync } from "node:fs";
|
|
14
|
-
import { fileURLToPath } from "node:url";
|
|
24
|
+
import { fileURLToPath, resolve as resolveUrl } from "node:url";
|
|
15
25
|
import { dirname, join } from "node:path";
|
|
26
|
+
import { createRequire } from "node:module";
|
|
16
27
|
|
|
17
|
-
const
|
|
18
|
-
const
|
|
19
|
-
|
|
20
|
-
// Load registry files
|
|
21
|
-
export const sizes = JSON.parse(
|
|
22
|
-
readFileSync(join(__dirname, "registry", "sizes.json"), "utf-8"),
|
|
23
|
-
);
|
|
24
|
-
|
|
25
|
-
export const states = JSON.parse(
|
|
26
|
-
readFileSync(join(__dirname, "registry", "states.json"), "utf-8"),
|
|
27
|
-
);
|
|
28
|
-
|
|
29
|
-
export const variants = JSON.parse(
|
|
30
|
-
readFileSync(join(__dirname, "registry", "variants.json"), "utf-8"),
|
|
31
|
-
);
|
|
32
|
-
|
|
33
|
-
export const anatomyTerms = JSON.parse(
|
|
34
|
-
readFileSync(join(__dirname, "registry", "anatomy-terms.json"), "utf-8"),
|
|
35
|
-
);
|
|
36
|
-
|
|
37
|
-
export const propertyTerms = JSON.parse(
|
|
38
|
-
readFileSync(join(__dirname, "registry", "property-terms.json"), "utf-8"),
|
|
39
|
-
);
|
|
40
|
-
|
|
41
|
-
export const components = JSON.parse(
|
|
42
|
-
readFileSync(join(__dirname, "registry", "components.json"), "utf-8"),
|
|
43
|
-
);
|
|
44
|
-
|
|
45
|
-
export const scaleValues = JSON.parse(
|
|
46
|
-
readFileSync(join(__dirname, "registry", "scale-values.json"), "utf-8"),
|
|
47
|
-
);
|
|
48
|
-
|
|
49
|
-
export const categories = JSON.parse(
|
|
50
|
-
readFileSync(join(__dirname, "registry", "categories.json"), "utf-8"),
|
|
51
|
-
);
|
|
52
|
-
|
|
53
|
-
export const platforms = JSON.parse(
|
|
54
|
-
readFileSync(join(__dirname, "registry", "platforms.json"), "utf-8"),
|
|
55
|
-
);
|
|
56
|
-
|
|
57
|
-
export const navigationTerms = JSON.parse(
|
|
58
|
-
readFileSync(join(__dirname, "registry", "navigation-terms.json"), "utf-8"),
|
|
59
|
-
);
|
|
60
|
-
|
|
61
|
-
export const tokenTerminology = JSON.parse(
|
|
62
|
-
readFileSync(join(__dirname, "registry", "token-terminology.json"), "utf-8"),
|
|
63
|
-
);
|
|
64
|
-
|
|
65
|
-
export const glossary = JSON.parse(
|
|
66
|
-
readFileSync(join(__dirname, "registry", "glossary.json"), "utf-8"),
|
|
67
|
-
);
|
|
68
|
-
|
|
69
|
-
export const tokenObjects = JSON.parse(
|
|
70
|
-
readFileSync(join(__dirname, "registry", "token-objects.json"), "utf-8"),
|
|
71
|
-
);
|
|
72
|
-
|
|
73
|
-
export const structures = JSON.parse(
|
|
74
|
-
readFileSync(join(__dirname, "registry", "structures.json"), "utf-8"),
|
|
75
|
-
);
|
|
76
|
-
|
|
77
|
-
export const substructures = JSON.parse(
|
|
78
|
-
readFileSync(join(__dirname, "registry", "substructures.json"), "utf-8"),
|
|
79
|
-
);
|
|
80
|
-
|
|
81
|
-
export const orientations = JSON.parse(
|
|
82
|
-
readFileSync(join(__dirname, "registry", "orientations.json"), "utf-8"),
|
|
83
|
-
);
|
|
84
|
-
|
|
85
|
-
export const positions = JSON.parse(
|
|
86
|
-
readFileSync(join(__dirname, "registry", "positions.json"), "utf-8"),
|
|
87
|
-
);
|
|
28
|
+
const require = createRequire(import.meta.url);
|
|
29
|
+
const registryPkg = require.resolve("@adobe/spectrum-design-data/package.json");
|
|
30
|
+
const registryDir = join(dirname(registryPkg), "registry");
|
|
88
31
|
|
|
89
|
-
|
|
90
|
-
readFileSync(join(
|
|
91
|
-
|
|
32
|
+
function load(name) {
|
|
33
|
+
return JSON.parse(readFileSync(join(registryDir, name), "utf-8"));
|
|
34
|
+
}
|
|
92
35
|
|
|
93
|
-
export const
|
|
94
|
-
|
|
95
|
-
);
|
|
36
|
+
export const sizes = load("sizes.json");
|
|
37
|
+
export const states = load("states.json");
|
|
38
|
+
export const variants = load("variants.json");
|
|
39
|
+
export const anatomyTerms = load("anatomy-terms.json");
|
|
40
|
+
export const propertyTerms = load("property-terms.json");
|
|
41
|
+
export const components = load("components.json");
|
|
42
|
+
export const scaleValues = load("scale-values.json");
|
|
43
|
+
export const categories = load("categories.json");
|
|
44
|
+
export const platforms = load("platforms.json");
|
|
45
|
+
export const navigationTerms = load("navigation-terms.json");
|
|
46
|
+
export const tokenTerminology = load("token-terminology.json");
|
|
47
|
+
export const glossary = load("glossary.json");
|
|
48
|
+
export const tokenObjects = load("token-objects.json");
|
|
49
|
+
export const structures = load("structures.json");
|
|
50
|
+
export const substructures = load("substructures.json");
|
|
51
|
+
export const orientations = load("orientations.json");
|
|
52
|
+
export const positions = load("positions.json");
|
|
53
|
+
export const densities = load("densities.json");
|
|
54
|
+
export const shapes = load("shapes.json");
|
|
96
55
|
|
|
97
|
-
/**
|
|
98
|
-
* Get all values from a registry by ID
|
|
99
|
-
* @param {object} registry - The registry object
|
|
100
|
-
* @returns {string[]} Array of value IDs
|
|
101
|
-
*/
|
|
102
56
|
export function getValues(registry) {
|
|
103
57
|
return registry.values.map((v) => v.id);
|
|
104
58
|
}
|
|
105
59
|
|
|
106
|
-
/**
|
|
107
|
-
* Find a registry value by ID or alias
|
|
108
|
-
* @param {object} registry - The registry object
|
|
109
|
-
* @param {string} searchTerm - The ID or alias to search for
|
|
110
|
-
* @returns {object|undefined} The matching value or undefined
|
|
111
|
-
*/
|
|
112
60
|
export function findValue(registry, searchTerm) {
|
|
113
61
|
return registry.values.find(
|
|
114
62
|
(v) => v.id === searchTerm || v.aliases?.includes(searchTerm),
|
|
115
63
|
);
|
|
116
64
|
}
|
|
117
65
|
|
|
118
|
-
/**
|
|
119
|
-
* Check if a value exists in a registry
|
|
120
|
-
* @param {object} registry - The registry object
|
|
121
|
-
* @param {string} searchTerm - The ID or alias to search for
|
|
122
|
-
* @returns {boolean} True if the value exists
|
|
123
|
-
*/
|
|
124
66
|
export function hasValue(registry, searchTerm) {
|
|
125
67
|
return findValue(registry, searchTerm) !== undefined;
|
|
126
68
|
}
|
|
127
69
|
|
|
128
|
-
/**
|
|
129
|
-
* Get the default value from a registry
|
|
130
|
-
* @param {object} registry - The registry object
|
|
131
|
-
* @returns {object|undefined} The default value or undefined
|
|
132
|
-
*/
|
|
133
70
|
export function getDefault(registry) {
|
|
134
71
|
return registry.values.find((v) => v.default === true);
|
|
135
72
|
}
|
|
136
73
|
|
|
137
|
-
/**
|
|
138
|
-
* Get all non-deprecated values from a registry
|
|
139
|
-
* @param {object} registry - The registry object
|
|
140
|
-
* @returns {array} Array of non-deprecated values
|
|
141
|
-
*/
|
|
142
74
|
export function getActiveValues(registry) {
|
|
143
75
|
return registry.values.filter((v) => !v.deprecated);
|
|
144
76
|
}
|
|
145
77
|
|
|
146
|
-
/**
|
|
147
|
-
* Load a platform extension file
|
|
148
|
-
* @param {string} extensionPath - Path to the extension JSON file
|
|
149
|
-
* @returns {object} The extension object
|
|
150
|
-
*/
|
|
151
78
|
export function loadPlatformExtension(extensionPath) {
|
|
152
79
|
return JSON.parse(readFileSync(extensionPath, "utf-8"));
|
|
153
80
|
}
|
|
154
81
|
|
|
155
|
-
/**
|
|
156
|
-
* Get platform-specific term for a registry value
|
|
157
|
-
* @param {object} registry - The base registry object
|
|
158
|
-
* @param {string} termId - The term ID to look up
|
|
159
|
-
* @param {string} platform - The platform name
|
|
160
|
-
* @param {object} extension - Optional: The platform extension object
|
|
161
|
-
* @returns {object|undefined} Platform-specific term info or undefined
|
|
162
|
-
*/
|
|
163
82
|
export function getTermForPlatform(registry, termId, platform, extension) {
|
|
164
|
-
// First, find the base term
|
|
165
83
|
const baseTerm = findValue(registry, termId);
|
|
166
84
|
if (!baseTerm) return undefined;
|
|
167
85
|
|
|
168
|
-
// Check if the term has platform-specific info in its platforms property
|
|
169
86
|
if (baseTerm.platforms && baseTerm.platforms[platform]) {
|
|
170
|
-
return {
|
|
171
|
-
...baseTerm,
|
|
172
|
-
platform: baseTerm.platforms[platform],
|
|
173
|
-
};
|
|
87
|
+
return { ...baseTerm, platform: baseTerm.platforms[platform] };
|
|
174
88
|
}
|
|
175
89
|
|
|
176
|
-
// If extension is provided, check for platform-specific overrides
|
|
177
90
|
if (extension && extension.platform === platform) {
|
|
178
91
|
const ext = extension.extensions.find((e) => e.termId === termId);
|
|
179
92
|
if (ext) {
|
|
@@ -191,30 +104,17 @@ export function getTermForPlatform(registry, termId, platform, extension) {
|
|
|
191
104
|
}
|
|
192
105
|
}
|
|
193
106
|
|
|
194
|
-
// Return base term if no platform-specific info found
|
|
195
107
|
return baseTerm;
|
|
196
108
|
}
|
|
197
109
|
|
|
198
|
-
/**
|
|
199
|
-
* Get all extensions for a specific platform
|
|
200
|
-
* @param {array} extensions - Array of extension objects
|
|
201
|
-
* @param {string} platform - The platform name
|
|
202
|
-
* @returns {array} Array of extensions for the platform
|
|
203
|
-
*/
|
|
204
110
|
export function getPlatformExtensions(extensions, platform) {
|
|
205
111
|
return extensions.filter((ext) => ext.platform === platform);
|
|
206
112
|
}
|
|
207
113
|
|
|
208
|
-
/**
|
|
209
|
-
* Load all platform extensions from a directory
|
|
210
|
-
* @param {string} extensionsDir - Path to the extensions directory
|
|
211
|
-
* @returns {array} Array of loaded extension objects
|
|
212
|
-
*/
|
|
213
114
|
export function loadAllPlatformExtensions(extensionsDir) {
|
|
214
115
|
const extensionFiles = readdirSync(extensionsDir).filter((f) =>
|
|
215
116
|
f.endsWith(".json"),
|
|
216
117
|
);
|
|
217
|
-
|
|
218
118
|
return extensionFiles.map((file) =>
|
|
219
119
|
loadPlatformExtension(join(extensionsDir, file)),
|
|
220
120
|
);
|
package/moon.yml
CHANGED
|
@@ -1,4 +1,4 @@
|
|
|
1
|
-
# Copyright
|
|
1
|
+
# Copyright 2026 Adobe. All rights reserved.
|
|
2
2
|
# This file is licensed to you under the Apache License, Version 2.0 (the "License");
|
|
3
3
|
# you may not use this file except in compliance with the License. You may obtain a copy
|
|
4
4
|
# of the License at http://www.apache.org/licenses/LICENSE-2.0
|
|
@@ -8,33 +8,6 @@
|
|
|
8
8
|
# OF ANY KIND, either express or implied. See the License for the specific language
|
|
9
9
|
# governing permissions and limitations under the License.
|
|
10
10
|
|
|
11
|
+
# Deprecated shim — no tasks. Registry data, tests, and validation have moved to design-data.
|
|
11
12
|
$schema: "https://moonrepo.dev/schemas/project.json"
|
|
12
13
|
layer: library
|
|
13
|
-
fileGroups:
|
|
14
|
-
registry:
|
|
15
|
-
- "registry/**/*.json"
|
|
16
|
-
schemas:
|
|
17
|
-
- "schemas/**/*.json"
|
|
18
|
-
tests:
|
|
19
|
-
- "test/**/*"
|
|
20
|
-
tasks:
|
|
21
|
-
test:
|
|
22
|
-
command:
|
|
23
|
-
- pnpm
|
|
24
|
-
- ava
|
|
25
|
-
inputs:
|
|
26
|
-
- "@globs(registry)"
|
|
27
|
-
- "@globs(schemas)"
|
|
28
|
-
- "@globs(tests)"
|
|
29
|
-
- "index.js"
|
|
30
|
-
- "ava.config.js"
|
|
31
|
-
platform: node
|
|
32
|
-
validate:
|
|
33
|
-
command:
|
|
34
|
-
- node
|
|
35
|
-
- scripts/validate-registry.js
|
|
36
|
-
inputs:
|
|
37
|
-
- "@globs(registry)"
|
|
38
|
-
- "@globs(schemas)"
|
|
39
|
-
- "scripts/validate-registry.js"
|
|
40
|
-
platform: node
|
package/package.json
CHANGED
|
@@ -1,33 +1,11 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@adobe/design-system-registry",
|
|
3
|
-
"version": "
|
|
4
|
-
"description": "
|
|
3
|
+
"version": "5.0.0",
|
|
4
|
+
"description": "DEPRECATED — registry data and API have moved to @adobe/spectrum-design-data. This package is a thin compatibility shim.",
|
|
5
5
|
"type": "module",
|
|
6
6
|
"main": "index.js",
|
|
7
7
|
"exports": {
|
|
8
|
-
".": "./index.js"
|
|
9
|
-
"./registry/sizes.json": "./registry/sizes.json",
|
|
10
|
-
"./registry/states.json": "./registry/states.json",
|
|
11
|
-
"./registry/variants.json": "./registry/variants.json",
|
|
12
|
-
"./registry/anatomy-terms.json": "./registry/anatomy-terms.json",
|
|
13
|
-
"./registry/components.json": "./registry/components.json",
|
|
14
|
-
"./registry/scale-values.json": "./registry/scale-values.json",
|
|
15
|
-
"./registry/categories.json": "./registry/categories.json",
|
|
16
|
-
"./registry/platforms.json": "./registry/platforms.json",
|
|
17
|
-
"./registry/token-objects.json": "./registry/token-objects.json",
|
|
18
|
-
"./registry/structures.json": "./registry/structures.json",
|
|
19
|
-
"./registry/substructures.json": "./registry/substructures.json",
|
|
20
|
-
"./registry/orientations.json": "./registry/orientations.json",
|
|
21
|
-
"./registry/positions.json": "./registry/positions.json",
|
|
22
|
-
"./registry/densities.json": "./registry/densities.json",
|
|
23
|
-
"./registry/shapes.json": "./registry/shapes.json",
|
|
24
|
-
"./registry/color-families.json": "./registry/color-families.json",
|
|
25
|
-
"./registry/alignments.json": "./registry/alignments.json",
|
|
26
|
-
"./registry/typography-families.json": "./registry/typography-families.json",
|
|
27
|
-
"./registry/typography-weights.json": "./registry/typography-weights.json",
|
|
28
|
-
"./registry/typography-styles.json": "./registry/typography-styles.json",
|
|
29
|
-
"./registry/motion-roles.json": "./registry/motion-roles.json",
|
|
30
|
-
"./registry/easing-curves.json": "./registry/easing-curves.json"
|
|
8
|
+
".": "./index.js"
|
|
31
9
|
},
|
|
32
10
|
"repository": {
|
|
33
11
|
"type": "git",
|
|
@@ -47,14 +25,7 @@
|
|
|
47
25
|
"node": ">=20.12.0",
|
|
48
26
|
"pnpm": ">=10.17.1"
|
|
49
27
|
},
|
|
50
|
-
"
|
|
51
|
-
"
|
|
52
|
-
"ajv-formats": "^3.0.1",
|
|
53
|
-
"ava": "^6.0.1",
|
|
54
|
-
"@adobe/spectrum-component-api-schemas": "6.1.17"
|
|
55
|
-
},
|
|
56
|
-
"scripts": {
|
|
57
|
-
"validate": "node scripts/validate-registry.js",
|
|
58
|
-
"test": "ava"
|
|
28
|
+
"dependencies": {
|
|
29
|
+
"@adobe/spectrum-design-data": "0.2.0"
|
|
59
30
|
}
|
|
60
31
|
}
|
package/AUTHORING.md
DELETED
|
@@ -1,290 +0,0 @@
|
|
|
1
|
-
# Authoring Guide: Spectrum Design System Glossary
|
|
2
|
-
|
|
3
|
-
This guide explains how to author and maintain glossary terms in the Spectrum Design System Registry.
|
|
4
|
-
|
|
5
|
-
## Overview
|
|
6
|
-
|
|
7
|
-
The Design System Registry serves as the single source of truth for Spectrum design terminology. Each term includes:
|
|
8
|
-
|
|
9
|
-
* **Basic Information**: ID, label, description
|
|
10
|
-
* **Definition**: Structured definition following Spectrum's naming methodology
|
|
11
|
-
* **Platform Variations**: How the term differs across platforms (web, iOS, Android, etc.)
|
|
12
|
-
* **Terminology Metadata**: Classification and naming rationale
|
|
13
|
-
* **Sources**: References to documentation and standards
|
|
14
|
-
* **Governance**: Ownership and review information
|
|
15
|
-
* **Related Terms**: Cross-references to related concepts
|
|
16
|
-
|
|
17
|
-
## File Structure
|
|
18
|
-
|
|
19
|
-
Registry files are located in `registry/` and organized by type:
|
|
20
|
-
|
|
21
|
-
* `sizes.json` - Size scale values (xs, s, m, l, xl, etc.)
|
|
22
|
-
* `states.json` - Interaction states (default, hover, focus, etc.)
|
|
23
|
-
* `variants.json` - Color and style variants (accent, negative, primary, etc.)
|
|
24
|
-
* `anatomy-terms.json` - Component anatomy parts (edge, visual, text, icon, etc.)
|
|
25
|
-
* `components.json` - Spectrum component names
|
|
26
|
-
* `scale-values.json` - Numeric scale values (50, 75, 100, 200, etc.)
|
|
27
|
-
* `categories.json` - Component categories
|
|
28
|
-
* `platforms.json` - Platform names (desktop, mobile, web, iOS, Android)
|
|
29
|
-
|
|
30
|
-
## Writing Definitions
|
|
31
|
-
|
|
32
|
-
Follow the [Spectrum Naming and Definition Writing Guide](https://wiki.corp.adobe.com/display/AdobeDesign/Spectrum+Design+System%3A+Naming+and+definition+writing+guide) methodology:
|
|
33
|
-
|
|
34
|
-
### 1. Superordinate
|
|
35
|
-
|
|
36
|
-
The higher-level category or class this term belongs to. This provides context for the reader.
|
|
37
|
-
|
|
38
|
-
**Examples**:
|
|
39
|
-
|
|
40
|
-
* "interaction state" for states like hover or focus
|
|
41
|
-
* "size value" for size scales
|
|
42
|
-
* "user interface component" for components
|
|
43
|
-
* "design token" for token-related terms
|
|
44
|
-
|
|
45
|
-
### 2. Description
|
|
46
|
-
|
|
47
|
-
A clear, concise explanation of what the term is and how it differs from related concepts.
|
|
48
|
-
|
|
49
|
-
**Good example**:
|
|
50
|
-
|
|
51
|
-
> "The state when a component receives focus through keyboard navigation, indicating it will respond to keyboard input"
|
|
52
|
-
|
|
53
|
-
**Bad example**:
|
|
54
|
-
|
|
55
|
-
> "When you tab to something"
|
|
56
|
-
|
|
57
|
-
### 3. Essential Characteristics
|
|
58
|
-
|
|
59
|
-
Key features that distinguish this term from similar concepts. Use bullet points for clarity.
|
|
60
|
-
|
|
61
|
-
**Example for "keyboard-focus"**:
|
|
62
|
-
|
|
63
|
-
* Specifically indicates focus achieved through keyboard interaction (Tab, arrow keys)
|
|
64
|
-
* Requires prominent visual indicator for accessibility (WCAG 2.4.7)
|
|
65
|
-
* Different from generic focus to support :focus-visible patterns
|
|
66
|
-
* Critical for keyboard-only users to understand their current position
|
|
67
|
-
|
|
68
|
-
## JSON Structure
|
|
69
|
-
|
|
70
|
-
### Basic Entry (Minimum Required)
|
|
71
|
-
|
|
72
|
-
```json
|
|
73
|
-
{
|
|
74
|
-
"id": "unique-identifier",
|
|
75
|
-
"label": "Human Readable Label",
|
|
76
|
-
"description": "Brief description of the term",
|
|
77
|
-
"usedIn": ["tokens", "component-schemas"]
|
|
78
|
-
}
|
|
79
|
-
```
|
|
80
|
-
|
|
81
|
-
### Enhanced Entry (Full Glossary)
|
|
82
|
-
|
|
83
|
-
```json
|
|
84
|
-
{
|
|
85
|
-
"id": "keyboard-focus",
|
|
86
|
-
"label": "Keyboard Focus",
|
|
87
|
-
"aliases": ["keyboard focus"],
|
|
88
|
-
"description": "Focused via keyboard navigation",
|
|
89
|
-
"usedIn": ["tokens", "component-options", "component-schemas"],
|
|
90
|
-
|
|
91
|
-
"definition": {
|
|
92
|
-
"superordinate": "interaction state",
|
|
93
|
-
"description": "The state when a component receives focus through keyboard navigation",
|
|
94
|
-
"essentialCharacteristics": [
|
|
95
|
-
"Specifically indicates focus achieved through keyboard interaction",
|
|
96
|
-
"Requires prominent visual indicator for accessibility",
|
|
97
|
-
"Different from generic focus to support :focus-visible patterns"
|
|
98
|
-
]
|
|
99
|
-
},
|
|
100
|
-
|
|
101
|
-
"platforms": {
|
|
102
|
-
"web": {
|
|
103
|
-
"term": "keyboard-focus",
|
|
104
|
-
"notes": "Often implemented with :focus-visible pseudo-class",
|
|
105
|
-
"reference": "https://developer.mozilla.org/en-US/docs/Web/CSS/:focus-visible"
|
|
106
|
-
},
|
|
107
|
-
"iOS": {
|
|
108
|
-
"term": "focused",
|
|
109
|
-
"notes": "UIFocusSystem for keyboard and pointer navigation",
|
|
110
|
-
"reference": "UIFocusSystem"
|
|
111
|
-
}
|
|
112
|
-
},
|
|
113
|
-
|
|
114
|
-
"terminology": {
|
|
115
|
-
"conceptType": "term",
|
|
116
|
-
"namingRationale": "Distinguishes keyboard-based focus from programmatic focus",
|
|
117
|
-
"alternatives": ["tab-focus", "keyboard-navigated"]
|
|
118
|
-
},
|
|
119
|
-
|
|
120
|
-
"sources": [
|
|
121
|
-
{
|
|
122
|
-
"type": "industry-standard",
|
|
123
|
-
"reference": "WCAG 2.4.7 Focus Visible",
|
|
124
|
-
"url": "https://www.w3.org/WAI/WCAG21/Understanding/focus-visible.html",
|
|
125
|
-
"date": "2025-01-12"
|
|
126
|
-
}
|
|
127
|
-
],
|
|
128
|
-
|
|
129
|
-
"governance": {
|
|
130
|
-
"owner": "Spectrum Core Team",
|
|
131
|
-
"reviewDate": "2025-01-12",
|
|
132
|
-
"status": "approved"
|
|
133
|
-
},
|
|
134
|
-
|
|
135
|
-
"relatedTerms": ["focus", "default", "hover"]
|
|
136
|
-
}
|
|
137
|
-
```
|
|
138
|
-
|
|
139
|
-
## Field Reference
|
|
140
|
-
|
|
141
|
-
### Required Fields
|
|
142
|
-
|
|
143
|
-
| Field | Type | Description |
|
|
144
|
-
| ------- | ------ | ------------------------------ |
|
|
145
|
-
| `id` | string | Unique identifier (kebab-case) |
|
|
146
|
-
| `label` | string | Human-readable label |
|
|
147
|
-
|
|
148
|
-
### Optional Fields
|
|
149
|
-
|
|
150
|
-
| Field | Type | Description |
|
|
151
|
-
| ------------------ | --------------------- | ---------------------------------------------------------- |
|
|
152
|
-
| `aliases` | array | Alternative names or spellings |
|
|
153
|
-
| `description` | string | Brief description |
|
|
154
|
-
| `default` | boolean | Whether this is the default value |
|
|
155
|
-
| `deprecated` | boolean | Whether this value is deprecated |
|
|
156
|
-
| `usedIn` | array | Where this value is used (tokens, component-schemas, etc.) |
|
|
157
|
-
| `category` | string | Category or grouping |
|
|
158
|
-
| `value` | string/number/boolean | Actual value (if different from id) |
|
|
159
|
-
| `documentationUrl` | string | URL to documentation |
|
|
160
|
-
|
|
161
|
-
### Enhanced Fields (Glossary)
|
|
162
|
-
|
|
163
|
-
| Field | Type | Description |
|
|
164
|
-
| -------------- | ------ | ---------------------------------------------------------------------------- |
|
|
165
|
-
| `definition` | object | Structured definition (superordinate, description, essentialCharacteristics) |
|
|
166
|
-
| `platforms` | object | Platform-specific terminology and notes |
|
|
167
|
-
| `terminology` | object | Classification and naming rationale |
|
|
168
|
-
| `sources` | array | References to source documentation |
|
|
169
|
-
| `governance` | object | Ownership and review metadata |
|
|
170
|
-
| `relatedTerms` | array | IDs of related terms |
|
|
171
|
-
|
|
172
|
-
## Concept Types
|
|
173
|
-
|
|
174
|
-
From the Spectrum Naming Guide:
|
|
175
|
-
|
|
176
|
-
* **word**: Fundamental building block with multiple possible meanings
|
|
177
|
-
* **term**: Word or phrase with precise meaning in a specific domain
|
|
178
|
-
* **name**: Identifier that distinguishes one thing from another (proper noun)
|
|
179
|
-
* **concept**: Abstract idea that words/terms/names represent
|
|
180
|
-
|
|
181
|
-
## Source Types
|
|
182
|
-
|
|
183
|
-
* **wiki**: Internal Spectrum wiki pages
|
|
184
|
-
* **industry-standard**: W3C, WCAG, platform specifications
|
|
185
|
-
* **platform-standard**: Apple HIG, Material Design, etc.
|
|
186
|
-
* **internal-doc**: Internal Adobe documentation
|
|
187
|
-
* **research**: User research or design research
|
|
188
|
-
|
|
189
|
-
## Governance Status
|
|
190
|
-
|
|
191
|
-
* **draft**: Work in progress, not yet reviewed
|
|
192
|
-
* **review**: Under review by stakeholders
|
|
193
|
-
* **approved**: Reviewed and approved for use
|
|
194
|
-
* **deprecated**: No longer recommended (use `replacedBy` field)
|
|
195
|
-
|
|
196
|
-
## Workflow
|
|
197
|
-
|
|
198
|
-
### Adding a New Term
|
|
199
|
-
|
|
200
|
-
1. **Research**: Understand the concept thoroughly
|
|
201
|
-
2. **Write Definition**: Follow the naming guide methodology
|
|
202
|
-
3. **Check References**: Validate against industry standards and platform docs
|
|
203
|
-
4. **Add Entry**: Create JSON entry with all required fields
|
|
204
|
-
5. **Validate**: Run `pnpm validate` to check schema compliance
|
|
205
|
-
6. **Test**: Run `pnpm test` to ensure no regressions
|
|
206
|
-
7. **Create PR**: Submit for review with changeset
|
|
207
|
-
|
|
208
|
-
### Updating an Existing Term
|
|
209
|
-
|
|
210
|
-
1. **Load Term**: Find the term in the appropriate registry file
|
|
211
|
-
2. **Update Fields**: Make necessary changes
|
|
212
|
-
3. **Update Governance**: Update `reviewDate` and `owner` if needed
|
|
213
|
-
4. **Validate**: Run validation and tests
|
|
214
|
-
5. **Create PR**: Submit for review with changeset explaining changes
|
|
215
|
-
|
|
216
|
-
### Deprecating a Term
|
|
217
|
-
|
|
218
|
-
1. **Set Deprecated**: Add `"deprecated": true`
|
|
219
|
-
2. **Add Replacement**: Set `governance.replacedBy` to new term ID
|
|
220
|
-
3. **Update Status**: Set `governance.status` to `"deprecated"`
|
|
221
|
-
4. **Document Reason**: Add note in PR description
|
|
222
|
-
5. **Create Changeset**: Document the deprecation
|
|
223
|
-
|
|
224
|
-
## Best Practices
|
|
225
|
-
|
|
226
|
-
### Naming
|
|
227
|
-
|
|
228
|
-
* Use kebab-case for IDs
|
|
229
|
-
* Be descriptive but concise
|
|
230
|
-
* Follow industry standards when they exist
|
|
231
|
-
* Avoid metaphorical or fanciful names
|
|
232
|
-
* Name for the action, not the appearance
|
|
233
|
-
|
|
234
|
-
### Definitions
|
|
235
|
-
|
|
236
|
-
* Start with the superordinate to set context
|
|
237
|
-
* Explain what it is AND how it differs from similar concepts
|
|
238
|
-
* Use essential characteristics to highlight unique features
|
|
239
|
-
* Write for both humans and AI systems
|
|
240
|
-
* Avoid circular definitions
|
|
241
|
-
|
|
242
|
-
### Platform Variations
|
|
243
|
-
|
|
244
|
-
* Document when platforms use different terminology
|
|
245
|
-
* Include platform-specific implementation notes
|
|
246
|
-
* Link to official platform documentation
|
|
247
|
-
* Help designers understand cross-platform differences
|
|
248
|
-
|
|
249
|
-
### Cross-References
|
|
250
|
-
|
|
251
|
-
* Link to related terms with `relatedTerms` array
|
|
252
|
-
* Use term IDs, not labels
|
|
253
|
-
* Bi-directional relationships are ideal but not required
|
|
254
|
-
* Help users discover related concepts
|
|
255
|
-
|
|
256
|
-
## Validation
|
|
257
|
-
|
|
258
|
-
Run validation before submitting:
|
|
259
|
-
|
|
260
|
-
```bash
|
|
261
|
-
# Validate all registry files
|
|
262
|
-
pnpm validate
|
|
263
|
-
|
|
264
|
-
# Run test suite
|
|
265
|
-
pnpm test
|
|
266
|
-
```
|
|
267
|
-
|
|
268
|
-
The validation script checks:
|
|
269
|
-
|
|
270
|
-
* JSON schema compliance
|
|
271
|
-
* No duplicate IDs
|
|
272
|
-
* No duplicate aliases
|
|
273
|
-
* Only one default value per registry
|
|
274
|
-
* Valid relatedTerms references
|
|
275
|
-
* Valid governance.replacedBy references
|
|
276
|
-
|
|
277
|
-
## Questions?
|
|
278
|
-
|
|
279
|
-
For questions or feedback:
|
|
280
|
-
|
|
281
|
-
* Slack: #spectrum\_dna
|
|
282
|
-
* Content Strategists: Jess Sattell, Kari Brookmyer
|
|
283
|
-
* GitHub: [Spectrum Design Data Discussions](https://github.com/adobe/spectrum-design-data/discussions)
|
|
284
|
-
|
|
285
|
-
## Related Resources
|
|
286
|
-
|
|
287
|
-
* [Spectrum Naming and Definition Writing Guide](https://wiki.corp.adobe.com/display/AdobeDesign/Spectrum+Design+System%3A+Naming+and+definition+writing+guide)
|
|
288
|
-
* [Spectrum Tokens Wiki](https://wiki.corp.adobe.com/display/AdobeDesign/Spectrum+tokens)
|
|
289
|
-
* [Design System Registry Package README](README.md)
|
|
290
|
-
* [RFC: Spectrum Design System Glossary](https://github.com/adobe/spectrum-design-data/discussions/661)
|