Tidewell design system

DESIGN.md

# Tidewell design system

Onest on a warm paper ground (#fdd4bd), Jasper Red as the one accent, pill buttons, frosted glass panels. Built for: AI inbox and sales agent.

> **For AI coding agents.** Build UI from this file alone. Paste the tokens (section 11) into the global stylesheet and load the fonts (section 2). Use only the colours, fonts, sizes, radii, shadows and easings defined here: no new hex values, no other fonts, no Tailwind default palette. When something is not covered, derive it from the nearest rule here and keep it quieter, not louder.

## 1. At a glance

| | |
|---|---|
| Theme | Light first; dark included via `data-theme="dark"` |
| Palette | Sanzo Wada combination 194: Jasper Red `#eb5324` · Seashell Pink `#fdd4bd` · Olympic Blue `#5a82b3` |
| Type | Onest (display) |
| Shape | cards 32px, buttons pill; soft shadows, 1px hairline rings |
| Motion | 250ms / 500ms / 1250ms; `cubic-bezier(.22, .8, .2, 1)`, `cubic-bezier(.76, 0, .24, 1)` |
| Layout | 1240px max width, clamp(16px, 3vw, 40px) gutter, clamp(88px, 10vw, 150px) section padding, center-aligned headings |

**The designer's notes** (from the template's token file):

- Tidewell design tokens. Glass: frosted panels with real depth over a slow field of light, sunset over water.
- Palette: Sanzo Wada combination 194 (Jasper Red, Seashell Pink, Olympic Blue) plus white and ink.

## 2. Setup

Fonts (put in `<head>`):

```html
<link rel="preconnect" href="https://fonts.googleapis.com">
<link rel="preconnect" href="https://fonts.gstatic.com" crossorigin>
<link rel="stylesheet" href="https://fonts.googleapis.com/css2?family=Onest:wght@400;500;600&display=swap">
```

Base styles, after the tokens:

```css
*, *::before, *::after { box-sizing: border-box; }
body {
  margin: 0;
  background: var(--color-background);
  color: var(--color-body);
  font-family: var(--font-body);
  font-size: var(--text-body, 16px);
  line-height: var(--text-body--line-height, 1.5);
  letter-spacing: var(--text-body--letter-spacing, 0);
  -webkit-font-smoothing: antialiased;
}
h1, h2, h3, h4 { margin: 0; font-family: var(--font-display); color: var(--color-foreground); text-wrap: balance; }
p { margin: 0; text-wrap: pretty; }
.container { max-width: var(--container); margin-inline: auto; padding-inline: var(--gutter); }
.section { padding-block: var(--section-y); }
:focus-visible { outline: 2px solid var(--color-ring); outline-offset: 2px; }
```

## 3. Colour

### Palette

| Name | Hex | Token |
|---|---|---|
| Jasper Red (Wada) | `#eb5324` | `--palette-jasper-red` |
| Seashell Pink (Wada) | `#fdd4bd` | `--palette-seashell-pink` |
| Olympic Blue (Wada) | `#5a82b3` | `--palette-olympic-blue` |

### Roles

