# AGENTS.md: how an AI makes allGaia designs

You are rendering an allGaia / EVENRA design (a social post, a banner, a page section) as
HTML + CSS. Read this whole file first. It is short on purpose. The visual reference is
`index.html`; the values are in `css/allgaia-tokens.css` (and its mirror, `tokens/allgaia.tokens.json`).

**On the web:** this file is at **https://design.allgaia.team/AGENTS.md**, and the visual guide is at
https://design.allgaia.team/. If you can't read this repo's files, use the web:
- Index of everything: https://design.allgaia.team/llms.txt
- Tokens (JSON): https://design.allgaia.team/tokens/allgaia.tokens.json
- Whole kit (CSS, fonts, logos, photos, templates, renderer): https://design.allgaia.team/allgaia-design-kit.zip
  Unzip it and follow §1 below; every path in this file is relative to the kit root.
- Or link the CSS directly from your own HTML (CORS is open, so the fonts load too):
  ```html
  <link rel="stylesheet" href="https://design.allgaia.team/css/allgaia-tokens.css">
  <link rel="stylesheet" href="https://design.allgaia.team/css/allgaia-components.css">
  <link rel="stylesheet" href="https://design.allgaia.team/css/allgaia-social.css">
  ```
  Images and logos: `https://design.allgaia.team/assets/...`, templates to copy: `https://design.allgaia.team/social/templates/<name>.html`.

**Source of truth:** the live site **allgaia.com** (repo `evenra-theme`). The old CVI 2.0
(Open Sauce One / Aileron, Deep Tide `#357575` buttons, Charcoal text) is **retired** for new work.
`index.html` has a mapping table from CVI 2.0.

---

## 1. Fast path: make a social post

1. Copy the closest file in `social/templates/` (each one says its slots and limits in its header comment).
2. Change only the copy, the photo, and (rarely) a `margin-top`. Keep the classes.
3. Render: `render/render.sh social/templates/<file>.html` writes `out/<file>.png` at exact size.
   Add `SCALE=2` for a 2× export.
4. Look at the PNG and run the checklist in §8 before you hand it over.

| Template | Format | Surface | Use for |
|---|---|---|---|
| `dark-01-cover-photo` | 1080×1350 | photo | Carousel cover: badge, headline, sub-lines |
| `dark-02-product` | 1080×1350 | night | Product + how to use + two facts |
| `dark-03-rows` | 1080×1350 | night | Label/value table (ingredients, specs) |
| `dark-04-checklist` | 1080×1350 | night | 3–5 big rows (tests, promises) |
| `dark-05-big-number` | 1080×1350 | night | One big number (30 days, 20 ingredients) |
| `dark-06-cta` | 1080×1350 | photo | Last slide: headline, 3 lines, URL, no arrow |
| `light-01-statement` | 1080×1350 | light | A plain statement with chips and product |
| `light-02-steps` | 1080×1350 | light + paper cards | 3 steps / 3 points |
| `light-03-split-photo` | 1080×1080 | light | Photo + quote (founder, review) |
| `story-01-cover` | 1080×1920 | photo | Story / Reel cover |

New layout? Start from the skeleton in §7 and reuse the classes. Don't invent new colours or sizes.

## 2. The surface rule (this is how readability works)

Every design sits on **one surface class**. The class sets the semantic colour tokens, and
every component reads only those tokens. So the same markup reads correctly on light and dark.

| Class | Ground | Headline | Body | Accent (labels, arrow, URL) | Sub-line (light teal) | Lines |
|---|---|---|---|---|---|---|
| `ag-light` | cream `#FBF8F2` | slate `#4E6466` | ink `#1D4249` | tide `#1F5962` | ink | linen `#E3DDD3` |
| `ag-paper` | paper `#F3F3EB` | slate | ink | tide | ink | linen |
| `ag-white` | white | slate | ink | tide | ink | linen |
| `ag-dark` | ink `#1D4249` | white | white | signal `#51D1EC` | ice `#CEFFFF` | cream 16% |
| `ag-deep` | deep `#13434F` | white | white | signal | ice | cream 16% |
| `ag-night ag-grad` | abyss `#042832` + teal glow | white | white | signal | ice | rule `#467884` |
| `ag-photo` | photo + shade | white | white | signal | ice | cream 16% |
| `ag-sachet` | sachet `#2DB8CE` | abyss `#042832` | abyss | abyss | abyss | abyss 22% |

