# Obelism Improve — Design & Brand Guide

> A machine-readable reference for the Obelism design system as used by
> **Obelism Improve** (A/B testing & feature flags). Point an LLM or coding
> agent at this file and it should be able to build UI and write copy that
> looks and sounds like Improve without guessing. For the SDK and API, see
> [`/sdk.md`](/sdk.md), or [`/llms.txt`](/llms.txt) for an index of everything.

Obelism Improve is a product of the Obelism software studio
(`obelism.studio`). Improve gives you a focused toolkit for optimizing your
website — A/B tests for hard data on what works for your customers, and
feature flags for no-sweat continuous delivery of major features.

This is the same shared design system every Obelism surface uses; this repo is
its source of truth (`src/styles/foundation/**`). The studio site publishes a
sibling copy at `obelism.studio/design.md`.

- **Product:** Obelism Improve — `improve.obelism.studio`
- **Studio:** Obelism — software studio
- **Contact:** improve@obelism.studio
- **Tagline:** Improve your platform today
- **Docs:** `improve.obelism.studio/docs` · **SDK/API for LLMs:** `/sdk.md` (index: `/llms.txt`)

---

## Principles

Four ideas drive every decision. When a design or a sentence is in doubt,
these break the tie.

1. **Help, don't complicate.** Our goal is to help, not make things more
   complicated. Cut steps, cut jargon, cut chrome. If a feature doesn't move
   the user toward what they came to do, it's a candidate for removal. Improve
   is focused on one task: giving you the tools to make your platform better.
2. **Focus on the task.** Design the flow around what the user needs to
   accomplish. Come up with an idea, configure it, and start measuring the
   same day.
3. **Driven by perfection.** Craft and attention to detail are the point.
   Software that isn't made with care gets in the way of its own purpose.
4. **Show the numbers, keep it light.** Back claims with data and clear
   visualisations, and ship the smallest, fastest thing that does it — the
   client SDK is 2.1 kB min+gz, and that's the bar.

---

## Voice & tone

Improve sounds like a sharp, friendly engineer explaining something they
genuinely care about — plain-spoken, confident, a little playful, never
corporate.

**Do**

- Write short, direct sentences. Lead with the benefit, then the mechanism.
- Be warm and human. Contractions are good. A wink is fine
  ("But wait, there is more", "But what about …", "We know it's important").
- Be concrete and honest about limits ("currently in closed beta",
  "there is a no-code plugin in beta").
- Use plain verbs: _help, ship, test, track, release, measure._
- Address the reader as "you"; refer to the studio as "we".

**Don't**

- Reach for hype or buzzwords ("revolutionary", "synergy", "next-gen",
  "10x"). Let the work be the claim.
- Pad sentences with filler or hedging. If a word can go, it goes.
- Over-explain. Trust the reader.
- Be cold or bureaucratic.

**Reference copy** (the house style, verbatim from shipping surfaces)

- Hero: _"Improve your platform today."_ /
  _"Obelism Improve provides streamlined AB testing and feature flags.
  Giving you the tools to effortlessly upgrade your platform based on
  numbers."_
- Value: _"Improve gives you the toolkit focussed on optimizing your website.
  AB-tests to get hard data on what works for your customers and Feature flags
  for no sweat continuous delivery of major features."_
- Feature (Simple): _"Our goal is to help, not make things more complicated.
  Giving you easy summaries and clear visualisations to share."_

**Mechanics**

