@adobe/design-system-registry 0.0.0-layout-20260209174611

package/PLATFORM_EXTENSIONS.md

@@ -0,0 +1,315 @@
+# Platform Extensions Guide
+
+This guide explains how platform teams can extend the Spectrum Design System Registry with platform-specific terminology and implementation details.
+
+## Overview
+
+The Platform Extension system allows platform implementations (iOS, Android, Web Components, Qt, etc.) to:
+
+* Define platform-specific terminology for registry terms
+* Document implementation differences
+* Provide code examples in platform-specific APIs
+* Map Spectrum terms to platform conventions
+
+## Extension Approaches
+
+Platform teams have two options for contributing extensions:
+
+### Option 1: Centralized Contributions (Recommended)
+
+Contribute platform-specific metadata directly to the central registry via pull requests.
+
+**Pros**:
+
+* Single source of truth
+* Easy to discover for all users
+* Maintained alongside core registry
+* Included in npm package
+
+**Cons**:
+
+* Requires PR approval from registry maintainers
+* May slow down platform-specific updates
+
+**When to use**: For stable, well-established platform terminology that benefits the entire Spectrum community.
+
+### Option 2: Plugin/Extension System
+
+Maintain platform extensions in your own repository or as separate files.
+
+**Pros**:
+
+* Platform teams have full control
+* Faster iteration for platform-specific changes
+* Can be versioned independently
+* No approval required from central team
+
+**Cons**:
+
+* Users must load extensions separately
+* Risk of fragmentation
+* May become out of sync with base registry
+
+**When to use**: For experimental features, platform-specific implementations, or rapidly changing APIs.
+
+## Creating a Platform Extension
+
+### 1. Create Extension File
+
+Extensions are JSON files that reference base registry terms and add platform-specific information.
+
+**File naming convention**: `{platform}-{registry}.json`
+
+Examples:
+
+* `ios-states.json` - iOS extensions for interaction states
+* `android-sizes.json` - Android extensions for size values
+* `web-components-variants.json` - Web Components extensions for variants
+
+### 2. Extension Schema
+
+```json
+{
+  "$schema": "https://opensource.adobe.com/spectrum-design-data/schemas/platform-extension.json",
+  "platform": "iOS",
+  "platformVersion": "iOS 17+",
+  "description": "iOS-specific terminology for interaction states",
+  "extends": "states",
+  "extensions": [
+    {
+      "termId": "hover",
+      "platformTerm": "highlighted",
+      "platformAliases": ["isHighlighted"],
+      "notes": "iOS uses 'highlighted' state for pointer interactions",
+      "reference": "UIControl.State.highlighted",
+      "codeExample": "button.isHighlighted = true",
+      "differences": [
+        "Only available on devices with pointer support",
+        "Not triggered by touch interactions"
+      ]
+    }
+  ]
+}
+```
+
+### 3. Extension Fields
+
+| Field             | Required | Description                                               |
+| ----------------- | -------- | --------------------------------------------------------- |
+| `platform`        | Yes      | Platform name (iOS, Android, Web Components, Qt, etc.)    |
+| `platformVersion` | No       | Platform or framework version                             |
+| `description`     | No       | What this extension provides                              |
+| `extends`         | Yes      | Which registry it extends (sizes, states, variants, etc.) |
+| `extensions`      | Yes      | Array of term extensions                                  |
+
+### 4. Term Extension Fields
+
+| Field             | Required | Description                                  |
+| ----------------- | -------- | -------------------------------------------- |
+| `termId`          | Yes      | ID of the base term (must exist in registry) |
+| `platformTerm`    | No       | Platform-specific term name                  |
+| `platformAliases` | No       | Platform-specific aliases                    |
+| `notes`           | No       | Implementation notes                         |
+| `reference`       | No       | API name or documentation reference          |
+| `codeExample`     | No       | Code snippet showing usage                   |
+| `differences`     | No       | Key differences from base term               |
+
+## Using Platform Extensions
+
+### In Code
+
+```javascript
+import { 
+  states, 
+  getTermForPlatform,
+  loadPlatformExtension 
+} from '@adobe/design-system-registry';
+
+// Load platform extension
+const iosStates = loadPlatformExtension('./platform-extensions/ios-states.json');
+
+// Get platform-specific term
+const hoverTerm = getTermForPlatform(states, 'hover', 'iOS', iosStates);
+
+console.log(hoverTerm.platform.term); // "highlighted"
+console.log(hoverTerm.platform.reference); // "UIControl.State.highlighted"
+console.log(hoverTerm.platform.codeExample); // "button.isHighlighted = true"
+```
+
+### Loading All Extensions
+
+```javascript
+import { loadAllPlatformExtensions } from '@adobe/design-system-registry';
+import { join } from 'node:path';
+
+const extensionsDir = join(__dirname, 'registry', 'platform-extensions');
+const allExtensions = loadAllPlatformExtensions(extensionsDir);
+
+// Filter by platform
+const iosExtensions = allExtensions.filter(ext => ext.platform === 'iOS');
+```
+
+## Example: iOS States Extension
+
+Here's a complete example showing how iOS extends the states registry:
+
+```json
+{
+  "$schema": "https://opensource.adobe.com/spectrum-design-data/schemas/platform-extension.json",
+  "platform": "iOS",
+  "platformVersion": "iOS 17+",
+  "description": "iOS-specific terminology for interaction states",
+  "extends": "states",
+  "extensions": [
+    {
+      "termId": "hover",
+      "platformTerm": "highlighted",
+      "platformAliases": ["isHighlighted"],
+      "notes": "iOS uses 'highlighted' for pointer interactions on devices with pointer support",
+      "reference": "UIControl.State.highlighted",
+      "codeExample": "button.isHighlighted = true",
+      "differences": [
+        "Only available on iOS devices with pointer support",
+        "Not triggered by touch interactions",
+        "Maps to UIControl.State.highlighted property"
+      ]
+    },
+    {
+      "termId": "disabled",
+      "platformTerm": "disabled",
+      "platformAliases": ["isEnabled"],
+      "notes": "iOS uses isEnabled property (inverted boolean)",
+      "reference": "UIControl.isEnabled",
+      "codeExample": "button.isEnabled = false",
+      "differences": [
+        "Property is named 'isEnabled' but inverted (false = disabled)",
+        "Affects both visual appearance and interaction"
+      ]
+    }
+  ]
+}
+```
+
+## Contributing Centralized Extensions
+
+### 1. Fork and Clone
+
+```bash
+git clone https://github.com/adobe/spectrum-design-data.git
+cd spectrum-design-data
+pnpm install
+```
+
+### 2. Create Extension File
+
+Create your extension file in `packages/design-system-registry/registry/platform-extensions/`.
+
+### 3. Validate
+
+```bash
+cd packages/design-system-registry
+pnpm validate
+```
+
+### 4. Test
+
+Ensure helper functions work with your extension:
+
+```bash
+pnpm test
+```
+
+### 5. Create Changeset
+
+```bash
+pnpm changeset
+```
+
+Select `@adobe/design-system-registry` and describe your changes.
+
+### 6. Submit Pull Request
+
+```bash
+git checkout -b feat/add-{platform}-{registry}-extension
+git add .
+git commit -m "feat(registry): add {platform} extensions for {registry}"
+git push origin feat/add-{platform}-{registry}-extension
+```
+
+Create a PR with:
+
+* Clear description of platform and what's being extended
+* Examples of how the extension improves platform consistency
+* Link to platform documentation
+
+## Maintaining Platform Extensions
+
+### Versioning
+
+* Extension files should evolve with the platform
+* Use `platformVersion` field to indicate compatibility
+* Breaking changes should be documented in commit messages
+
+### Deprecation
+
+When platform APIs change:
+
+1. Add new extension for the new API
+2. Mark old extension term with deprecation note
+3. Provide migration guidance in `differences` field
+
+Example:
+
+```json
+{
+  "termId": "hover",
+  "platformTerm": "highlighted",
+  "notes": "DEPRECATED: Use isPointerInteractionEnabled instead (iOS 18+)",
+  "differences": [
+    "Deprecated in iOS 18",
+    "Replace with isPointerInteractionEnabled property"
+  ]
+}
+```
+
+### Review Cycle
+
+Centralized extensions should be reviewed:
+
+* Annually for accuracy
+* When platform versions update
+* When base registry terms change
+
+## Best Practices
+
+### DO
+
+* ✅ Use official platform terminology
+* ✅ Link to official platform documentation
+* ✅ Provide code examples in platform's language
+* ✅ Document key differences from base term
+* ✅ Use platform naming conventions
+
+### DON'T
+
+* ❌ Invent new terminology not used by platform
+* ❌ Duplicate information already in base term
+* ❌ Include deprecated APIs without notes
+* ❌ Skip validation before submitting
+* ❌ Mix multiple platforms in one extension file
+
+## Questions?
+
+For questions or feedback:
+
+* Slack: #spectrum\_dna
+* GitHub: [Spectrum Design Data Issues](https://github.com/adobe/spectrum-design-data/issues)
+* Email platform leads for platform-specific questions
+
+## Related Resources
+
+* [Design System Registry README](README.md)
+* [Authoring Guide](AUTHORING.md)
+* [Platform Extension Schema](schemas/platform-extension.json)
+* [Example: iOS States Extension](registry/platform-extensions/ios-states.json)
+* [Example: Web Components States Extension](registry/platform-extensions/web-components-states.json)

package/README.md

@@ -0,0 +1,268 @@
+# Design System Registry
+
+A single source of truth for design system terminology used across Spectrum tokens, component schemas, and anatomy.
+
+## Overview
+
+The Design System Registry provides a centralized, validated registry of terminology used throughout the Adobe Spectrum Design System. It ensures consistency in naming and helps prevent divergence across different packages and tools.
+
+## Registries
+
+The package includes the following registries:
+
+### Core Registries
+
+* **sizes.json** - Size scale values (xs, s, m, l, xl, xxl, xxxl, numeric sizes)
+* **states.json** - Interaction states (default, hover, focus, disabled, etc.) with enhanced definitions
+* **variants.json** - Color and style variants (accent, negative, primary, etc.)
+* **anatomy-terms.json** - Anatomical part names (edge, visual, text, icon, etc.)
+* **components.json** - Spectrum component names
+* **scale-values.json** - Numeric scale values (50, 75, 100, 200, etc.)
+* **categories.json** - Component categories (actions, inputs, navigation, etc.)
+* **platforms.json** - Platform names (desktop, mobile, web, iOS, Android)
+
+### Glossary Registries
+
+* **glossary.json** - General design system terminology and concepts
+* **navigation-terms.json** - Navigation-specific terminology (side navigation, header, nav items, etc.)
+* **token-terminology.json** - Token-specific concepts (component, object, scale, property, edge, visual)
+
+### Platform Extensions
+
+Platform-specific terminology extensions are available in `registry/platform-extensions/`:
+
+* **ios-states.json** - iOS-specific state terminology (UIControl.State, etc.)
+* **web-components-states.json** - Web Components state terminology (CSS pseudo-classes, etc.)
+
+## Installation
+
+```bash
+pnpm add @adobe/design-system-registry
+```
+
+## Usage
+
+### Importing Registries
+
+```javascript
+import {
+  // Core registries
+  sizes,
+  states,
+  variants,
+  anatomyTerms,
+  components,
+  scaleValues,
+  categories,
+  platforms,
+  
+  // Glossary registries
+  glossary,
+  navigationTerms,
+  tokenTerminology
+} from '@adobe/design-system-registry';
+
+// Access registry values
+console.log(sizes.values); // Array of size values
+console.log(states.values); // Array of state values with enhanced definitions
+console.log(glossary.values); // General glossary terms
+```
+
+### Enhanced Definitions
+
+Many registry values now include rich definitions following the [Spectrum Naming and Definition Writing Guide](https://wiki.corp.adobe.com/display/AdobeDesign/Spectrum+Design+System%3A+Naming+and+definition+writing+guide):
+
+```javascript
+import { states } from '@adobe/design-system-registry';
+
+const hoverState = states.values.find(v => v.id === 'hover');
+
+console.log(hoverState.definition.superordinate); // "interaction state"
+console.log(hoverState.definition.description); // Full definition
+console.log(hoverState.definition.essentialCharacteristics); // Array of key features
+console.log(hoverState.platforms.web); // Web-specific info
+console.log(hoverState.platforms.iOS); // iOS-specific info
+console.log(hoverState.sources); // Documentation references
+console.log(hoverState.governance); // Ownership and status
+console.log(hoverState.relatedTerms); // Cross-references
+```
+
+### Using Helper Functions
+
+```javascript
+import {
+  sizes,
+  getValues,
+  findValue,
+  hasValue,
+  getDefault,
+  getActiveValues
+} from '@adobe/design-system-registry';
+
+// Get all value IDs
+const sizeIds = getValues(sizes);
+// => ['xs', 's', 'm', 'l', 'xl', 'xxl', 'xxxl', ...]
+
+// Find a value by ID or alias
+const mediumSize = findValue(sizes, 'm');
+const alsoMedium = findValue(sizes, 'medium'); // Using alias
+// => { id: 'm', label: 'Medium', aliases: ['medium'], ... }
+
+// Check if a value exists
+if (hasValue(sizes, 'xl')) {
+  console.log('XL is a valid size');
+}
+
+// Get the default value
+const defaultSize = getDefault(sizes);
+// => { id: 'm', label: 'Medium', default: true, ... }
+
+// Get only non-deprecated values
+const activeSizes = getActiveValues(sizes);
+```
+
+### Importing Individual Registry Files
+
+```javascript
+import sizesData from '@adobe/design-system-registry/registry/sizes.json' assert { type: 'json' };
+import statesData from '@adobe/design-system-registry/registry/states.json' assert { type: 'json' };
+```
+
+## Registry Structure
+
+Each registry file follows this JSON structure:
+
+```json
+{
+  "$schema": "../schemas/registry-value.json",
+  "type": "size",
+  "description": "Standard size scale values used across Spectrum",
+  "values": [
+    {
+      "id": "m",
+      "label": "Medium",
+      "aliases": ["medium"],
+      "default": true,
+      "usedIn": ["tokens", "component-options", "component-schemas"],
+      "description": "Optional detailed description"
+    }
+  ]
+}
+```
+
+### Value Properties
+
+#### Basic Properties
+
+* **id** (required): Unique identifier
+* **label** (required): Human-readable label
+* **aliases**: Alternative names or spellings
+* **description**: Detailed description
+* **default**: Whether this is the default value
+* **deprecated**: Whether this value is deprecated
+* **usedIn**: Where this value is used (tokens, component-schemas, etc.)
+* **category**: Category or grouping
+* **value**: Actual value if different from ID
+* **documentationUrl**: URL to documentation
+
+#### Enhanced Glossary Properties
+
+* **definition**: Structured definition (superordinate, description, essentialCharacteristics)
+* **platforms**: Platform-specific terminology and notes
+* **terminology**: Classification and naming rationale (conceptType, namingRationale, alternatives)
+* **sources**: References to source documentation
+* **governance**: Ownership and review metadata (owner, reviewDate, status, replacedBy)
+* **relatedTerms**: IDs of related terms
+
+See [AUTHORING.md](AUTHORING.md) for detailed documentation on using these properties.
+
+## Validation
+
+The registry includes JSON Schema validation and consistency checks:
+
+```bash
+# Validate all registries
+pnpm run validate
+
+# Run tests
+pnpm test
+```
+
+The validation script checks for:
+
+* JSON Schema compliance
+* Duplicate IDs within a registry
+* Duplicate aliases within a registry
+* Multiple default values
+* Required fields
+* Valid relatedTerms references
+* Valid governance.replacedBy references
+
+### Working with Platform Extensions
+
+Platform teams can extend the registry with platform-specific terminology:
+
+```javascript
+import { 
+  states, 
+  getTermForPlatform,
+  loadPlatformExtension 
+} from '@adobe/design-system-registry';
+
+// Load platform extension
+const iosStates = loadPlatformExtension('./registry/platform-extensions/ios-states.json');
+
+// Get platform-specific term
+const hoverTerm = getTermForPlatform(states, 'hover', 'iOS', iosStates);
+
+console.log(hoverTerm.platform.term); // "highlighted"
+console.log(hoverTerm.platform.reference); // "UIControl.State.highlighted"
+console.log(hoverTerm.platform.codeExample); // "button.isHighlighted = true"
+```
+
+See [PLATFORM\_EXTENSIONS.md](PLATFORM_EXTENSIONS.md) for detailed documentation.
+
+## Development
+
+### Running Tests
+
+```bash
+pnpm test
+```
+
+### Validating Registry
+
+```bash
+pnpm run validate
+```
+
+### Contributing
+
+When adding new values to registries:
+
+1. Ensure the value has a unique `id`
+2. Provide a clear `label`
+3. Add `aliases` for common alternative names
+4. Set `usedIn` to indicate where it's used
+5. Add `description` for clarity
+6. Run validation to check for errors
+7. Run tests to ensure consistency
+
+## Used By
+
+This registry is consumed by:
+
+* `@adobe/spectrum-tokens` - Design tokens
+* `@adobe/spectrum-component-api-schemas` - Component schemas
+* `@adobe/component-options-editor` - Component options authoring tool
+* Token validation tools
+* Future anatomy editor
+
+## Related Packages
+
+* [@adobe/spectrum-tokens](../tokens) - Design tokens for Spectrum
+* [@adobe/spectrum-component-api-schemas](../component-schemas) - Component API schemas
+
+## License
+
+Apache 2.0

package/ava.config.js

@@ -0,0 +1,21 @@
+/*
+Copyright 2025 Adobe. All rights reserved.
+This file is licensed to you under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License. You may obtain a copy
+of the License at http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software distributed under
+the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR REPRESENTATIONS
+OF ANY KIND, either express or implied. See the License for the specific language
+governing permissions and limitations under the License.
+*/
+
+export default {
+  files: ["test/**/*.test.js"],
+  environmentVariables: {
+    NODE_ENV: "test",
+  },
+  verbose: true,
+  failFast: false,
+  failWithoutAssertions: true,
+};