# Phoenix Duskmoon Design
> Design conventions and visual quality guide for Phoenix projects using DuskMoon UI. Defines component color defaults, theme setup, surface elevation, color pairing rules, typography, layout composition, and motion patterns. Read this before writing any HEEX template, CSS, layout code, or creating new pages/views.
- Skill: `gsmlg-dev/phoenix-duskmoon-design` (Agent Skill)
- Install (CLI): `npx skillmds@latest add gsmlg-dev/phoenix-duskmoon-design`
- Raw SKILL.md: https://api.skillmd.com/api/skills/gsmlg-dev/phoenix-duskmoon-design/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Design & Media
- Author: gsmlg-dev (https://skillmd.com/u/gsmlg-dev)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/gsmlg-dev/phoenix-duskmoon-design
---
# 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)
```css
@import "tailwindcss";
@plugin "@duskmoon-dev/core/plugin";
@import "phoenix_duskmoon/components";
```
### HTML Root (Required)
```heex
```
Themes: `sunshine` (light), `moonlight` (dark).
### Body Base
```heex
```
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 `` |
| 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.
```heex
<.dm_appbar title={@page_title} sticky>
<:logo>...
<:menu to={~p"/dashboard"} active={@active == :dashboard}>Dashboard
<:user_profile><.dm_theme_switcher />
```
---
## Motion & Transitions
### Theme Transition
```css
* {
transition: background-color 0.2s ease, color 0.2s ease, border-color 0.2s ease;
}
```
### Card Hover
```css
.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:
```css
@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
1. **Tailwind color scale** — No `bg-blue-500`, `text-gray-600`. Breaks theme switching.
2. **Hardcoded colors** — No hex, rgb, hsl, or named colors.
3. **Opacity faking surfaces** — No `bg-white/80`. Use `surface-container-*` tokens.
4. **Inline color styles** — No `style="color: ..."`.
5. **Raw HTML over components** — Use `dm_*` components when available.
6. **Uniform primary everywhere** — One primary action per view. Supporting actions recede.
7. **Semantic colors as decoration** — `success`/`error`/`warning`/`info` are for states only.
8. **Generic fonts** — No Inter, Roboto, Arial as conscious choices. Pick distinctive typefaces.
9. **Missing text pairing** — Every `bg-*` needs its `text-*-content` or `text-on-*`.
10. **Flat layouts** — Use surface elevation for depth. Pages should never feel like a single flat plane.
11. **Timid color usage** — A dominant primary with sharp accents outperforms evenly-distributed, wishy-washy palettes. Commit to the hierarchy.
12. **Cookie-cutter pages** — Each view type (dashboard, form, content, marketing) should have a distinct spatial composition. Don't copy-paste the same layout everywhere.