Authoring Guide
Design System & Configuration
Semantic colours, where colour props apply, typography, and the config files that control branding, navigation and theming.
The look of the site comes from a small set of semantic colour tokens and a few config files. Knowing these lets you brand a build and theme any component consistently.
Semantic colours
Components take a color describing intent, not a literal hue — so a theme change recolours
everything at once.
| Token | Default | Use for |
|---|---|---|
primary | green | main CTAs, active nav, brand |
secondary | blue | complementary actions |
success | green | positive / completed states |
info | blue | informational notices |
warning | yellow | attention needed |
error | red | errors, destructive actions |
neutral | slate | text, borders, backgrounds |
primary secondary success info warning error neutral
:u-badge[primary]{color="primary"} :u-badge[secondary]{color="secondary"} :u-badge[success]{color="success"} :u-badge[info]{color="info"} :u-badge[warning]{color="warning"} :u-badge[error]{color="error"} :u-badge[neutral]{color="neutral"}
Where the color prop applies
::callout, ::card, :u-badge, :u-button and most Nuxt UI components accept these
tokens:
An info-coloured callout.
A success-coloured callout.
::callout{icon="i-lucide-info" color="info"}
An info-coloured callout.
::
::callout{icon="i-lucide-check" color="success"}
A success-coloured callout.
::
Typography
Body and code fonts are driven by the --font-sans and --font-mono CSS variables, and
prose spacing/sizing comes from the theme. Override them in CSS with Tailwind's @theme
block; colour shades (50–950) are customised the same way.
@theme {
--font-sans: 'Inter', sans-serif;
--font-mono: 'JetBrains Mono', monospace;
}
The config files
app/app.config.ts
defineAppConfig
Runtime UI:
header.logo, ui.colors (map a token to a Tailwind colour), ui.page (the
nav/content column widths), keyboard shortcuts. Hot-reloads, no rebuild.nuxt.config.ts
defineNuxtConfig
Build-time wiring:
DOCS_TARGET branding/gating, routeRules, Studio, content highlight
languages, prerender seeding.content.config.ts
defineContentConfig
Which content tiers ship for the active
DOCS_TARGET, and the collection schema (custom
frontmatter fields you want to query)..navigation.yml
per-folder
Section
title and icon in the sidebar. One per content folder.Branding a build
DOCS_TARGET (public | cloud | internal) selects the audience tier, gating and
branding at build time. Per-page metadata lives in frontmatter:
title
string required
<h1>, tab title, breadcrumb, search entry.description
string
Sub-title and SEO/social description.
navigation
boolean | object
false hides the page; an object overrides its icon/title.seo
object
Optional
title/description overrides for SEO only.Numeric filename prefixes (
1., 2.…) set order and are stripped from the URL. The tier
folder (1.public/2.cloud/3.internal) is stripped on single-tier builds and becomes
the first URL segment on the internal build.