#Theming

Change the look of every UI component by editing one CSS file. Components take their colors from theme tokens: CSS variables such as --primary whose values you set.

#How it works

page {
  --primary: rgba(24, 24, 27, 1);
  --primary-foreground: rgba(250, 250, 250, 1);
}

<view class="bg-primary p-4">
  <text class="text-primary-foreground">Saved</text>
</view>

• The tokens are set on page, the root element of every Lynx app (see Glossary), so every element can read them.
• Each token holds a complete rgba() color. tailwind-plugin.ts maps the classes straight to the variable: bg-primary becomes background-color: var(--primary).
• dolan init copied both files into src/styles/. They're yours to edit.

The tokens are complete colors because of how Lynx parses them. Lynx accepts only comma-separated hsl(), while the usual shadcn/ui setup produces space-separated hsl(var(--x) / 1). Lynx drops that value without a warning, and the element renders transparent. See CSS on Lynx for the other color rules.

#Opacity modifiers don't work

bg-primary/50 and border-destructive/50 don't work. The token is one finished color, so Tailwind has no separate channels to add alpha to.

Use one of these instead:

• A translucent token. The theme has --destructive-subtle (red at 10%), used as bg-destructive-subtle. Add your own the same way, as shown in Add a token.
• A solid token. bg-muted makes a subtle track or background.
• opacity-* on the element. This fades the element and its children together.

Named Tailwind colors keep their modifiers. bg-black/50 compiles to rgb(0 0 0 / 0.5), which Lynx accepts.

#Tokens

Every color class works with bg-, text- and border-. The plugin also sets border-color: var(--border) on every element, so a plain border class draws in the theme's border color.

#Radius

--radius (default 8px) sets three classes:

• rounded-lg: var(--radius)
• rounded-md: calc(var(--radius) - 2px)
• rounded-sm: calc(var(--radius) - 4px)

#Safe area

The plugin also adds padding classes that keep content clear of the notch and home indicator: pt-safe, pb-safe, px-safe, p-safe and the others. The numbered forms add a spacing value on top, so pb-safe-4 is calc(1rem + env(safe-area-inset-bottom)). See Safe area.

#Customize your brand

Edit the values in default.css. Write each one as a complete rgba() or hex color.

page {
  --primary: rgba(37, 99, 235, 1);
  --primary-foreground: rgba(255, 255, 255, 1);
  --ring: rgba(37, 99, 235, 1);
  --ring-subtle: rgba(37, 99, 235, 0.4);
  --radius: 12px;
  /* …keep the other tokens… */
}

• Change the same tokens in dark.css if you use dark mode.
• Charts draw with a TypeScript copy of these colors, because Lynx's SVG renderer can't read CSS variables. Pass your new values to provideChartTheme(), as shown on Chart.
• dolan update merges theme changes too, so your edits survive updates.

#Add a token

Add the variable to both theme files, then map it in the plugin:

page {
  --success: rgba(22, 163, 74, 1);
  --success-subtle: rgba(22, 163, 74, 0.1);
}

colors: {
  // …the existing colors…
  success: {
    DEFAULT: 'var(--success)',
    subtle: 'var(--success-subtle)',
  },
},

You can now use bg-success, text-success and bg-success-subtle.

#Start a new theme

npx @blotch/dolan theme ocean

This copies default.css to src/styles/ocean.css. Edit it, then import it in place of default.css in src/styles.css. dolan update doesn't merge themes you create this way.

#Dark mode

dark.css has a dark value for every token, under the selector page.dark. AngularLynx creates page for you and has no API for its classes. To switch themes at runtime, move the dark values onto a class you can bind.

1. In src/styles/dark.css, change the selector page.dark to .dark.

2. Bind that class on your root view from LynxTheme:

import { Component, inject } from '@angular/core';
import { LYNX_ELEMENTS, LynxTheme } from '@blotch/angular-lynx';

@Component({
  selector: 'app-root',
  imports: [LYNX_ELEMENTS],
  template: `
    <view class="h-full bg-background" [class.dark]="theme.isDarkMode()">
      <text class="text-foreground">This follows the device theme.</text>
    </view>
  `,
})
export class App {
  protected readonly theme = inject(LynxTheme);
}

• isDarkMode() is a signal. The host app (the native app that runs your bundle, see Glossary) sets it from the device's appearance setting.
• Charts default to light colors. Add provideChartTheme({ colorScheme: 'system' }) to make them follow too (see Chart).
• For a manual toggle, bind [class.dark] to your own signal instead. See Dark mode and LynxTheme.

#Variable reference

Generated from default.css and dark.css.

#Related

• UI Components: install the theme with dolan init
• CSS on Lynx: color formats and other CSS differences
• Tailwind CSS: the Tailwind setup the plugin builds on
• Dark mode: switching themes at runtime