/Docs
Search docs or ask a question⌘K
DocsAgent
Changelog
Guides Theming

Theming

Presets, appearance and token overrides — how to give your docs your brand's look, with contrast checks built in.

12 min read

Syntext sites are customizable to match your brand without forking anything. A look is built in three layers, each one optional and each one overriding the last:

1.
A preset — a complete starting look, picked with theme.
2.
appearance — single choices on top of the preset: accent, mode, fonts, size, corners, density, width, the layout and component styles.
3.
themeOverrides — exact token values, for the cases a choice can't express.

The easiest way to work with all three is the appearance editor in the dashboard (Settings › Appearance): it shows a live preview and writes the syntext.json changes for you, as a pull request.

1. Pick a preset

Doc engine v2 has eight presets — Workbench, Paper, Console, Atlas, Plain, Orbit, Grid and Margin. Each sets the fonts, accent, shell, header, navigation and the style of every component:

json
{
"theme": "paper"
}

See Presets for what each one looks like. To share one look across every project in your organization, save it as an organization theme and use "theme": "@your-org/brand".

Note
v1 themes

"theme": "default" and "theme": "gravv" are the doc engine v1 themes. A site on a v1 theme with no appearance block keeps the v1 renderer, and everything in Typography and below still applies to it as before. A preset name, an organization theme or an appearance block opts a site in to v2 — see Opting in.

2. Change single choices with appearance

json
{
"theme": "paper",
"appearance": {
"accent": { "light": "#0E7A63", "dark": "#3DDC97" },
"mode": "system",
"fonts": { "heading": "Fraunces", "body": "Inter", "mono": "JetBrains Mono" },
"size": 16,
"radius": "small",
"density": "compact",
"width": "full",
"layout": { "nav": "tree" },
"components": { "code": "dark", "callout": "box" }
}
}

Every field is optional and works with every preset. The full list of fields and values is in the appearance reference.

Header background and code corners

On Orbit the floating header lets the page scroll behind it. Any preset can do the same, or keep a band behind the header:

json
{
"appearance": { "layout": { "headerBackground": "transparent" } }
}

transparent keeps Orbit's island on its own background with the content showing around it; on a full-width header bar the content shows through it, blurred. solid puts a band behind the header, so text stops at its edge. Without the setting, the island header is transparent and every other header solid.

Code blocks follow the site's corners and their code style. To set their corners on their own — code blocks, code tabs, request and response panels and the copy and ask buttons — use codeRadius:

json
{
"appearance": { "components": { "code": "light", "codeRadius": "large" } }
}

Values: site (default), none, small, medium, large. In the dashboard both are under Settings › Appearance: Header background in Layout, next to Header, and Code block corners in Components, next to Code blocks.

Brand colour

Set one accent, or a different one for dark mode. Everything else — link colour, hover, tints, the text on buttons — is derived from it per mode, the way the preset derives its own:

json
{
"appearance": { "accent": "#6366F1" }
}

Contrast

Syntext checks your accent against the page background in each mode:

CheckWhat's measuredNeeds
LinksThe derived link colour on the page background4.5:1 (WCAG AA for text)
FillsThe accent itself — buttons, active states — on the page background3:1 (WCAG AA for controls)

A colour that misses either check is never blocked. The build log warns and suggests the nearest shade of your accent that passes, and keeps your colour:

text
appearance.accent.light: In light mode on #FFFFFF, links (#cb9a04) reach 2.57:1 of the 4.5:1 text needs and accent fills (#F2B705) reach 1.82:1 of the 3:1 controls need. The nearest passing accent is #b38704. The build keeps your colour.

The appearance editor shows the same checks as you pick a colour, with a one-click fix, and stx check --explain appearance prints them locally. A very light accent usually passes in dark mode and fails in light mode — set accent to { "light", "dark" } to use a darker shade in light mode only.

Dark mode

appearance.mode sets the mode a first-time reader sees: light, dark, or system to follow their operating system. Readers can switch with the light/dark toggle, and their choice is remembered. Set "toggle": false to remove the toggle and pin the site to mode.

