DSDS Link Definition

The category of the linked resource or relationship. Standard external kinds: 'source', 'design', 'storybook', 'documentation', 'package', 'repository'. Standard relationship kinds: 'alternative', 'parent', 'child', 'related'. Standard artifact kinds (for internal references): 'component', 'token', 'token-group', 'style', 'pattern', 'theme'. Custom values are allowed and SHOULD match ^[a-z][a-z0-9-]*$.

The URL of the linked resource. MUST be a valid absolute URI. Required for external resource links. Optional for internal artifact references (where identifier names the artifact). When both url and identifier are present, url points to the artifact's docs page and identifier is the machine-readable cross-reference.

The identifier of a referenced DSDS artifact (e.g., 'button', 'form-field', 'color-text'). MUST match the identifier property of a documented DSDS artifact. Required for internal artifact references. Optional for external resource links. When present, tools SHOULD resolve this identifier against the artifact catalog to create navigable cross-references.

Display text for this link — what a user sees when the link renders (e.g., 'React component source', 'Design file — variants', 'Button component'). Use it for the display name of the resource. To describe an internal artifact's role, use role instead.

The functional role this artifact plays in the current entity (e.g., 'Primary action trigger', 'Error summary container', 'Provides semantic text color tokens'). Distinct from label, which is display text for the link itself. Use it on internal artifact references to explain *why* this artifact is linked. When omitted, the link is a general association.

Whether this linked artifact is required for the parent entity to work. Used on internal artifact references — for example, a form-validation pattern might mark 'form-field' as required and 'toast' as optional. Defaults to false. Not used on external resource links.
Default: false

Constraint: At least one of url, identifier must be present.

[ { "kind": "source", "url": "https://code.acme.com/design-system/src/components/button/button.tsx", "label": "React component source" }, { "kind": "design", "url": "https://design-tool.acme.com/file/abc123?node-id=1234:5678", "label": "Design file — component" }, { "kind": "documentation", "url": "https://design.acme.com/components/button", "label": "Button documentation" }, { "kind": "storybook", "url": "https://storybook.acme.com/?path=/docs/components-button--docs", "label": "Interactive docs" }, { "kind": "package", "url": "https://www.npmjs.com/package/@acme/components", "label": "npm package" }, { "kind": "repository", "url": "https://code.acme.com/design-system", "label": "Repository root" }, { "kind": "alternative", "url": "https://design.acme.com/components/link", "label": "Link component (alternative)" }, { "kind": "parent", "url": "https://design.acme.com/components/button-group", "label": "Button Group (parent)" } ]