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.

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).
2. Project theme (set via PUT /api/v1/orgs/:slug/projects/:pslug/theme).
3. Org theme (set via PUT /api/v1/orgs/:slug/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

# 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. 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.