Skip to content

README-CSS.md

Latest commit

 

History

History
334 lines (260 loc) · 12.1 KB

README-CSS.md

File metadata and controls

334 lines (260 loc) · 12.1 KB

📚 CSS Architecture Guide - Tasks-v2

A comprehensive guide to the modular CSS architecture for the Tasks-v2 PWA

🏗️ Architecture Overview

The Tasks-v2 project uses a modular CSS architecture that replaces the previous monolithic approach. Instead of one large CSS file, we now have 12 focused modules that are easier to maintain, debug, and scale.

Core Principles:

  • ✅ Separation of Concerns: Each file has a specific purpose
  • ✅ Easy Debugging: Know exactly where to look for issues
  • ✅ Scalable: Add new features without breaking existing code
  • ✅ Team-Friendly: Multiple developers can work on different files
  • ✅ Performance: Better browser caching and load optimization

📁 File Structure

css/
├── core/                     ← Foundational styles
│   ├── variables.css         ← CSS custom properties (colors, fonts, etc.)
│   ├── base.css             ← Typography, resets, general styles
│   └── animations.css       ← Keyframes and animation utilities
├── themes/                   ← Theme variations
│   ├── modern.css           ← Modern theme (default Bootstrap-style)
│   └── retro.css            ← Retro theme (terminal/hacker aesthetic)
├── components/              ← Reusable UI components
│   ├── buttons.css          ← All button variants and states
│   ├── cards.css            ← Card layouts and containers
│   ├── forms.css            ← Form controls, inputs, validation
│   ├── navigation.css       ← Header, navbar, navigation elements
│   └── tasks.css            ← Task-specific components
├── pages/                   ← Page-specific styles
│   ├── index.css            ← Main page layouts and sections
│   └── about.css            ← About page specific styling
├── utilities/               ← Helper utilities
│   ├── responsive.css       ← Media queries and responsive utilities
│   └── accessibility.css   ← Focus states, a11y, reduced motion
├── styles.css              ← 🎯 MAIN FILE (imports all others)
└── styles-monolithic-backup.css ← Backup of old monolithic file

🎯 Quick Decision Guide: Where Do I Make Changes?

🔍 "I need to fix/change..."

What you're working on File to modify Example
Colors, fonts, theme variables core/variables.css Changing accent color, adding new theme variable
Typography, general layout core/base.css Font sizes, line heights, container styles
Animations, transitions core/animations.css Adding new keyframes, transition effects
Button styling components/buttons.css Button colors, hover effects, new button variants
Form inputs, validation components/forms.css Input styling, error states, form layouts
Header, navbar, navigation components/navigation.css Logo styling, menu items, navigation behavior
Task items, task list components/tasks.css Task cards, completion states, task actions
Card containers, layouts components/cards.css Card shadows, borders, card layouts
Home page specific layout pages/index.css Welcome section, task input area, page structure
About page specific layout pages/about.css Hero section, feature grid, README container
Mobile responsiveness utilities/responsive.css Breakpoints, mobile layouts, responsive utilities
Focus states, accessibility utilities/accessibility.css Keyboard navigation, screen reader support
Modern theme styling themes/modern.css Professional, Bootstrap-style overrides
Retro theme styling themes/retro.css Terminal, neon, hacker aesthetic

🎨 Theme System

How Themes Work:

  1. Variables (core/variables.css) define colors for both themes
  2. Theme files (themes/modern.css, themes/retro.css) override these variables
  3. Components use CSS custom properties that adapt automatically

Adding a New Theme:

/* 1. Add theme variables in core/variables.css */
[data-theme="dark"] {
  --primary-bg: #1a1a1a;
  --text-primary: #ffffff;
  --accent-color: #6366f1;
  /* ... more variables */
}

/* 2. Create themes/dark.css with theme-specific overrides */
[data-theme="dark"] .card {
  box-shadow: 0 4px 16px rgba(255, 255, 255, 0.1);
}

/* 3. Import in styles.css */
@import url('themes/dark.css');

Switching Themes:

  • HTML: <html data-theme="modern"> or <html data-theme="retro">
  • JavaScript: document.documentElement.setAttribute('data-theme', 'retro')

🧩 Component Development

Adding a New Component:

  1. Create the component file (e.g., components/modals.css)
  2. Follow the naming pattern: 
    /* Modal Component Styles for Tasks-v2 */
/* Modal dialogs, overlays, and popup styling */

/* ===== BASE MODAL STYLES ===== */
.modal {
  /* Base styles using CSS custom properties */
}

/* ===== THEME OVERRIDES ===== */
[data-theme="retro"] .modal {
  /* Retro-specific styling */
}

/* ===== RESPONSIVE ===== */
@media (max-width: 768px) {
  .modal {
    /* Mobile adjustments */
  }
}
  3. Import in styles.css: 
    @import url('components/modals.css');

Component Best Practices:

  • ✅ Use CSS custom properties (var(--accent-color)) instead of hardcoded values
  • ✅ Include both modern and retro theme overrides
  • ✅ Add responsive breakpoints
  • ✅ Follow the established naming conventions
  • ✅ Include accessibility considerations

📱 Responsive Development

Breakpoint Strategy:

/* Mobile First Approach */
.component { /* Mobile styles (default) */ }

@media (min-width: 576px) { /* Small tablets */ }
@media (min-width: 768px) { /* Tablets */ }
@media (min-width: 992px) { /* Desktop */ }
@media (min-width: 1200px) { /* Large desktop */ }

