Making design knowledge navigable
A design system documented only in Figma, or scattered across wiki pages and Notion docs, is invisible to an AI
agent. DESIGN.md acts as the design-system knowledge entry point — it provides
context, design principles, and decision guidance, and tells an agent where to find tokens, component requirements,
architectural rules, and constraints, without duplicating any of them. One origin per decision; the map just points.
Design knowledge — foundations, components, patterns, governance
| What | File |
|---|---|
| Token usage principles, surface model, cascade architecture | src/system/design-system/foundations.md |
| Component index, ownership table, cross-cutting rules | src/system/design-system/components.md |
| Per-component design intent (CRDs) | src/system/design-system/components/*.crd.md (portfolio components — M2b/M2c in progress) |
| Versioning, contribution process, discrepancy log | src/system/design-system/governance.md |
| Composition patterns | src/system/design-system/patterns.md (stub) |
⚠️ Educational examples — not authoritative portfolio CRDs The following CRDs were created as illustrative examples for the XConf Americas 2026 talk "Your Design System Has a New User: AI." They demonstrate the CRD format using a fictional product called Acme. No Acme component exists in this portfolio's design system. Do not treat them as implemented requirements for jeensdesign.com.
Component Requirements Documents
Component documentation typically covers appearance and props. A Component Requirements Document (CRD) adds the layer that matters most for AI agents: why a component exists, when to use it versus alternatives, and which product-specific decisions apply. The document below is the Switch CRD from this repository — created for the talk using a fictional product called Acme to illustrate the format. Each selection control has its own CRD: Checkbox and Radio Group.
Best practices
Use a switch when a setting applies on change, with no confirmation step required.
Use switches for:
- Notification preferences (email, SMS, push, marketing)
- Privacy settings and data-sharing toggles
- Feature flags a user enables for their account
- Automatic updates or sync settings
- Any binary preference that takes effect on toggle
Avoid switches when:
- The setting is collected alongside others and submitted together (use a checkbox)
- The change has significant, hard-to-reverse consequences that warrant a confirmation dialog (use a button with a confirmation pattern instead)
- An explicit save or submit action follows the user's choices
Labeling: The label should describe the setting, not the toggle state. "Email notifications" is correct. "Enable email" or "On/Off" alone is not. The current state must be clear from the visual position of the thumb — not from the label alone.
Notification preferences example: A notification preferences screen that applies settings immediately — no save button — uses one switch per notification type. Each is labeled with the notification type; supporting text explains what the notification covers. This is a direct application of the guidance above.
CRD approach inspired by Cassie Groos. Example adapted for this talk.
Notification preferences: before and after
The comparison below illustrates an AI-generated notification screen (using checkboxes) alongside the design-system intended version (using switches). In the Acme product, notification settings take effect immediately — no submit button, no confirmation step. The CRD establishes that Switch is the required control for this context; Checkbox implies deferred submission that never arrives.
This is an illustrative comparison. It does not represent the output of a specific AI model or a measured experiment result.
Notification preferences
Checkboxes imply selections are applied on submission. These settings take effect immediately — there is no submit step.
Notification preferences
Switches correctly convey that these settings take effect immediately, without a submit step.