| Role | Light | Dark | Use for |
|---|---|---|---|
| `--color-background` | `#fdd4bd` | `#15171c` | Page background |
| `--color-foreground` | `#15171c` | `#ffffff` | Headings and primary text |
| `--color-body` | `#685b56` | `#afb0b2` | Body copy |
| `--color-surface` | `#fee6d9` | `#212327` | Cards and raised panels |
| `--color-surface-foreground` | `#15171c` | `#ffffff` | Text on surfaces |
| `--color-muted` | `#f3ccb5` | `#2b2b2b` | Quiet bands, wells, hover rows |
| `--color-muted-foreground` | `#685b56` | `#afb0b2` | Secondary text, captions, labels |
| `--color-border` | `#ffffffbf` | `#ffffff38` | Hairlines, dividers, card edges |
| `--color-border-strong` | `#15171c47` | `#ffffff47` | Emphasised rules, input edges on hover |
| `--color-input` | `#ffffff8c` | `#ffffff1f` | Input borders |
| `--color-input-background` | `#fef0e7` | `#212327` | Input fill |
| `--color-ring` | `#5a82b3` | `#5a82b3` | Focus ring |
| `--color-primary` | `#15171c` | `#fdd4bd` | Primary action fill |
| `--color-primary-foreground` | `#ffffff` | `#15171c` | Text on primary |
| `--color-secondary` | `#eb5324` | `#eb5324` | Secondary action fill |
| `--color-secondary-foreground` | `#15171c` | `#15171c` | Text on secondary |
| `--color-accent` | `#eb5324` | `#fdd4bd` | Brand accent: highlights, links, active states |
| `--color-accent-foreground` | `#15171c` | `#15171c` | Text on accent |
| `--color-inverse` | `#15171c` | `#ffffff` | Inverted band (dark on light pages, light on dark) |
| `--color-inverse-foreground` | `#fdd4bd` | `#15171c` | Text on inverse |
| `--color-inverse-muted` | `#a58c80` | `#6e6f72` | Secondary text on inverse |
| `--color-inverse-border` | `#fdd4bd29` | `#15171c29` | Hairlines on inverse |
| `--color-destructive` | `#eb5324` | `#ed683e` | Errors and destructive actions |
| `--color-destructive-foreground` | `#111111` | `#111111` | Text on destructive |

### How the colours are used

