Standardize styling approach across frontend

[bitcoinbrisbane]

Priority: MEDIUM

Problem

The codebase mixes three styling approaches inconsistently:

1. CSS Modules (Primary)

   • Table.css (485 LOC)
   • Footer.css (219 LOC)
   • Badge.css (214 LOC)

2. Inline Styles (Common in modals)

   style={{ backgroundColor: colors.ui.bgDark, border: \`1px solid \${colors.ui.borderColor}\` }}

3. Tailwind Classes (Layout)

   className="flex justify-between gap-1 lg:gap-2 mb-1 rounded-lg"

Issues:

• Inconsistent patterns make code harder to maintain
• Inline styles scattered throughout (especially modals)
• Duplicate gradient definitions across files
• No design system established

Solution

1. Standardize on CSS Modules + Tailwind
2. Move all inline styles to CSS modules
3. Use CSS variables for colors (leverage existing colorConfig.ts)
4. Create shared gradient/style variables

Acceptance Criteria

• Audit all inline styles in components
• Migrate inline styles to CSS modules
• Create CSS variables for common colors
• Document styling conventions
• Update contributing guide with styling standards

Related

Parent issue: #45

[bitcoinbrisbane]

Objective

Establish and enforce consistent styling standards across the entire frontend application.

Current Issues:

• Mix of CSS Modules, inline styles, and utility classes
• Inconsistent naming conventions
• Hard-coded colors and spacing values
• No clear component hierarchy
• Difficult to maintain and update styles
• Theme switching not properly supported

Proposed Styling Approach:

Technology Stack Decision:

Choose ONE primary method:

Option 1: CSS Modules + CSS Variables

• Scoped styles per component
• CSS custom properties for theming
• Familiar CSS syntax
• Good performance

Option 2: Styled Components

• CSS-in-JS with TypeScript support
• Dynamic styling based on props
• Automatic critical CSS
• Theme provider built-in

Option 3: Tailwind CSS

• Utility-first approach
• Rapid development
• Smaller bundle size
• Consistent design tokens

Recommendation: CSS Modules + Tailwind for utilities + CSS Variables for theming

Design Tokens:

Colors:

Spacing:

• Base unit: 4px or 8px
• Scale: 0.25rem, 0.5rem, 1rem, 1.5rem, 2rem, 3rem, 4rem
• Use spacing tokens instead of arbitrary values

Typography:

• Font families: Primary, Monospace
• Type scale: xs, sm, base, lg, xl, 2xl, 3xl
• Line heights: tight, normal, relaxed
• Font weights: normal, medium, semibold, bold

Breakpoints:

• Mobile: 320px - 767px
• Tablet: 768px - 1023px
• Desktop: 1024px+
• Large: 1440px+

Implementation Guidelines:

File Organization:

Naming Conventions:

• BEM for CSS class names: block__element--modifier
• PascalCase for component files: PlayerCard.tsx
• camelCase for CSS Module imports: styles.playerCard
• Kebab-case for CSS custom properties: --color-primary

Best Practices:

• Use CSS variables for all theme-able values
• Avoid inline styles (use className)
• Mobile-first responsive design
• Prefer composition over inheritance
• Keep specificity low (avoid !important)
• Use semantic HTML elements

Migration Plan:

1. Define design tokens and create CSS variables
2. Set up theming system
3. Create utility classes for common patterns
4. Update component library to use new system
5. Gradually migrate existing components
6. Remove old styling approaches
7. Document standards in style guide

Acceptance Criteria:

• Single source of truth for styles
• All colors use CSS variables
• Consistent spacing throughout app
• Theme switching works everywhere
• No inline styles in components
• Style guide documentation complete
• All developers trained on new standards