A literal value carried by the example. Used for API property examples where the content is a concrete value rather than a visual demo. Can display code that reflects the example. Accepts any JSON type: string, number, boolean, object, array, or null. When provided without a presentation, this value alone is the example. Do not use `value` for display text — use `title` for captions and `description` for explanations.
The visual or interactive presentation for the example. Required when no `value` is set. Optional when `value` is present — value-only examples represent concrete data points that tools render as table rows or inline displays.
A human-readable caption for the example (e.g., 'Primary button in default state'). For API property examples, use `value` for the literal content and `title` for the display label.
An explanation of the example — why it is encouraged, discouraged, or notable.
Constraint: At least one of presentation, value must be present.
References:
presentationImage, presentationVideo, presentationCode, presentationUrl
[
{
"title": "Primary button — default state",
"description": "The high-emphasis button style used for the most important action on a surface.",
"presentation": {
"kind": "image",
"url": "https://design.acme.com/assets/button-primary-default.png",
"alt": "A primary button with a solid blue background and white label text reading Save."
}
},
{
"title": "JSX — button group with primary and secondary",
"presentation": {
"kind": "code",
"code": "<ButtonGroup>\n <Button variant=\"secondary\">Cancel</Button>\n <Button variant=\"primary\">Save</Button>\n</ButtonGroup>",
"language": "jsx"
}
},
{
"title": "Loading state transition",
"description": "Shows the full loading lifecycle from click through completion.",
"presentation": {
"kind": "video",
"url": "https://design.acme.com/assets/button-loading-interaction.mp4",
"alt": "A user clicks Save. The label is replaced by a spinner. After two seconds, the spinner becomes a checkmark and the label changes to Saved."
}
},
{
"title": "Interactive primary button story",
"presentation": {
"kind": "url",
"url": "https://storybook.acme.com/?path=/story/components-button--primary"
}
},
{
"title": "variant property — primary",
"value": "primary",
"presentation": {
"kind": "code",
"code": "<Button variant=\"primary\">Save</Button>",
"language": "jsx"
}
}
]
Design System Documentation Standard (DSDS) 0.1 — Draft Specification
GitHub