Phoenix DuskMoon Design Conventions

Design Thinking

Before building any page or view, commit to an intentional aesthetic direction within the DuskMoon design system:

Purpose: What does this page do? Dashboard, form, marketing, admin, content?
Density: Dense data UI vs generous editorial spacing — pick one per view
Emphasis: Identify the single most important action or content block — that gets primary color; everything else recedes
Depth: How many surface layers does this view need? Flat (1-2 levels) vs layered (3-4 levels)

DuskMoon provides the tokens — your job is to use them with intention, not uniformly.

Theme Setup

CSS Entry (Required)

@import "tailwindcss";
@plugin "@duskmoon-dev/core/plugin";
@import "phoenix_duskmoon/components";

HTML Root (Required)

<html lang="en" data-theme="sunshine">

Themes: sunshine (light), moonlight (dark).

Body Base

<body class="bg-surface text-on-surface">

Every page starts on surface with on-surface text. No exceptions.

Theme Switcher

Always include <.dm_theme_switcher /> in the appbar. Requires ThemeSwitcher hook.

Component Default Colors

Page Shell

Component	Color	Class / Pattern
Appbar	primary	`appbar appbar-primary appbar-sticky`
Page background	surface	`bg-surface` on `<body>`
Sidebar	secondary	`bg-secondary text-secondary-content`
Footer	surface-container-high	`bg-surface-container-high`
Bottom nav	primary	`color="primary"`
Drawer	secondary	`bg-secondary text-secondary-content`

The appbar is the brand anchor — always primary. The sidebar and drawer use secondary to create a strong navigation identity distinct from the content area. The page body is always surface. Footer uses higher surface elevation for subtle separation.

<.dm_appbar title={@page_title} sticky>
  <:logo>...</:logo>
  <:menu to={~p"/dashboard"} active={@active == :dashboard}>Dashboard</:menu>
  <:user_profile><.dm_theme_switcher /></:user_profile>
</.dm_appbar>

<div class="flex">
  <aside class="bg-secondary text-secondary-content w-64 min-h-screen p-4">
    <.dm_left_menu active={@current_path}>
      <:menu>...</:menu>
    </.dm_left_menu>
  </aside>
  <main class="flex-1 p-6">
    <%= @inner_content %>
  </main>
</div>

<.dm_page_footer label="© 2026 MyApp" />

Actions

Component	Default	When to Change
Primary button	`variant="primary"`	Main page action — one per view
Secondary button	`variant="secondary"`	Alternative actions
Tertiary button	`variant="tertiary"`	Accent features, special highlights
Destructive button	`variant="error"`	Delete, remove, irreversible
Ghost button	`variant="ghost"`	Toolbar, low-emphasis, cancel
Link button	`variant="link"`	Inline text actions
Outline button	`variant="outline"`	Medium emphasis, toggleable

<div class="flex gap-2">
  <.dm_btn variant="ghost">Cancel</.dm_btn>
  <.dm_btn variant="primary">Save Changes</.dm_btn>
</div>

Content

Component	Color	Notes
Card	surface-container	Default CSS — no class needed
Card (elevated)	surface-container-high	Add `shadow="md"`
Modal / Dialog	surface-container-highest	Highest elevation
Tooltip	primary	`color="primary"` default
Popover	surface-container-high
Accordion	surface-container
Bottom sheet	surface-container-high
Snackbar	inverse-surface or type-based	Use `type` for semantic

Data Display

Component	Color	Notes
Badge	`variant="primary"`	Use `secondary`/`tertiary` for category differentiation
Chip	`color="primary"`	Semantic colors for status: `success`, `error`
Progress	`color="primary"`	`success` for completion, `error` for limits
Avatar	`color="primary"`	Initials placeholder color
Stat	no color	`color="primary"` for key metrics only
Timeline	semantic per item	`completed` = green, `active` = primary
Table	no color	`zebra` + `hover` for readability

Forms

Component	Color	Notes
Input	no color	Uses outline border. Set `color` only for emphasis
Checkbox	`color="primary"`
Radio	`color="primary"`
Switch	`color="primary"`
Select	no color
Slider	`color="primary"`
Rating	`color="primary"`	`warning` for star ratings

Feedback

Component	Color	Notes
Alert	type-based	`variant="info"`, `"success"`, `"warning"`, `"error"`
Flash	kind-based	`:info`, `:error`
Toast	type-based	Always set `type`
Loading spinner	`variant="primary"`

