Styling System - SoundWave

Overview

SoundWave implements a Spotify-inspired dark theme design system using vanilla CSS. The styling architecture emphasizes consistency, accessibility, and responsive design across different viewport sizes.

Color System

Primary Color Palette

The application uses a carefully curated color scheme that matches Spotify’s brand identity:

Primary Green

color

#1db954Usage: Buttons, links, interactive elements, headingsReference: styles.css:10, styles.css:55

Hover Green

color

#1ed760Usage: Button hover states, interactive feedbackReference: styles.css:62, styles.css:129

Dark Green

color

#14833bUsage: Button pressed state (in index.html inline styles)Reference: index.html:60

Background Dark

color

#121212Usage: Main page background, player backgroundReference: styles.css:3, index.html:11

Surface Dark

color

#282828Usage: Input fields, suggestion containers, content cardsReference: styles.css:22, styles.css:38, styles.css:66

Surface Light

color

#383838Usage: Hover states for suggestions and linksReference: styles.css:46, styles.css:101

Text Primary

color

#ffffffUsage: Primary text, button textReference: styles.css:4, styles.css:23

Text Secondary

color

#b3b3b3Usage: Placeholder text, secondary informationReference: styles.css:28, styles.css:136

Color Usage Matrix

/* Background Hierarchy */
background-color: #121212;  /* Level 0: Page background */
background-color: #282828;  /* Level 1: Component background */
background-color: #383838;  /* Level 2: Interactive hover */
background-color: #484848;  /* Level 3: Active state (styles.css:109) */

/* Accent Colors */
color: #1db954;             /* Primary accent */
color: #1ed760;             /* Hover accent */
color: #14833b;             /* Pressed accent */

/* Text Colors */
color: #ffffff;             /* Primary text */
color: #b3b3b3;             /* Secondary text */

Typography

Font Stack

font-family: Arial, sans-serif;

Reference: styles.css:2

The Spotify-themed pages (index.html, index3.html) use Roboto from Google Fonts:

<link href="https://fonts.googleapis.com/css2?family=Roboto:wght@400;700&display=swap" rel="stylesheet">

font-family: 'Roboto', sans-serif;

Reference: index.html:7, index.html:10

Font Sizes

Base Font Size

size

16pxUsage: Input fields, buttons, body textReference: styles.css:21, styles.css:54

Small Font Size

size

14pxUsage: Group information, metadataReference: styles.css:135

Component Styles

Input Fields

#song-name {
    width: 100%;
    padding: 12px;
    margin-bottom: 20px;
    border: none;
    border-radius: 25px;
    font-size: 16px;
    background-color: #282828;
    color: #ffffff;
    outline: none;
}

#song-name::placeholder {
    color: #b3b3b3;
}

Reference: styles.css:15-25, styles.css:27-29

Border Radius

size

25px creates pill-shaped inputs

Padding

size

12px provides comfortable touch targets

The outline: none rule removes default browser focus indicators. For accessibility, consider adding a custom focus style:

#song-name:focus {
    box-shadow: 0 0 0 2px #1db954;
}

Buttons

#search-button {
    width: 100%;
    padding: 12px;
    border: none;
    border-radius: 25px;
    font-size: 16px;
    background-color: #1db954;
    color: #ffffff;
    cursor: pointer;
    transition: background-color 0.3s;
}

#search-button:hover {
    background-color: #1ed760;
}

Reference: styles.css:49-59, styles.css:61-63

Show Button Variations

The group separator buttons have additional styling:

.group-separator button {
    background-color: #1db954;
    border: none;
    border-radius: 25px;
    color: #ffffff;
    padding: 10px 20px;
    cursor: pointer;
    transition: background-color 0.3s;
}

.group-separator button:hover {
    background-color: #1ed760;
}

Reference: styles.css:118-126, styles.css:128-130

Suggestion Items

.suggestion {
    cursor: pointer;
    padding: 10px;
    background-color: #282828;
    border-radius: 10px;
    margin-bottom: 5px;
    color: #ffffff;
    transition: background-color 0.3s;
}