Use the tokens, never hex: `var(--ag-heading)`, `--ag-text`, `--ag-text-2`, `--ag-muted`,
`--ag-accent`, `--ag-highlight`, `--ag-line`, `--ag-line-strong`, `--ag-bg`, `--ag-card`.

**Hard rules**
- Bright teals (`sachet #2DB8CE`, `signal #51D1EC`, `ice #CEFFFF`, `aqua #A9E2E0`, `mist #78C8D2`)
  are **for dark surfaces only**. On cream they fail contrast (2.2–1.3:1). On light, use tide `#1F5962`.
- Text over a photo always has a shade under it (`.p-shade` in posts, `.ag-card--photo` on the web).
  If a bright part of the photo sits behind text, add a side gradient and, if needed, a soft local
  `.scrim` behind just that text block (see `dark-01`: the moon behind the sub-line). Check the rendered PNG:
  the ground right behind body text must still give 4.5:1.
- `--ag-muted` on light is 4.2:1, so use it for text 18px and up only (web) or 28px and up (post canvas).
  Smaller secondary text uses `--ag-text-2`.
- One warm accent (`sun #C8642F`, `clay`, `berry`) per design at most, as a marker or fill, never body text.
- Decorative lines on dark use `#467884` (`--ag-line-strong`). They are not text.

## 3. Light cards and dark cards