Navigation

Component	Color	Notes
Appbar	primary	Always
Navbar	surface-container-high	`navbar-surface-container-high`
Tabs	no color	Active = primary underline
Breadcrumb	on-surface-variant	Muted text
Steps	`color="primary"`	Completed = filled, upcoming = outline
Left menu	secondary	Active item = primary-content highlight

Color Rules

Rule 1: No Hardcoded Colors

Never use hex, rgb, hsl, named colors, or Tailwind palette classes (bg-blue-500, text-slate-600). All colors from design tokens only.

<%# FORBIDDEN %>
<div style="background: #3b82f6;">
<div class="bg-blue-500 text-white">

<%# CORRECT %>
<div class="bg-primary text-primary-content">

Rule 2: Pair Background + Text

Every background token has a text counterpart. Always use them together.

Background	Text
`bg-primary`	`text-primary-content`
`bg-secondary`	`text-secondary-content`
`bg-tertiary`	`text-tertiary-content`
`bg-surface`	`text-on-surface`
`bg-surface-container-*`	`text-on-surface`
`bg-primary-container`	`text-on-primary-container`
`bg-error`	`text-error-content`
`bg-error-container`	`text-on-error-container`
`bg-inverse-surface`	`text-inverse-on-surface`

Rule 3: Surface Elevation — Low to High

Nest surfaces from low to high. Never place lower elevation inside higher.

surface (page)
  ├─ secondary (sidebar, drawer)
  └─ surface-container (card)
       └─ surface-container-high (navbar, popover, elevated card)
            └─ surface-container-highest (dialog, tooltip)

Rule 4: Semantic Colors for States Only

success, warning, error, info communicate state — never for decoration or branding.

<%# CORRECT %>
<.dm_alert variant="error">Validation failed</.dm_alert>
<.dm_badge variant="success">Active</.dm_badge>

<%# WRONG %>
<.dm_btn variant="success">Submit</.dm_btn>   <%# Use primary %>

Rule 5: Primary = Brand, Secondary = Support, Tertiary = Accent

Role	Purpose	Examples
Primary	Brand identity, main actions, key focus	Appbar, main CTA, active nav
Secondary	Supporting actions, alternative emphasis	Secondary CTA, toggles
Tertiary	Special highlights, decorative accents	Feature badges, accent cards

Rule 6: One Primary Action Per View

One variant="primary" button per visible section. Supporting actions use secondary, ghost, or outline.

Rule 7: Icons Inherit Color

dm_mdi and dm_bsi default to currentcolor. Do not set explicit color= unless the icon must differ from surrounding text.

Rule 8: Container Colors for Soft Emphasis

Use primary-container / on-primary-container for tinted backgrounds with lower contrast. Good for featured sections, highlight cards, selected states.

<div class="bg-primary-container text-on-primary-container p-4 rounded-lg">
  Featured content with softer emphasis
</div>

Typography

Font Strategy

DuskMoon does not prescribe a typeface — projects choose their own. Rules:

Pick a distinctive display font for headings — avoid Inter, Roboto, Arial, system-ui. Load from Google Fonts or self-host.
Pair with a clean body font that complements the display choice.
Use a monospace font for code blocks — JetBrains Mono, Fira Code, or similar.
Define fonts as CSS variables, not inline.

/* Project CSS — after DuskMoon imports */
:root {
  --font-display: 'Instrument Serif', serif;
  --font-body: 'DM Sans', sans-serif;
  --font-mono: 'JetBrains Mono', monospace;
}

body { font-family: var(--font-body); }
h1, h2, h3 { font-family: var(--font-display); }
code, pre { font-family: var(--font-mono); }

Type Scale

Element	Class	Usage
Page title	`text-3xl font-bold`	One per page
Section heading	`text-2xl font-semibold`
Card title	`text-lg font-semibold`
Body text	`text-base`	Default
Secondary text	`text-sm text-on-surface-variant`	Muted supporting info
Caption	`text-xs text-on-surface-variant`	Timestamps, metadata

Text Color Hierarchy

Priority	Token	Usage
Primary text	`text-on-surface`	Headings, body text, labels
Secondary text	`text-on-surface-variant`	Descriptions, hints, timestamps
Disabled text	`text-on-surface-variant` with `opacity-50`	Disabled states
Link text	`text-primary`	Clickable inline text

