DSP is a new open-format folder-structure created to help teams share design system information across tools.
This document describes the Design System Package (DSP) structure, including details of how each internal file or folder should be used.
A Design System Package (DSP) is a folder containing subfolders with assets and JSON files that represent design system information:
DSP example: Adobe Spectrum DSP
These are the contents of each DSP folder:
This folder contains all the static assets included in the DSP, such as SVG or PNG files.
This folder contains all of the data that comprises the DSP format. The folder has no required files. File examples are components.json, docs.json, fonts.json and tokens.json.
This folder contains platform-specific code generated by a build system. For example, the Adobe XD extension for Visual Studio Code has Style Dictionary as its build system. Examples of folders created by a build system are /android, /css and /styledictionary. Dist also contains non-platform-specific code such as the Style Dictionary input files and folders (config and properties).
This folder could hold files written by third party tools. Its subfolders must follow the reverse domain name convention of "com_partner_name" (e.g. for Adobe, the folder should be named "com_adobe").
This is the entry point for the Design System Package (DSP). It includes package info, settings, and imports.
The dsp.json file has specific elements:
// DSP Spec Version, present in all DSP JSON files
"dsp_spec_version": "1.0",
// Who last updated this file
"last_updated_by": "Author Name",
// When this file was last updated using UTCDateTime (eg. 2020-09-24T06:08:46.497Z)
"last_updated": "UTCDateTime",
"settings": {
"name": "My Design System",
"package_version": "0.5.0",
// Examples: dev, staged, released, deprecated
"build_status_label": "dev",
// Prefix that will be prepended to code snippets
"snippet_trigger_prefix": "xd-",
"build_tool": "styledictionary",
"build_tool_version": "1.0.0",
// extra command line parameters that can be passed to the build tool during token compilation
"build_params": "-c ./config.json",
// languages to be used in component code snippets and build tool
"languages": [
{
"label": "Spectrum CSS",
"export_tokens": true,
// snippet_id is used in components to identify a language option for code snippets
"snippet_id": "my-css-snippet",
"syntax": "text/css"
/*
additional properties that are not core to DSP should follow the reverse domain
naming convention (e.g. 'ext-com_adobe_xd-styledictionary_id' is set to use Style
Dictionary transform group 'css' to compile agnostic design tokens stored in /data,
into CSS variables, if export_tokens is set to true)
*/
"ext-com_adobe_xd-styledictionary_id": "css"
},
{
"label": "React",
"export_tokens": false,
"snippet_id": "react",
"syntax": "javascript"
},
{
"label": "Angular",
"export_tokens": false,
"snippet_id": "angular",
"syntax": "javascript"
}
]
}/*
DSP JSON files can be imported into other packages,
by being added to the import array.
If there are overrides, the first instance in
the array wins.
*/
"import": [
{"src": "data/components.json"},
{"src": "data/docs.json"},
{"src": "data/tokens.json"},
{"src": "data/fonts.json"}
],/*
If partners need to add specific information that
is not core to DSP, the new information has to be placed
inside an ext object following the reverse domain
naming convention (https://en.wikipedia.org/wiki/Reverse_domain_name_notation)
*/
"ext-com_partnername": {
"foo": "..."
},The entities array contains objects defining the entities that comprise the design system. This can include entities such as design tokens, collections of tokens, documentation pages, and components. While entities can be defined in dsp.json, it is common to split them into separate files and include them via the import property.
Note: See the sample in Imported JSON files for additional information and examples.
class Currently recognized values are:
type Divides each class by functional category. Currently recognized values for each class are:
*Note: For the color value, we recommend using RGBA hexadecimal (#RRGGBBAA, hex value with alpha).
Note 1: Collections have a tokens element listing all tokens that make that collection.
Note 2: Component pages can have related_entity_ids for "used by" tokens, as well as snippets.
{
"dsp_spec_version": "1.0",
"last_updated": "UTCDateTime",
"last_updated_by": "Author Name",
"ext-com_partnername": {
"foo": "..."
},
"import": [
{"src": "data/components.json"},
{"src": "data/docs.json"},
{"src": "data/tokens.json"},
{"src": "data/fonts.json"}
],
"settings": {
"name": "My Design System",
"package_version": "0.5.0",
"build_status_label": "dev",
"snippet_trigger_prefix": "xd-",
"build_tool": "styledictionary",
"build_tool_version": "1.0.0",
"build_params": "-c ./config.json",
"languages": [
{
"label": "CSS",
"export_tokens": true,
"snippet_id": "css",
"syntax": "text/css"
},
{
"label": "React",
"export_tokens": true,
"snippet_id": "react",
"syntax": "javascript",
"ext-com_adobe_xd-styledictionary_id": "js"
},
{
"label": "Angular",
"export_tokens": true,
"snippet_id": "angular",
"syntax": "javascript",
"ext-com_adobe_xd-styledictionary_id": "js"
}
]
}
}Additional JSON files can be imported to define additional tokens, components, docs and collections. They can be broken down into separate JSON files, or can be all in one JSON file. For organization purposes, we recommend saving them in the /data folder.
Each JSON file must include the standard file header, and may contain any of the properties defined for the dsp.json file. If a settings property is defined in an imported file, it will be ignored in favor of the dsp.json value.
{
"dsp_spec_version": "1.0",
"last_updated": "UTCDateTime",
"last_updated_by": "Author Name",
"entities": [
{
"class": "token",
"type": "color",
"id": "warning-label-color",
"value": "FFFF0011",
"name": "name is optional, will default to id if omitted",
"last_updated": "UTCDateTime",
"last_updated_by": "Author Name",
"description": "The red used everywhere",
"tags": [
"branding",
"color",
"primary"
],
"ext-com_adobe-cclib": {
"source": "http://cclib-full-url",
"id": "cclibid",
"last_sync": "UTCDateTime",
"sync": true
}
},
{
"class": "token",
"type": "size",
"id": "size-font-medium",
"value": "14.0",
"last_updated": "UTCDateTime",
"last_updated_by": "Author Name",
"description": "The medium 14 used everywhere",
"tags": [
"branding",
"color",
"primary"
]
},
{
"class": "token",
"type": "color",
"id": "primary-red",
"name": "primary-red",
"value": "#FF0000",
"description": "This is the red used _everywhere_, it is **important** to remember our brand guidelines",
"last_updated": "2020-07-28T22:44:29.537Z",
"last_updated_by": "Author Name",
"tags": [
"branding",
"color",
"primary"
]
},
{
"class": "token",
"type": "color",
"id": "primary-green",
"name": "primary-green",
"value": "#00ff00",
"description": "The green used everywhere",
"last_updated": "2020-07-28T22:44:29.537Z",
"last_updated_by": "Author Name",
"tags": []
},
{
"class": "token",
"type": "alias",
"id": "cta-background",
"name": "cta-background",
"value": "{primary-red}",
"description": "The background color used for calls to action",
"last_updated": "2020-07-28T22:44:29.537Z",
"last_updated_by": "Author Name",
"tags": []
},
{
"class": "token",
"type": "custom",
"id": "base-weight-value",
"name": "base-weight-value",
"value": "bold",
"description": "Token description here",
"last_updated": "2020-07-28T22:44:29.537Z",
"last_updated_by": "Author Name",
"tags": []
},
{
"class": "token",
"type": "custom",
"id": "custom-value",
"name": "custom-value",
"value": "foo",
"description": "",
"last_updated": "2020-07-28T22:44:29.537Z",
"last_updated_by": "Author Name",
"tags": []
},
{
"class": "token",
"type": "custom",
"id": "font-default-text-family",
"name": "font-default-text-family",
"value": "Segoe UI",
"description": "",
"last_updated": "2020-07-28T22:44:29.537Z",
"last_updated_by": "Author Name",
"tags": []
},
{
"class": "token",
"type": "custom",
"id": "font-default-text-weight",
"name": "font-default-text-weight",
"value": "Bold",
"description": "",
"last_updated": "2020-07-28T22:44:29.537Z",
"last_updated_by": "Author Name",
"tags": []
},
{
"class": "token",
"type": "size",
"id": "font-default-text-size",
"name": "font-default-text-size",
"value": "12",
"description": "",
"last_updated": "2020-07-28T22:44:29.537Z",
"last_updated_by": "Author Name",
"tags": []
},
{
"class": "token",
"type": "size",
"id": "base-line-height",
"name": "base-line-height",
"value": "4",
"description": "Line height description here",
"last_updated": "2020-07-28T22:44:29.537Z",
"last_updated_by": "Author Name",
"tags": [],
"category_id": "912ab61e-5227-4ec7-8649-fd50e1423724" //optional
},
{
"class": "token",
"type": "size",
"id": "spacing-10",
"name": "spacing-10",
"value": "10",
"description": "Spacing description here",
"last_updated": "2020-07-28T22:44:29.537Z",
"last_updated_by": "Author Name",
"tags": [],
"category_id": "24c6d6be-9004-4ca7-be4c-309b6b55fbb3" //optional
}
],
"categories": [
{
"id": "912ab61e-5227-4ec7-8649-fd50e1423724", //unique id
"label": "Line Height"
},
{
"id": "24c6d6be-9004-4ca7-be4c-309b6b55fbb3",
"label": "Spacing"
}
]
}{
"dsp_spec_version": "1.0",
"last_updated": "UTCDateTime",
"last_updated_by": "Author Name",
"entities": [
{
"class": "collection",
"type": "font",
"id": "myfont",
"last_updated": "UTCDateTime",
"last_updated_by": "Author Name",
"description": "The red used everywhere",
"tags": [
"branding",
"color",
"primary"
],
"ext-com_adobe-cclib": {
"source": "http://cclib-full-url",
"id": "cclibid",
"last_sync": "UTCDateTime",
"sync": true
},
"tokens": [
{
"key": "family",
"id": "font-myfont-family",
"type": "custom",
"value": "Segoe UI, Arial, sans-serif"
},
{
"key": "size",
"id": "size-myfont-small",
"type": "size",
"value": "10"
}
],
"related_entity_ids": ["ids_of_added_tokens"] // optional
},
{
"class": "collection",
"type": "font",
"id": "default-text",
"name": "default-text",
"tags": [],
"tokens": [
{
"id": "font-default-text-family",
"type": "custom",
"value": "Segoe UI",
"key": "family"
},
{
"id": "font-default-text-weight",
"type": "custom",
"value": "Bold",
"key": "weight"
},
{
"id": "font-default-text-size",
"type": "size",
"value": "12",
"key": "size"
}
]
}
]
}{
"dsp_spec_version": "1.0",
"last_updated": "UTCDateTime",
"last_updated_by": "Author Name",
"entities": [
{
"class": "component",
"type": "page",
"id": "unique-id",
"name": "Button",
"last_updated": "UTCDateTime",
"last_updated_by": "Author Name",
"description": "Markdown with support for basic HTML including img and iframe tags.",
"tags": [
"branding",
"color",
"primary"
],
"related_entity_ids": [
"btn-background-color",
"default-text"
],
"snippets": {
"trigger": "my_component",
"languages": {
"my-css-snippet": "...",
"react": "...",
"angular": "..."
}
},
"renditions": ["component-rendition.svg"]
}
]
}{
"dsp_spec_version": "1.0",
"last_updated": "UTCDateTime",
"last_updated_by": "Author Name",
"import": [],
"entities": [
{
"class": "doc",
"type": "page",
"id": "a-unique-id",
"name": "Introduction",
"last_updated": "UTCDateTime",
"last_updated_by": "Author Name",
"description": "The red used everywhere. This field fully supports [Markdown](https://commonmark.org/help/) with support for basic HTML.",
"tags": [
"branding",
"color",
"primary"
]
}
]
}If you decide to use NPM to distribute your package, please add a package.json file to the root folder by following the instructions to publish to NPM.
One example is Adobe Spectrum DSP on npm, that can be installed on your project with npm install adobe-spectrum-dsp.
For iOS you can explore sharing the tokens using CocoaPods, and for Android you can explore sharing the tokens as part of a Gradle.
Please file an issue.