Convert CSS styles to use CSS custom properties for theming support

[deltork]

Summary

Refactor existing CSS styles in web components to use CSS custom properties (variables) instead of hardcoded values. This will enable easier theming, customization, and style overrides.

Problem

Currently, the web component use hardcoded CSS values for colors, spacing, typography, and other design tokens. This makes it difficult to:

• Create custom themes
• Allow users to customize the appearance
• Override styles without using !important
• Maintain design consistency when making style updates

Proposed Solution

Convert hardcoded CSS values to CSS custom properties following this pattern:

Before:

.read-along-container {
  background-color: #ffffff;
  color: #333333;
  border: 1px solid #cccccc;
  padding: 16px;
  border-radius: 4px;
}

After:

.read-along-container {
  background-color: var(--read-along-bg-color, #ffffff);
  color: var(--read-along-text-color, #333333);
  border: var(--read-along-border-width, 1px) solid var(--component-border-color, #cccccc);
  padding: var(--read-along-padding, 16px);
  border-radius: var(--read-along-border-radius, 4px);
}

Implementation Details

1. Identify CSS Properties to Convert

Focus on converting these types of values:

• Colors (text, background, borders, shadows)
• Spacing (padding, margin, gaps)
• Typography (font sizes, line heights, font weights)
• Borders (width, radius)
• Shadows and effects
• Transitions and animations

2. Naming Convention

Use a consistent naming pattern for CSS variables:

• --component-name-property-variant (e.g., --button-bg-color-primary)
• --component-name-property for single values (e.g., --card-padding)
• Use semantic names where possible (e.g., --text-color-primary vs --color-gray-900)

3. Default Values

Always provide fallback values in the var() function to ensure components work even when variables aren't defined.

4. Documentation

Create documentation showing:

• Available CSS variables for each component
• Example of how to override variables
• Sample theme configurations

Benefits

• Easier theming: Users can override variables to create custom themes
• Better maintainability: Central control of design tokens
• Consistency: Shared variables ensure consistent styling
• Flexibility: No need for !important to override styles
• Future-proof: Foundation for advanced theming features

Acceptance Criteria

• All hardcoded color values converted to CSS custom properties
• All spacing values (padding, margin) converted to variables
• Typography-related values converted to variables
• Border and border-radius values converted to variables
• All variables include fallback values
• Variable naming follows established convention
• Documentation updated with available CSS variables
• Existing functionality remains unchanged
• Components still work when variables are not defined

Example Usage After Implementation

/* Custom theme */
:root {
  --read-along-bg-color: #f8f9fa;
  --read-along-text-color: #212529;
  --read-along-border-color: #dee2e6;
  --read-along-padding: 20px;
}

/* Dark theme */
[data-theme="dark"] {
  --read-along-bg-color: #343a40;
  --read-along-text-color: #f8f9fa;
  --read-along-border-color: #495057;
}

---