Configure Theme

Apply the TailNG design token layer, override CSS variables to match your brand, set up dark mode, and wire tokens into Tailwind utility classes.

Getting Started

Configure Theme

Apply and customize the TailNG theme using CSS variables, dark mode, and Tailwind integration.

Create a custom theme Build a brand-specific token set from scratch — define your own color scales, radius, shadow, and typography variables, then export the finished theme for use across your Angular workspace.

1. Import the theme stylesheet

@tailng-ui/theme ships a ready-to-use CSS file that declares all semantic tokens as CSS custom properties. Import it once — either in your global stylesheet or via angular.json.

/* styles.css */
@import '@tailng-ui/theme/css';

// angular.json
"styles": [
  "node_modules/@tailng-ui/theme/css/index.css",
  "src/styles.css"
]

2. Semantic CSS token reference

Every visual property — color, spacing scale, radius, shadow — is expressed as a CSS custom property under the --tng-semantic-* namespace. Components read these at runtime, so a single variable change ripples across your entire app automatically.

/* Example semantic tokens exposed by @tailng-ui/theme */
:root {
  /* Brand / accent */
  --tng-semantic-accent-brand:          #6366f1;
  --tng-semantic-accent-brand-hover:    #4f46e5;

  /* Foreground */
  --tng-semantic-foreground-primary:    #0f172a;
  --tng-semantic-foreground-secondary:  #64748b;
  --tng-semantic-foreground-disabled:   #94a3b8;

  /* Background */
  --tng-semantic-background-surface:    #ffffff;
  --tng-semantic-background-subtle:     #f8fafc;

  /* Border */
  --tng-semantic-border-default:        #e2e8f0;
  --tng-semantic-border-subtle:         #f1f5f9;

  /* Feedback */
  --tng-semantic-feedback-error:        #ef4444;
  --tng-semantic-feedback-success:      #22c55e;
  --tng-semantic-feedback-warning:      #f59e0b;
  --tng-semantic-feedback-info:         #3b82f6;

  /* Focus */
  --tng-semantic-focus-ring:            #6366f1;
}

The full token list ships inside the package at node_modules/@tailng-ui/theme/css/index.css.

3. Dark mode

The theme bundle ships both light and dark token sets. Choose a strategy that fits your app.

Strategy A — automatic via prefers-color-scheme

Dark tokens activate automatically when the OS is in dark mode. No extra configuration. Importing the theme stylesheet is all you need.

/* styles.css – media strategy (automatic) */
@import '@tailng-ui/theme/css';
/* Dark tokens are applied via @media (prefers-color-scheme: dark)
   inside the theme bundle – nothing extra required. */

Strategy B — class-based toggle

Add the dark class to <html> to force dark mode regardless of OS preference.

<!-- index.html – class strategy -->
<html class="dark">
  ...
</html>

// app.component.ts
import { Component, inject, signal } from '@angular/core';
import { DOCUMENT } from '@angular/common';

@Component({ selector: 'app-root', template: `
  <button (click)="toggleDark()">Toggle dark mode</button>
` })
export class AppComponent {
  private readonly doc = inject(DOCUMENT);
  readonly isDark = signal(false);

  toggleDark(): void {
    this.isDark.update((v) => !v);
    this.doc.documentElement.classList.toggle('dark', this.isDark());
  }
}

4. Customizing tokens

Override any token after the import statement. The cascade ensures your values take precedence over the defaults. Define matching overrides inside .dark { } for the dark-mode variant.

/* styles.css – override any token after importing the theme */
@import '@tailng-ui/theme/css';

:root {
  /* Swap brand accent to teal */
  --tng-semantic-accent-brand:       #0d9488;
  --tng-semantic-accent-brand-hover: #0f766e;
  --tng-semantic-focus-ring:         #0d9488;
}

.dark {
  --tng-semantic-accent-brand:       #2dd4bf;
  --tng-semantic-accent-brand-hover: #5eead4;
}

5. Tailwind integration

Map TailNG CSS variables to Tailwind utility classes by extending the theme.colors config. You can then write bg-tng-brand or text-tng-fg-secondary anywhere in your templates, and the colors will automatically update when you swap tokens.

// tailwind.config.ts
import type { Config } from 'tailwindcss';

export default {
  content: ['./src/**/*.{html,ts}'],
  darkMode: 'class',
  theme: {
    extend: {
      colors: {
        tng: {
          brand:      'var(--tng-semantic-accent-brand)',
          'brand-hover': 'var(--tng-semantic-accent-brand-hover)',
          'fg-primary':   'var(--tng-semantic-foreground-primary)',
          'fg-secondary': 'var(--tng-semantic-foreground-secondary)',
          'bg-surface':   'var(--tng-semantic-background-surface)',
          'bg-subtle':    'var(--tng-semantic-background-subtle)',
          'border':       'var(--tng-semantic-border-default)',
        },
      },
    },
  },
} satisfies Config;

<!-- Use TailNG tokens as Tailwind utility classes -->
<button class="bg-tng-brand hover:bg-tng-brand-hover text-white rounded px-4 py-2">
  Save changes
</button>

6. Runtime theme provider (optional)

For fine-grained runtime control — such as persisting the user's color scheme preference or reading the current scheme in components — register provideTheme() in your main.ts. Accepted values for colorScheme are 'light', 'dark', or 'system'.

// main.ts
import { bootstrapApplication } from '@angular/platform-browser';
import { provideTheme } from '@tailng-ui/theme';
import { AppComponent } from './app/app.component';

bootstrapApplication(AppComponent, {
  providers: [
    provideTheme({ colorScheme: 'system' }), // 'light' | 'dark' | 'system'
  ],
});