Styling

How styling works

Oat CSS uses a layered architecture with @layer — theme tokens come first, then base element styles, then component styles, then utilities. This means you can override any token in your own stylesheet without specificity wars.

ng-oat components render semantic HTML elements that Oat already knows how to style. A <ng-oat-button> renders a real <button>, a <ng-oat-card> renders a <div class="card">, and so on. This means Oat's CSS applies naturally — no shadow DOM, no encapsulation issues.

Design tokens

Oat defines 80+ CSS custom properties (design tokens) that control colors, spacing, typography, borders, and animations globally. All tokens use light-dark() for automatic dark-mode support and clamp() for fluid scaling.

Colors

Spacing (fluid)

Border radius

Typography

Line-height & letter-spacing

Font weight & family

Effects

Overriding tokens globally

The simplest way to customize the look is to override tokens in your styles.css:

/* src/styles.css */
:root {
  --primary: #6366f1;        /* Indigo primary */
  --radius-medium: 12px;     /* Rounder cards */
  --font-bold: 700;          /* Heavier bold weight */
}

Because Oat uses @layer, your overrides in styles.css will always win regardless of source order.

Runtime theming with provideNgOatTheme

For dynamic themes (dark mode toggle, user-selected palettes), use the built-in theme provider:

// app.config.ts
import { provideNgOat, provideNgOatTheme } from '@letsprogram/ng-oat';

export const appConfig: ApplicationConfig = {
  providers: [
    provideNgOat(),
    provideNgOatTheme({
      tokens: {
        '--oat-primary': '#6366f1',
        '--oat-background': '#fafafa',
        '--oat-radius-medium': '12px',
      },
    }),
  ],
};

Then inject NgOatThemeRef to change tokens at runtime:

// any component
import { Component, inject } from '@angular/core';
import { NgOatThemeRef } from '@letsprogram/ng-oat';

@Component({ ... })
export class SettingsPage {
  private theme = inject(NgOatThemeRef);

  switchToOcean() {
    this.theme.setTokens({
      '--oat-primary': '#0ea5e9',
      '--oat-background': '#0f172a',
      '--oat-foreground': '#f8fafc',
    });
  }

  resetTheme() {
    this.theme.reset();
  }
}

Dark mode

Oat CSS has built-in dark mode support via color-scheme. You can toggle it by setting the color-scheme property on the document root:

// In your root component
import { Component, inject, signal } from '@angular/core';
import { DOCUMENT } from '@angular/common';

@Component({ ... })
export class App {
  private doc = inject(DOCUMENT);
  isDark = signal(false);

  toggleTheme() {
    this.isDark.update(v => !v);
    this.doc.documentElement.style.colorScheme =
      this.isDark() ? 'dark' : 'light';
  }
}

Oat automatically adjusts all token values when the color scheme changes. No need to define separate dark token values yourself — it's handled by the framework.

Scoped overrides

Since tokens are CSS custom properties, you can scope them to any container:

/* Darker sidebar section */
.sidebar {
  --primary: #10b981;
  --background: #0f172a;
  --foreground: #e2e8f0;
  --border: #334155;
}

Any ng-oat component rendered inside .sidebar will pick up those overrides automatically. This is useful for sections with different visual treatments.

Oat's CSS layers

Oat organizes its CSS into layers for clean override behavior:

/* Oat's internal layer order */
@layer theme, base, components, animations, utilities;

/* theme     → CSS custom property definitions */
/* base      → element-level styles (h1, p, button, table, etc.) */
/* components → card, dialog, sidebar, accordion, etc. */
/* animations → keyframes and transitions */
/* utilities  → helper classes (.hstack, .mt-4, etc.) */

Your app styles (outside any @layer) automatically take precedence over all Oat layers. This is why simple token overrides in styles.css just work.

Utility classes

Oat provides a comprehensive set of utility classes for layout, spacing, typography, and responsive design. Here's a quick summary — see the Utilities page for the full reference.