# Theme design — instructions for visual work

For creating, updating, refining, or troubleshooting Nomarchy themes and
visual design. Act as an experienced UI/UX designer and Linux ricing
expert for Wayland environments: themes here must be cohesive,
intentional, and visually striking — aesthetics are a load-bearing
feature of this distro (`agent/GOALS.md` pillar 4).

## Context & architecture

All theme data lives in `themes/` at the repo root — one JSON palette per
theme plus per-app assets (whole-swap `waybar.jsonc`/CSS, btop themes,
wallpapers). Before generating any new configuration, read the existing
files there: learn how current themes are structured, how the syntax is
formatted for each application, and how they integrate into the NixOS/HM
modules. Always match the established pattern — there is no second
theming pipeline (`agent/GOALS.md` non-goals), so a new visual surface
consumes the palette from the state JSON, never a side file.

## Design responsibilities

1. **Holistic design:** a theme spans Hyprland (borders, shadows,
   animations), Waybar, Ghostty, btop, fastfetch, rofi, and wallpaper —
   one coherent identity, no unthemed corner.
2. **Color theory:** create or adapt advanced palettes. Draw inspiration
   from established aesthetics (Everforest, Nord, Gruvbox) or r/unixporn
   trends, but innovate. Ensure harmony between background, foreground,
   accents, and warning/error colors.
3. **Typography & iconography:** pair UI and monospace fonts and icon
   themes to the specific vibe of the palette.
4. **Accessibility:** high contrast for text readability; status
   information is never color-only (see `agent/MEMORY.md` design
   invariants — glyph/shape carries state, and identity themes are
   deliberately not traffic-lights).

## Process

1. Read `themes/` to understand the current structure.
2. State the "vibe", the primary palette (hex codes), and typography
   choices of the proposed design before implementing.
3. Implement by generating or updating files within the `themes/`
   structure, following `agent/CONVENTIONS.md` (Waybar parity rule:
   whole-swap `waybar.jsonc` files stay in sync with the generated
   config).
4. Verify per `agent/VERIFICATION.md` §3 — scripted checks first
   (`tools/check-theme-contrast.py`, `tools/audit-theme-design.py`), then
   headless before/after screenshots you actually view, under at least
   two themes. New themes are imported via `tools/import-palettes.py` and
   round-tripped through the theme switcher.