DSDS integration

The Design System Documentation Specification (DSDS) describes a design system's documentation. The contract describes its rules. They meet in two places: a DSDS component entry points at its contract through specs, and a consumer can project contract props and states onto DSDS traits.

The `specs` pointer

`specs` entry #

Location: A DSDS component entry's specs array
Written by: Publisher (SR-138)
Cardinality: One entry per component per contract format

Member	Value
`href`	A relative path or a URI that resolves to the contract file
`rel`	The string `contract`
`role`	The string `Design System Contract`

{
  "id": "button-primary",
  "specs": [
    { "href": "./contracts/button-primary.contract.json", "rel": "contract", "role": "Design System Contract" }
  ]
}

`contractId` and the DSDS `id` #

Rule: contractId SHOULD equal the DSDS component id
Strength: Recommendation, not a requirement. A different value is permitted but discouraged.

Every valid contractId is a valid DSDS id, because the contractId pattern is a subset of the DSDS id pattern.

Multiple contract formats #

A component published in two contract formats has two specs entries, each with its own role.

DSDS validation #

The DSDS document validates against DSDS's own published schema, unchanged. DSDS does not parse the contract that href points at.

Trait mapping

Normative for projection. A consumer that projects a contract onto a DSDS component entry's traits applies this table. The trait's name is the prop or state name, unchanged.

Contract	DSDS `traits` entry	Note	Spec
Prop with `enum`	`traitType: variant`, `kind: enum`, `values` = `default` first, then the remaining `enum` values in declared order	DSDS reads the first value as the default. Without a `default`, the first declared value takes that role.	SR-139
Prop with `type: boolean`	`traitType: variant`, `kind: boolean`		SR-140
Entry in `states`	`traitType: state`, `kind: boolean`	A state is present or absent.	SR-141
Prop with any other type	No trait	DSDS traits do not model free-form props. The contract is the record.
Cross-prop rules	Not in v0.1	Out of scope. DSDS `combos` is cited as prior art for a later version.

Enum prop without a default

When an enum prop has no default, values keeps the declared order. DSDS reads the first value as the default. That default is an assumption DSDS makes; the contract does not assert it. A consumer records that DSDS will read the first value as the default (SCN-018).

Worked example

Contract input

{
  "contractId": "button-primary",
  "component": "Button Primary",
  "props": {
    "properties": {
      "label":    { "type": "string", "description": "Visible text" },
      "variant":  { "type": "string", "enum": ["primary", "secondary"], "default": "primary" },
      "disabled": { "type": "boolean", "default": false }
    },
    "required": ["label"],
    "additionalProperties": false
  },
  "states": ["hover"]
}

Projected traits

Source	Trait name	`traitType`	`kind`	`values`
Prop `variant` (enum, default `primary`)	`variant`	`variant`	`enum`	`["primary", "secondary"]`
Prop `disabled` (boolean)	`disabled`	`variant`	`boolean`
State `hover`	`hover`	`state`	`boolean`
Prop `label` (string, no enum)	No trait

Default ordering variations

Prop schema	Projected `values`
`{ "type": "string", "enum": ["primary", "secondary"], "default": "primary" }`	`["primary", "secondary"]`
`{ "type": "string", "enum": ["primary", "secondary"], "default": "secondary" }`	`["secondary", "primary"]`
`{ "type": "string", "enum": ["primary", "secondary"] }`	`["primary", "secondary"]` (DSDS reads `primary` as the default)

This page lists trait properties by DSDS's own names. It does not restate the JSON shape of a DSDS traits entry; that shape belongs to DSDS.

Cases the mapping table does not address

The v0.1 mapping table doesn't state an outcome for these inputs. They're listed in the known limitations and will be settled in a later version.

A prop and a state with the same name. The example contract button-primary.contract.json declares both a disabled prop and a disabled state, which would project to two traits named disabled.
A prop with type: "boolean" that also carries enum, which matches both the enum row and the boolean row.
A prop whose type is an array that includes boolean, such as ["boolean", "null"].