@adobe/design-data-spec 0.7.0 → 0.8.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@adobe/design-data-spec",
-  "version": "0.7.0",
+  "version": "0.8.0",
   "description": "Design Data Specification — prose, JSON Schemas, rule catalog, and conformance fixtures for Spectrum design data",
   "type": "module",
   "repository": {

package/rules/rules.yaml

@@ -244,3 +244,27 @@ rules:
     message: "Component '{component}' tokenBindings references unknown token '{token}'"
     spec_ref: spec/component-format.md#token-bindings
     introduced_in: "1.0.0-draft"
+
+  - id: SPEC-028
+    name: document-block-agents-equals-content
+    severity: warning
+    category: completeness
+    assert: >
+      A document block's agents field, when present, SHOULD contain phrasing that differs from
+      content. An identical copy provides no agent-specific value and SHOULD be omitted or refined.
+      Applies to tokens, components, and anatomy parts.
+    message: "'{entity}' has a document block whose agents text is identical to content — tailor it for agent consumption or omit the agents field"
+    spec_ref: spec/document-blocks.md
+    introduced_in: "1.0.0-draft"
+
+  - id: SPEC-029
+    name: document-block-missing-purpose
+    severity: warning
+    category: completeness
+    assert: >
+      An entity that carries a non-empty documentBlocks array SHOULD include at least one block
+      with type 'purpose' to document the entity's intent.
+      Applies to tokens, components, and anatomy parts.
+    message: "'{entity}' has documentBlocks but no purpose block — add a block with type 'purpose'"
+    spec_ref: spec/document-blocks.md
+    introduced_in: "1.0.0-draft"

package/schemas/anatomy-part.schema.json

@@ -29,6 +29,12 @@
       },
       "uniqueItems": true,
       "description": "Informative list of child anatomy part names nested within this part. Does not carry enforcement semantics."
+    },
+    "documentBlocks": {
+      "type": "array",
+      "items": { "$ref": "document-block.schema.json" },
+      "minItems": 1,
+      "description": "Typed prose blocks for this anatomy part. See spec/document-blocks.md (Phase 9)."
     }
   },
   "additionalProperties": false

package/schemas/component.schema.json

@@ -68,6 +68,12 @@
       "type": "array",
       "items": { "$ref": "#/$defs/tokenBinding" },
       "description": "Tokens this component uses, including foundation/structure tokens not scoped to the component in their name-object. See spec/component-format.md#token-bindings (Phase 6.7)."
+    },
+    "documentBlocks": {
+      "type": "array",
+      "items": { "$ref": "document-block.schema.json" },
+      "minItems": 1,
+      "description": "Typed prose blocks for this component. See spec/document-blocks.md (Phase 9)."
     }
   },
   "additionalProperties": false,
@@ -203,6 +209,11 @@
           "type": "array",
           "items": { "type": "string" },
           "description": "Informative: anatomy part names nested within this part."
+        },
+        "documentBlocks": {
+          "type": "array",
+          "items": { "$ref": "document-block.schema.json" },
+          "description": "Typed prose blocks for this anatomy part. See spec/document-blocks.md (Phase 9)."
         }
       },
       "additionalProperties": false

package/schemas/document-block.schema.json

@@ -0,0 +1,43 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://opensource.adobe.com/spectrum-design-data/schemas/v0/document-block.schema.json",
+  "title": "Document block",
+  "description": "A typed prose block attachable to tokens, components, or anatomy parts. See spec/document-blocks.md.",
+  "type": "object",
+  "required": ["type", "content"],
+  "properties": {
+    "type": {
+      "type": "string",
+      "enum": ["purpose", "guideline", "accessibility", "do-dont", "examples"],
+      "description": "Block type. One of: purpose, guideline, accessibility, do-dont, examples."
+    },
+    "content": {
+      "type": "string",
+      "minLength": 1,
+      "description": "Human-readable prose for this block."
+    },
+    "agents": {
+      "type": "string",
+      "minLength": 1,
+      "description": "Optional LLM-tuned rephrasing of content for agent consumption. Should differ from content."
+    },
+    "do": {
+      "type": "string",
+      "minLength": 1,
+      "description": "Recommended practice. Meaningful only on do-dont blocks."
+    },
+    "dont": {
+      "type": "string",
+      "minLength": 1,
+      "description": "Anti-pattern to avoid. Meaningful only on do-dont blocks."
+    }
+  },
+  "additionalProperties": false,
+  "if": {
+    "properties": { "type": { "const": "do-dont" } },
+    "required": ["type"]
+  },
+  "then": {
+    "anyOf": [{ "required": ["do"] }, { "required": ["dont"] }]
+  }
+}