.suggestion:hover {
    background-color: #383838;
}

Reference: styles.css:35-43, styles.css:45-47

The transition: background-color 0.3s creates smooth hover animations. This same pattern is used for all interactive elements.

Content Containers

#filtered-content {
    background-color: #282828;
    border-radius: 10px;
    padding: 20px;
    margin-top: 20px;
    color: #ffffff;
}

#filtered-content a {
    color: #1db954;
    text-decoration: none;
}

#filtered-content a:hover {
    text-decoration: underline;
}

Reference: styles.css:65-71, styles.css:73-76, styles.css:78-80

Audio Player

#audio-player {
    width: 100%;
    margin-top: 20px;
    background-color: #282828;
    border-radius: 10px;
}

Reference: styles.css:82-87

The native <audio> controls inherit the dark background, creating visual consistency with the rest of the interface.

Source Links Container

#source-links {
    background-color: #282828;
    border-radius: 10px;
    padding: 20px;
    margin-top: 20px;
    color: #ffffff;
    display: none;
}

.audio-link {
    cursor: pointer;
    padding: 10px;
    background-color: #383838;
    border-radius: 10px;
    margin-top: 5px;
    color: #ffffff;
    transition: background-color 0.3s;
}

.audio-link:hover {
    background-color: #484848;
}

Reference: styles.css:89-96, styles.css:98-106, styles.css:108-110

display: none

visibility

The container is hidden by default and shown via JavaScript when audio links are available:

container.style.display = 'block';

Layout Patterns

Page Structure

body {
    font-family: Arial, sans-serif;
    background-color: #121212;
    color: #ffffff;
    margin: 0;
    padding: 20px;
}

Reference: styles.css:1-7

margin: 0 removes default browser margins, while padding: 20px creates consistent page gutters.

Heading Styles

h1 {
    color: #1db954;
    text-align: center;
    margin-bottom: 20px;
}

Reference: styles.css:9-13

.group-separator {
    display: flex;
    justify-content: space-between;
    margin-top: 20px;
}

.group-info {
    text-align: center;
    margin-top: 10px;
    font-size: 14px;
    color: #b3b3b3;
}

Reference: styles.css:112-116, styles.css:132-137

Show Navigation Layout

Responsive Design

Media Query Breakpoint

@media (min-width: 768px) {
    #song-name, #search-button {
        width: 50%;
        margin-left: 25%;
    }

    #filtered-content, #source-links {
        width: 70%;
        margin-left: 15%;
    }
}

Reference: styles.css:139-149

Breakpoint

size

768px (tablet and above)

Mobile

layout

Full width (100%) for inputs and content

Desktop

layout

Centered column:

Inputs: 50% width, centered with 25% left margin
Content: 70% width, centered with 15% left margin

Inline Responsive Styles

The Spotify-themed pages include additional inline media queries:

@media (max-width: 1024px) {
    body {
        width: 1024px;
    }
}

Reference: index.html:64-68

This forces a 1024px width on smaller screens, causing horizontal scrolling. This appears to be intentional to maintain the desktop layout on mobile devices but is generally not recommended for responsive design.

@media (max-width: 600px) {
    iframe {
        width: 100%;
        height: 80px;
    }
}

Reference: index3.html:61-66

This reduces the Spotify embed height on mobile to save vertical space.

Animation and Transitions

Hover Transitions

All interactive elements use consistent 0.3s transitions:

transition: background-color 0.3s;

Applied to:

.suggestion (styles.css:42)
#search-button (styles.css:58)
.audio-link (styles.css:105)
.group-separator button (styles.css:125)

Text Decorations

Hover effects for links:

li:hover {
    text-decoration: underline;
}

#filtered-content a:hover {
    text-decoration: underline;
}

Reference: index.html:35-37, styles.css:78-80

Accessibility Considerations

Focus Management

Current implementation removes default focus outlines:

outline: none;

