# Agentic Design System by Madhav Nair: instructions for AI agents
> A small, headless design system (CSS variables + W3C design tokens + semantic HTML recipes). Free to use. No framework, no build step.

## Files (load the CSS in this order)
1. https://madhavnair.in/css/base.css: base colour, type, shadow and motion tokens per mode (+ Inter @font-face)
2. https://madhavnair.in/css/tokens.css: spacing, radii, type scale and semantic tokens
3. https://madhavnair.in/css/themes.css: themes as token overrides (html[data-theme], html[data-mode])
4. https://madhavnair.in/css/components.css: component recipes (prefix c-)
- https://madhavnair.in/design/tokens.json: the same tokens in W3C Design Tokens (DTCG) format
- https://madhavnair.in/design/components.json: component specs: anatomy, variants, tokens used, accessibility rules, exact HTML
- https://madhavnair.in/DESIGN.md: the design language for humans
- https://madhavnair.in/design/madhav-design-system.zip: all of the above, plus Inter, licences and a sample index.html that works offline

## Rules (must)
1. Use tokens only. No raw hex/rgb colours or radii in component CSS. Radii: --r-sm, --r, --r-lg, --r-pill.
2. Set html[data-mode="light"|"dark"] before first paint; themes change tokens, never components.
3. One accent (--accent). Use it for the current item, the primary chip and small tags. Never for body text or large fills.
4. Dark mode primary button = dark pill (--pill) + accent chip (c-btn + c-btn__chip).
5. Sticky bars are solid (--chrome) and sit at top: var(--hh). Never translucent.
6. Media sits in c-plate or c-card--media and is clipped. Real images with width, height and alt.
7. No fixed min-heights on stacked cards. Spacing from the --s-1…--s-9 scale.
8. Geist Pixel (--pixel) for tiny labels only.
9. Copy: candid, specific, British English. No invented metrics, quotes or claims.

## Don't
Glow, gradient text, HUD looks, heavy gradients, neon overload, nested double frames, hover-only content, autoplaying motion.

## Test checklist (must pass before shipping)
- No horizontal scroll at 320, 360, 390, 412, 768, 1024, 1280, 1440, 1920px.
- Text ≥ 4.5:1, text on accent ≥ 4.5:1, focus ring ≥ 3:1, in light and dark.
- Tap targets ≥ 44px on touch; everything reachable by keyboard with visible focus.
- prefers-reduced-motion: no running animations. 200% zoom: reflows.
- One h1, title, description, canonical, OG image, alt text on every image.
- Sticky elements don't overlap each other or hide content.

## Components
### card (.c-card)
Anatomy: c-pill (optional), heading, body, c-card__foot (optional, pinned to bottom)
Variants: c-card--lead: the one current thing; 3px accent edge, c-card--media: no padding, media clipped, body in c-card__body, c-card--quiet: sunken, no shadow
Tokens: --bg-raised, --bg-sunken, --r-lg, --s-5, --shadow-1, --border, --accent
A11y: One heading per card. If the whole card is a link, use only one <a>. No fixed min-height.
HTML: <article class="c-card"><span class="c-pill"><span class="c-pill__dot"></span>Now</span><h3>Card title</h3><p>Short supporting text.</p><a class="c-card__foot" href="#">Read more</a></article>

### button (.c-btn)
Anatomy: c-btn__chip (icon on accent), label
Variants: (base): ink pill (light), dark pill (dark) with accent chip, c-btn--accent: accent fill, c-btn--ghost: outline only
Tokens: --fg, --bg-page, --pill, --accent, --on-accent, --r, --r-sm
A11y: At least 44×44px. Visible :focus-visible ring ≥3:1. Text on accent ≥4.5:1.
HTML: <a class="c-btn" href="#"><span class="c-btn__chip" aria-hidden="true">→</span>Primary</a>

### pill (.c-pill)
Anatomy: c-pill__dot (optional), text
Variants: none
Tokens: --bg-sunken, --fg-2, --accent, --r-sm, --t-xs
A11y: Not interactive. The dot is decorative.
HTML: <span class="c-pill"><span class="c-pill__dot"></span>Label</span>

### chip (.c-chip)
Anatomy: text
Variants: [aria-pressed=true]: selected
Tokens: --fg, --bg-page, --fg-2, --r-pill, --border-strong
A11y: State via aria-pressed. 44px tap height on touch.
HTML: <button class="c-chip" aria-pressed="true">Selected</button> <button class="c-chip" aria-pressed="false">Filter</button>

### tag (.c-tag)
Anatomy: text
Variants: c-tag--pixel: Geist Pixel label; sparingly
Tokens: --accent, --on-accent, --r-sm, --t-xs, --pixel
A11y: Text on accent ≥4.5:1. Never the only signal of state.
HTML: <span class="c-tag">New</span> <span class="c-tag c-tag--pixel">BETA</span>

### section (.c-section)
Anatomy: c-section__head, content
Variants: c-section--tight: smaller block padding
Tokens: --s-8, --s-6, --s-5
A11y: Has a heading or aria-label.
HTML: <section class="c-section c-section--tight"><div class="c-section__head"><h2>Section title</h2></div><p>Section content.</p></section>

### sticky-bar (.c-sticky)
Anatomy: controls
Variants: none
Tokens: --chrome, --line, --hh, --s-2
A11y: Solid, never translucent. top = header height (--hh). Anchors need scroll-margin-top.
HTML: <div class="c-sticky" style="position:static"><div style="display:flex;gap:8px;padding-inline:12px"><button class="c-chip" aria-pressed="true">All</button><button class="c-chip" aria-pressed="false">Notes</button></div></div>

### plate (.c-plate)
Anatomy: img with width/height + alt, figcaption (optional)
Variants: none
Tokens: --bg-raised, --r-lg, --shadow-1, --border
A11y: Meaningful alt. Lazy-load below the fold.
HTML: <figure class="c-plate"><div class="ds-ph" role="img" aria-label="Placeholder image">16:9 image</div><figcaption>Caption</figcaption></figure>