Skip to content
compodocx
Skip to article content

Guide 09

Themes

cngxjs (opens in new tab) Updated Guide 09 of 13

Eight themes ship in the box. A theme is a CSS file that overrides any subset of the --color-cdx-* design tokens. About 101 tokens total, grouped by purpose. Unspecified tokens fall back to the default theme.

Bundled themes

  • Slate Noir

    --theme default

    Pure neutral greys. The opinion-free default.

  • Ocean

    --theme ocean

    Deep teal, cool surfaces, soft tension borders.

  • Midnight

    --theme midnight

    Indigo night, low contrast, focus-friendly.

  • Nord

    --theme nord

    Arctic palette, frost blue, calm primary.

  • Rose Pine

    --theme rose-pine

    Warm rose, muted greens, golden accents.

  • Ember

    --theme ember

    Warm amber on ember-grey, low-glare reading.

  • Neon

    --theme neon

    High-contrast electric primary on dark slate.

  • Brutalist

    --theme brutalist

    Hard edges, raw concrete, maximum legibility.

Each theme picks a Shiki light/dark pair to match. Ocean uses github-light / github-dark, Midnight uses tokyo-night, Neon uses synthwave-84, and so on.

Switching themes

bash 
# A bundled theme
--theme ocean

# Or your own CSS file
--theme ./my-brand.css

Custom logo & favicon

Branding the docs goes beyond colors. Pass a logo and a favicon via CLI flags or the JSON config. SVG works for the logo (it scales crisply in the topbar); a multi-size ICO or 32×32 PNG works for the favicon.

bash 
compodocx -p tsconfig.doc.json \
  --theme ./my-brand.css \
  --customLogo ./brand/logo.svg \
  --customFavicon ./brand/favicon.ico

Or pin all three in the JSON config so the team runs the same brand on every build:

json compodocx.json 
{
  "tsconfig": "tsconfig.doc.json",
  "theme": "./my-brand.css",
  "customLogo": "./brand/logo.svg",
  "customFavicon": "./brand/favicon.ico"
}

Paths are resolved relative to the project root (the directory containing the package.json). Drop the asset under ./brand/ or wherever your assets live; compodocx copies it into the static output.

Author a custom theme

Start from the theme template (opens in new tab). Every token below is commented out so you uncomment exactly what you want to override. Both :root (light) and .dark blocks are supported. Omit .dark to use the same values in both modes.

css my-brand.css 
:root {
  --color-cdx-bg:      hsl(220 20% 96%);
  --color-cdx-text:    hsl(220 30% 12%);
  --color-cdx-primary: hsl(220 70% 40%);
}

.dark {
  --color-cdx-bg:      hsl(220 25% 8%);
  --color-cdx-text:    hsl(220 15% 92%);
  --color-cdx-primary: hsl(220 80% 65%);
}

Note for radii, fonts, and transitions: override the Tailwind alias tokens marked /* [TW] */ too. Otherwise @apply-generated utility classes don't pick up your values. Color tokens don't need aliases.

All available tokens

Every token compodocx exposes, grouped by purpose. Click a section to expand. Defaults shown are the light-mode values from the upstream template (opens in new tab).

  • Surface hierarchy 5 tokens

    Page, sidebar, cards, inline-code, fenced-code-block. The full vertical stack of background layers.

    css 
    --color-cdx-bg:            hsl(220 16% 98%);
--color-cdx-bg-alt:        hsl(220 16% 96%);
--color-cdx-bg-elevated:   hsl(0 0% 100%);
--color-cdx-bg-code:       hsl(220 16% 95%);
--color-cdx-bg-code-block: hsl(225 16% 16%);
  • Text hierarchy 4 tokens

    Body, secondary, muted, and inverse. Match contrast carefully against the surfaces.

    css 
    --color-cdx-text:           hsl(220 20% 14%);
