# ai.com — Quiet Sky v2.0 · engineering handover

Everything needed to put the product on the current design system. August 2026.

**Fastest way in:** open `index.html`, then launch `catalog.html`. The catalog renders every
component in both themes, with a theme toggle in the sidebar — it settles most
questions faster than reading.

> Two reference pages fetch files at runtime (the logo construction diagram, the
> icon sprite). Serve the folder rather than opening those from `file://`:
> `python3 -m http.server` then visit `localhost:8000`.

---

## What's in the box

```
design-system/
├── README.md                  ← you are here
├── index.html                 ← browsable entry point
├── tokens.css                 ← design tokens for plain-CSS repos
├── tokens.tailwind.css        ← the same values for Tailwind v4 repos — use ONE, never both
├── app-design-system.md       ← THE SPEC OF RECORD. Parts A–M. Read Part B first.
├── catalog.html               ← living reference: every component, both themes
│
├── assets/                    ← ship as-is to /public/assets. Generated — never hand-edit.
│   ├── fonts/onest/           ← the only typeface (variable woff2, SIL OFL 1.1)
│   ├── icons/                 ← 106 icons: per-file svg + sprite.svg + icons.json manifest
│   ├── logo/                  ← logotype svg masters + png exports
│   ├── favicon/               ← favicon set + site.webmanifest
│   ├── agent/                 ← agent avatar (the dot)
│   └── social/                ← OG images
│
├── reference/                 ← visual documentation (read, don't ship)
│   ├── design-system.html     ← foundations: colour, type, space, elevation, motion
│   ├── logo.html              ← logotype construction, clear space, minimum sizes, misuse
│   ├── icons.html             ← icon family: keylines, full set, colour roles, rules
│   └── chart-ramps.md         ← the validated chart ramps + how to re-check them
```

Everything in `assets/` is derived from vector masters by generators that live in
the brand workspace, not in this package. Edit requests go to design; never patch
the output files.

---

## Quick start (new surface)

**1 · Ship the tokens.** Plain-CSS app → `tokens.css`. Tailwind v4 app →
`tokens.tailwind.css` (imported in `globals.css` after the tailwind import). One or
the other, never both. Import before any component CSS, and add the theme bootstrap
from the bottom of the file to `<head>` **before first paint**, or the page flashes
the wrong theme on load.

**2 · Ship the assets.** Copy `assets/` to wherever static files are served —
`/public/assets/` in most setups. Paths inside `site.webmanifest` assume
`/assets/…`; change them there if you serve from somewhere else.

**3 · Wire the head.**

```html
<link rel="stylesheet" href="/tokens.css">
<link rel="icon" href="/assets/favicon/favicon.svg" type="image/svg+xml">
<link rel="icon" href="/assets/favicon/favicon.ico" sizes="48x48">
<link rel="apple-touch-icon" href="/assets/favicon/apple-touch-icon.png">
<link rel="mask-icon" href="/assets/logo/safari-pinned-tab.svg" color="#0E0E14">
<link rel="manifest" href="/assets/favicon/site.webmanifest">
<meta name="theme-color" content="#FBFBFD" media="(prefers-color-scheme: light)">
<meta name="theme-color" content="#0A0D12" media="(prefers-color-scheme: dark)">
<meta property="og:image" content="https://ai.com/assets/social/og-image.png">
<meta name="twitter:card" content="summary_large_image">
```

Onest is the only typeface — 400/500/600/700/800, including numbers. Nothing in
product UI is monospaced except code *content* authored by users or agents.

---

## Using the icons

One request, one cache entry:

```html
<svg width="0" height="0" style="position:absolute" aria-hidden="true"
     fill="none" stroke="currentColor" stroke-width="1.5"
     stroke-linecap="round" stroke-linejoin="round">
  <!-- inline assets/icons/sprite.svg here, or fetch it once at boot -->
</svg>

<svg class="ic ic--18" aria-hidden="true"><use href="#ic-command-center"/></svg>
```

- 106 drawings, 108 files (two aliases). Every name is in `assets/icons/icons.json`
  with its group, keyline and intent.
- Sizes **14** inline · **16** buttons and meta · **18** navigation · **20** headers.
- Icons take `currentColor`. Colour them with text tokens — `--text-3` in chrome,
  `--text-2` in content rows, `--text-1` on hover — and **accent only when the icon
  *is* the active-state signal.**
- Icon-only buttons need `aria-label` **and** a tooltip. Both, not either.

## Using the logotype

The masters are outlined vector paths, so no font has to load and nothing reflows.

- **≥ 48px** — `assets/logo/aicom-logotype-{light,dark}.svg`
- **24–48px** (nav, sidebar, chrome) — the `-ui-` cut. It's a real optical size, not
  the same file scaled: heavier particle, tighter clearance, looser tracking.
- **Unknown surface** — `aicom-logotype-adaptive.svg`; letters take `currentColor`,
  the particle stays cyan.
- **< 24px** — the particle alone.
- Keep one x-height of clear space on all four sides.

**Never re-set the wordmark in live type.** Typing `ai.com` in Onest gives you a
period that is the wrong size and sits on the baseline. The dot in the logotype is
the same circle as the tittle on the `i` — that rhyme is the whole mark, and typing
it destroys it.

---

## The things that are easy to get wrong

- **No gradients. Anywhere.** Not on the logotype, not on a chart, not on a
  thumbnail. One colour carries the brand.
- **No second hue.** Mint and danger are *state*, never "series 2", and always ship
  with an icon and a word beside them.
- **There is no amber.** Orange was deleted, so "warning" is copy and placement, not
  paint.
- **The accent means something.** Cyan appears on live dots, agent presence, active
  states, checkpoints and links — never as decoration, never in body text, never as
  a button fill.
- **Product dark mode is flat.** No aurora, no horizon glow, no grain — those are
  marketing surfaces only.
- **Approvals, denials and Stop are never optimistic.** A checkpoint that looks
  approved before the server agrees is a trust failure.
- **`--chart-5` is always "most"** and always the highest-contrast step: darkest on
  canvas, brightest on night. The anchor flips with the theme.

The binding rules live in `app-design-system.md`.