- Sentence case for headings and buttons ("Start testing", not "Start
  Testing"). The one exception is the wordmark and product names
  ("Obelism Improve").
- Emoji are used sparingly, one per feature card as a friendly marker
  (🕺 📡 🚠 🔒 📊 🪶). Don't scatter them through prose.
- Numbers and units stay tight and specific ("2.1 kB", "three environments").

---

## Color

The palette is a warm neutral core — **beige** and near-**black** — with a
single **orange** accent. Blue is the interactive/link color. The decorative
brand colors (red, purple, green, blue) are for illustration only; data
visualisation uses a separate, colorblind-checked series palette (below).

Every color is defined as an RGB triple custom property
(`--color-<name>-rgb`, in `src/styles/foundation/variables.css`) so it can be
used at any opacity via `rgb(var(--color-x-rgb) / <alpha>)`. Hex equivalents
are given here for convenience.

### Neutrals (white → black)

| Token                | Hex       | RGB         |
| -------------------- | --------- | ----------- |
| `--color-white`      | `#F8F8F8` | 248 248 248 |
| `--color-white-off`  | `#F0F0F0` | 240 240 240 |
| `--color-grey-light` | `#848484` | 132 132 132 |
| `--color-grey-blue`  | `#868F97` | 134 143 151 |
| `--color-grey`       | `#6C6C6C` | 108 108 108 |
| `--color-grey-dark`  | `#282828` | 40 40 40    |
| `--color-black-off`  | `#141414` | 20 20 20    |
| `--color-black`      | `#0C0C0C` | 12 12 12    |

### Brand & accent

| Token                | Hex       | Role                                               |
| -------------------- | --------- | -------------------------------------------------- |
| `--color-beige`      | `#EEECE9` | Primary light background                           |
| `--color-beige-off`  | `#E4E1D9` | Muted / action surface (light)                     |
| `--color-orange`     | `#D4821E` | **Accent** — primary CTAs, focus rings, highlights |
| `--color-blue`       | `#005492` | Interactive / links (light)                        |
| `--color-blue-light` | `#8EB9F0` | Interactive / links (dark)                         |
| `--color-red`        | `#F05D5D` | Decorative / error                                 |
| `--color-purple`     | `#AD64BB` | Decorative                                         |
| `--color-green`      | `#7DB47A` | Decorative / success                               |

Orange is the one accent that carries the brand — use it deliberately (one
clear call to action per view), not as a fill.

### Semantic theme tokens

The UI is themed through a small set of semantic tokens that remap between
light and dark (`src/styles/foundation/theme.css`, via
`prefers-color-scheme`). In the docs (Fumadocs) these are mirrored onto
`--color-fd-*`. Build with these, not raw palette values.

| Token                        | Light      | Dark      |
| ---------------------------- | ---------- | --------- |
| `--theme-foreground`         | black      | white     |
| `--theme-background-main`    | beige      | black     |
| `--theme-background-alt`     | white      | black-off |
| `--theme-background-actions` | beige-off  | grey-dark |
| `--theme-border`             | grey-light | grey      |
| `--theme-accent`             | orange     | orange    |

Docs links use the brand **blue** (`#005492` light / `#8EB9F0` dark) for
readability on both backgrounds; hover and focus rings use the orange accent.

### Data-viz series palette

For charts only. A fixed-order categorical palette, validated for
colorblind-safe adjacent separation (CVD ΔE ≥ 8, normal-vision ≥ 15) and
contrast on our actual light/dark backgrounds. Assign in slot order — never
cycle or reassign per filter.

| Slot | Light     | Dark      |
| ---- | --------- | --------- |
| 1    | `#2A78D6` | `#3987E5` |
| 2    | `#008300` | `#008300` |
| 3    | `#E87BA4` | `#D55181` |
| 4    | `#EDA100` | `#C98500` |
| 5    | `#1BAF7A` | `#199E70` |
| 6    | `#EB6834` | `#D95926` |
| 7    | `#4A3AA7` | `#9085E9` |
| 8    | `#E34948` | `#E66767` |

---

## Typography

One typeface: **Inter** (self-hosted `InterVariable` woff2, weights 100–900,
with a matching italic). System-font fallbacks keep the first paint honest.

```css
--font-inter: 'InterVariable', system-ui, -apple-system, BlinkMacSystemFont,
	Segoe UI, Roboto, Helvetica Neue, Arial, Noto Sans, sans-serif,
	Apple Color Emoji, Segoe UI Emoji, Segoe UI Symbol, Noto Color Emoji;
--font-mono: ui-monospace, Menlo, Monaco, 'Cascadia Mono', 'Segoe UI Mono',
	'Roboto Mono', 'Oxygen Mono', 'Ubuntu Monospace', 'Source Code Pro',
	'Fira Mono', 'Droid Sans Mono', 'Courier New', monospace;
```

Headings are heavy and tight: **weight 800**, `letter-spacing: -0.015em`,
`line-height: 1.2`. Body is **weight 400** at `line-height: 1.6`. Labels run
300–400. Sizes below list mobile → `min-width: 768px` where they scale up
(`src/styles/foundation/typography.module.css`).

| Style     | Size (mobile → ≥768px) | Weight | Line height |
| --------- | ---------------------- | ------ | ----------- |
| heading-1 | 48 → 62 px             | 800    | 1.2         |
| heading-2 | 40 → 48 px             | 800    | 1.2         |
| heading-3 | 36 → 42 px             | 800    | 1.2         |
| heading-4 | 26 → 32 px             | 800    | 1.2         |
| body-1    | 22 px                  | 400    | 1.6         |
| body-2    | 18 px                  | 400    | 1.6         |
| body-3    | 16 px                  | 400    | 1.6         |
| label-1   | 14 → 16 px             | 400    | 1.4         |
| label-2   | 12 → 14 px             | 400    | 1.4         |
| label-3   | 12 px                  | 300    | 1.4         |

---

## Space, layout & radius

- **Content max-width:** `1260px` (`--max-width`).
- **Grid:** 6 columns / 24 px gutter on portrait, 12 columns / 48 px gutter on
  landscape (`--grid-columns`, `--grid-gutter`).
- **Radii:** things are soft and rounded.

| Token                     | Value | Use                     |
| ------------------------- | ----- | ----------------------- |
| `--border-radius-small`   | 4 px  | Inputs, small chips     |
| `--border-radius-default` | 12 px | Default surfaces        |
| `--border-radius-medium`  | 20 px | Cards                   |
| `--border-radius-large`   | 30 px | Large panels            |
| pill                      | `5em` | Buttons (fully rounded) |

Spacing is em/rem-based and generous — favor breathing room over density.
Prefer relative units (`em`, `ch`, `rem`) so type and spacing scale together.

---

## Components

Conventions distilled from the shipping UI (`src/elements/**`). Reuse these
shapes rather than inventing new ones.

**Buttons** (`src/elements/actions/Button.tsx`) — pill-shaped
(`border-radius: 5em`), `padding: 0.4em 1.2em`, `label-1` type, 1px border at
`rgba(--theme-border, 0.2)`. Three variants via `data-theme`:

- `primary` — white text on the orange accent. One per view.
- `secondary` — foreground text on the background color.
- `transparent` — foreground text, no fill.

Disabled: `opacity: 0.5`, `cursor: not-allowed`. Loading: `cursor: progress`.
Buttons have a subtle per-character "roll" hover animation — decorative, and
disabled under `prefers-reduced-motion: reduce`.

**Cards** — rounded (medium/large radius), on `--theme-background-alt`, often
introduced by a small `subTitle` label above a heading. Feature cards carry a
single leading emoji.

**Surfaces** — float rounded panels over the main background rather than using
flush, hard-bordered blocks. Borders are low-contrast
(`rgba(--theme-border, 0.2–0.35)`). The floated, large-radius sidebar card is
the reference shape.

---

## Motion

- Motion is purposeful and quick, never showy. Typical transition:
  `0.25s cubic-bezier(0.65, 0, 0.35, 1)`, with small staggered delays
  (~18 ms per index) for character/list rolls.
- **Always** honor `prefers-reduced-motion: reduce` — disable decorative
  animation, keep essential feedback.

---

## Accessibility

- Full light and dark support via `prefers-color-scheme`; `color-scheme` is
  set so form controls and scrollbars match.
- Meet WCAG AA contrast against the actual beige/black backgrounds — the
  neutral scale and blue link colors are chosen for this.
- Preserve accessible names when text is decorative (e.g. the button roll
  keeps a visually-hidden real label).
- Data-viz colors are colorblind-checked; never rely on color alone to convey
  meaning — pair with labels, shapes, or direct values.

---

## Assets & code style

- **Fonts:** self-hosted `InterVariable.woff2` + `InterVariable-Italic.woff2`
  under `public/fonts`, `font-display: swap`.
- **Icons/illustration:** inline SVG, `fill: currentColor` so marks inherit
  the theme foreground.
- **Code formatting** (Prettier): **tabs**, single quotes, no semicolons,
  trailing commas. Match this in any file you touch.

---

_This file is the source of truth for the Obelism / Improve look and voice.
Keep it in sync with `src/styles/foundation/**` when tokens change._