@lapidist/dscp | Design System Context Protocol

🤖

Agent-first

DSCP documents are structured for both human reading and LLM parsing. Typed HTML comment markers let agents locate the exact section they need without reading the whole file.

🔒

Violation prevention

Surface known bad values — raw hex colours, hardcoded spacing — directly in the context window so agents avoid them before writing a single character.

🛠️

Tool-agnostic

Any tool can emit a DSCP document — dtifx, design-lint, or a bespoke script. The spec defines the envelope; the generator is a reference implementation.

📐

Versioned spec

The DSCPDocument shape is pinned to a semver spec version and validated by a JSON Schema. Consumers can detect breaking changes before parsing.

What is DSCP?

The Design System Context Protocol defines a versioned JSON envelope — DSCPDocument — that captures the constraints of a design system in a form AI coding agents can act on:

Token graph — every resolved design token, grouped by type, with values and deprecation status

Component registry — registered components, their packages, and their deprecation replacements

Deprecation ledger — a full log of deprecated pointers with optional replacement pointers

Violation patterns — known bad values observed in the codebase, with the correct token to use instead

Active rules — the lint rules currently enforced, so agents know what will be flagged

DESIGN_SYSTEM.md

The reference generator can render a DSCPDocument as a DESIGN_SYSTEM.md file at the repo root. The file is structured for both human reading and agent parsing using typed HTML comment markers:

markdown

<!-- dscp:tokens:color -->
## Tokens: color

| Token | Value | Deprecated |
|-------|-------|------------|
| `#/color/brand/primary` | `#3B82F6` | No |
<!-- /dscp:tokens:color -->

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

Agents can locate any section with a simple string search on the marker comment.

Generate a document

import { generateDocument, renderMarkdown } from '@lapidist/dscp';

const doc = generateDocument({
  tokenGraph: { tokens, byType },
  componentRegistry: { components },
  deprecationLedger: { entries },
  ruleRegistry: { rules },
  violations,
  snapshotHash: 'abc123',
});

const markdown = renderMarkdown(doc);
// Write markdown to DESIGN_SYSTEM.md

dscpDesign System Context Protocol