DSDS Link Definition

The category of the linked resource or relationship. Standard external types: 'source', 'design', 'storybook', 'documentation', 'package', 'repository'. Standard relationship types: 'alternative', 'parent', 'child', 'related'. Standard artifact types (for internal references): 'component', 'token', 'token-group', 'style', 'pattern', 'theme'. Custom values are permitted 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 `name` identifies the artifact). When both `url` and `name` are present, `url` points to the artifact's docs page and `name` is the machine-readable cross-reference.

The name of a referenced DSDS artifact (e.g., 'button', 'form-field', 'color-text'). MUST match the `name` property of a documented DSDS artifact. Required for internal artifact references. Optional for external resource links. When present, tools SHOULD resolve this name 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 for the human-readable resource name. To describe an internal artifact's functional relationship, use `role` instead.

The functional relationship this artifact has to the current entity — what part it plays (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 for 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 function. Used for internal artifact references — for example, a form-validation pattern might mark 'form-field' as required and 'toast' as optional. Defaults to false. Not applicable to external resource links.
Default: false

Constraint: At least one of url, name 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)" } ]