Design tokens

What a token changes

NeuTokens exposes 28 theme properties. NeuThemeComponent also derives 45 CSS variables from the resolved theme. The properties and variables are two ways to consume the same design decisions, not independent token catalogs. Use Partial<NeuTokens> to override only the properties you need.

Tokens affect the components and styles that consume them. They are not a universal override of every native primitive. For example, spacing controls Card padding and your own styles that use --neu-spacing; it does not replace all fixed gaps and padding throughout the library.

Color tokens: exact default values

All color properties are strings. These are the light and dark defaults shipped with Neural Native 0.1.0. Override semantic pairs together and review text contrast in both modes.

Style variables use the --neu- prefix: --neu-accent, --neu-surface, --neu-canvas, --neu-text, --neu-muted, --neu-border, --neu-tonal, --neu-danger, --neu-success, --neu-info and --neu-warning. The camel-case onAccent property becomes --neu-on-accent.

Semantic text, surfaces and image viewers

These optional NeuTokens properties are also part of the public theme API. The default objects supply surface and image-viewer values. When a semantic text override is omitted, the library resolves a readable text color for that tone.

Dimensions, typography and motion

These four properties are numbers. Pass radius: 16, not radius: "16px". Native layout resolves px according to the framework’s layout units; do not treat them as raw physical screen pixels.

The theme derives caption, label, row, heading and metric sizes and line heights from fontSize; components consume those variables where supported. It does not select a font family or replace every fixed size. Check system text scaling. The duration token does not disable every animation: reduced motion also depends on the component and framework.

Complete theme CSS reference

The following variables are generated on neu-theme. Use them in your native styles to share its palette and scale. To change the theme consistently, pass the corresponding NeuTokens properties through [tokens]; a local CSS override does not update the injected NEU_THEME value or components that compute their colors from it.

For numeric variables, the source column shows the multiplier and output unit. Radii, sizes, line heights and spaces use px; duration uses ms. Semantic text variables can be computed from the theme rather than copied directly from an accent color.

Keep custom tokens in one typed file

Create src/app/theme-tokens.ts and export the overrides used by the root theme. The satisfies operator checks property names and types while preserving TypeScript inference. This example keeps control text, decorative surfaces and the full-screen image canvas separate.

import type { NeuTokens } from '@neural-ui/native/foundation';

export const brandLight = {
  accent: '#3B5BDB',
  accentText: '#3048A5',
  onAccent: '#FFFFFF',
  tonal: '#EBEFFF',
  surfaceBorder: '#D8DEEB',
  divider: '#E8ECF3',
  surfaceSecondary: '#F0F3FA',
  mediaCanvas: '#101828',
  mediaText: '#F1F5F9',
  mediaBarStyle: 'light',
  radius: 16,
} satisfies Partial<NeuTokens>;

export const brandDark = {
  accent: '#B8C6FF',
  accentText: '#C6D0FF',
  onAccent: '#172955',
  tonal: '#293756',
  surfaceBorder: '#3B4863',
  divider: '#33405A',
  surfaceSecondary: '#263249',
  mediaCanvas: '#101828',
  mediaText: '#F1F5F9',
  mediaBarStyle: 'light',
  radius: 16,
} satisfies Partial<NeuTokens>;

The four optional semantic text colors are explicit overrides: when supplied, they are used as given. Check their contrast against your surfaces. The mediaBarStyle values are light and dark on both languages; they describe the foreground of system bars, not the application theme.

For a complete palette, spread the exported default instead of mutating it. The defaults are readonly frozen objects. The following src/app/complete-tokens.ts is an alternative to the partial objects above, useful when a service needs a full NeuTokens value.

import {
  NEU_LIGHT_TOKENS,
  NEU_DARK_TOKENS,
  type NeuTokens,
} from '@neural-ui/native/foundation';

export const completeLight: Readonly<NeuTokens> = {
  ...NEU_LIGHT_TOKENS,
  accent: '#3B5BDB',
  onAccent: '#FFFFFF',
};

export const completeDark: Readonly<NeuTokens> = {
  ...NEU_DARK_TOKENS,
  accent: '#B8C6FF',
  onAccent: '#172955',
};

Use tokens in your own native components

Create src/app/summary.component.ts and place app-summary inside the root neu-theme. The --neu-* variables let native styles share the palette. For properties computed in TypeScript or style bindings, inject NEU_THEME and read its signal. A computed value follows theme changes without caching an outdated snapshot.

import { Component, computed, inject } from '@angular/core';
import { Text, View } from '@ng-native/components';
import { NEU_THEME } from '@neural-ui/native/foundation';

@Component({
  selector: 'app-summary',
  imports: [Text, View],
  template: `
    <view class="panel" [style.borderColor]="borderColor()">
      <text class="title">Your workspace</text>
      <text class="description">Shared with your team</text>
    </view>
  `,
  styles: `
    .panel {
      padding: var(--neu-space-20);
      gap: var(--neu-space-8);
      background-color: var(--neu-surface);
      border-width: 1px;
      border-radius: var(--neu-surface-radius);
    }
    .title { color: var(--neu-text); font-size: var(--neu-heading-size); line-height: var(--neu-heading-line); font-weight: 600; }
    .description { color: var(--neu-muted); font-size: var(--neu-caption-size); line-height: var(--neu-caption-line); }
  `,
})
export class SummaryComponent {
  private readonly theme = inject(NEU_THEME);
  readonly borderColor = computed(() => this.theme().surfaceBorder ?? this.theme().border);
}

This example requires a theme ancestor because it injects NEU_THEME directly. Keep native token styles inside the native application or playground. The documentation shell uses Neural UI v2 and has its own web theme; do not apply its web styles to the Native preview.