On v1 sites, the toggle is controlled by features.themeToggle — deprecated: it stays a warning on v1 and moves to appearance.toggle when the site switches to v2.

3. Exact values with themeOverrides

themeOverrides sets individual tokens by name — colours per mode, fonts, named text styles and corner radii:

json
{
"theme": "paper",
"themeOverrides": {
"colors": {
"light": { "bg-page": "#FBFAF7", "content-primary": "#1C1917" },
"dark": { "bg-page": "#0C0A09" }
},
"radius": { "sm": 4, "md": 6, "lg": 8 }
}
}

On a v2 site it applies on top of appearance. Not every v1 token has a v2 equivalent — the token map lists which ones change v2 pages and which are ignored. On v1 sites it applies on top of the v1 theme, and every token in this guide is available.

The full order, including organization themes and the legacy colors and fonts blocks, is in Precedence.

Legacy brand colours

Warning

The colors block is deprecated. Use appearance.accent on v2, or themeOverrides on v1. stx migrate moves it for you.

json
{
"colors": {
"primary": "#6366F1",
"accent": "#2AC3DE",
"background": "#0F172A"
}
}
PropertyUse instead
primaryappearance.accent (v2) — on v1 it stays a warning until the site moves to v2
accentthemeOverrides.colors.{light,dark}.accent-strong
backgroundthemeOverrides.colors.{light,dark}.bg-page

colors is applied after themeOverrides, so an existing site never changes because a preset was introduced.

Typography

Font roles

A theme sets three font roles. Every named text style refers to one of them, so changing a role restyles everything that uses it.

RoleUsed bydefault theme (v1)
displayH1–H4Inter
bodyBody copy, navigation, labels, captionsInter
monoCode blocks, inline codeJetBrains Mono

A theme is free to make body monospace — the gravv theme (v1) sets body, nav and labels in Geist Mono, with only headings in a display face.

Custom fonts

json
{
"themeOverrides": {
"fonts": {
"display": "Plus Jakarta Sans",
"body": "Nunito Sans",
"mono": "Fira Code"
}
}
}

Families are fetched from Google Fonts automatically. When one family serves two roles, it appears once in the request with the weights unioned.

For more control, pass an object:

json
{
"themeOverrides": {
"fonts": {
"display": {
"family": "Bricolage Grotesque",
"weights": [500, 600],
"fallback": "Inter, system-ui, sans-serif"
}
}
}
}

Load only the weights you use — each extra weight is bytes on the wire. If a named style needs a weight the family does not load, the browser synthesizes it and the result looks subtly wrong.