package/schemas/token.schema.json

@@ -180,6 +180,12 @@
           "type": "array",
           "items": { "$ref": "#/$defs/componentBinding" },
           "description": "Reverse index: components that declare this token in their tokenBindings. Optional and derivable from component files."
+        },
+        "documentBlocks": {
+          "type": "array",
+          "items": { "$ref": "document-block.schema.json" },
+          "minItems": 1,
+          "description": "Typed prose blocks for this token. See spec/document-blocks.md (Phase 9)."
         }
       },
       "additionalProperties": false
@@ -258,6 +264,12 @@
           "type": "array",
           "items": { "$ref": "#/$defs/componentBinding" },
           "description": "Reverse index: components that declare this token in their tokenBindings. Optional and derivable from component files."
+        },
+        "documentBlocks": {
+          "type": "array",
+          "items": { "$ref": "document-block.schema.json" },
+          "minItems": 1,
+          "description": "Typed prose blocks for this token. See spec/document-blocks.md (Phase 9)."
         }
       },
       "additionalProperties": false

package/spec/component-format.md

@@ -29,16 +29,17 @@ A component declaration **MUST** contain:
 
 ### Optional fields
 
-| Field           | Type   | Description                                                                                                                                |
-| --------------- | ------ | ------------------------------------------------------------------------------------------------------------------------------------------ |
-| `specVersion`   | string | Declares which spec version this document targets. Currently `"1.0.0-draft"`; future stable releases will accept their own version string. |
-| `description`   | string | Plain-text description of the component's purpose.                                                                                         |
-| `options`       | object | Component API options — see [Options](#options).                                                                                           |
-| `slots`         | array  | Named content injection points — see [Slots](#slots).                                                                                      |
-| `anatomy`       | array  | Named anatomy parts — see [Anatomy (stub)](#anatomy-stub).                                                                                 |
-| `states`        | array  | Per-component state declarations — see [States (stub)](#states-stub).                                                                      |
-| `lifecycle`     | object | Version lifecycle metadata — see [Lifecycle](#lifecycle).                                                                                  |
-| `tokenBindings` | array  | Tokens this component uses — see [Token bindings](#token-bindings) (Phase 6.7).                                                            |
+| Field            | Type   | Description                                                                                                                                |
+| ---------------- | ------ | ------------------------------------------------------------------------------------------------------------------------------------------ |
+| `specVersion`    | string | Declares which spec version this document targets. Currently `"1.0.0-draft"`; future stable releases will accept their own version string. |
+| `description`    | string | Plain-text description of the component's purpose.                                                                                         |
+| `options`        | object | Component API options — see [Options](#options).                                                                                           |
+| `slots`          | array  | Named content injection points — see [Slots](#slots).                                                                                      |
+| `anatomy`        | array  | Named anatomy parts — see [Anatomy (stub)](#anatomy-stub).                                                                                 |
+| `states`         | array  | Per-component state declarations — see [States (stub)](#states-stub).                                                                      |
+| `lifecycle`      | object | Version lifecycle metadata — see [Lifecycle](#lifecycle).                                                                                  |
+| `tokenBindings`  | array  | Tokens this component uses — see [Token bindings](#token-bindings) (Phase 6.7).                                                            |
+| `documentBlocks` | array  | Typed prose blocks for this component — see [Document blocks](#document-blocks) (Phase 9).                                                 |
 
 **NORMATIVE:** No properties beyond those listed above are permitted at the top level of a component declaration. Additional fields **MUST** cause a Layer 1 schema error.
 
@@ -349,3 +350,34 @@ A complete button component declaration:
   }
 }
 ```
+
+## Document blocks
+
+**Phase 9.** Component declarations MAY carry a `documentBlocks` array at the top level, and individual anatomy parts MAY carry their own `documentBlocks` arrays. See [spec/document-blocks.md](document-blocks.md) for the full block schema, type vocabulary, and SPEC rules.
+
+```json
+{
+  "name": "button",
+  "displayName": "Button",
+  "meta": { "category": "actions", "documentationUrl": "https://spectrum.adobe.com/page/button/" },
+  "documentBlocks": [
+    {
+      "type": "purpose",
+      "content": "Buttons trigger a discrete action or event.",
+      "agents": "Use Button when the user must trigger an action. For navigation, use Link."
+    }
+  ],
+  "anatomy": [
+    {
+      "name": "label",
+      "required": true,
+      "documentBlocks": [
+        {
+          "type": "guideline",
+          "content": "Button labels should be action verbs (Save, Delete, Submit)."
+        }
+      ]
+    }
+  ]
+}
+```

package/spec/document-blocks.md

@@ -0,0 +1,182 @@
+# Document blocks
+
+**Spec version:** `1.0.0-draft` (see [Overview](index.md))
+
+This document defines **document blocks**: typed prose objects attachable to tokens, components, and anatomy parts. Blocks carry design guidance — intent, usage rules, accessibility notes, do/don't pairs, and examples — alongside the structured data they describe, making that guidance machine-readable and queryable by agents.
+
+Design guidance like "accent backgrounds are for primary CTAs only" or "don't combine `negative` with `subtle`" previously lived in scattered Markdown documents invisible to the spec's resolver, validator, and agent surface. Document blocks attach that prose directly to the entities it describes so it cascades with the tokens and components it governs.
+
+Inspired by the [Design System Documentation Spec (DSDS)](https://designsystemdocspec.org/) document-block model.
+
+Scoped under RFC-D / Phase 9. See [rfc-coordination.md](../docs/rfc-coordination.md).
+
+## Document block shape
+
+A document block is a JSON object conforming to [`document-block.schema.json`](../schemas/document-block.schema.json).
+
+### Required fields
+
+| Field     | Type   | Description                              |
+| --------- | ------ | ---------------------------------------- |
+| `type`    | string | Block type — one of the five types below |
+| `content` | string | Human-readable prose for this block      |
+
+### Optional fields
+
+| Field    | Type   | Description                                                 |
+| -------- | ------ | ----------------------------------------------------------- |
+| `agents` | string | LLM-tuned rephrasing of `content` for agent consumption     |
+| `do`     | string | Recommended practice — meaningful only on `do-dont` blocks  |
+| `dont`   | string | Anti-pattern to avoid — meaningful only on `do-dont` blocks |
+
+**NORMATIVE:** `type` and `content` are required on every document block. A block with an empty string for either field **MUST** fail Layer 1 schema validation.
+
+**NORMATIVE:** `do` and `dont` are defined on all block shapes (Layer 1 does not restrict them by type), but implementations SHOULD treat them as meaningful only on `do-dont` blocks. Using them on other block types is valid but has no defined semantics.
+
+**RECOMMENDED:** When `agents` is present, its content SHOULD differ meaningfully from `content`. An `agents` value identical to `content` provides no agent-specific value and SHOULD be omitted or refined (see SPEC-028).
+
+## Block types
+
+### `purpose`
+
+Describes the intent and design role of the entity. Answers "what is this for?"
+
+```json
+{
+  "type": "purpose",
+  "content": "Accent background tokens represent the primary brand call-to-action surface. They establish hierarchy by drawing attention to the most important interactive element on screen.",
+  "agents": "Use accent-background tokens on the highest-priority interactive element. They signal 'primary action here' to users."
+}
+```
+
+### `guideline`
+
+A usage rule or constraint. Answers "how should this be used?"
+
+```json
+{
+  "type": "guideline",
+  "content": "Accent backgrounds should appear on no more than one element per focal area. Multiple accent surfaces compete for attention and dilute the hierarchy signal."
+}
+```
+
+### `accessibility`
+
+Accessibility notes specific to this entity — contrast behavior, screen reader considerations, or interaction semantics.
+
+```json
+{
+  "type": "accessibility",
+  "content": "Accent background tokens must maintain a minimum 3:1 contrast ratio against the surface they sit on in both light and dark schemes. The high-contrast dimension variant provides an alternative that meets 4.5:1."
+}
+```
+
+### `do-dont`
+
+A paired recommended practice and anti-pattern. The `do` and `dont` fields carry the pairing; `content` provides context or a summary heading.
+
+**NORMATIVE:** A `do-dont` block **MUST** include at least one of `do` or `dont`. A `do-dont` block with neither field **MUST** fail Layer 1 schema validation.
+
+```json
+{
+  "type": "do-dont",
+  "content": "Combining semantic backgrounds",
+  "do": "Use accent-background for the primary CTA and informative-background for supporting UI.",
+  "dont": "Combine accent-background with negative-background in the same focal area — both are high-attention surfaces and the pairing creates visual conflict."
+}
+```
+
+### `examples`
+
+Concrete usage examples — code snippets, component references, or scenario descriptions.
+
+```json
+{
+  "type": "examples",
+  "content": "A primary Button uses accent-background-color-default. A disabled Button uses gray-background-color-default. A destructive Button uses negative-background-color-default."
+}
+```
+
+## Attachment points
+
+**NORMATIVE:** Document blocks MAY be attached to the following entities. When `documentBlocks` is present, it **MUST** contain at least one block — an empty array **MUST** fail Layer 1 schema validation.
+
+### Tokens
+
+Add a `documentBlocks` array at the top level of a token object:
+
+```json
+{
+  "name": { "property": "background-color", "variant": "accent" },
+  "value": "#0265DC",
+  "documentBlocks": [
+    {
+      "type": "purpose",
+      "content": "Primary call-to-action background. Use for the most important interactive element in a focal area."
+    },
+    {
+      "type": "guideline",
+      "content": "Limit to one accent background per focal area to preserve hierarchy."
+    }
+  ]
+}
+```
+
+### Components
+
+Add a `documentBlocks` array at the top level of a component declaration:
+
+```json
+{
+  "name": "button",
+  "displayName": "Button",
+  "meta": { "category": "actions", "documentationUrl": "https://spectrum.adobe.com/page/button/" },
+  "documentBlocks": [
+    {
+      "type": "purpose",
+      "content": "Buttons trigger an action or event, such as submitting a form, opening a dialog, or performing a destructive operation.",
+      "agents": "Use Button when the user needs to trigger a discrete action. For navigation, use a Link instead."
+    }
+  ]
+}
+```
+
+### Anatomy parts
+
+Add a `documentBlocks` array within an anatomy part object:
+
+```json
+{
+  "name": "label",
+  "required": true,
+  "description": "Button text visible to the user.",
+  "documentBlocks": [
+    {
+      "type": "guideline",
+      "content": "Button labels should be action verbs (Save, Delete, Submit). Avoid noun-only labels like 'Confirmation'."
+    }
+  ]
+}
+```
+
+## SPEC rules
+
+| Rule ID  | Severity | Name                                 | Assert                                                                   |
+| -------- | -------- | ------------------------------------ | ------------------------------------------------------------------------ |
+| SPEC-028 | warning  | document-block-agents-equals-content | A block's `agents` field SHOULD differ from `content`                    |
+| SPEC-029 | warning  | document-block-missing-purpose       | An entity with `documentBlocks` SHOULD have at least one `purpose` block |
+
+Both rules are `warning` severity — they do not block validation.
+
+## `agents` field guidance
+
+The `agents` field exists to let documentation authors provide LLM-optimized phrasing alongside human prose. Human content may use visual formatting cues, assumed visual context, or prose conventions that agents process poorly. The `agents` field carries alternative phrasing tuned for programmatic consumption.
+
+**RECOMMENDED:** `agents` text SHOULD:
+
+* Omit references to visual appearance that agents cannot act on ("the blue button")
+* Use explicit, unambiguous phrasing ("Use Button when triggering an action, not Link")
+* Include the token or component name explicitly rather than relying on surrounding context
+* Be shorter and more directive than `content` where possible
+
+When no agent-specific rephrasing is needed, omit the `agents` field entirely. A duplicate of `content` adds size with no benefit.