A card is a surface: `class="ag-card ag-paper"` (light) or `class="ag-card ag-dark"` (dark).
- **Cream page → light card `ag-paper`, or dark card `ag-dark`** (the site's lab-results card).
- **Dark page/post → dark card `ag-dark` on `ag-night`**, or a light card `ag-paper` for strong contrast.
- **Photo card:** `ag-card ag-card--photo ag-photo` with an `<img>` as the first child. Add `ag-grain` for film grain.
- Never put a light card on a light card of the same colour; step cream → paper → white.

## 4. Typography

- **One typeface: Public Sans** (`--ag-font`), weights **400** and **600** only. No other fonts.
- **Headlines are 400 (regular)**, tight tracking `-0.02em` to `-0.03em`, line-height 1.02–1.08.
  This is the site's look. Don't make headlines bold.
- 600 is for emphasis: row labels, badges, prices, short `<strong>` words.
- UPPERCASE is only for eyebrows/labels (`.p-label`, tracking 0.14em) and buttons/tags (0.06em). Never for headlines or body.
- Post scale (1080 canvas): h1 92, h2 72, h3 52, lead 44, body 36, small 28, label 24.
  **Body never goes below 28px on a 1080 canvas.** Line-height for body is 1.42.
- Write numbers with a space before the unit: `18 g`, `750 mg`, `5 g`, `30 days`, `€84` (EN) / `84 €` (DE).
- Product name: **EVENRA** in capitals. Company: **allGaia** (wordmark) / AllGaia in running text.
- Don't use the ® mark (paused until the EVENRA trademark is granted).
- The font subset lacks `→ ✓` and some latin-ext letters (š ž). Use the inline SVG arrow and tick from the templates;
  latin-ext falls back to jsDelivr automatically, so renders need network on first load.

## 5. Social layout rules

- Default format **1080×1350 portrait**. Margins: 104px left/right, 120px top, 96px bottom.
- Keep the headline and the key line in the **centre 1080×1080** too: the profile grid crops 4:5 to a square-ish preview.
- **Carousel arrow:** thin arrow, bottom-right (`.p-arrow`), signal `#51D1EC` on dark, on **every slide except the last**.
  A foot line (terms, URL) sits on the arrow's baseline (`.p-foot`).
- **Badge** (`.ag-badge`) above the cover headline: sachet fill `#2DB8CE`, abyss text `#042832`, sentence case.
- Light-teal sub-lines (`.p-lead`, ice `#CEFFFF`) go under the headline and as a closing thought.
- Big decorative numbers: `.p-num-bg`, mist `#78C8D2` at 25% opacity, in the lower half.
- One idea per slide. 3–6 rows maximum in a table. Headline ≤ 4 lines, body ≤ 4 lines.
- Logo on the last slide or bottom-left on light single posts. Never bottom-left on profile **banners** (the avatar covers it).
- Stories: nothing important in the top 250px or bottom 300px (`data-format="story"` handles the margins).

## 6. Imagery

- Use photos from `assets/img/` (copied from the site) or new ones the business provides. No stock people.
  Stock photos are allowed only for plants. Raw-material photos come from the factory.
- Photo treatment: `saturate(.75–.8)`, an optional film grain (`.p-grain` / `.ag-grain`), and a night or teal shade for text.
- Product cut-out: `assets/img/evenra-sachet-reveal-800.webp` (transparent). Rotate it, but don't recolour, stretch or crop the logo off.
- Logo: `assets/logo/allgaia-wordmark-{white|ink|slate|cream|graphite}.svg`, or the inline `currentColor` SVG
  (`allgaia-wordmark.svg`). Minimum 50px wide on the web, 36px high on posts. No effects, no outline, no recolouring off-palette.

## 7. Skeleton for a new post

```html
<!doctype html><html lang="en"><head><meta charset="utf-8">
<link rel="stylesheet" href="../../css/allgaia-tokens.css">
<link rel="stylesheet" href="../../css/allgaia-components.css">
<link rel="stylesheet" href="../../css/allgaia-social.css">
</head><body>
<main class="ag-post ag-night ag-grad" data-format="portrait">   <!-- surface + format -->
  <p class="p-label">Eyebrow</p>
  <h2 class="p-h2" style="margin-top:22px">Headline in sentence case.</h2>
  <p class="p-body" style="margin-top:30px">Body copy, 36px, white on dark.</p>
  <p class="p-lead" style="margin-top:32px">A light-teal line.</p>
  <div class="p-spacer"></div>                                   <!-- pushes the rest to the bottom -->
  <p class="p-foot p-small">Full terms at <span class="p-url">allgaia.com</span>.</p>
  <span class="p-arrow" aria-hidden="true"><svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.1" stroke-linecap="round" stroke-linejoin="round"><path d="M2 12h20M15 5l7 7-7 7"/></svg></span>
</main></body></html>
```
Formats: `portrait` 1080×1350 · `square` 1080×1080 · `story` 1080×1920 · `landscape` 1200×628 · `linkedin-banner` 1584×396.
Add `show-safe` to `<main>` while designing to see the safe area, and remove it before export.

## 8. Checklist before you hand over a PNG

- [ ] Exactly one surface class on `<main>`; no hex colours in the markup.
- [ ] Bright teals only on dark; text on photos has a shade; nothing under 4.5:1 for body text.
- [ ] Public Sans only; headlines at 400; no ALL-CAPS headlines; body ≥ 28px on a 1080 canvas.
- [ ] Nothing touches the margins; nothing hides under the arrow; story safe zones respected.
- [ ] Arrow on every carousel slide but the last; badge in sachet/abyss.
- [ ] Units with a space (`18 g`); EVENRA in capitals; no ®.
- [ ] Copy is the approved copy. Agents do not write claims (see §9).

## 9. Copy you must not change or invent

- **EU health claims** must be the exact EU Register wording that is already on allgaia.com. Don't paraphrase or add one.
  Creatine gets no claim line.
- **Ingredient amounts and NRV %** are label facts: copy them exactly from the box or the site.
- **Reviews** are verbatim Judge.me reviews only. Never write or edit one. Never invent a quote.
- **Prices and guarantees** follow the live site. Current site: 30-day returns for *unopened* boxes; skip or cancel
  auto-reorder any time. (The 2026-11-09 carousel draft said "even from an opened box". That is outdated, so check before posting.)
- The business gives the final yes on all texts before posting.

## 10. Changing the system

If a design needs a new colour, size or rule: add it to `css/allgaia-tokens.css` **and**
`tokens/allgaia.tokens.json` **and** the right section of `index.html`, then add a line to the change log in `README.md`.
A value that lives only in one post does not exist.