- Share of page area by surface colour, measured on the home page: #ffffff 75.5%, #15171c 20.6%, Jasper Red 2.1%, #ea5325 0.9%. Keep roughly that balance; the accent's share is about where it is used, not how much.
- `--color-accent` (#eb5324) is the brand's accent: use it sparingly, on one thing per view: a primary action, a highlight, an active state, an underline. Never use it for body text.
- `--color-primary` (#15171c) fills the main action; its text is `--color-primary-foreground` (#ffffff), contrast 17.93:1.
- Text: headings `--color-foreground` (13.09:1 on the page), secondary text `--color-muted-foreground` (4.76:1). Don't go lighter than muted for anything people must read.
- Surfaces step: `background` → `muted` for quiet bands → `surface` for cards → `inverse` (#15171c) for one contrasting band or card per page.
- Borders are hairlines: `--color-border` (#ffffffbf), often drawn as `box-shadow: 0 0 0 1px` (inset on cards) rather than `border`.
- Every chromatic colour is one of the Wada combination's colours or a tint, shade or alpha of one. Neutrals (white, greys, near-black) are free. No other hues, no rainbow gradients.
- Gradients appear (35 on the measured pages), only between this palette's colours.

## 4. Typography

| Family | Role | Weights | Licence | Source |
|---|---|---|---|---|
| Onest | display | 400, 500, 600 | SIL Open Font License 1.1 | Google Fonts |

| Token | Desktop (1440) | Phone (390) | CSS size | Weight | Line height | Tracking | Case | Font |
|---|---|---|---|---|---|---|---|---|
| `--text-display` | 103.68px | 48px | `clamp(48px, 7.2vw, 110px)` | 600 | 0.96 | -0.052em | as written | `--font-display` |
| `--text-h1` | 80.64px | 42px | `clamp(42px, 5.6vw, 84px)` | 600 | 0.98 | -0.045em | as written | `--font-display` |
| `--text-h2` | 66px | 36px | `clamp(36px, 4.6vw, 66px)` | 600 | 1 | -0.045em | as written | `--font-display` |
| `--text-h3` | 20px | 20px | `clamp(17px, 1.4vw, 20px)` | 600 | 1.55 | -0.02em | as written | `--font-display` |
| `--text-lead` | 20px | 17px | `clamp(17px, 1.4vw, 20px)` | 400 | 1.5 | 0 | as written | `--font-body` |
| `--text-body` | 16.5px | 16px | `16.5px` | 400 | 1.55 | 0 | as written | `--font-body` |
| `--text-small` | 13.5px | 13.5px | `13.5px` | 400 | 1.55 | 0 | as written | `--font-body` |
| `--text-eyebrow` | 12.5px | 12.5px | `12.5px` | 600 | 1.55 | 0 | as written | `--font-body` |

Rules:
- Headlines: weight 600, tracking -0.045em, line height 1. Tight tracking is part of the look; keep it on every heading above 32px. Use only the weights listed above.
- Headlines are one voice: no mixed fonts, no coloured or italic accent words inside a headline.
- Eyebrow above section titles: 12.5px, weight 600, sentence case, `--color-muted-foreground`, in Onest.
- Body copy: 16.5px in `--color-body`, lines no longer than 65 characters (`max-width: 60ch`).
- No uppercase text except where a token above says so.
- No italics anywhere.

## 5. Layout and spacing

- Container: max 1240px, centred, side padding `--gutter` (clamp(16px, 3vw, 40px); 40px at 1440, 16px on phones).
- Sections: `--section-y` top and bottom (clamp(88px, 10vw, 150px); 144px at 1440, 88px on phones). Adjacent sections on the same ground share the rhythm; don't add extra margins.
- Spacing scale (base 4px): `--space-1` 4px, `--space-2` 6px, `--space-3` 10px, `--space-4` 14px, `--space-5` 22px, `--space-6` 32px, `--space-7` 48px, `--space-8` 64px. Most common gaps on the pages: 10px, 8px, 6px, 4px, 16px, 24px.
- Section headings are centred; keep paragraphs centred under them with a narrow measure.
- Breakpoints (desktop-first): 760px, 900px, 960px, 1080px. Phone layout (the phone gutter and section padding above) applies below 760px.
- Grids of three or four equal items: all in one row above 1080px, two columns down to 760px, one column below. Items in a row share the same height and their actions align at the bottom.

## 6. Shape and depth

- Radii: `--radius-sm` 14px, `--radius-md` 32px, `--radius-lg` clamp(28px, 3vw, 44px) (43px at 1440), `--radius-pill` 9999px.
- Rules and borders: 1px #14141d1a.
- Buttons: pill (`--radius-pill`). Cards: 32px. Inputs: 999px.
- Shadows: `--shadow-sm`, `--shadow-md`, `--shadow-lg`; used on floating elements only (menus, popovers, lifted cards); cards themselves use the 1px ring.
- Frosted glass: `backdrop-filter: blur(22px) saturate(1.45)` on sticky bars and overlays, over a translucent surface.

## 7. Motion

- Durations: `--duration-fast` 250ms, `--duration-base` 500ms, `--duration-slow` 1250ms.
- Easings: `--ease-out` `cubic-bezier(.22, .8, .2, 1)`, `--ease-in-out` `cubic-bezier(.76, 0, .24, 1)`. Use `--ease-out` for things that enter, lift or underline; `--ease-in-out` for things that move across or open and close.
- What animates: background, color, box-shadow, opacity and top. Hover changes colour or fill, never layout.
- The template uses 14 keyframe animations: content rises or fades in once as it enters the viewport.
- Respect `prefers-reduced-motion`: drop to opacity changes or none.

## 8. Components

Exact recipes, measured from the template. Use these classes or translate them 1:1 into your framework.

### Buttons

Primary: (“See integrations”) var(--color-foreground) fill, 48px tall. Secondary: var(--color-accent) fill. 

```css
.btn {
  display: inline-flex; align-items: center; justify-content: center; gap: 8px;
  height: 48px;
  padding-inline: 22px 22px;
  border-radius: var(--radius-pill);
  font-family: var(--font-display);
  font-size: 15px;
  font-weight: 600;
  letter-spacing: -0.01em;
  line-height: 1;
  text-decoration: none;
  white-space: nowrap;
  cursor: pointer;
  transition: background 300ms ease, color 300ms ease, transform 300ms ease, box-shadow 300ms ease;
}
.btn-primary {
  background: var(--color-primary);
  color: var(--color-primary-foreground);
  border: none;
  box-shadow: rgba(21, 23, 28, 0.6) 0px 10px 24px -12px;
}
.btn-primary:hover { background: var(--color-accent); color: var(--color-foreground) }
.btn-secondary {
  background: var(--color-secondary);
  color: var(--color-secondary-foreground);
  border: none;
  box-shadow: rgb(235, 83, 36) 0px 10px 22px -12px;
}
.btn-secondary:hover { background: color-mix(in srgb, var(--color-accent) 88%, var(--color-primary-foreground)) }
.btn-outline { background: transparent; color: var(--color-foreground); border: 1px solid var(--color-border-strong); }
.btn-outline:hover { border-color: var(--color-foreground); }
.card-inverse .btn-outline { color: var(--color-inverse-foreground); border-color: var(--color-inverse-border); }
```

Use one `.btn-primary` per view. Actions beside it, and the actions of the other items in a set, use `.btn-outline`; `.btn-secondary` is for the one featured item (see Cards). All buttons share the `.btn` base height and padding.

```html
<a class="btn btn-primary" href="#">See integrations</a>
<a class="btn btn-secondary" href="#">Approve</a>
```

### Inputs

```css
.field { display: grid; gap: 8px; }
.label { font-size: 15px; font-weight: 400; color: var(--color-foreground); }
.input {
  height: 49px;
  padding: 0 18px;
  background: #ffffffa3;
  color: var(--color-foreground);
  border: none;
  box-shadow: rgba(255, 255, 255, 0.55) 0px 0px 0px 1px inset, rgba(21, 23, 28, 0.06) 0px 1px 2px 0px inset;
  border-radius: 999px;
  font: inherit; font-size: 16px;
}
.input::placeholder { color: #14171ca3; }
.input:focus { outline: none; box-shadow: 0 0 0 2px var(--color-ring); }
textarea.input { height: auto; min-height: 140px; padding-block: 14px; }
```

### Cards

Cards sit on the page in grids with 16px gaps. 

```css
.card {
  background: #ffffff6b;
  color: var(--color-surface-foreground);
  border-radius: 32px;
  padding: 30px 30px;
  box-shadow: rgba(255, 255, 255, 0.75) 0px 1px 0px 0px inset, rgba(255, 255, 255, 0.4) 0px 0px 0px 1px inset, rgba(21, 23, 28, 0.3) 0px 30px 60px -30px;
  backdrop-filter: blur(22px) saturate(1.45);
}
.card h3 { font-size: var(--text-h3, 24px); font-weight: var(--text-h3--font-weight, 500); letter-spacing: var(--text-h3--letter-spacing, 0); line-height: var(--text-h3--line-height, 1.2); }
.card p { color: var(--color-muted-foreground); }
[data-theme="dark"] .card { background: var(--color-surface); }
.card ul { list-style: none; margin: 0; padding: 0; display: grid; gap: 10px; }
.card li { display: flex; gap: 10px; align-items: baseline; }
.card li::before { content: ""; flex: none; width: 8px; height: 1px; background: currentColor; opacity: .5; transform: translateY(-4px); }
```

To feature one item in a set (a recommended plan, the main offer), make it the card with a 1px `--color-foreground` border with the `.btn-secondary` action; the others stay `.card` with `.btn-outline`. Mark it with a small text label in the eyebrow style, not a badge.

Big figures (prices, stats): `--font-display` at `--text-h2` size, weight and tracking, `font-variant-numeric: tabular-nums`; the unit or period beside it in `--text-small` and the muted colour.

### Navigation bar

80px tall, sticky to the top, transparent over the page. Logo left, 5 links (15px, weight 500), then one primary button (“Start free”) on the right.

```css
.nav { position: sticky; top: 0; z-index: 50; height: 80px; display: flex; align-items: center; justify-content: space-between; gap: 24px; padding-inline: var(--gutter); }
.nav a.link { font-size: 15px; font-weight: 500; color: var(--color-foreground); text-decoration: none; opacity: .8; }
.nav a.link:hover { opacity: 1; }
```

### Footer

On the page ground, link columns, links 14px in `--color-muted-foreground`, the wordmark and a one-line note, legal links last.

### Section header

```html
<section class="section">
  <div class="container">
    <header class="section-head">
      <p class="eyebrow">Section label</p>
      <h2>Short statement headline</h2>
      <p class="lead">One sentence that says what the section gives the reader.</p>
    </header>
    <!-- grid of .card -->
  </div>
</section>
```

```css
.section-head { display: grid; gap: 14px; max-width: 720px; margin-inline: auto; text-align: center; margin-bottom: 48px; }
.section-head h2 { font-size: var(--text-h2); line-height: var(--text-h2--line-height); letter-spacing: var(--text-h2--letter-spacing); font-weight: var(--text-h2--font-weight); }
.lead { font-size: var(--text-lead, 18px); color: var(--color-muted-foreground); max-width: 56ch; }
.eyebrow { font-family: var(--font-display); font-size: 12.5px; font-weight: 600; letter-spacing: 0; color: var(--color-muted-foreground); }
```

## 9. Voice and copy

Written for: AI inbox and sales agent. Tidewell answers replies, follows up and books meetings across your team’s inboxes. It asks before it acts.

- Headlines: 6 words typical (1–12), sentence case, no closing full stop. Plain statements, no hype words.
- Buttons: two words or fewer, a verb first (“Start free”, “See it work”, “Edit”, “Approve”).
- Minimal text: every word earns its place. One idea per section, one sentence of support under a headline.
- No decorative micro-text, fake data readouts, “LIVE” chips or invented metrics.

Headlines from the template, for tone:

- It asks. You answer in one tap.
- Works where your team already works.
- Let it read the inbox. You keep the last word.
- Colour
- Type · Onest
- Buttons and controls

## 10. Do and don’t

**Do**

- Use `--color-background` for the page and step to `--color-muted` / `--color-surface` for bands and cards.
- Give the main action `--color-primary` in a pill; one primary button per view. Other actions beside it use `.btn-outline`.
- Keep headings in `--font-display` at the scale above, with its tracking.
- Use hairline borders (`--color-border`) to separate, and generous `--section-y` spacing between sections.
- Animate with `--ease-*` and `--duration-*` only.

**Don’t**

- Introduce colours outside the palette and roles (no Tailwind blue/indigo/gray defaults).
- Use a font other than Onest.
- Stack heavy shadows; one level of lift at most.
- Use gradients between colours that are not in the palette.
- Use italics.
- Use uppercase text, except for tiny labels if the scale says so.
- Mix radii: actions are pills, cards 32px, inputs 999px.
- Centre long paragraphs, or let text run wider than 65 characters.
- Add emoji, icons in every heading, or decorative badges.

## 11. Tokens

The complete set. Paste into your global stylesheet before anything else.

```css
:root {
  color-scheme: light;
  /* palette */
  --palette-jasper-red:          #eb5324;
  --palette-seashell-pink:       #fdd4bd;
  --palette-olympic-blue:        #5a82b3;

  /* colour roles (light) */
  --color-background:            #fdd4bd;
  --color-foreground:            #15171c;
  --color-body:                  #685b56;
  --color-surface:               #fee6d9;
  --color-surface-foreground:    #15171c;
  --color-muted:                 #f3ccb5;
  --color-muted-foreground:      #685b56;
  --color-border:                #ffffffbf;
  --color-border-strong:         #15171c47;
  --color-input:                 #ffffff8c;
  --color-input-background:      #fef0e7;
  --color-ring:                  #5a82b3;
  --color-primary:               #15171c;
  --color-primary-foreground:    #ffffff;
  --color-secondary:             #eb5324;
  --color-secondary-foreground:  #15171c;
  --color-accent:                #eb5324;
  --color-accent-foreground:     #15171c;
  --color-inverse:               #15171c;
  --color-inverse-foreground:    #fdd4bd;
  --color-inverse-muted:         #a58c80;
  --color-inverse-border:        #fdd4bd29;
  --color-destructive:           #eb5324;
  --color-destructive-foreground: #111111;

  /* type */
  --font-display:                Onest, ui-sans-serif, system-ui, -apple-system, "Segoe UI", sans-serif;
  --font-body:                   Onest, ui-sans-serif, system-ui, -apple-system, "Segoe UI", sans-serif;
  --text-display:                clamp(48px, 7.2vw, 110px);
  --text-display--line-height:   0.96;
  --text-display--letter-spacing: -0.052em;
  --text-display--font-weight:   600;
  --text-h1:                     clamp(42px, 5.6vw, 84px);
  --text-h1--line-height:        0.98;
  --text-h1--letter-spacing:     -0.045em;
  --text-h1--font-weight:        600;
  --text-h2:                     clamp(36px, 4.6vw, 66px);
  --text-h2--line-height:        1;
  --text-h2--letter-spacing:     -0.045em;
  --text-h2--font-weight:        600;
  --text-h3:                     clamp(17px, 1.4vw, 20px);
  --text-h3--line-height:        1.55;
  --text-h3--letter-spacing:     -0.02em;
  --text-h3--font-weight:        600;
  --text-lead:                   clamp(17px, 1.4vw, 20px);
  --text-lead--line-height:      1.5;
  --text-lead--letter-spacing:   0;
  --text-lead--font-weight:      400;
  --text-body:                   16.5px;
  --text-body--line-height:      1.55;
  --text-body--letter-spacing:   0;
  --text-body--font-weight:      400;
  --text-small:                  13.5px;
  --text-small--line-height:     1.55;
  --text-small--letter-spacing:  0;
  --text-small--font-weight:     400;
  --text-eyebrow:                12.5px;
  --text-eyebrow--line-height:   1.55;
  --text-eyebrow--letter-spacing: 0;
  --text-eyebrow--font-weight:   600;

  /* space and layout */
  --space-1:                     4px;
  --space-2:                     6px;
  --space-3:                     10px;
  --space-4:                     14px;
  --space-5:                     22px;
  --space-6:                     32px;
  --space-7:                     48px;
  --space-8:                     64px;
  --container:                   1240px;
  --gutter:                      clamp(16px, 3vw, 40px);
  --section-y:                   clamp(88px, 10vw, 150px);

  /* shape */
  --radius-sm:                   14px;
  --radius-md:                   32px;
  --radius-lg:                   clamp(28px, 3vw, 44px);
  --radius-pill:                 9999px;
  --shadow-sm:                   rgba(21, 23, 28, 0.5) 0px 6px 16px -10px, rgba(255, 255, 255, 0.75) 0px 1px 0px 0px inset;
  --shadow-md:                   rgb(235, 83, 36) 0px 10px 22px -12px;
  --shadow-lg:                   rgba(21, 23, 28, 0.6) 0px 20px 40px -14px;
  --shadow-ring:                 rgba(255, 255, 255, 0.75) 0px 1px 0px 0px inset, rgba(255, 255, 255, 0.4) 0px 0px 0px 1px inset, rgba(21, 23, 28, 0.3) 0px 30px 60px -30px;
  --backdrop:                    blur(22px) saturate(1.45);

  /* motion */
  --ease-out:                    cubic-bezier(.22, .8, .2, 1);
  --ease-in-out:                 cubic-bezier(.76, 0, .24, 1);
  --duration-fast:               250ms;
  --duration-base:               500ms;
  --duration-slow:               1250ms;
}

/* dark theme: <html data-theme="dark"> or class="dark" */
[data-theme="dark"], .dark {
  color-scheme: dark;
  --color-background:            #15171c;
  --color-foreground:            #ffffff;
  --color-body:                  #afb0b2;
  --color-surface:               #212327;
  --color-surface-foreground:    #ffffff;
  --color-muted:                 #2b2b2b;
  --color-muted-foreground:      #afb0b2;
  --color-border:                #ffffff38;
  --color-border-strong:         #ffffff47;
  --color-input:                 #ffffff1f;
  --color-input-background:      #212327;
  --color-ring:                  #5a82b3;
  --color-primary:               #fdd4bd;
  --color-primary-foreground:    #15171c;
  --color-secondary:             #eb5324;
  --color-secondary-foreground:  #15171c;
  --color-accent:                #fdd4bd;
  --color-accent-foreground:     #15171c;
  --color-inverse:               #ffffff;
  --color-inverse-foreground:    #15171c;
  --color-inverse-muted:         #6e6f72;
  --color-inverse-border:        #15171c29;
  --color-destructive:           #ed683e;
  --color-destructive-foreground: #111111;
}

/* breakpoints (desktop-first): 760px, 900px, 960px, 1080px */
@media (prefers-reduced-motion: reduce) {
  :root { --duration-fast: 1ms; --duration-base: 1ms; --duration-slow: 1ms; }
}
```

---
Source: the Tidewell template, measured from its rendered pages (2026-10-08).