SCSS Architecture Documentation

Overview

This document provides comprehensive documentation for the Smollan Technologies website SCSS architecture. The system uses a consolidated, modular approach with SCSS compilation to generate the final CSS output.

Current Architecture Summary

Consolidated File Structure

src/assets/scss/
├── main.scss                      # Main import file with new structure
├── _media-queries.scss            # Responsive breakpoints (187 lines)
├── _tokens.scss                   # 🆕 CONSOLIDATED: All design tokens, variables & functions
├── _base.scss                     # 🆕 CONSOLIDATED: Reset, typography & accessibility
├── _utilities.scss                # 🆕 CONSOLIDATED: All utility classes
├── _layout.scss                   # 🆕 CONSOLIDATED: Grid, containers & sections
├── _components.scss               # 🆕 CONSOLIDATED: Core components (cards, buttons, etc.)
├── abstracts/                     # Essential mixins only
│   ├── _mixins.scss               # Core mixins (554 lines)
│   ├── _mixins-advanced.scss      # Advanced mixins (459 lines)
│   └── _mixins-examples.scss      # Mixin examples (209 lines)
├── animations/
│   └── _animations.scss           # Scroll animations (168 lines)
├── components/                    # Complex components (kept separate)
│   ├── _navigation.scss           # Navigation system (691 lines)
│   ├── _forms.scss                # Form components (376 lines)
│   ├── _hero.scss                 # Hero sections (148 lines)
│   ├── _footer.scss               # Footer styles (544 lines)
│   ├── _carousel.scss             # Carousel component (527 lines)
│   ├── _tabs.scss                 # Tab components (498 lines)
│   ├── _pagination.scss           # Pagination components (205 lines)
│   ├── _job-cards.scss            # Job card components (353 lines)
│   ├── _post.scss                 # Post/blog components (346 lines)
│   ├── _quotes.scss               # Quote components (116 lines)
│   ├── _timeline.scss             # Timeline components (79 lines)
│   ├── _metrics.scss              # Metrics display (118 lines)
│   └── _social-links.scss         # Social media links (160 lines)
├── pages/                         # Page-specific styles
│   ├── _heritage.scss             # Heritage page (53 lines)
│   ├── _job-detail.scss           # Job detail pages (297 lines)
│   ├── _job-layouts.scss          # Job layout variants (26 lines)
│   ├── _story.scss                # Story page (15 lines)
│   └── _thank-you.scss            # Thank you page (55 lines)
└── scss-backup/                   # Complete backup of original 43-file system

🆕 Consolidated Architecture Benefits

Design Philosophy

This project uses a consolidated component-based design system with streamlined SCSS architecture for improved maintainability.

Core Principles

  1. Logical grouping: Related functionality consolidated into single files
  2. Reduced complexity: 33% fewer files to manage
  3. Preserved functionality: 100% backward compatibility maintained
  4. Clear separation: Complex components kept separate when warranted

🎨 New SCSS System Components

1. Design Tokens (_tokens.scss)

Consolidates: Variables, functions, breakpoints, design tokens

// All CSS custom properties, SCSS variables, and utility functions
:root {
  --color-primary: #0879bf;
  --space-lg: 2rem;
  // ... all design tokens
}

// SCSS functions and variables for generation
@function rem($px) { ... }
$breakpoints: (mobile: 768px, tablet: 1024px, desktop: 1200px);

2. Base Styles (_base.scss)

Consolidates: Reset, typography, accessibility

// CSS reset, typography system, accessibility helpers
* { box-sizing: border-box; }
.section-title { font-size: var(--font-size-4xl); }
.sr-only { position: absolute; width: 1px; }

3. Utilities (_utilities.scss)

Consolidates: Spacing, text, background, display, positioning

// All utility classes in one place
.mb-lg { margin-bottom: var(--space-lg) !important; }
.text-center { text-align: center !important; }
.bg-primary { background: var(--color-primary) !important; }

4. Layout (_layout.scss)

Consolidates: Containers, grid, sections

// Layout system components
.container { max-width: var(--container-max-width); }
.grid--auto-fit-300 { grid-template-columns: repeat(auto-fit, minmax(300px, 1fr)); }
.section { padding: var(--section-padding); }

5. Components (_components.scss)

Consolidates: Cards, buttons, icons, filters, lists, badges

// Core reusable components
.card { background: var(--color-background-white); }
.cta-button { background: var(--gradient-primary); }
.filter-button { border: 1px solid var(--color-primary-dark); }

Essential CSS Classes (Unchanged)

Card System

// Base card classes - unchanged
.card                    // Base card styling
.card--primary          // Primary card variant
.card--secondary        // Secondary card variant
.card--centered         // Centered text alignment
.glass-card             // Glass morphism effect
.scroll-fade            // Scroll animation

// Card structure - unchanged  
.card__title            // Standard card title
.card__description      // Standard card description
.card__header           // Card header sections

Layout Classes

// Section & layout - unchanged
.section                // Base section with padding
.section--light         // Light background variant
.container              // Standard container with max-width
.grid--auto-fit-300     // Auto-fit grid with 300px min

Filter & Interactive Elements

// Filter system - unchanged
.filter-button          // Base filter button
.filter-button.active   // Active state
.content-filters        // Container for content filters
.post-filters-section   // Posts page filter section

Build Process (Unchanged)

Development

npm run dev          # Development server with SCSS watch
npm run scss:watch   # SCSS watch mode only
npm run serve        # Eleventy server only

Production

npm run scss:build   # Single SCSS build
npm run build        # Complete build
npm run build:prod   # Production build (minified)

Output

Usage Patterns (Unchanged)

Creating New Components

  1. Use existing design tokens from _tokens.scss
  2. Build with existing card/section base classes
  3. Follow BEM-like naming conventions
  4. Add new styles to appropriate consolidated file

Common Class Combinations

<!-- Primary card with animation - same as before -->
<div class="card card--primary scroll-fade">
  <div class="card__header">
    <h3 class="card__title">Title</h3>
  </div>
  <p class="card__description">Description</p>
</div>

<!-- Section with light background - same as before -->
<section class="section section--light">
  <div class="container">
    <div class="grid grid--auto-fit-300">
      <!-- Content -->
    </div>
  </div>
</section>

🆕 Maintenance Guidelines

Adding New Styles

  1. Check consolidated files first: All basic components are in _components.scss
  2. Use appropriate file:
  3. Follow import order: New component files must be imported in main.scss
  4. Use design tokens: Reference CSS custom properties instead of hardcoded values

File Selection Guide

Performance Considerations

Migration Notes

What Changed

What Stayed the Same

Backup Available

Consolidated System Benefits

  1. Easier Maintenance: Find related styles in logical files
  2. Faster Development: Fewer files to navigate and manage
  3. Better Organization: Clear separation of concerns
  4. Reduced Duplication: Eliminated redundant declarations
  5. Improved Performance: Streamlined build process
  6. Future-Proof: Scalable architecture for continued development

Key Files for Reference

Memory Annotations

JavaScript and Scroll Animations