# Lucian Labs — Brand Kit for Agents

You are building a UI. Do not invent a visual language. Pick one of the looks
below, load its spec and its stylesheet, and derive everything else from
the rules in that spec.

Base URL: `https://lucianlabs.ca/branding/`

| File | What it is |
| --- | --- |
| `AGENT.md` | this file — read first |
| `brands.json` | all four looks as machine-readable tokens |
| `console.md` / `console.css` | Look A — dark instrument panel |
| `house-pour.md` / `house-pour.css` | Look B — warm printed paper |
| `punch-clock.md` / `punch-clock.css` | Look C — LED readout |
| `field-notes.md` / `field-notes.css` | Look D — long-form reading |
| `theme-engine.md` | System A — how to define a re-skinnable look |
| `skin-swap.md` | System B — how a brand changes on screen |

The four **looks** are finished identities: pick one and build in it. The two
**systems** are machinery you reach for when the brief needs it — a
user-themeable app (theme engine) or a live switch between two identities
(skin swap). A system is not a substitute for picking a look.

---

## Step 1 — pick a look

**Console** — anything that reads as an instrument: audio tools, dashboards,
dev tools, monitors, editors, anything with live state or numbers that move.
Dark, hairline-ruled, sharp-cornered, pixel-display headings. Shipped in
WaveLoop / Choppa.

**House Pour** — anything that reads as hospitality or print: events, menus,
kiosks, checkout, invitations, anything a guest touches once. Ivory paper,
serif display, champagne gold. Shipped in DrinkTix.

**Punch Clock** — single-purpose apps with one live headline figure and an
on/off state: timers, trackers, counters, meters, money clocks. Dark, chunky
2px borders, giant LED numerals, green/red stoplight. Shipped in Time Warrior.

**Field Notes** — anything that reads as long-form prose: blogs, essays,
writeups, build logs told as narrative, documentation that argues rather than
lists. Plum-black paper, serif body at 18px/1.8, amber headings, lavender in
the margins. Shipped in the Lucian Labs blog.

Decide in this order:

1. Is it prose someone reads start to finish? → **Field Notes**.
2. Is it guest-facing and touched once? → **House Pour**.
3. Can you name the single number the user opened the app to see? → **Punch
   Clock**.
4. Otherwise → **Console**.

Console and Punch Clock are both dark and both set numerals in Micro 5, so read
the comparison table in `punch-clock.md` before choosing between them. The short
version: you *operate* something in Console, you *watch a number* in Punch Clock.

If none fits, pick the closest mood and say in your response which you picked
and why. Never blend two looks — a page is entirely one or entirely another.

## Step 2 — load, don't reimplement

Link the stylesheet. It carries the tokens, the base components, and the three
faces as self-hosted `@font-face` rules — no Google Fonts link needed.

```html
<link rel="stylesheet" href="https://lucianlabs.ca/branding/console.css" />
```

Or vendor it into the project (`styles/console.css`) if the app must work
offline — in that case also copy the fonts and rewrite the four absolute
`@font-face` URLs, which point at `ds.lucianlabs.ca`. Do not retype the token
values from memory — copy them.

**`console.css` is GENERATED.** Its single source is `waveloop/ds/` — tokens in
`ds/src/tokens.css`, components in `ds/src/console.components.css` — and it is
emitted by `node ds/build.mjs --sync-site`. Edit those, never the built file,
or the next build silently reverts you. The same token file also emits
`waveloop.css`, which is why Console and the WaveLoop device face cannot drift
apart.

Then read the look's `.md` for the rules the CSS cannot express: type roles,
accent budget, spacing rhythm, copy voice, and the gap-filling procedure.

## Step 3 — delete the defaults

These are the tells that make generated UI look generated. None of them are
allowed in either look. Grep your own output for them before you ship.

**Type**
- `Inter`, `Poppins`, `Nunito`, `Montserrat`, or a bare `system-ui` stack used
  as the *brand* face. Each look names its own display face — use it.
