Bose-SoundTouch/.impeccable.md

Design Context

Users

The primary users are tech-savvy individuals (including IT professionals and dedicated enthusiasts) who need to migrate their Bose SoundTouch speakers from the Bose Cloud to a local service. While the initial setup requires technical knowledge (SSH, network config), the ultimate goal is a "set and forget" solution that provides a seamless experience for everyday use.

Brand Personality

• Voice & Tone: Open, Transparent, Technical.
• 3-word personality: Reliable, Precise, Empowering.
• Emotional Goal: Confidence. The interface should make users feel that their hardware is safe and will continue to work indefinitely.

Aesthetic Direction

• Visual Tone: "Pro-consumer" but clean. It should feel like a high-quality utility rather than a marketing site.
• References: Bose (clean typography, generous whitespace, focused interactions).
• Anti-references: "AI Slop" (generic, cluttered, over-saturated designs).
• Theme: Light mode by default. Dark mode is a nice-to-have but secondary.

Design Principles

1. Clarity over Flash: Prioritize clear instructions and immediate feedback. The interface exists to solve a technical problem, not to sell a product.
2. Confidence-Building Interactions: Every action (especially destructive ones like migration) must have clear confirmations and status indicators (e.g., ✅ Success/❌ Error).
3. Utility with Polish: Maintain a technical feel (using code blocks and data tables where necessary) but elevate them with consistent spacing, refined typography, and subtle visual cues.
4. Future-Proof Consistency: Design components and patterns that can scale to a consumer-oriented mobile or desktop application.
5. Component-Based Scalability: Move away from inline styles toward a clean, token-based CSS approach to improve maintainability and responsiveness.

Component Library (Standard Patterns)

1. Callouts & Status Indicators

Use for feedback, warnings, and instructions.

• Base Class: .callout or .status
• Variants: .callout-info (blue), .callout-success (green), .callout-warning (yellow), .callout-error (red)
• Usage:

  <div class="callout callout-info">
      <strong>Title:</strong> Your message here.
  </div>
  

2. Buttons

• Primary: .btn-primary (Blue/Accent) - Main action.
• Secondary: .btn-secondary (Grey) - Neutral action.
• Success: .btn-success (Green) - Positive/Confirm action.
• Warning: .btn-warning (Yellow) - Revert/Caution action.
• Danger: .btn-danger (Red) - Destructive action.
• Spotify: .btn-spotify (Spotify Green) - Spotify-specific actions.

3. Data Containers

• Cards: .card or .summary-box - Grouped information.
• Consoles: .console-box or pre - Monospace output, logs, or code.
• Viewers: .viewer-box - Dark-themed container for detailed technical analysis (JSON/XML).

4. Layout Utilities

• Flexbox: .flex-row, .flex-between, .flex-grow.
• Spacing: .mt-{size}, .mb-{size}, .ml-{size}, .p-{size}.
  • Sizes: xs (4px), sm (8px), md (16px), lg (24px), xl (32px).
• Visibility: .hidden, .visible, .flex-visible.

5. Typography

• Subtitle: .subtitle - Small italicized text below headings.
• Help Text: .help-text or .help-text-sm - Descriptive text for inputs or status.
• Badges: .badge with variants .badge-info, .badge-success, etc.