DESIGN_SYSTEM.md format

renderMarkdown produces a DESIGN_SYSTEM.md file structured for both human reading and AI agent parsing. The file uses typed HTML comment markers to delimit sections so agents can locate exactly the data they need without reading the entire file.

File layout

# DESIGN_SYSTEM.md

> Generated by @lapidist/dscp v1.0.0 at 2026-01-01T00:00:00.000Z
> Kernel snapshot: `abc123`

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

<!-- dscp:tokens:spacing -->
## Tokens: spacing
...
<!-- /dscp:tokens:spacing -->

<!-- dscp:violations -->
## Known violations
...
<!-- /dscp:violations -->

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

<!-- dscp:rules -->
## Active rules
...
<!-- /dscp:rules -->

Section markers

Each section is wrapped in an opening marker <!-- dscp:<tag> --> and a closing marker <!-- /dscp:<tag> -->. The tag identifies the section type:

Tag	Content
dscp:tokens:<type>	All active tokens of the given DTIF type
dscp:violations	Known bad values and the tokens to use instead
dscp:components	Registered components with deprecation status
dscp:rules	Active (enabled) lint rules

Token section

Each token type gets its own section. Only non-deprecated tokens are listed. Sections for types with no active tokens are omitted entirely.

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

| Token | Value | Deprecated |
|-------|-------|------------|
| `#/color/brand/primary` | `#3B82F6` | No |
| `#/color/brand/secondary` | `#6366F1` | No |

<!-- /dscp:tokens:color -->

Violations section

The violations section lists raw values that must not appear in generated code. When correctToken is set, agents must use that token. When it is null, agents must avoid the raw value entirely.

<!-- dscp:violations -->
## Known violations

The following raw values have been observed in the codebase. Use the corresponding token instead.

- **DO NOT use** `color: #3B82F6` → use `#/color/brand/primary` (seen 12 times)
- **DO NOT use** `font-size: 14px` (no token found) [agent] (seen 3 times)

<!-- /dscp:violations -->

The [agent] suffix indicates the violation was introduced by an AI agent.

Components section

<!-- dscp:components -->
## Components

| Component | Package | Deprecated |
|-----------|---------|------------|
| `Button` | `@acme/ui` | No |
| `OldButton` | `@acme/ui` | Yes → `Button` |

<!-- /dscp:components -->

Rules section

Only rules with enabled: true appear in this section.

<!-- dscp:rules -->
## Active rules

| Rule | Category | Severity | Fixable |
|------|----------|----------|---------|
| `no-hardcoded-color` | tokens | error | No |
| `no-hardcoded-spacing` | tokens | warn | Yes |

<!-- /dscp:rules -->

Agent usage

Agents should read the entire DESIGN_SYSTEM.md at the start of a session and keep it in context for the duration. For targeted lookups, search for the opening marker:

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

Everything between the opening and closing marker is the data for that section.