---
name: themes
description: Per-org, per-project, and per-share theme overrides — the cascade and what's themeable.
---

# Themes

A theme is a small JSON object that tweaks the colors and typography of a share's render. Themes can be set at three levels — **org**, **project**, or **share** — and the renderer picks the most specific one available.

For per-org logo, footer line, and primary color (a lighter-weight subset of theming), see [Branding](/docs/branding).

## The cascade

When a share is rendered, the theme is resolved by walking from narrowest to broadest:

1. **Share theme** (`shares`-level override, set via [`PUT /api/v1/shares/:id/theme`](/docs/api#put-apiv1sharesidtheme--set-per-share-theme-overrides)).
2. **Project theme** (set via [`PUT /api/v1/orgs/:slug/projects/:pslug/theme`](/docs/api#put-apiv1orgsslugprojectspslugtheme--set-project-theme)).
3. **Org theme** (set via [`PUT /api/v1/orgs/:slug/theme`](/docs/api#put-apiv1orgsslugtheme--set-org-level-theme)).
4. **Default theme** — Anchorify's built-in look.

Each field is resolved independently. If your org theme sets `primary_color` but your project theme only sets `font_family`, a share in that project gets the project's font and the org's primary color.

## What's themeable

The theme schema accepts a small set of recognized fields:

- `primary_color` — accent color, used for links and call-to-action elements (6-digit hex, e.g. `#3b82f6`).
- `background_color` — page background (6-digit hex).
- `text_color` — body text color (6-digit hex).
- `font_family` — typography pick. Accepts the named values the renderer ships (e.g. `system`, `serif`, `mono`).

The schema is intentionally narrow. Raw CSS is rejected — the renderer needs to know what each field means so it can apply it consistently across markdown, code, slides, and the comments bar.

Sending a field set to `null` clears that field at the current level (so the cascade falls through to the next-narrower override). Omitting a field leaves whatever was there.

## Setting a theme

### Web

- Org theme: `Dashboard` → `Settings` → `Branding` (combined with logo/footer fields).
- Project theme: project page → `Settings` → **Theme**.
- Share theme: share row `⋯` → `Theme`.

Each surface has a small preview pane so you can iterate without re-rendering a real share.

### API

```bash
# Org-wide
curl -sX PUT https://anchorify.io/api/v1/orgs/alice/theme \
  -H "Authorization: Bearer $REPO_SHARE_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"primary_color":"#0f766e","font_family":"system"}'

# One project
curl -sX PUT https://anchorify.io/api/v1/orgs/alice/projects/q1-acme/theme \
  -H "Authorization: Bearer $REPO_SHARE_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"primary_color":"#1e40af"}'

# One share
curl -sX PUT https://anchorify.io/api/v1/shares/k3p9x2af/theme \
  -H "Authorization: Bearer $REPO_SHARE_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"background_color":"#fdfdfc"}'
```

`DELETE` on any of those endpoints clears the override at that level.

## When to set what

- **Org** — your brand. Set the org theme once and every share in the org inherits it.
- **Project** — per-client styling. One project per client; each gets its own colors without polluting your default.
- **Share** — usually unnecessary. Reach for a share-level override when a single deliverable has a different audience (e.g. a portfolio piece styled for a press kit) and you don't want a whole project for it.

## Audit trail

Theme changes emit `org.theme.set` / `org.theme.clear` (or the project/share variants) audit events on the org's [audit feed](/docs/audit). Useful when one of your client's brand colors quietly drifts.

## What's not in here

- **Raw CSS overrides** — the schema rejects arbitrary CSS. If you have a tweak the schema doesn't cover, file an issue.
- **Dark-mode toggle per share** — the render adapts to the visitor's system preference; you can't lock a share to one mode.
- **Per-content-type themes** — markdown and code shares share the same theme. Splitting (e.g. a different background for code views) is a follow-up.