Themes overview

Tangly ships five themes. One token swap, no component changes. Pick one or roll your own.

Themes

Tangly ships five themes out of the box. They share the same component shell (@tanglydocs/theme-ui) — what differs is colors, typography, layout dimensions, and chrome.

The five built-ins

Tang

Default. Mintlify-Mint inspired. Sans-serif headings, warm off-white surface, mandarin accent.

Pith

Editorial. Serif headings, cream background, all chrome in the left sidebar.

Pip

Minimal. Single-column, topbar-only chrome. For tiny sites — 4–5 pages.

Readable

Long-form. Cream paper, serif body, book-style chapter nav. For essays, books, manuscripts.

Geist

Modern dev-tool aesthetic. Vercel / Linear / Stripe family. Hairline borders, near-black CTAs.

Live demos

Every theme renders a real Tangly project at examples.tangly.dev. Each is a different docs.json + MDX corpus; the only thing that changes between them is the theme field.

Tang demo

Cipher — encryption SDK docs.

Pith demo

On Craft — handbook of small ideas.

Pip demo

Sprig — tiny CLI for shell history.

Readable demo

The Long Wait — short novel.

Geist demo

Halo — edge platform docs.

Starter demo

The default tangly init scaffold.

The source for each demo lives in examples/demo-<theme>/ in the Tangly repo — clone, edit, tangly dev to play.

Switch themes

One field in docs.json:

json

{ "theme": "tang" }

Reload the dev server (tangly dev) to see it. No other changes required — components are theme-agnostic.

Picking one

If your docs are…	Pick
A general OSS / dev-tool site	Tang
A handbook, knowledge base, or design-led docs	Pith
A 4–5 page README replacement	Pip
A book, essay collection, or long manuscript	Readable
A modern dev-tool with grayscale + restraint	Geist

How themes work

Each theme is a separate package: @tanglydocs/theme-tang, @tanglydocs/theme-pith, @tanglydocs/theme-pip, @tanglydocs/theme-readable, @tanglydocs/theme-geist.

Inside each package: a single theme.css file with the token table (colors, fonts, layout dimensions). Components are shared — they consume the tokens at render.

docs.json (theme: "pith")
   ↓
resolveTheme()
   ↓
@tanglydocs/theme-pith → theme.css with pith's tokens
   ↓
@tanglydocs/theme-ui   → renders Layout/TopNav/Sidebar/etc using those tokens

This means switching themes is risk-free. Authoring stays the same. No content edits. Just swap the field, rebuild.

Customization paths

Three knobs, in order of effort:

Override colors via colors in docs.json. Five tokens. See Colors.
Override fonts via fonts in docs.json. Heading and body. See Fonts & styling.
Override CSS variables in theme/styles/theme.css. Drop the file at your project root; Tangly concatenates after the active theme. Full control.

For deep custom layouts, shadow the components or eject.

See Customizing themes for the full picture.

Mintlify aliases

Existing Mintlify projects often have theme: "mint" or one of: maple, palm, willow, linden, almond, aspen, luma, sequoia. All resolve to tang. See Aliases for why.

Schema reference

For the full theme: field definition, see Schema → Themes.