Where to Add Responsive Styles:

  1. Component-specific responsive: Add to the component file
  2. Global responsive utilities: Add to utilities/responsive.css
  3. Page-specific responsive: Add to the appropriate page file

♿ Accessibility Development

Key Areas to Consider:

  • Focus States: Clear, visible focus indicators
  • High Contrast: Support for prefers-contrast: high
  • Reduced Motion: Respect prefers-reduced-motion: reduce
  • Touch Targets: Minimum 44px for touch devices
  • Screen Readers: Proper ARIA labels and semantic HTML

Where to Add Accessibility Styles:

  • Global a11y utilities: utilities/accessibility.css
  • Component-specific a11y: Within the component file
  • Theme-specific a11y: Within the theme file

🔧 Common Development Workflows

Scenario 1: "I need to fix a button style"

1. Open components/buttons.css
2. Find the relevant button class (.btn, .btn-primary, etc.)
3. Make changes
4. Test in both Modern and Retro themes
5. Check responsive behavior

Scenario 2: "I need to add a new page"

1. Create pages/new-page.css
2. Add page-specific styles following the pattern
3. Import in styles.css: @import url('pages/new-page.css');
4. Test across all themes and breakpoints

Scenario 3: "I need to modify the color scheme"

1. Open core/variables.css
2. Modify CSS custom properties in :root (modern) or [data-theme="retro"]
3. Changes will automatically apply across all components
4. Test thoroughly across all pages and components

Scenario 4: "I need to debug a styling issue"

1. Identify what type of element has the issue
2. Use the Quick Decision Guide to find the right file
3. Use browser dev tools to confirm which file contains the styles
4. Make targeted changes in the appropriate file

🚀 Performance Considerations

CSS Loading Strategy:

  • Single import chain: styles.css imports all modules
  • Browser caching: Individual modules can be cached separately
  • Critical path: Core styles load first, utilities last

Optimization Tips:

  • ✅ Keep individual files under 500 lines
  • ✅ Avoid deep nesting (max 3 levels)
  • ✅ Use CSS custom properties instead of repeated values
  • ✅ Group related styles together
  • ✅ Comment complex sections

🐛 Debugging Guide

CSS Not Loading?

  1. Check browser dev tools Network tab for failed imports
  2. Verify file paths in styles.css are correct
  3. Check for syntax errors in individual files
  4. Ensure server is serving .css files properly

Styles Not Applying?

  1. Check CSS specificity (avoid !important)
  2. Verify theme attribute: <html data-theme="modern">
  3. Check if styles are in the right file according to the architecture
  4. Use browser dev tools to see which styles are being overridden

Theme Switching Issues?

  1. Check JavaScript theme switching logic
  2. Verify CSS custom properties are defined for both themes
  3. Check that theme-specific overrides use correct selectors
  4. Test with browser dev tools by manually changing data-theme

📋 Code Review Checklist

Before Submitting CSS Changes:

  • Right file: Changes are in the appropriate file according to architecture
  • CSS variables: Used custom properties instead of hardcoded values
  • Both themes: Tested in both Modern and Retro themes
  • Responsive: Works across all breakpoints (mobile, tablet, desktop)
  • Accessibility: Includes proper focus states and a11y considerations
  • Performance: No unnecessary !important declarations
  • Comments: Complex sections are well-documented
  • Consistency: Follows established patterns and naming conventions

🎓 Learning Resources

Understanding the Architecture:

  1. Start here: Review styles.css to understand the import structure
  2. Study patterns: Look at existing component files for structure examples
  3. CSS Custom Properties: Learn how our theming system works
  4. Responsive Design: Understand our mobile-first approach

Recommended Reading Order:

  1. core/variables.css - Understand the theming system
  2. core/base.css - See foundational styles
  3. components/buttons.css - Good example of component structure
  4. themes/retro.css - Understanding theme overrides
  5. utilities/responsive.css - Responsive patterns

🆘 Getting Help

Common Questions:

Q: "Where do I add global styles?"
A: core/base.css for typography and layout, core/variables.css for colors and theme variables.

Q: "How do I add a new color?"
A: Add CSS custom property in core/variables.css for both themes, then use var(--your-color) in components.

Q: "My responsive styles aren't working."
A: Check if you're using mobile-first approach and that breakpoints match our standard breakpoints.

Q: "How do I test both themes?"
A: Use browser dev tools to change data-theme attribute, or use the theme toggle button in the app.

Q: "Can I modify the import order in styles.css?"
A: Only with careful consideration - the order prevents specificity conflicts and ensures proper cascade.

🎯 Quick Reference

File Purpose Summary:

  • styles.css → Main import file (don't add styles here)
  • core/* → Foundation (variables, base styles, animations)
  • themes/* → Theme variations (modern, retro)
  • components/* → UI components (buttons, forms, cards, etc.)
  • pages/* → Page-specific layouts
  • utilities/* → Helper utilities (responsive, accessibility)

CSS Custom Properties Naming:

  • --primary-bg → Background colors
  • --text-primary → Text colors
  • --accent-color → Interactive elements
  • --border-color → Borders and lines
  • --success-color → Status colors

Remember: When in doubt, check existing patterns in similar files! 🎯

Last updated: July 2025 | Tasks-v2 Modular CSS Architecture