--color-cdx-text-secondary: hsl(220 12% 44%);
--color-cdx-text-muted:     hsl(220 10% 45%);
--color-cdx-text-inverse:   hsl(220 16% 96%);
  • Primary accent 3 tokens

    Brand color, hover variant, and a subtle tint for backgrounds and rings.

    css 
    --color-cdx-primary:        hsl(222 68% 52%);
--color-cdx-primary-hover:  hsl(222 68% 44%);
--color-cdx-primary-subtle: hsl(222 68% 96%);
  • Entity-type accents 13 tokens

    One color per entity kind. Used for sidebar dots, type chips, and dependency-graph nodes.

    css 
    --color-cdx-entity-component:   #0e8578;
--color-cdx-entity-service:     #a56a07;
--color-cdx-entity-directive:   #7c3aed;
--color-cdx-entity-pipe:        #e2177b;
--color-cdx-entity-module:      #1e6ff5;
--color-cdx-entity-class:       #05875f;
--color-cdx-entity-interface:   #475569;
--color-cdx-entity-guard:       #eb1515;
--color-cdx-entity-interceptor: #ba25cd;
--color-cdx-entity-function:    #52840b;
--color-cdx-entity-variable:    #617087;
--color-cdx-entity-typealias:   #6164f1;
--color-cdx-entity-enum:        #c2410c;
  • Badge base colors 21 tokens

    Each badge derives text, border, and background from one base color via color-mix(). Override the base only.

    css 
    --color-cdx-badge-standalone:          hsl(170 55% 38%);
--color-cdx-badge-token:               hsl(260 50% 48%);
--color-cdx-badge-beta:                hsl(35 75% 42%);
--color-cdx-badge-factory:             hsl(200 50% 42%);
--color-cdx-badge-zoneless:            hsl(280 45% 48%);
--color-cdx-badge-breaking:            hsl(0 65% 45%);
--color-cdx-badge-signal:              hsl(210 60% 42%);
--color-cdx-badge-computed:            hsl(270 50% 45%);
--color-cdx-badge-effect:              hsl(45 70% 40%);
--color-cdx-badge-resource:            hsl(190 55% 38%);
--color-cdx-badge-model:               hsl(240 45% 45%);
--color-cdx-badge-after-render:        hsl(25 65% 40%);
--color-cdx-badge-after-next-render:   hsl(15 65% 42%);
--color-cdx-badge-after-every-render:  hsl(5 60% 42%);
--color-cdx-badge-after-render-effect: hsl(340 55% 42%);
--color-cdx-badge-input:               hsl(145 50% 35%);
--color-cdx-badge-output:              hsl(350 50% 42%);
--color-cdx-badge-view-child:          hsl(165 50% 35%);
--color-cdx-badge-content-child:       hsl(55 60% 35%);
--color-cdx-badge-inject:              hsl(320 45% 45%);
--color-cdx-badge-host:                hsl(180 50% 35%);
  • Modifier base colors 5 tokens

    Visibility and lifecycle modifiers. Same color-mix() derivation as badges.

    css 
    --color-cdx-mod-private:   hsl(0 50% 40%);
--color-cdx-mod-protected: hsl(35 60% 35%);
--color-cdx-mod-readonly:  hsl(210 50% 40%);
--color-cdx-mod-static:    hsl(270 40% 42%);
--color-cdx-mod-async:     hsl(170 45% 32%);
  • Status, overlay, feedback 6 tokens

    Coverage report, deprecation banners, modal backdrops, and the danger color for destructive UI.

    css 
    --color-cdx-status-pass:    #16a34a;
--color-cdx-status-fail:    #ef4444;
--color-cdx-status-warning: #ca8a04;
--color-cdx-overlay:        hsl(220 20% 14% / 0.4);
--color-cdx-deprecated:     hsl(38 92% 32.5%);
--color-cdx-danger:         hsl(0 72% 51%);
  • Borders & shadows 6 tokens

    Three border weights (default, strong, focus) plus the standard shadow ramp for elevated surfaces.

    css 
    --color-cdx-border:        hsl(220 14% 90%);
