Modular CSS Architecture

This project uses a modular CSS architecture to improve organization, maintainability, and developer experience.

Structure

The CSS is organized in the following structure:

assets/css/
├── core/                      # Core styles
│   ├── animations.css         # Transitions and animations
│   ├── base.css               # Base elements
│   ├── typography.css         # Typography system
│   └── variables.css          # Design tokens & theme variables
├── components/                # Component styles
│   ├── cards.css              # Card components
│   ├── navigation.css         # Navigation elements
│   ├── terminal.css           # Terminal styles
│   └── ...
├── utilities/                 # Utility styles
│   ├── colors.css             # Color utilities
│   └── responsive.css         # Media queries
├── style.css                  # Production CSS (combined)
├── style-modular.css          # Development CSS (imports)
└── build-css.js               # Build script for production

Development Workflow

During development, we use the modular CSS approach for better organization:

  1. Edit the specific CSS module files in core/, components/, or utilities/
  2. Jekyll will use style-modular.css which imports all the modules
  3. Changes will be reflected immediately during development

Production Build

For production, we combine all CSS modules into a single file to reduce HTTP requests:

  1. Run npm run build:css or use the production build script
  2. The build script processes all imports and outputs a single style.css file
  3. Jekyll will use this combined file in production mode

Adding New Components

To add a new component:

  1. Create a new CSS file in the appropriate directory (e.g., components/my-component.css)
  2. Add the component's styles to this file
  3. Import the file in style-modular.css

Using the Styles

The HTML includes handle loading the appropriate CSS file based on the environment:


  <!-- Use compiled CSS in production -->
  <link rel="stylesheet" href="/assets/css/style.css">

Commands

  • npm run build:css - Build the CSS for production
  • npm run start - Start Jekyll development server with live reload
  • ./build.sh -p - Full production build including CSS

Best Practices

  1. Keep each CSS file focused on a specific purpose
  2. Use variables from variables.css for consistency
  3. Follow the existing naming conventions
  4. Document complex CSS with comments
  5. Test both development and production environments