allstarr/DESIGN.md

# Allstarr WebUI Design System

## Product stance

Allstarr is a music control room. Every route must quickly answer:

1. What is happening?
2. Which library, user, source, and account are involved?
3. Is it healthy and complete?
4. What can I safely do next?

## Visual system

Use Google Material 3 as the interaction and visual grammar, adapted to Allstarr rather than copied component by component.

- Role-based `--md-sys-color-*` tokens own light and dark themes.
- Allstarr blue is the only general action accent. Provider marks and music artwork provide the wider palette.
- Tonal surfaces communicate grouping. General panels do not use decorative glass, glow, gradients, or heavy shadows.
- Use one system sans family, restrained type sizes, sentence case, and short operational copy.
- Shapes follow Material roles: 8px fields, 12px compact containers, 16px panels, 24–28px dialogs, and full pills only for buttons, badges, and navigation indicators.
- Theme defaults to the operating-system preference and offers explicit System, Light, and Dark choices.

## Shared components

- Keep the existing Svelte, Bits UI, Tailwind, shadcn-style primitives, and Lucide stack. Do not add Material Web and duplicate the control layer.
- Routes compose shared Button, Checkbox, Select, Dialog, Menu, Tabs, Badge, Progress, Skeleton, Tooltip, and table patterns. They do not restyle raw controls.
- Provider identity uses the existing provider mark and artwork components.
- Creative canvas effects require a GPL-compatible implementation or license. Canvas UI is not vendored because its Commons Clause adds distribution restrictions that conflict with this repository's GPL terms.

## Information architecture

- **Home:** current playback and listeners first; source route, scrobble delivery, health, and work follow.
- **Library:** playlists, mappings, cached files, and kept files share one task vocabulary and aligned tables.
- **Intelligence:** Overview → History → Import → Discover → Automation. Import is a top-level task, not a setting hidden inside history.
- **Integrations:** Services owns provider configuration and diagnostics. Extensions owns package lifecycle. Accounts and Routing explain their scope in plain language.
- **Activity:** outcome, actor, target, duration, and time are primary; technical payloads are progressive detail.
- **Settings:** deployment and operator controls only. User-scoped controls stay near the data they affect.

## Interaction rules

- One clear primary action per task area.
- Dense lists and tables are preferred when comparison matters; spacious guidance is used for onboarding and empty states.
- Modals protect destructive or interrupting work only. Routine configuration stays inline or in a route-level detail pane.
- Administrative Jellyfin controls appear only when the authenticated backend permission explicitly allows them. The UI never infers authorization.
- Loading uses skeletons; empty states explain the next action; errors name both the problem and recovery.

## Motion

- Use 150–250ms Material-style state transitions for selection, reveal, progress, and completion.
- No decorative page-load choreography, looping control animation, or movement that reorders content under the pointer.
- Respect reduced motion. Expensive media effects are lazy, bounded, paused off-screen, and disposable on unmount.

## Quality bar

- Core tasks work at 320px, keyboard-only, reduced-motion, light, and dark themes.
- Status is never color-only.
- Tables share gutters, row heights, alignment, and action placement.
- Shared-system changes should delete route-specific CSS over time and keep the current JS/CSS budgets green.