To self-host a face, set webfont: "self-hosted" (or "system" for a family the reader's device already has) so no Google Fonts request is made for it. On doc engine v2, appearance.fonts loads any Google Fonts family by name, and only the three families in use are fetched.

Named text styles

Each style carries family role, weight, size, line-height and letter-spacing. size and letterSpacing are px. lineHeight is px when greater than 4, a unitless multiplier at 4 or below, or "normal".

The multiplier form matters for inheritance, not just notation. A unitless line-height is recomputed from each element's own font size, while a px value is inherited as-is — so a px line-height on body copy also sets the leading of tables, cards and code inside it. Figma reports px; hand-written CSS usually means a multiplier.

json
{
"themeOverrides": {
"typography": {
"display-h1": { "size": 34, "lineHeight": 42, "letterSpacing": -1.5, "weight": 600 },
"nav-section": { "size": 11, "letterSpacing": 0.77 }
}
}
}
Warning

Letter-spacing from Figma needs converting. Figma lets a text style express letter-spacing in either pixels or percent, but its API reports the bare number with the unit stripped — a style set to 7% and a style set to 7px both come across as 7.

Copied straight into letterSpacing, a percent value lands as pixels. On small text the result is dramatic: 7 on an 11px label is 64% tracking, roughly double the intended width, and it looks like a rendering fault rather than a mis-transcribed number.

Check the unit in Figma's type panel before copying. Where it reads percent, convert it: letterSpacing = size x percent / 100. An 11px label at 7% is 0.77.

Available styles: display-h1, heading-h2, heading-h3, heading-h4, body-lg, body-md, body-sm, label-md, label-sm, strong-sm, strong-md, code-md, code-sm, caption, eyebrow, nav-item, nav-section, mono-label, card-title.

The API-reference scale

API reference pages carry more structure per screen than a guide, so they can run a denser type scale. Set it with apiTypography, which takes the same style names and applies scoped to that surface only — guide pages keep the base scale.

json
{
"themeOverrides": {
"apiTypography": {
"display-h1": { "size": 32, "lineHeight": 38 },
"body-md": { "size": 15, "lineHeight": 27 }
}
}
}

A partial patch inherits everything it does not restate from the base scale, so overriding just size keeps the family, weight and tracking. Sites that want one scale everywhere simply omit the block.

Add your logo for light and dark modes:

json
{
"logo": {
"light": "/logo-light.svg",
"dark": "/logo-dark.svg"
}
}

Place logo files in your public/ directory. On doc engine v2 sites the header, menu and footer show the dark logo in dark mode.

For a single logo that works on both backgrounds:

json
{
"logo": "/logo.svg"
}

Favicon

json
{
"favicon": "/favicon.ico"
}

Every page links it, on doc engine v1 and v2. Only a single URL is used — an object of sizes is accepted but ignored.

Code Theme

Syntax colours come from the theme's syntax-* tokens:

json
{
"themeOverrides": {
"colors": {
"light": {
"syntax-keyword": "#c792ea",
"syntax-string": "#9ece6a",
"syntax-key": "#7dd3c0",
"syntax-number": "#ffb86c",
"syntax-punct": "#8a93a6",
"syntax-comment": "#5f6a7d",
"syntax-text": "#cbd5e1"
},
"dark": { "syntax-keyword": "#c792ea" }
}
}
}

bg-code and bg-code-header set the code surface itself, and content-code sets inline code. A theme may keep code surfaces dark in both modes — the gravv theme (v1) does.

Warning

The codeTheme key is accepted but has no effect. Code colours are fixed when your site is built, so custom CSS can't change them afterwards — set them with the syntax-* tokens above instead.

Custom CSS

customCSS in syntext.json is accepted but not applied by hosted builds. Put your CSS in _syntext/*.css in your docs folder — up to 50 KB, loaded after the theme on every page — see Custom code from your docs. Pasted CSS still works under Integrations › Custom code › Override (advanced) (Starter plan and up) and applies last; saving it redeploys the site.

On doc engine v2 sites, style with the supported --stx-* variables and data-stx hooks — page and header backgrounds (gradients included), colours, fonts, corners and widths, in light and dark mode. See Custom CSS for the full reference and examples.

Available CSS variables (doc engine v1)

On doc engine v1 sites every token is emitted as a CSS custom property, so your custom CSS can reference the resolved theme instead of hardcoding values. Doc engine v2 pages don't use these names — see Coming from doc engine v1. Colours are emitted twice — once on :root for light mode and once under [data-theme="dark"].

css
/* Colours — content */
--color-content-primary --color-content-secondary --color-content-muted
--color-content-inverse --color-content-code --color-content-code-inline
/* Colours — surfaces */
--color-bg-page --color-bg-sidebar --color-bg-subtle --color-bg-raised
--color-bg-header --color-bg-code --color-bg-code-header
--color-bg-code-inline
/* Colours — lines */
--color-border --color-border-subtle --color-border-code
/* Colours — accent */
--color-accent --color-accent-hover --color-accent-subtle
--color-accent-strong --color-accent-muted --color-on-accent
--color-accent-fill
/* Colours — status */
--color-status-success --color-status-success-bg
--color-status-warning --color-status-warning-bg --color-status-warning-text
--color-status-error --color-status-info --color-status-info-bg
--color-status-info-text
/* Colours — call to action and hero card (inverted surfaces, so they cannot be
derived from the page background) */
--color-cta-bg --color-cta-fg
--color-hero-card-bg --color-hero-card-fg
/* Colours — API parameter fields */
--color-param-name --color-param-required --color-param-required-bg
--color-param-type
/* Colours — HTTP methods (foreground + badge background) */
--color-method-get --color-method-get-bg --color-method-post
--color-method-post-bg --color-method-put --color-method-put-bg
--color-method-patch --color-method-patch-bg --color-method-delete
--color-method-delete-bg --color-method-neutral --color-method-neutral-bg
/* Colours — syntax (also drives the highlighter) */
--color-syntax-text --color-syntax-keyword --color-syntax-string
--color-syntax-key --color-syntax-number --color-syntax-punct
--color-syntax-comment --color-syntax-inserted --color-syntax-deleted
/* Colours — chrome */
--color-scrollbar
/* Fonts */
--font-display --font-body --font-mono
/* Type styles: a CSS `font:` shorthand, plus tracking (which the
shorthand cannot express) */
--type-display-h1 --tracking-display-h1
--type-heading-h2 --tracking-heading-h2
--type-body-md --tracking-body-md
/* …one pair per named text style */
/* Radii and elevation */
--radius-sm --radius-md --radius-lg --radius-xl --radius-full
--shadow-sm --shadow-md --shadow-lg

Use them like any custom property:

css
.my-callout {
background: var(--color-accent-subtle);
border: 1px solid var(--color-border);
border-radius: var(--radius-md);
font: var(--type-body-md);
letter-spacing: var(--tracking-body-md);
}
Info

Older variable names (--primary, --bg, --text, --border, --font-sans) are still emitted as aliases onto the tokens above, so existing custom CSS keeps working. Prefer the --color-* names for anything new.

Custom JavaScript

scripts and customJS in syntext.json are accepted but not applied by hosted builds. Put analytics and other head tags in _syntext/head.html and scripts in _syntext/*.js, then have a workspace admin turn on Head tags from your docs and Scripts from your docs under Integrations › Custom code — see Custom code from your docs. Pasted snippets still work under Override (advanced) (Starter plan and up): up to 10 Head snippets and 10 Body snippets, 10 KB each, each with a name and an Active switch. Saving them redeploys the site.

Top Banner

Display announcements or promotional banners:

json
{
"banner": {
"text": "📢 Version 2.0 is here!",
"link": "/changelog/v2",
"dismissible": true
}
}

On doc engine v1, every page ends with a full-width footer band. By default it shows your social links and a "Powered by Syntext" credit, which links to the Syntext dashboard at app.syntext.dev. Add footer.columns for a rich footer with your logo and grouped link columns. On doc engine v2 the footer appears only when footer.columns has entries — your logo, GitHub, X and LinkedIn icons, a copyright line and a "Built with Syntext" link:

json
{
"footer": {
"columns": [
{
"title": "Product",
"links": [
{ "label": "Documentation", "url": "/guides/quickstart" },
{ "label": "Status", "url": "https://status.example.com" }
]
},
{
"title": "Legal",
"links": [
{ "label": "Terms", "url": "https://example.com/terms" },
{ "label": "Privacy", "url": "https://example.com/privacy" }
]
}
]
}
}

Relative URLs stay on your doc site; on v1, absolute URLs open in a new tab. See the footer reference for details.

Add social links. On doc engine v1 they appear at the top of the sidebar and in the footer. On doc engine v2, GitHub, X and LinkedIn appear as footer icons when the footer has columns.

json
{
"socialLinks": [
{ "platform": "GitHub", "url": "https://github.com/yourorg" },
{ "platform": "X", "url": "https://x.com/yourhandle" },
{ "platform": "Discord", "url": "https://discord.gg/your-server" }
]
}

Platforms with icons on v1: GitHub, X, Discord, LinkedIn, YouTube, Slack. v2 shows GitHub, X (or Twitter) and LinkedIn.

Was this page helpful? Yes No
Product
Resources
Company
© 2026 SyntextBuilt with Syntext