CSS Architecture Documentation

This project uses a token-based, modular CSS architecture to maintain consistency and prevent future styling conflicts.

File Structure

src/assets/styles/
├── tokens.css              # Design tokens (colors, typography, spacing)
├── typography.css          # All typography rules
├── components/
│   ├── header.css          # Navigation & header
│   ├── footer.css          # Footer
│   └── layout.css          # Grid, containers, blog layout
├── projects/
│   └── footnotes.css       # Footnotes project overrides
└── index.css               # Main import file

Architecture Principles

1. Single Source of Truth

All design values are defined once in tokens.css as CSS custom properties:

:root {
  --font-size-body: 1.2rem;
  --color-accent-burgundy: #8B4049;
  --spacing-lg: 2rem;
}

2. Typography System

All text styling is unified in typography.css. Body text elements automatically inherit consistent sizing:

.body-text,
.page-wrapper,
.post-body,
.post-excerpt,
.project-description {
    font-size: var(--font-size-body);  /* Always 1.2rem */
}

This prevents the issue we had where project pages had different mobile font sizes.

3. Component Isolation

Each major UI component has its own file:

• Header/navigation → components/header.css
• Footer → components/footer.css
• Page layouts → components/layout.css

4. Project Overrides Only

Project-specific CSS files (projects/*.css) should only contain true customizations, not redefinitions:

/* ✅ GOOD - Only unique styling */
.project-cta {
  background: var(--color-accent-beige);
}

/* ❌ BAD - Redefining shared styles */
.project-description {
  font-size: 1.2rem;  /* This is already in typography.css */
}

How to Make Changes

Changing Typography

1. Update token in tokens.css:

   --font-size-body: 1.3rem;  /* Was 1.2rem */

2. Change automatically applies to:

   • Blog posts
   • Blog index
   • About page
   • Project pages

Adding New Colors

1. Add to tokens.css:

   --color-accent-purple: #8B4499;

2. Use anywhere:

   .my-element {
     color: var(--color-accent-purple);
   }

Creating New Components

1. Create file in components/:

   /* components/sidebar.css */
   .sidebar {
     width: var(--sidebar-width);
     padding: var(--spacing-lg);
   }

2. Import in index.css:

   @import './components/sidebar.css';

Mobile Responsive Changes

Responsive breakpoints are managed in the component where they're needed:

• Typography responsive rules → typography.css
• Header responsive rules → components/header.css
• Layout responsive rules → components/layout.css

Benefits

✅ Consistency: Change --font-size-body once, updates everywhere ✅ Maintainability: Easy to find where styles are defined ✅ No Drift: Typography automatically consistent across all pages ✅ Clear Overrides: Project CSS only contains actual customizations ✅ Better Organization: Logical separation of concerns

Migration Notes

The old monolithic index.css has been backed up to index.css.backup.

What Was Changed:

1. Extracted design values to tokens.css
2. Unified all typography in typography.css
3. Separated header, footer, and layout into component files
4. Simplified project CSS to use tokens and remove redundancy
5. Replaced index.css with import-based structure

What Stayed the Same:

• All visual appearance and behavior
• Responsive breakpoints (768px, 480px)
• Color palette
• Font sizes
• Spacing values

Common Tasks

Find where a style is defined:

• Colors, spacing, fonts → tokens.css
• Body text, headings, links → typography.css
• Navigation, mobile menu → components/header.css
• Footer → components/footer.css
• Page layouts, blog structure → components/layout.css
• Project customizations → projects/*.css

Add a new project:

1. Create projects/myproject.css
2. Add project-specific overrides only
3. Import in index.css:

   @import './projects/myproject.css';

Questions?

If you're unsure where a style should go, follow this decision tree:

1. Is it a design value (color, size, spacing)? → tokens.css
2. Is it typography? → typography.css
3. Is it navigation/header? → components/header.css
4. Is it footer? → components/footer.css
5. Is it page layout? → components/layout.css
6. Is it project-specific? → projects/*.css