# Design System Context Protocol — Specification v1.0.0

**Status:** Stable  
**Authors:** Lapidist contributors  
**Canonical schema URI:** `https://raw.githubusercontent.com/bylapidist/dscp/main/schema/v1.json`  
**Current schema URI:** `https://raw.githubusercontent.com/bylapidist/dscp/main/schema/v1.json`

---

## 1. Introduction

The Design System Context Protocol (DSCP) is a versioned, tool-agnostic specification
for communicating design system constraints to generative AI models before code
generation begins. A DSCP document encodes the complete set of information an AI agent
needs to generate code that conforms to the design system without introducing
hard-coded values or deprecated patterns.

DSCP is produced by the Design System Runtime (DSR) or any compatible toolchain and
consumed by:

- AI coding assistants (via MCP servers)
- Code generation pipelines
- Design system linting tools
- CI validation hooks

## 2. Goals

1. **Correctness** — prevent AI agents from introducing raw values where design tokens
   exist.
2. **Discoverability** — give agents a structured, queryable view of all available
   tokens, components, and rules.
3. **Interoperability** — any tool that can produce a valid DSCPDocument can participate
   in the protocol.
4. **Human readability** — the DESIGN_SYSTEM.md rendering is navigable without tooling.

## 3. Definitions

| Term | Definition |
|------|------------|
| **DSCPDocument** | A JSON document conforming to this specification and `schema/v1.json`. |
| **token** | A named, typed design value defined in a DTIF document. |
| **violation pattern** | An observed instance of a raw value being used where a token should have been used. |
| **agent attribution** | A flag indicating whether a violation was introduced by an AI agent. |
| **snapshot hash** | The SHA-256 hash of the DSR kernel snapshot used to generate this document. |

## 4. Document structure

A DSCPDocument MUST contain all of the following top-level fields:

| Field | Type | Description |
|-------|------|-------------|
| `$schema` | `string` (URI) | MUST be `https://raw.githubusercontent.com/bylapidist/dscp/main/schema/v1.json` |
| `specVersion` | `string` (semver) | MUST be `1.0.0` for documents conforming to this revision |
| `generatedAt` | `string` (ISO 8601) | Timestamp of document generation |
| `kernelSnapshotHash` | `string` | SHA-256 of the source snapshot; empty string if derived from live state |
| `tokenGraph` | `DSCPTokenGraph` | See §5 |
| `componentRegistry` | `DSCPComponentSummary` | See §6 |
| `deprecationLedger` | `DSCPDeprecationEntry[]` | See §7 |
| `violations` | `DSCPViolationPattern[]` | See §8 |
| `rules` | `DSCPRuleSummary[]` | See §9 |

## 5. Token graph (`DSCPTokenGraph`)

The token graph summarises the complete set of design tokens grouped by DTIF type.

### 5.1 DSCPTokenGraph

| Field | Type | Description |
|-------|------|-------------|
| `totalCount` | `integer ≥ 0` | Total number of tokens across all types |
| `byType` | `object` | Map of DTIF token type → `DSCPTokenEntry[]` |

### 5.2 DSCPTokenEntry

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `pointer` | `string` | Yes | JSON pointer to the token in the DTIF document |
| `name` | `string` | Yes | Human-readable dot-notation name |
| `type` | `string` | Yes | DTIF token type (e.g. `color`, `fontSizes`) |
| `value` | `string` | Yes | Serialised value; complex objects are JSON-encoded |
| `deprecated` | `boolean` | Yes | Whether this token is deprecated |
| `replacement` | `string` | No | Pointer to the replacement token if deprecated |

## 6. Component registry (`DSCPComponentSummary`)

| Field | Type | Description |
|-------|------|-------------|
| `totalCount` | `integer ≥ 0` | Total number of registered components |
| `components` | `DSCPComponentEntry[]` | All registered components |

### 6.1 DSCPComponentEntry

| Field | Type | Required |
|-------|------|----------|
| `name` | `string` | Yes |
| `package` | `string` | Yes |
| `version` | `string` | No |
| `deprecated` | `boolean` | Yes |
| `replacedBy` | `string` | No |

## 7. Deprecation ledger (`DSCPDeprecationEntry[]`)

Each entry describes a deprecated token pointer and its optional replacement.

| Field | Type | Required |
|-------|------|----------|
| `pointer` | `string` | Yes |
| `replacement` | `string` | No |
| `since` | `string` | No |
| `reason` | `string` | No |

## 8. Violation patterns (`DSCPViolationPattern[]`)

Violation patterns encode observed misuse of raw values to help agents avoid repeating
known mistakes.

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `property` | `string` | Yes | CSS property where the violation occurs |
| `rawValue` | `string` | Yes | The raw value that was used |
| `frequency` | `integer ≥ 1` | Yes | How many times this pattern has been observed |
| `correctToken` | `string \| null` | Yes | Pointer to the correct token, or null if unknown |
| `agentAttributed` | `boolean` | Yes | Whether the violation was introduced by an AI agent |

## 9. Rule summaries (`DSCPRuleSummary[]`)

Rule summaries communicate the active lint configuration so agents know what will be
flagged in CI.

| Field | Type | Required |
|-------|------|----------|
| `id` | `string` | Yes |
| `category` | `string` | Yes |
| `description` | `string` | Yes |
| `enabled` | `boolean` | Yes |
| `severity` | `"error" \| "warn" \| "off"` | Yes |
| `fixable` | `boolean` | Yes |

## 10. DESIGN_SYSTEM.md format

The `renderMarkdown()` function generates a `DESIGN_SYSTEM.md` file structured for both
human reading and machine parsing. Sections are delimited by HTML comment markers:

```html
<!-- dscp:tokens:color -->
| Token | Value | Deprecated |
...
<!-- /dscp:tokens:color -->

<!-- dscp:violations -->
- DO NOT use `color: #3B82F6` → use `#/color/brand/primary` (seen 14 times)
<!-- /dscp:violations -->

<!-- dscp:components -->
...
<!-- /dscp:components -->

<!-- dscp:rules -->
...
<!-- /dscp:rules -->
```

Parsers MUST treat content between matching open/close markers as the authoritative
data for that section. Content outside markers is for human readers only.

## 11. Versioning

DSCP documents are versioned via the `specVersion` field. This spec defines `1.0.0`.
Future revisions MUST increment the version according to Semantic Versioning:

- **Patch** — clarifications with no schema change
- **Minor** — new optional fields added to the JSON Schema
- **Major** — breaking changes to required fields or semantics

## 12. Conformance

A document is considered conforming to DSCP v1 if and only if:

1. It validates against `schema/v1.json`
2. `specVersion` equals `"1.0.0"`
3. `$schema` equals `"https://raw.githubusercontent.com/bylapidist/dscp/main/schema/v1.json"`