Layout Composition

Spatial Principles

Content pages: Generous whitespace — p-6 or p-8 on main, gap-6 between cards
Data views: Dense spacing — p-4 on main, gap-3 between items
Consistent gaps: Pick one scale per view (gap-4 or gap-6, not mixed)
Max width: Content areas should constrain width — max-w-7xl mx-auto for wide, max-w-3xl for text-heavy

Card Grid

<div class="grid grid-cols-auto-fit-80 gap-6">
  <.dm_card :for={item <- @items}>
    <:title><%= item.name %></:title>
    <%= item.description %>
  </.dm_card>
</div>

Sidebar + Content

<div class="flex min-h-screen">
  <aside class="bg-secondary text-secondary-content w-64 border-r border-outline-variant p-4 shrink-0">
    <.dm_left_menu active={@current_path} />
  </aside>
  <main class="flex-1 bg-surface p-6 overflow-auto">
    <%= @inner_content %>
  </main>
</div>

Stacked Sections with Depth

<section class="bg-surface-container-low p-8 rounded-2xl">
  <h2 class="text-2xl font-semibold mb-6">Featured</h2>
  <div class="grid grid-cols-3 gap-4">
    <.dm_card shadow="md">...</.dm_card>
    <.dm_card shadow="md">...</.dm_card>
    <.dm_card shadow="md">...</.dm_card>
  </div>
</section>

Backgrounds & Depth

Surface Layering

Don't use flat pages. Build depth with surface tokens:

<body class="bg-surface text-on-surface">
  <header class="bg-primary text-primary-content">...</header>
  <div class="bg-surface-container-low -mt-8 pt-12 pb-8 rounded-t-3xl">
    <div class="max-w-6xl mx-auto px-6">
      <.dm_card shadow="lg" class="bg-surface-container">
        ...
      </.dm_card>
    </div>
  </div>
</body>

Hero Sections

Use container color gradients for hero areas:

.hero {
  background: linear-gradient(
    135deg,
    var(--color-primary-container) 0%,
    var(--color-tertiary-container) 100%
  );
}

Scrim & Overlays

.overlay {
  background-color: hsl(var(--color-scrim) / 0.5);
  backdrop-filter: blur(4px);
}

Borders & Dividers

outline-variant → subtle dividers, decorative borders
outline → interactive borders (inputs, focused states)

<hr class="border-outline-variant" />
<div class="border border-outline rounded-lg">Interactive element</div>

Motion & Transitions

Theme Transition

* {
  transition: background-color 0.2s ease, color 0.2s ease, border-color 0.2s ease;
}

Card Hover

.interactive-card {
  transition: transform 0.15s ease, box-shadow 0.15s ease;
}
.interactive-card:hover {
  transform: translateY(-2px);
  box-shadow: var(--shadow-md);
}

Reduced Motion

Always respect user preference:

@media (prefers-reduced-motion: reduce) {
  * { transition: none !important; animation: none !important; }
}

Motion Principles

One transition property per interaction — don't animate everything
Page-level animations on route change (LiveView transitions)
Subtle hover states on cards and buttons — translateY(-2px) max
Loading states use dm_loading_spinner or skeleton components — no custom spinners

Anti-Patterns

Tailwind color scale — No bg-blue-500, text-gray-600. Breaks theme switching.
Hardcoded colors — No hex, rgb, hsl, or named colors.
Opacity faking surfaces — No bg-white/80. Use surface-container-* tokens.
Inline color styles — No style="color: ...".
Raw HTML over components — Use dm_* components when available.
Uniform primary everywhere — One primary action per view. Supporting actions recede.
Semantic colors as decoration — success/error/warning/info are for states only.
Generic fonts — No Inter, Roboto, Arial as conscious choices. Pick distinctive typefaces.
Missing text pairing — Every bg-* needs its text-*-content or text-on-*.
Flat layouts — Use surface elevation for depth. Pages should never feel like a single flat plane.
Timid color usage — A dominant primary with sharp accents outperforms evenly-distributed, wishy-washy palettes. Commit to the hierarchy.
Cookie-cutter pages — Each view type (dashboard, form, content, marketing) should have a distinct spatial composition. Don't copy-paste the same layout everywhere.

phoenix-duskmoon-design