# HumanLayer — brand book

## How to build with this kit

```html
<link rel="stylesheet" href="tokens.css">
<link rel="stylesheet" href="components.css">
<html data-theme="dark">   <!-- respondent-facing -->
<html data-theme="light">  <!-- client-facing, documents, email, print -->
```

Start from `starter.html` (a complete page, both themes). Use token names and `hl-` classes; never type a hex value into a page. Each component has a working example in `components/`.

---

HumanLayer is verified human data infrastructure for the AI economy. Two products share this system: the **respondent app** (people earn by taking studies) and the **client app** (research and AI teams hire verified respondents). Positioning line: *The intelligence layer that compounds.*

Spell the brand **HumanLayer** — one word, capital H and L — in all copy. The domain is **humnlayer.ai** (no "a" after "m"); use it only as a URL, never as the name.

---

## CONTENT FUNDAMENTALS

**Two voices, one brand.**

- **Respondent-facing** (the respondent app, invites, SMS): warm, first-name, short. Say what the study is, how long it takes, what it pays, and when it closes. "Good morning, Jonathan!" · "Your food habits and routines" · "Video call · 45 min · $150 · 7 days left".
- **Client-facing** (the client app, site, decks): direct and numeric. Lead with the figure. "1,786 respondents hired. Avg trust score 91."

Rules for both:

- **Sentence case** for every heading, button and tab: "Recommended studies", "View details", "Accept invite". Proper nouns keep their caps (Platinum, Gold, Silver as tier names).
- **Numbers are concrete and formatted:** `$624.48`, `+$260`, `45 min`, `92%`, `1,786`. Currency always carries `$`; durations use `min`; never round a payout.
- **"You" and "your."** The product never says "I". Respondents see "Your balance"; clients see "Your studies".
- **No corporate filler:** leverage, seamless, robust, best-in-class, synergy, unlock, empower.
- **No emoji** in product UI, marketing or decks. Exclamation marks only in a greeting or a reward ("Refer and earn!").
- **Verbs on buttons, 1–3 words:** Accept invite, View details, View profile, Create study, Invite, Copy link.

| Write | Not |
| --- | --- |
| Video call · 45 min · $150 | A 45-minute video interview opportunity with compensation |
| 20 more to Platinum | You are close to reaching the next membership tier! |
| Medical verified | Pre-screened healthcare professional |
| Create study | Get started with your research journey |

---

## VISUAL FOUNDATIONS

