{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"$id": "https://designsystemdocspec.org/v0.15.2/common/presentation.schema.json",
"title": "Presentation definitions",
"description": "Typed presentation objects for visual and interactive demos: image, video, code snippet, or URL. Used by `example` and any schema that embeds a demo.",
"$defs": {
"mediaUrl": {
"type": "string",
"format": "uri-reference",
"description": "URL or relative path to a media file. Relative paths resolve against the referencing document."
},
"mediaAlt": {
"type": "string",
"minLength": 1,
"description": "Alt text for assistive technology. MUST NOT be empty."
},
"presentationImage": {
"type": "object",
"description": "An image. Represents a screenshot, diagram, mockup, or exported design frame.",
"required": [
"kind",
"url",
"alt"
],
"properties": {
"kind": {
"type": "string",
"const": "image",
"description": "Identifies this presentation as an image."
},
"url": {
"$ref": "#/$defs/mediaUrl",
"description": "URL or relative path to the image file."
},
"alt": {
"$ref": "#/$defs/mediaAlt",
"description": "Alt text for the image. MUST NOT be empty."
}
},
"additionalProperties": false
},
"presentationVideo": {
"type": "object",
"description": "A video — screen recording, animated transition, or interaction walkthrough.",
"required": [
"kind",
"url",
"alt"
],
"properties": {
"kind": {
"type": "string",
"const": "video",
"description": "Identifies this presentation as a video."
},
"url": {
"$ref": "#/$defs/mediaUrl",
"description": "URL or relative path to the video file."
},
"alt": {
"$ref": "#/$defs/mediaAlt",
"description": "Alt text for the video. MUST NOT be empty."
}
},
"additionalProperties": false
},
"presentationCode": {
"type": "object",
"description": "A source code snippet showing how to use the artifact.",
"required": [
"kind",
"code",
"language"
],
"properties": {
"kind": {
"type": "string",
"const": "code",
"description": "Identifies this presentation as a code snippet."
},
"code": {
"type": "string",
"description": "The source code of the example.",
"minLength": 1
},
"language": {
"type": "string",
"description": "The language or syntax (ex: 'tsx', 'html', 'css', 'swift', 'kotlin')."
}
},
"additionalProperties": false
},
"presentationUrl": {
"type": "object",
"description": "A link to a web resource — live demo, interactive example, docs page, or hosted story (Storybook, CodeSandbox, StackBlitz, etc.).",
"required": [
"kind",
"url"
],
"properties": {
"kind": {
"type": "string",
"const": "url",
"description": "Identifies this presentation as a URL."
},
"url": {
"type": "string",
"format": "uri",
"description": "URL to the web resource (ex: a Storybook story or CodeSandbox link)."
}
},
"additionalProperties": false
}
}
}
Identifies this presentation as an image.URL or relative path to the image file.Alt text for the image. MUST NOT be empty.References:mediaUrl, mediaAlt{
"kind": "image",
"url": "https://design.acme.com/assets/button-primary-default.png",
"alt": "A primary button in its default state, with a solid blue background and white label text reading Save."
}Identifies this presentation as a video.URL or relative path to the video file.Alt text for the video. MUST NOT be empty.References:mediaUrl, mediaAlt{
"kind": "video",
"url": "https://design.acme.com/assets/button-loading-interaction.mp4",
"alt": "A user clicks a primary button labeled Save. The label is replaced by a spinner animation while the button maintains its width. After two seconds, the spinner is replaced by a checkmark and the label changes to Saved."
}Identifies this presentation as a code snippet.The source code of the example.The language or syntax (ex: 'tsx', 'html', 'css', 'swift', 'kotlin').{
"kind": "code",
"code": "<ButtonGroup>\n <Button variant=\"secondary\">Cancel</Button>\n <Button variant=\"primary\">Save</Button>\n</ButtonGroup>",
"language": "jsx"
}Identifies this presentation as a URL.URL to the web resource (ex: a Storybook story or CodeSandbox link).{
"kind": "url",
"url": "https://storybook.acme.com/?path=/story/components-button--primary"
}