--color-cdx-border-strong: hsl(220 14% 59%);
--color-cdx-border-focus:  hsl(222 68% 52%);
--shadow-cdx-sm: 0 1px 2px hsl(220 20% 14% / 0.06);
--shadow-cdx-md: 0 4px 12px hsl(220 20% 14% / 0.08);
--shadow-cdx-lg: 0 12px 32px hsl(220 20% 14% / 0.12);
  • Typography 5 tokens

    Heading, body, and code stacks. Tokens marked [TW] are Tailwind aliases needed when you @apply utility classes.

    css 
    --font-heading: "Instrument Sans", system-ui, sans-serif;
--font-body:    "Source Sans 3", system-ui, sans-serif;
--font-code:    ui-monospace, "Cascadia Code", "SF Mono", Menlo, Consolas, monospace;
--font-sans:    "Source Sans 3", system-ui, sans-serif;    /* [TW] */
--font-mono:    ui-monospace, "SF Mono", Menlo, monospace; /* [TW] */
  • Radii 7 tokens

    Three semantic radii plus four Tailwind aliases. Override the [TW] tokens too if you @apply rounded utilities.

    css 
    --radius-cdx-sm: 4px;
--radius-cdx-md: 8px;
--radius-cdx-lg: 12px;
--radius-sm: 4px;   /* [TW] */
--radius-md: 8px;   /* [TW] */
--radius-lg: 12px;  /* [TW] */
--radius-2xl: 12px; /* [TW] */
  • Spacing 7 tokens

    Six general spacing steps plus the sidebar width. Component spacing also uses these.

    css 
    --spacing-cdx-xs:  4px;
--spacing-cdx-sm:  8px;
--spacing-cdx-md:  12px;
--spacing-cdx-lg:  16px;
--spacing-cdx-xl:  20px;
--spacing-cdx-2xl: 24px;
--spacing-cdx-sidebar: 320px;
  • Code blocks 13 tokens

    Fenced code, the source viewer, line numbers, line highlights, copy button, and the language chip in code-snippet headers.

    css 
    --color-cdx-snippet-bg:           hsl(220 14% 96%);
--color-cdx-snippet-border:       transparent;
--color-cdx-snippet-radius:       var(--radius-cdx-md);
--color-cdx-code-inline:          #c2185b;
--color-cdx-code-dark-surface:    hsl(225 16% 14%);
--color-cdx-scrollbar:            hsl(220 10% 50% / 0.4);
--color-cdx-line-number:          hsl(220 10% 50% / 0.5);
--color-cdx-line-hover:           hsl(220 20% 14% / 0.06);
--color-cdx-line-highlight:       hsl(48 96% 53% / 0.25);
--color-cdx-line-highlight-flash: hsl(48 96% 53% / 0.3);
--color-cdx-copy-success:         hsl(142 50% 40%);
--color-cdx-lang-chip:            hsl(220 10% 60%);
--color-cdx-lang-chip-bg:         hsl(220 10% 50% / 0.1);
  • Graphs 4 tokens

    Dependency-graph and DOM-tree chrome. Default to bg-alt + transparent border.

    css 
    --color-cdx-graph-bg:           var(--color-cdx-bg-alt);
--color-cdx-graph-border:       transparent;
--color-cdx-graph-border-width: 0;
--color-cdx-graph-radius:       var(--radius-cdx-md);
  • Transitions 2 tokens

    Two timing tokens used across hovers, focus rings, and disclosure widgets.

    css 
    --cdx-transition-fast: 120ms ease;
--cdx-transition-base: 200ms ease;

Per-component theming tokens

Components can document their own theming surface via JSDoc on the component’s associated SCSS / CSS file: @overview for a description, @type / @default / @group per token, plus @example, @since, @deprecated, and @see. Each component page surfaces a Theming Tokens tab with a grouped catalog and an optional source preview.