---
name: CDS AI Surface Kit
description: Design and build AI features with the 22-entry AI & Agents domain — gates that sign exact payloads, traces that record blocks, streaming that stays accessible, honest capability disclosure.
audience: designer · developer
---

# CDS AI Surface Kit

## What this is

The applied method for the system's most contract-dense domain. Every AI surface decision — composer, streaming, citations, confidence, gates, traces, memory, handoff — already has an entry; this skill sequences them into a coherent feature.

## What this is NOT

Not model work. It governs the surface between a model and a person; model quality, safety tuning, and evals are separate disciplines this skill assumes exist.

## When to use

Adding an assistant, agent, or generative feature to a consumer product; auditing an existing AI surface; briefing an agent that is, itself, building AI UI.

## Method

1. **Start with capability disclosure** (the anti-magic card): three can, three can't, one data line linking to grants. Underclaim.
2. **Scope what it sees** — context as removable chips, tool & data grants one per capability, payments never bundled.
3. **Stream correctly**: `aria-live="off"` during, announce once on completion; Stop keeps partials.
4. **Ground or label**: citations attach to claims actually retrieved; ungrounded sentences labelled, never color-only; no raw-probability confidence badges.
5. **Gate the irreversible**: exact payload, editable at the gate, never batched — and every gate decision lands in the activity trace, blocks included (an approval without an audit trail is theatre).
6. **Give refusals a door**: abstention routes to a human with a stated response time.
7. **Memory honestly**: readable rows, real delete, inferred says inferred; training and personalisation are two switches, training off by default.

## Quality bar

Every surface maps to an ai-domain entry id · gates verified against the exact-payload rule · trace records at least one deliberately-blocked test action · EU AI Act Art 50/14/12 anchors satisfied by design.

## Guardrails & escalation

Money, health, legal, and child-facing AI surfaces escalate to counsel review before launch. The hard rule `human-signs` is not waivable by product priority.

## References

- Catalogue: https://edwson.com/consumer-design-system.html
- Machine contracts: https://edwson.com/cds/components.json (142 entries, agentProtocol, bundles, hardRules) · https://edwson.com/cds/tokens.json (both themes)
- Agent brief: https://edwson.com/cds/AGENTS.md · MCP precedent: https://github.com/Edwson/eds-mcp