Recommendation: Add custom focus styles for keyboard navigation:

#song-name:focus,
#search-button:focus {
    box-shadow: 0 0 0 3px rgba(29, 185, 84, 0.5);
    outline: 2px solid #1db954;
    outline-offset: 2px;
}

Color Contrast

The dark theme provides excellent contrast ratios:

Primary Text

White on dark background (#ffffff on #121212)Contrast Ratio: 15.3:1 (WCAG AAA)

Secondary Text

Gray on dark background (#b3b3b3 on #121212)Contrast Ratio: 8.6:1 (WCAG AAA)

Green Accent

Green on dark background (#1db954 on #121212)Contrast Ratio: 5.2:1 (WCAG AA)

Button Text

White on green (#ffffff on #1db954)Contrast Ratio: 2.9:1 (WCAG AA Large)

Cursor Feedback

cursor: pointer;

Applied to all clickable elements to provide visual feedback.

Styling Best Practices

1. Border Radius Consistency

Pill Shapes (25px):

Input fields
Buttons
Navigation buttons

Card Shapes (10px):

Content containers
Suggestion items
Audio player

Embed Shapes (12px):

Spotify iframe (index.html:84)

2. Spacing System

Component Padding

size

20px for content containers12px for input fields and buttons10px for list items and suggestions

Margins

size

20px for vertical spacing between major sections10px for spacing between related items5px for tight grouping (suggestion items)

3. Layering System

The application uses background color depth to create visual hierarchy:

Layer 0: #121212 (Page background)
   ↓
Layer 1: #282828 (Component background)
   ↓
Layer 2: #383838 (Hover state)
   ↓
Layer 3: #484848 (Active state)

Inline Styling Patterns

Some pages use inline styles for quick prototyping:

index.html Inline Styles

<style>
    body {
        font-family: 'Roboto', sans-serif;
        background-color: #121212;
        color: white;
        padding: 20px;
        text-align: center;
        width: 1024px;
        margin: 0 auto;
        overflow-x: hidden;
    }
</style>

Reference: index.html:9-18

The inline styles duplicate functionality from styles.css but add page-specific constraints like the 1024px width.

index2.html Inline Styles

<style>
    body {
        font-family: Arial, sans-serif;
        background-color: #f4f4f4;
        margin: 0;
        padding: 0;
    }
    .container {
        width: 80%;
        max-width: 600px;
        margin: 50px auto;
        background-color: #fff;
        padding: 20px;
        border-radius: 8px;
        box-shadow: 0 4px 8px rgba(0, 0, 0, 0.1);
    }
</style>

Reference: index2.html:8-58

This page uses a light theme instead of the dark theme, creating inconsistency with the rest of the application. Consider adopting the dark theme for all pages.

Theming Recommendations

CSS Custom Properties

For better maintainability, consider converting to CSS variables:

:root {
    /* Colors */
    --color-primary: #1db954;
    --color-primary-hover: #1ed760;
    --color-primary-active: #14833b;
    --color-bg-dark: #121212;
    --color-surface-dark: #282828;
    --color-surface-light: #383838;
    --color-text-primary: #ffffff;
    --color-text-secondary: #b3b3b3;
    
    /* Spacing */
    --spacing-xs: 5px;
    --spacing-sm: 10px;
    --spacing-md: 12px;
    --spacing-lg: 20px;
    
    /* Border Radius */
    --radius-pill: 25px;
    --radius-card: 10px;
    --radius-embed: 12px;
    
    /* Transitions */
    --transition-default: 0.3s;
}

body {
    background-color: var(--color-bg-dark);
    color: var(--color-text-primary);
    padding: var(--spacing-lg);
}

Dark/Light Theme Toggle

With CSS variables, implementing theme switching becomes straightforward:

[data-theme="light"] {
    --color-bg-dark: #ffffff;
    --color-surface-dark: #f4f4f4;
    --color-text-primary: #000000;
}

[data-theme="dark"] {
    --color-bg-dark: #121212;
    --color-surface-dark: #282828;
    --color-text-primary: #ffffff;
}

Component Library Patterns

Reusable Button Class

.btn {
    padding: 12px;
    border: none;
    border-radius: 25px;
    font-size: 16px;
    cursor: pointer;
    transition: background-color 0.3s;
}

.btn-primary {
    background-color: #1db954;
    color: #ffffff;
}

.btn-primary:hover {
    background-color: #1ed760;
}

Card Component Pattern

.card {
    background-color: #282828;
    border-radius: 10px;
    padding: 20px;
    margin-top: 20px;
    color: #ffffff;
}

.card-interactive {
    cursor: pointer;
    transition: background-color 0.3s;
}

.card-interactive:hover {
    background-color: #383838;
}

Performance Considerations

CSS Loading Strategy

External Stylesheet: styles.css is linked for global styles
Inline Critical CSS: Page-specific styles inlined to reduce render blocking
Font Loading: Google Fonts loaded asynchronously with display=swap

<link href="https://fonts.googleapis.com/css2?family=Roboto:wght@400;700&display=swap" rel="stylesheet">

Transition Performance

All transitions use background-color which is GPU-accelerated:

transition: background-color 0.3s;

Avoid animating properties like width, height, or margin as they trigger layout recalculations. Stick to transform, opacity, and color properties for best performance.

Browser Compatibility

The styling uses standard CSS properties with broad support:

Flexbox: Supported in all modern browsers
Border Radius: Supported in all modern browsers
Transitions: Supported in all modern browsers
::placeholder: Supported in all modern browsers

No vendor prefixes are used. For maximum compatibility, consider adding:

input::-webkit-input-placeholder { color: #b3b3b3; }
input::-moz-placeholder { color: #b3b3b3; }
input:-ms-input-placeholder { color: #b3b3b3; }

Getting Started

Features

User Guide

Technical Reference

​Overview

​Color System

​Primary Color Palette

​Color Usage Matrix

​Typography

​Font Stack

​Font Sizes

​Component Styles

​Input Fields

​Buttons

​Suggestion Items

​Content Containers

​Audio Player

​Source Links Container

​Layout Patterns

​Page Structure

​Heading Styles

​Group Navigation

​Responsive Design

​Media Query Breakpoint

​Inline Responsive Styles

​Animation and Transitions

​Hover Transitions

​Text Decorations

​Accessibility Considerations

​Focus Management

​Color Contrast

Primary Text

Secondary Text

Green Accent

Button Text

​Cursor Feedback

​Styling Best Practices

​1. Border Radius Consistency

​2. Spacing System

​3. Layering System

​Inline Styling Patterns

​index.html Inline Styles

​index2.html Inline Styles

​Theming Recommendations

​CSS Custom Properties

​Dark/Light Theme Toggle

​Component Library Patterns

​Reusable Button Class

​Card Component Pattern

​Performance Considerations

​CSS Loading Strategy

​Transition Performance

​Browser Compatibility

​Next Steps

Architecture

API Integration

Build docs developers (and LLMs) love

Overview

Color System

Primary Color Palette

Color Usage Matrix

Typography

Font Stack

Font Sizes

Component Styles

Input Fields

Buttons

Suggestion Items

Content Containers

Audio Player

Source Links Container

Layout Patterns

Page Structure

Heading Styles

Group Navigation

Responsive Design

Media Query Breakpoint

Inline Responsive Styles

Animation and Transitions

Hover Transitions

Text Decorations

Accessibility Considerations

Focus Management

Color Contrast

Cursor Feedback

Styling Best Practices

1. Border Radius Consistency

2. Spacing System

3. Layering System

Inline Styling Patterns

index.html Inline Styles

index2.html Inline Styles

Theming Recommendations

CSS Custom Properties

Dark/Light Theme Toggle

Component Library Patterns

Reusable Button Class

Card Component Pattern

Performance Considerations

CSS Loading Strategy

Transition Performance

Browser Compatibility

Next Steps