# Ceol UI/UX beauty gate
Ceol treats the compact player as an intentional second surface. This gate is
run before a public release so visual polish does not trade away playback
capability, clarity, or keyboard access.
## Pattern comparison
| [Apple Music MiniPlayer](https://support.apple.com/en-nz/guide/music/mus71d7dcfce/mac) | A small persistent surface retains artwork, transport, seeking, volume, and access to the larger experience. | Keep identity, timeline, status, shuffle/repeat, seeking, transport, and mute visible; use one explicit **Expand** action instead of hiding the route back. |
| [GNOME adaptive layouts](https://developer.gnome.org/hig/guidelines/adaptive.html) | Start with constrained space, choose meaningful layout changes, and preserve equivalent functions rather than merely scaling everything down. | Use a separate `GtkStack` compact surface with its own hierarchy. The full player restores the queue and visualizer without changing playback state. |
| [GNOME button guidance](https://developer.gnome.org/hig/patterns/controls/buttons.html) | Icon buttons and toggles work well where space is limited when icons are familiar and every control has a tooltip. | Compact transport uses familiar symbolic icons, visible active states, and descriptive tooltips; text is reserved for the mode-changing action. |
| [GNOME header bars](https://developer.gnome.org/hig/patterns/containers/header-bars.html) | Keep global actions few, relevant, and predictable. | The full top bar exposes only mode, folder import, and file import. Queue manipulation stays beside the queue; playback stays on the stage. |
| [GNOME boxed lists](https://developer.gnome.org/hig/patterns/containers/boxed-lists.html) | Small editable collections work best as semantic sections with simple rows, restrained controls, and clear add/remove actions. | Library sources and playlists use two peer cards, two-level row text, symbolic icons, explicit selection, active/offline tags, and disabled invalid actions. |
| [GNOME navigation](https://developer.gnome.org/hig/guidelines/navigation.html) | Central tasks belong in an in-window view with shallow, predictable navigation. | Library management is one peer view reached from the player and returned with a single Player action or Escape—no stacked dialogs or deep hierarchy. |
## Full and compact capability comparison
| Artwork, title, metadata, and playback status | ✓ | ✓ |
| Direct timeline seeking and exact time | ✓ | ✓ |
| Play/pause, previous, next, ±10 seconds | ✓ | ✓ |
| Shuffle, repeat, and mute | ✓ | ✓ |
| Save and navigate track-specific points | ✓ | ✓ |
| Queue preview and direct track activation | ✓ | ✓ |
| Queue reorder, remove, and clear | ✓ | Expand once |
| Folder/file import and drag-and-drop | ✓ | Drop directly or expand once |
| Spectrum visualization | ✓ | Expand once |
| Multi-field queue search | ✓ | `Ctrl+F` expands and focuses |
| Keyboard controls | ✓ | ✓ |
## Library configuration comparison
| See remembered folders | Hidden across repeated file pickers | One persistent, scannable source list |
| Switch music roots | Browse from scratch each time | Select once, then **Load Selected** |
| Combine locations | Repeat imports manually | **Load All** merges every online source |
| Handle disconnected drives | Fail after selection | Preserve the source and mark it **Offline** |
| Reuse a queue | Rebuild track by track | Save, update, replace, append, or export a named playlist |
| Understand destructive scope | Ambiguous remove actions | Copy explicitly says files are never deleted |
## Theme comparison
| Signal | Electric cyan over deep ocean surfaces | Original high-energy identity; cyan remains focused on signal, selection, and primary action. |
| Ember | Warm gold over smoked copper and near-black | Warm accents replace every cyan dependency, including focus, sliders, status, spectrum, and disabled states. |
| Ultraviolet | Violet bloom over midnight ink | Primary violet and secondary pink remain legible without flattening list, card, or transport hierarchy. |
| Daylight | Clear sky over soft mineral surfaces | Dark type, cool teal actions, outlined controls, and restrained shadows preserve the same hierarchy on a light canvas. |
Theme selection changes the entire rendering vocabulary rather than tinting one
accent. Shells, cards, queue states, form controls, artwork placeholders, live
spectrum drawing, compact controls, and focus feedback update together. A short
eased crossfade bridges the palettes without delaying input, and the selected
theme survives restart.
Motion is independently selectable as **Still**, **Calm**, or **Alive**. Still
keeps audio-reactive spectrum data but removes ambient drift and theme fades;
Calm reduces the animation range and transition duration; Alive enables the
full drifting glow, bar shimmer, waveform motion, and eased palette transition.
This preference persists independently of theme.
The compact surface omits only tasks that need scanning space or sustained
attention. It does not omit any control needed to listen to the current queue.
## Release checks
- **Hierarchy:** artwork and track title lead; metadata and status support them;
transport remains the strongest interactive group.
- **Constrained layout:** the compact widget targets a `520 × 166` content
baseline and measures `520 × 191` at its GTK natural size in the desktop
audit, with all eight controls coherent across all four themes.
- **Desktop constraint:** the full player and Library page keep every action
visible and reachable in a `1024 × 600` client area without horizontal
scrolling or clipped cards.
- **Long content:** title and detail use end ellipsis rather than widening or
clipping the surface.
- **Queue discovery:** live filtering never mutates playback order; visible row
actions resolve through stable underlying queue indices, and an empty result
has a specific recovery state rather than resembling an empty library.
- **Control integrity:** all eight compact controls remain visible, focused, and
clickable; active shuffle, repeat, and mute states are visually distinct.
- **Queue peek integrity:** the popover marks the current track, presents no
more than six scannable rows, fills boundary space with nearby context,
activates the underlying queue index, and never claims a deterministic
upcoming order while shuffle is active.
- **State continuity:** switching layouts never restarts playback, loses seek
position, or changes the queue.
- **Empty and error states:** no-track, paused, loading, end-of-queue, and
playback-error states remain legible in both layouts.
- **Input parity:** mouse, keyboard, files, folders, local M3U/M3U8 manifests,
command-line paths, and drag-and-drop converge on the same ordered queue
behavior; remote manifest URLs are rejected at the local-first boundary.
- **Saved-point parity:** the same bookmark popover and wraparound point
navigation are available without leaving either layout.
- **Library hierarchy:** source switching and playlist management remain two
equal, digestible sections with no modal stack or nested configuration.
- **Safe collection editing:** load/save actions are prominent, invalid actions
are insensitive, and removal language never implies audio deletion.
- **Portable export:** the save dialog is transient and fully on-screen at the
desktop constraint; M3U8 output is atomic, ordered, local-only, and retains
offline entries rather than silently shrinking a saved playlist.
- **Color and focus:** each palette reserves its accent for signal/action
emphasis; keyboard focus uses a high-contrast outline independent of color
alone, and insensitive actions remain visibly distinct in every theme.
- **Motion restraint:** the spectrum can remain continuously alive, while theme
and page transitions are brief, eased, and never block playback or input.
Still and Calm profiles offer explicit lower-motion alternatives without
removing playback information.
Any clipped transport action, unreachable expansion control, state mismatch, or
loss of core playback capability fails the gate.