**Two themes, one per app.** The **Dark** theme is the respondent app (phone, near-black `neutral-primary` ground, warm dark cards). The **Light** theme is the client app (desktop, white content area, warm `surface-raised` #F7F4F0 sidebar and header) and also documents, email and print. Build respondent-facing screens in Dark and client-facing screens and anything printed in Light.

**Color roles — design by role, never by raw hex.**

- Ground: `surface-page` (dark `neutral-primary` #070501). Cards sit on it in `surface-card`; nested panels in `surface-raised`; wells and tracks in `surface-sunken`.
- Text: `text-primary` for headings and numbers, `text-secondary` for body, `text-muted` for captions. Nothing lighter is text.
- **Orange is the one bright move per view.** `brand-fill` (#F69F19) on the primary button, the active tab marker, and the score ring — not all three loud at once. Two orange things competing means one is wrong.
- **Green means verified or positive.** `secondary-fill` and `secondary-text` for "Verified", accepted states, and positive amounts. Never decorative.
- **Supporting hues are for tiers and charts:** Platinum = `tier-platinum` (purple), Gold = `tier-gold`, Silver = `tier-silver` (slate), each as a tinted pill on its `-wash`. Outside tiers, they are data-viz series in this order: orange, green, purple, gold, slate. Study progress bars stack `green` (completed), `orange` (in progress) and `border-subtle` (remaining).
- `danger` is for errors only, always with a word beside it.

**THE INK RULE.** Labels on orange, green and gold fills are `on-brand` — the brand's near-black #070501 — never white. White on orange measures 2:1 and fails. This matches the brand book's mono-black logo on orange and green.

**Light-mode rule.** Bright orange, green and gold are under 2.5:1 on white. In the Light theme they stay as fills only (buttons, progress bars, icon chips); text uses `brand-text` (#A35F00), `secondary-text` (#1F7A52) and the tier tokens, which pass 4.5:1.

**Dark-mode warmth.** The respondent app's grounds are warm near-blacks, never blue-black or pure #000: `neutral-primary` #070501, cards `surface-card` #12100B, the active tab pill `surface-raised` #22201C. The greeting name is set in `brand-text` ("Good morning, **Jonathan!**").

**Typography.** Geist throughout, in the four weights the brand book names: Regular 400, Medium 500, SemiBold 600, Bold 700. Headings Bold or SemiBold with tight tracking (`display`, `h1`–`h3`). Money and counts use `stat` / `stat-sm` with `font-variant-numeric: tabular-nums` so columns line up. Body `body` / `body-sm` in `text-secondary`. Labels and buttons `label`.

**Spacing and layout.** 4px base (`space-1` … `space-16`). Phone screens use a `space-5` (20px) gutter and `space-4` gaps between cards; desktop cards pad `space-6`. Dashboards lay stat tiles in a row of 2 (phone) or 5 (desktop), then cards in a list.

**Shape.** Rounded and friendly, echoing the rounded H: `radius-md` 12px on buttons and stat tiles, `radius-lg` 16px on cards, `radius-xl` 24px on sheets, `radius-pill` on badges.

**Borders, not shadows.** Cards are `surface-card` with a 1px `border-subtle` edge. `shadow-overlay` exists for sheets, menus and modals only. No glows, no gradients, no glassmorphism, no grid-line backgrounds.

**States.** Hover: `brand-fill` → `brand-fill-hover`; secondary and ghost buttons fill with `surface-raised`. Focus: a 2px solid `focus-ring` outline, 2px offset, on every interactive element. Disabled: avoid; if unavoidable, `text-muted` label on `surface-raised`.

**Motion.** 150–200ms ease-out on color and opacity only. The score ring may animate its fill once on first view. No bounce, no parallax, no count-up numbers.

**Imagery.** Real people, natural light, warm and documentary. No robots, no glowing brains, no circuit-board heads — HumanLayer sells the human, not the machine.

---

## ICONOGRAPHY

The brand book ships no icon set. Until one is chosen:

- Use **Lucide** outline icons, 24px grid, 1.5px stroke, round caps — a flagged substitute, not a brand decision. Size 20px in UI, `text-muted` by default, `brand-text` only on the active tab.
- The four tab icons: Dashboard (layout-grid), Studies (clipboard-list), Wallet (wallet), Profile (user).
- No emoji, ever. The middle dot "·" separates meta items: "Survey · 45 min".

---

## LOGO

The mark is a **rounded "H" monogram in orange with a green dot sitting in its crossbar** — a person inside the layer. It pairs with the wordmark **HumanLayer** in a horizontal or stacked lockup. Use the files in the `logos/` folder; never redraw, retype or recolor them.

Pick the file by ground:

| Ground | Horizontal | Stacked | Mark only |
| --- | --- | --- | --- |
| White or light (`surface-page` Light, `surface-raised` Light) | `logos/humanlayer-horizontal.svg` | `logos/humanlayer-stacked.svg` | `logos/humanlayer-mark.svg` |
| Dark (`neutral-primary`, `surface-card` Dark) | `logos/humanlayer-horizontal-reversed.svg` | `logos/humanlayer-stacked-reversed.svg` | `logos/humanlayer-mark.svg` |
| Orange or green fields | `logos/humanlayer-horizontal-black.svg` | `logos/humanlayer-stacked-black.svg` | `logos/humanlayer-mark-black.svg` |

- **Horizontal** is the default: app headers (28px tall in the respondent app), site nav, email headers, document running heads.
- **Stacked** for covers, title slides, splash screens and square placements.
- **Mark only** for app icons, favicons, avatars and anywhere under 24px tall; at that size the wordmark stops reading.
- Clear space on every side is at least the width of one H stem. Minimum size: mark 16px tall, horizontal lockup 20px tall.
- Never place the full-color mark on orange or green, never put the reversed (white) wordmark on a light ground, never add a glow, outline, gradient or drop shadow, and never stretch.
- The logo orange and the palette `orange` are the same color, #F69F19. (The original brand book listed #FCA311; #F69F19 was confirmed as official on Oct 20 2026.)

---

## Components (classes in components.css, examples in components/)

All taken from the respondent and client app mockups in the brand guidelines.

- **Button** — primary (orange, ink label), secondary (outlined), ghost.
- **Badge** — tier (Platinum / Gold / Silver), verified, status.
- **StatTile** — a labelled figure: Balance $624.48, Avg trust score 91.
- **StudyCard** — a study invite: type, length, payout, deadline, actions.
- **RespondentCard** — a candidate in the client app: role, match %, tier, verification.
- **ScoreRing** — the /100 trust score with tier and next-tier progress.
- **TabBar** — the respondent app's bottom navigation.
- **Logo** — the eight lockup files, picked by ground.

**Intentional additions:** the `danger` color (the book has no error state) and a focus ring.