Theme

Docd's visual system is built from three layers:

• UI Thing for the component primitives and UI building blocks
• Tailwind CSS v4 for utilities, tokens, and layout styling
• CSS variables for colors, radius, surfaces, and theme switching

That combination gives you both a usable default theme and a clean path for customization.

The stack Docd uses

Docd is not themed through a large runtime theme object. Instead, the layer leans on:

• reusable UI Thing components in packages/docd/app/components/Ui
• Tailwind CSS v4 utilities in packages/docd/app/assets/css/tailwind.css
• theme tokens and named palettes in packages/docd/app/assets/css/theme.css

If you want to change the look of a Docd site, that is where you should start.

Tailwind CSS in Docd

Docd uses Tailwind CSS directly in the layer stylesheet.

That includes:

• @theme for design tokens
• @theme inline for mapping CSS variables to Tailwind tokens
• custom utilities such as container
• custom variants such as dark
• Tailwind utility composition in component classes

For example, the layer stylesheet defines tokens like:

packages/docd/app/assets/css/tailwind.css

@theme inline {
  --color-background: var(--background);
  --color-foreground: var(--foreground);
  --color-primary: var(--primary);
  --color-border: var(--border);
  --font-sans: "Geist", ui-sans-serif, system-ui, sans-serif;
  --font-mono: "Geist Mono", ui-monospace, monospace;
}

That means most visual changes ultimately flow through CSS variables and Tailwind tokens, not through ad hoc component overrides everywhere.

CSS variable themes

The theme.css file defines the default theme tokens and a set of named theme classes such as:

• .theme-zinc
• .theme-stone
• .theme-neutral
• .theme-gray
• .theme-slate
• .theme-red
• .theme-rose
• .theme-orange
• .theme-green
• .theme-blue
• .theme-yellow
• .theme-violet
• .theme-nuxt

Each theme class defines values for tokens such as:

• --background
• --foreground
• --primary
• --secondary
• --muted
• --border
• --sidebar
• --radius

Docd then maps those variables into Tailwind token names through @theme inline.

Light and dark mode

Docd supports both light and dark mode, and the active tokens change under the .dark class.

You can:

• let users toggle color mode normally
• force one color mode through app/app.config.ts
• switch themes visually with the built-in theme customizer in the docs app

To force a mode:

app/app.config.ts

export default defineAppConfig({
  docd: {
    ui: {
      colorMode: "dark",
    },
  },
});

Supported values are:

• "light"
• "dark"

The built-in theme customizer

The docs app includes a theme customizer component that lets users adjust:

• the active named color theme
• the border radius token
• light or dark mode

This is useful for exploring the design space of the layer, but the actual source of truth is still the CSS variable theme system underneath.

UI Thing components

Docd uses UI Thing for the UI component layer rather than documenting a separate theme API for every primitive.

That means a lot of the visual feel comes from:

• the CSS tokens available to the components
• Tailwind utility classes applied in the layer's Vue files
• local component styling decisions in app/components/Ui and docs-specific wrappers

Docd uses UI Thing as the component base, then applies Docd-specific layout, prose, and docs styling on top.

What to customize first

If you want to rebrand a Docd site, the most effective order is:

1. Change the site title and logo in app/app.config.ts
2. Override CSS variables for your palette and surfaces
3. Adjust radius and spacing tokens
4. Tweak component classes only after the tokens are in a good place

This keeps your theme coherent and avoids one-off component overrides fighting the system.

Overriding the theme in your own site

In a consuming Docd project, a practical approach is to add your own CSS entry and override the tokens there.

For example:

app/assets/css/theme.css

:root {
  --background: oklch(0.99 0.01 95);
  --foreground: oklch(0.18 0.02 260);
  --primary: oklch(0.62 0.18 250);
  --primary-foreground: oklch(0.98 0.01 255);
  --border: oklch(0.9 0.01 260);
  --radius: 0.75rem;
}

.dark {
  --background: oklch(0.16 0.02 260);
  --foreground: oklch(0.96 0.01 255);
  --primary: oklch(0.75 0.16 250);
  --primary-foreground: oklch(0.14 0.02 260);
}

Then include it from your app:

Nuxt Config

export default defineNuxtConfig({
  extends: ["@baybreezy/docd"],
  css: ["~/app/assets/css/theme.css"],
});

You may also want to take a look at tweakcn for generating custom themes.

Changing typography

Docd maps typography through theme tokens as well.

The layer currently defines:

• --font-sans
• --font-mono

You can override those tokens in your own CSS if you want a different typographic voice.

App Assets Css Theme

@theme inline {
  --font-sans: "Satoshi", ui-sans-serif, system-ui, sans-serif;
  --font-mono: "JetBrains Mono", ui-monospace, monospace;
}

Changing the feel of the UI

Some of the strongest visual changes in Docd come from a small number of decisions:

• color palette
• radius
• border style
• typography
• page transition style

You do not need to rewrite every component to make the site feel different.

For example, a sharper, more editorial look might use:

• borderType: "solid"
• a lower --radius
• stronger foreground contrast
• a more distinctive display font

While a softer product-docs look might use:

• borderType: "dashed"
• a larger radius
• lower-contrast neutrals
• gentler motion presets

Theme vs configuration

A good rule is:

• use CSS variables and Tailwind tokens for visual identity
• use docd.ui config for structural UI options
• use component overrides only when tokens are not enough

That keeps the theme system simple and makes your Docd site easier to maintain over time.