# CNO developer system: instructions for AI agents

Applies to any UI that should look like Canada's National Observer tools and pages: static prototypes, admin screens and mock-ups.

Read these in order:

1. `design-tokens.md`: every colour, type, radius and shadow value, and the CSS custom properties
2. `components.md`: specs and starter CSS for each component

## Always

- **Use the tokens** (`var(--color-*)`, `--font-size-*`, `--radius-*`, `--shadow-*`) instead of hard-coded values.
- **Fonts:** `ProximaNova` for UI (link `fonts.css`; each weight has its own file), `Noto Serif` only for article body text. Set `-webkit-font-smoothing: antialiased` on body.
- **Colour is meaning:** black frames (sidebar, header), white carries content, Subscribe orange `var(--color-accent)` is the single call to action, light blue `var(--color-link)` is for links (dark blue `var(--color-primary)` on hover and in admin tables).
- **Buttons are pills:** `--radius-btn-sm|md|lg`, bold 16 to 18px text, 150ms colour fade.
- **Headings are extra bold (800)** with a 1px `var(--color-border)` rule under section headers.
- **Almost no shadows.** Separate with hairlines; elevation is only for menus and dialogs.
- **Use made-up data** in prototypes. Never put real reader or donor data in a repo or public page.

## Never

- Invent new colours, radii or font sizes. Pick the nearest token.
- Use orange for decoration or more than one call to action per view.
- Use the serif for UI controls.

## Quick reference

| Need | Use |
| --- | --- |
| Body text | `var(--color-text)` on `var(--color-surface)` |
| Muted label | `var(--color-text-muted)` |
| Link | `var(--color-link)`, hover `var(--color-primary)` |
| Call to action | `var(--color-accent)` pill button, hover `var(--color-ink)` |
| Sidebar / header | `var(--color-ink)` with `var(--color-text-on-dark)` |
| Hairline | `1px solid var(--color-border)` (rows: `--color-border-light`) |
| Footer | `var(--color-surface-alt)` |
| Success / error / warning | `--color-success*`, `--color-danger*`, `--color-warning*` |

## When unsure

Do not guess. Flag the question and take the safest option. Tokens tagged **Ours** in `tokens.css` are admin-tool choices, not site values.

Source of truth: the Developer System at `/admin/system/`.