Theming

ONE TOKEN PIPELINE

Theme layers

Components never hard-code a product palette. Primitive scales feed semantic colors; semantic colors feed component tokens; consumer classes and local custom properties remain the final override layer.

For the stable reference theme, import Neutral once. It contains the full Core token graph and both color modes.

@import '@neural-ng/core/themes/neutral.css';
@import '@neural-ng/icons/icons.css';

Live primary and surface palettes

Choose a palette to update the complete documentation shell. Primary owns emphasis and interaction; Surface owns canvas, elevation, text and borders. Light and dark modes consume the same immutable scales.

This picker uses the public NeuralAppearanceService. Register the provider once and inject the same Signal API in any application-owned settings panel.

import { provideNeuralAppearance } from '@neural-ng/core/appearance';

export const appConfig = {
  providers: [
    provideNeuralAppearance({
      primary: 'blue',
      surface: 'slate',
      mode: 'system',
      direction: 'auto',
    }),
  ],
};

Primitive scales stay stable

Primary exposes steps 50–950. Surface additionally exposes 0. The values do not reverse in dark mode; semantic aliases select suitable steps for the active mode.

:root {
  --neural-color-primary-50: #eef2ff;
  --neural-color-primary-100: #e0e7ff;
  --neural-color-primary-200: #c7d2fe;
  --neural-color-primary-300: #a5b4fc;
  --neural-color-primary-400: #818cf8;
  --neural-color-primary-500: #6366f1;
  --neural-color-primary-600: #4f46e5;
  --neural-color-primary-700: #4338ca;
  --neural-color-primary-800: #3730a3;
  --neural-color-primary-900: #312e81;
  --neural-color-primary-950: #1e1b4b;
}

Prefer semantic aliases in product CSS

Primitive steps are useful for deliberate palette work. General UI should consume semantic tokens so contrast decisions can change between light and dark without rewriting component CSS.

@neural-ng/theme is a development dependency. A compact JSON recipe expands deterministically into complete Core and Editor CSS, token interchange JSON, diagnostics and generated theme-name types.

npm install --save-dev @neural-ng/theme
npx neural-theme init
npx neural-theme validate
npx neural-theme build

{
  "$schema": "./node_modules/@neural-ng/theme/schema.json",
  "schemaVersion": 1,
  "name": "agent-workspace",
  "extends": "neutral",
  "color": {
    "primary": "violet",
    "surface": "zinc",
    "success": "#16a34a",
    "warning": "#ca8a04",
    "error": "#dc2626"
  },
  "shape": { "radius": "medium", "border": "default" },
  "density": "comfortable",
  "elevation": "soft",
  "motion": "default",
  "modes": { "dark": "auto" }
}

@import 'tailwindcss';
@import '@neural-ng/icons/icons.css';
@import './styles/generated/agent-workspace.css';

Keep overrides sparse and scoped

Use validated recipe properties for system-wide customization. Use a local CSS custom property when one product surface intentionally differs.

{
  "components": {
    "button": {
      "radius": "1rem",
      "primaryBackground": "{color.primary}"
    },
    "toast": {
      "messageRadius": "1rem",
      "progressHeight": "0.25rem"
    }
  }
}

.checkout-actions {
  --neural-button-radius: 999px;
  --neural-button-primary-background: var(--neural-color-primary-700);
}

Unknown components, token names, malformed aliases, declaration injection and external CSS URLs fail theme validation.

Optional Tailwind CSS v4 bridge

The bridge maps NeuralNg primitives to Tailwind's color namespace. Utilities such as bg-primary-500, text-surface-950 and dark:bg-surface-900 then follow the active NeuralNg palette. NeuralNg has no Tailwind runtime dependency.

@import 'tailwindcss';
@import '@neural-ng/core/themes/neutral.css';
@import '@neural-ng/core/themes/tailwind.css';
@import '@neural-ng/icons/icons.css';

@custom-variant dark (
  &:where([data-neural-mode='dark'], [data-neural-mode='dark'] *)
);