Packages
phoenix_duskmoon
9.4.1
9.9.2
9.9.1
9.9.0
9.8.0
9.7.1
9.7.0
9.6.4
9.6.3
9.6.2
9.6.1
9.6.0
9.5.4
9.5.3
9.5.2
9.5.1
9.5.0
9.4.3
9.4.2
9.4.1
9.4.0
9.3.0
9.2.0
9.1.4
9.1.3
9.1.1
9.1.1-rc.1
retired
9.0.1
9.0.0-rc.3
9.0.0-rc.2
9.0.0-rc.1
8.0.0
7.2.1
7.2.0
7.1.3
7.1.2
7.1.1
6.3.2
6.3.1
6.3.0
6.2.0
6.1.3
6.1.2
6.1.1
6.1.0
6.0.10
6.0.9
6.0.8
6.0.7
6.0.6
6.0.5
6.0.4
6.0.3
6.0.2
6.0.1
6.0.0
5.2.0-beta.5
5.2.0-beta.4
5.2.0-beta.3
5.2.0-beta.2
5.2.0-beta.1
5.1.0
5.0.6
5.0.5
5.0.4
5.0.3
5.0.2
5.0.1
5.0.0
4.6.6
4.6.5
4.6.4
4.6.3
4.6.2
4.6.1
4.6.0
4.5.2
4.5.1
4.5.0
4.4.4
4.4.3
4.4.2
4.4.1
4.4.0
4.3.2
4.3.1
4.3.0
4.2.0
4.1.1
4.1.0
4.0.0
Duskmoon UI component library for Phoenix LiveView
Current section
Files
Jump to
Current section
Files
guides/theming.md
# Theming
Phoenix Duskmoon UI uses CSS custom properties from `@duskmoon-dev/core` for all
colors, typography, spacing, and elevation. Two built-in themes are provided:
**sunshine** (light) and **moonlight** (dark).
## Built-in Themes
Import the themes in your CSS:
```css
@import "tailwindcss";
@plugin "@duskmoon-dev/core/plugin";
@import "@duskmoon-dev/core/themes/sunshine";
@import "@duskmoon-dev/core/themes/moonlight";
```
The `sunshine` theme activates with `[data-theme="sunshine"]` on the `<html>` element,
and `moonlight` with `[data-theme="moonlight"]`. Use the `<.dm_theme_switcher />`
component to let users toggle between them (requires the `ThemeSwitcher` hook — see
the [Hooks](hooks.md) guide).
## CSS Custom Properties
All component styles reference CSS custom properties. The full set includes:
### Brand colors
| Property | Description |
|----------|-------------|
| `--color-primary` | Primary brand color |
| `--color-primary-content` | Text on primary |
| `--color-secondary` | Secondary brand color |
| `--color-secondary-content` | Text on secondary |
| `--color-tertiary` | Tertiary brand color |
| `--color-accent` | Accent color (maps to tertiary) |
| `--color-accent-content` | Text on accent |
### Surface colors
| Property | Description |
|----------|-------------|
| `--color-surface` | Default surface background |
| `--color-surface-dim` | Dimmed surface |
| `--color-surface-bright` | Brightened surface |
| `--color-surface-variant` | Alternative surface |
| `--color-on-surface` | Text on surface |
| `--color-on-surface-variant` | Secondary text on surface |
### Semantic colors
| Property | Description |
|----------|-------------|
| `--color-info` | Informational |
| `--color-success` | Success state |
| `--color-warning` | Warning state |
| `--color-error` | Error state |
Each semantic color also has `-content`, `-container`, and `-on-container` variants.
### Design tokens
| Category | Properties |
|----------|-----------|
| Typography | `--font-family`, `--font-size-{xs,sm,md,lg,xl}`, `--font-weight-{normal,medium,semibold,bold}` |
| Shape | `--radius-{sm,md,lg,xl,full}` |
| Elevation | `--shadow-{sm,md,lg}` |
| Spacing | `--spacing-{xs,sm,md,lg,xl}` |
| Motion | `--transition-{fast,normal,slow}` |
| Focus | `--focus-ring`, `--focus-ring-offset` |
## Custom Colors
To customize the theme, override CSS custom properties in your stylesheet:
```css
:root {
--color-primary: oklch(0.65 0.19 250);
--color-secondary: oklch(0.75 0.15 200);
--color-accent: oklch(0.7 0.2 150);
--color-success: oklch(0.7 0.2 145);
--color-warning: oklch(0.8 0.15 85);
--color-error: oklch(0.6 0.2 25);
--color-info: oklch(0.7 0.15 250);
}
```
Use `oklch()` color values for perceptually uniform color manipulation. The
`@duskmoon-dev/core` design system uses oklch throughout.
## Element Theme Bridge
Custom elements render inside shadow DOM, which isolates them from the document's
CSS custom properties by default. Phoenix Duskmoon UI includes an **element theme
bridge** (`element-theme-bridge.css`) that forces all `el-dm-*` elements to
`inherit` the document's theme tokens.
This bridge is included automatically when you use `@plugin "@duskmoon-dev/core/plugin"`
in your CSS. It ensures that:
- All `el-dm-*` custom elements respect the document theme
- Theme switching (sunshine/moonlight) propagates into shadow DOM
- Custom property overrides in your stylesheets affect custom elements
### Per-element overrides
Some custom elements use non-standard property names internally. The bridge
maps these to the standard theme tokens:
- `el-dm-table` — bridges `--dm-color-*` namespace to `--color-*`
- `el-dm-pagination` — bridges `--color-border`, `--color-text` to theme tokens
- `el-dm-bottom-navigation` — bridges `--color-border`, `--color-text-secondary`
- `el-dm-popover` — fixes upstream shadow DOM arrow positioning via `::part(arrow)`
## CSS Class Naming (BEM)
Components follow BEM naming convention for CSS classes:
| Pattern | Example | Description |
|---------|---------|-------------|
| `dm-component` | `dm-btn`, `dm-card` | Block (component root) |
| `dm-component--variant` | `dm-btn--primary`, `dm-input--lg` | Modifier (variant/size) |
| `dm-component__element` | `dm-card__header`, `dm-switch__track` | Element (child part) |