- `ui-monospace` / `SFMono-Regular` / `Menlo` stacks as the *declared* face.
  House monospace is **Inconsolata** — with one named exception: Field Notes
  sets **Fira Code**, inherited from the blog it was extracted from. Swap the
  banned stacks on sight. (They are fine as the trailing fallback after the
  look's declared mono.)
- `system-ui` as the body face. House body is **Finlandica** — except in
  Field Notes, whose body is **Source Serif 4** by design.
- Emoji in headings, buttons, labels, or section markers. Zero. Not one.

**Color**
- Indigo/violet (`#6366f1`, `#8b5cf6`, `#a855f7`) and the purple→pink CTA
  gradient. Neither look owns purple as a primary.
- Multi-stop gradients on text, buttons, or headings. Both looks use flat fills
  or a single low-contrast directional wash, nothing else.
- More than one accent hue in a single view. See "accent budget" in the spec.

**Form**
- The `rounded-2xl` + `shadow-lg` + `p-6` card stack. Console and Punch Clock
  use **square corners, no shadow**. House Pour uses **one radius and a long
  soft shadow**. All three are specified — use the specified value, not the
  framework default.
- Glassmorphism applied because it looks nice. Console blurs panels that float
  over content; Punch Clock is flat and opaque throughout; nothing else blurs.
- Centered hero → three equal feature cards → CTA band. This layout is the
  single loudest tell. Both looks lead with a dense header and asymmetric
  content.

**Copy**
- "Seamlessly", "effortlessly", "powerful", "beautiful", "Get Started ✨",
  "Welcome back!", "Oops! Something went wrong."
- Exclamation marks. Sentence-case marketing enthusiasm.
- Each look has a voice section. Follow it.

## Step 4 — fill gaps from primitives

The specs do not enumerate every component. When you need one that isn't
listed, derive it in this order rather than reaching for a framework default:

1. **Surface** — which of the look's two or three surface tokens does this sit
   on? That fixes background and border colour.
2. **Boundary** — every edge is the look's `--line` at the look's border width:
   1px in Console and House Pour, 2px everywhere in Punch Clock. One width per
   look, no exceptions. No double borders, no drop shadows used as separators.
3. **Radius** — one value per look, applied to everything or to nothing. Do not
   introduce a second radius for a "special" element.
4. **Type role** — map the text to an existing role (display / body / label /
   numeric). Do not add a font size outside the ramp; pick the nearest step.
5. **Accent** — does this element carry the accent, or is it neutral? Default
   to neutral. In Console and House Pour the accent is a budget, not a
   decoration. Punch Clock trades that budget for a stricter rule: a colour must
   correspond to a state the user can name.
6. **Motion** — 150ms ease on colour and border. Nothing animates on page load.
   Beyond that, follow the look's own motion section rather than assuming:
   Console and House Pour have no transforms (House Pour's 1px `:active` press
   is the lone exception), while Punch Clock deliberately springs on press and
   runs a breathing live-pixel and a ping. Do not port one look's motion into
   another.

If after all six the component still has no obvious form, copy the structure of
the closest component that *is* specified and change only its content.

## Step 5 — self-check

Before reporting the work done, verify:

- [ ] No banned font, colour, or copy pattern from Step 3 survives in the diff.
- [ ] Every colour in the file is a `var(--token)` from the look's stylesheet.
      Zero raw hex outside the token block.
- [ ] Exactly one radius value and one border width, matching the look.
- [ ] Colour use satisfies the look's accent budget (or, in Punch Clock, every
      coloured element maps to a nameable state).
- [ ] A screenshot of the result is recognisably the *same product family* as
      the look's reference page (`console.html` / `house-pour.html` /
      `punch-clock.html`).

## Notes

- All four looks are token-compatible in *shape*: same variable names
  (`--bg`, `--panel`, `--ink`, `--line`, `--accent`, `--radius`,
  `--font-display`, `--font-body`, `--font-mono`). Swapping the stylesheet swaps
  the brand. Write components against the names, never the values.
- Third parties are welcome to use any of the looks for their own apps.
  Attribution is not required. Do not use the Lucian Labs, WaveLoop, DrinkTix,
  or Time Warrior wordmarks or logos for anything that isn't ours.