SCSS Organization

This guide explains how SCSS files are organized in LamaPress and when to use custom SCSS vs Tailwind utilities.

Table of Contents

• Overview
• SCSS Structure
  • Main Entry Point
  • Base Styles
  • Variables
  • Section Styles
  • Component Styles
• Using SCSS
  • When to Use SCSS
  • @apply Directive
  • Custom CSS Variables
• File Organization
  • Component SCSS
  • Global SCSS
• Best Practices
  • 1. Prefer Tailwind
  • 2. Component-Specific Styles
  • 3. Use @apply
• Related Documentation

---

Overview

LamaPress uses SCSS for custom styles that can't be achieved with Tailwind utilities. SCSS files are organized by purpose: base styles, variables, sections, and components.

SCSS Structure

Main Entry Point

src/scss/styles.scss imports all SCSS files:

@import 'tailwindcss/base';
@import 'tailwindcss/components';
@import 'tailwindcss/utilities';

@import 'base/reset';
@import 'base/base';
@import 'base/typography';
@import 'base/swup';
@import 'base/scroll';
@import 'base/cookiebot';

@import 'variables/*.scss';
@import 'sections/*.scss';

@import '../../components/**/*.scss';

Import Order:

1. Tailwind base/components/utilities
2. Base styles
3. Variables
4. Section styles
5. Component styles

Base Styles

Located in src/scss/base/:

• reset.scss - CSS reset
• base.scss - Base element styles
• typography.scss - Base typography styles
• swup.scss - Swup page transition styles
• scroll.scss - Scroll behavior styles
• cookiebot.scss - Cookiebot integration styles

Variables

Located in src/scss/variables/:

• containers.scss - Container variables

Add custom CSS variables here:

:root {
  --custom-variable: value;
}

Section Styles

Located in src/scss/sections/:

• general.scss - General section styles

Add section-specific styles here if needed.

Component Styles

Component SCSS files are located alongside component PHP files:

components/
├── sections/
│   └── hero_basic/
│       ├── index.php
│       └── style.scss  ← Component SCSS

These are automatically imported via glob pattern.

Using SCSS

When to Use SCSS

Use SCSS when:

• Tailwind utilities can't achieve the desired effect
• Complex animations or transitions
• Component-specific styles that don't fit Tailwind patterns
• Custom CSS variables or calculations

Avoid SCSS for:

• Simple spacing, colors, typography (use Tailwind)
• Basic layouts (use Tailwind grid)
• Standard responsive patterns (use Tailwind breakpoints)

@apply Directive

Use Tailwind's @apply directive to compose Tailwind utilities:

.custom-class {
  @apply ll-heading-1 mb-md text-primary;
}

Benefits:

• Reuses Tailwind utilities
• Maintains consistency
• Easy to maintain

Custom CSS Variables

Define custom CSS variables in src/scss/variables/:

:root {
  --custom-spacing: 2rem;
  --custom-color: #ff5733;
}

Use in SCSS:

.custom-element {
  margin: var(--custom-spacing);
  color: var(--custom-color);
}

File Organization

Component SCSS

Create style.scss in component directory:

components/sections/hero_basic/
├── index.php
├── acf.php
└── style.scss

Example:

.ll-section--hero-basic {
  // Component-specific styles
  .hero-content {
    @apply ll-heading-1 mb-md;
  }
}

Global SCSS

Add global styles to appropriate directories:

• Base styles: src/scss/base/
• Variables: src/scss/variables/
• Section styles: src/scss/sections/

Best Practices

1. Prefer Tailwind

Use Tailwind utilities whenever possible:

// Good - uses Tailwind
.custom-class {
  @apply ll-heading-1 mb-md;
}

// Avoid - custom SCSS
.custom-class {
  font-size: 2rem;
  margin-bottom: 1.5rem;
}

2. Component-Specific Styles

Keep SCSS component-specific:

// Good - component-specific
.ll-section--hero-basic {
  .hero-content {
    // Styles here
  }
}

// Avoid - global styles in component
body {
  // Don't put global styles here
}

3. Use @apply

Compose Tailwind utilities with @apply:

// Good
.custom-button {
  @apply bg-signalPrimary text-signalPrimaryContrast px-lg py-md;
}

// Avoid - rewriting Tailwind
.custom-button {
  background-color: rgb(var(--signalPrimary));
  color: rgb(var(--signalPrimaryContrast));
  padding: var(--spacing-lg) var(--spacing-md);
}

Related Documentation

• Styling Overview - Styling approach
• Tailwind Configuration - Tailwind setup
• Component System - Component structure

---

Next Steps:

• Review Styling Overview for styling approach
• Check Tailwind Configuration for Tailwind setup
• See existing component SCSS files for examples