Theming System

Configure light and dark themes for published sites. The theming system provides consistent styling across all viewer components with automatic persistence and CSS variable support.

February 5, 2026

Published NeoArc sites include a full theming system with light and dark modes. The theme affects all viewer components including pages, diagrams, code blocks, and API documentation. User preference persists across sessions.

Theme Modes

Light Mode

White backgrounds, dark text, optimised for daytime use and printing

Dark Mode

Dark backgrounds, light text, optimised for low-light environments and reduced eye strain

User Controls

Readers can toggle the theme using:

Theme Persistence

Theme selection persists in the browser's localStorage:

Storage	Key	Values
localStorage	neoarc-theme	"light" or "dark"
Initial value	(none)	Uses system preference
After toggle	Stored preference	Overrides system preference

Color Palette

Each theme defines a complete colour palette for consistent styling across components.

Background Colors

Token	Light	Dark	Usage
bgPrimary	#FFFFFF	#1a1a1a	Main content background
bgSecondary	#F5F5F5	#2d2d2d	Secondary panels, cards
bgTertiary	#EEEEEE	#3d3d3d	Tertiary backgrounds

Text Colors

Token	Light	Dark	Usage
textPrimary	#1a1a1a	#FFFFFF	Main text
textSecondary	#666666	#A0A0A0	Secondary text, captions
textTertiary	#999999	#707070	Muted text, placeholders

Component Colors

Component	Color Tokens
Top Bar	topBarBg, topBarText, topBarHover
Sidebar	sidebarBg, sidebarItemHover, sidebarItemActive
Code Blocks	codeBg, codeText
Diagrams	diagramBg, diagramBorder
Borders	borderPrimary, borderSecondary

HTTP Method Badge Colors

REST API documentation uses method-specific colours:

Method	Light Background	Dark Background
GET	#dcfce7 (green)	#166534
POST	#dbeafe (blue)	#1e40af
PUT	#fef3c7 (yellow)	#92400e
PATCH	#fef3c7 (yellow)	#92400e
DELETE	#fee2e2 (red)	#991b1b

Status Code Colors

HTTP status codes are colour-coded:

Range	Light Background	Meaning
2xx	Green	Success responses
3xx	Blue	Redirect responses
4xx	Yellow/Orange	Client errors
5xx	Red	Server errors

CSS Custom Properties

Theme colours are exposed as CSS custom properties for custom styling:

/* Example: Using theme variables in custom CSS */
.my-custom-component {
  background-color: var(--bg-secondary);
  color: var(--text-primary);
  border: 1px solid var(--border-primary);
}

.my-custom-component:hover {
  background-color: var(--hover-bg);
}

ThemeService API

The theme service provides programmatic access for custom components:

import { themeService } from './services/theme';

// Get current mode
const mode = themeService.getCurrentMode(); // 'light' or 'dark'

// Get current color palette
const colors = themeService.getCurrentColors();
console.log(colors.bgPrimary, colors.textPrimary);

// Toggle theme
themeService.toggle();

// Set specific mode
themeService.setMode('dark');

// Subscribe to changes
themeService.subscribe((mode, colors) => {
  console.log('Theme changed to:', mode);
});

Diagram Theme Integration

Embedded diagrams automatically respect the current theme:

WCAG Compliance

Theme colours are designed for WCAG AA contrast compliance:

Requirement	Standard	Status
Normal text contrast	4.5:1 minimum	Compliant
Large text contrast	3:1 minimum	Compliant
Interactive element focus	Visible focus indicators	Compliant
Colour not sole indicator	Text/icons supplement colour	Compliant