npm package: @rhavenside/scaffold
Description: A pure layout framework for structural arrangement of content in the browser
Latest version: 1.1.9

# Baseline Scaffold

A pure layout framework for structural arrangement of content in the browser.

## Framework Goals

Scaffold is a pure layout framework. It solves exclusively the problem of structural arrangement of content in the browser.


**The goal is** to arrange HTML content in an organized, responsive, and predictable way – so that any design system can be applied on top without fighting against it.

Scaffold should feel like: *"This is how browser layouts should have worked by default."*

## Installation

### As npm Package

Install Baseline Scaffold in your project:

```bash
npm install @rhavenside/scaffold
```

Then import the CSS in your project:

```html
<link rel="stylesheet" href="node_modules/baseline-scaffold/dist/scaffold.css">
```

Or if you're using a bundler (webpack, vite, etc.):

```javascript
import 'baseline-scaffold/dist/scaffold.css';
```



## Usage

Include the compiled CSS in your project:

```html
<link rel="stylesheet" href="path/to/scaffold.css">
```

## Architecture

Scaffold consists of five clearly separated modules:

1. **Container System**
2. **Grid System**
3. **Stack System**
4. **Spacing Utilities**
5. **Responsive Rules**

Each module can be used independently. No requirement to use everything.

## 1. Container System

Containers define boundaries and reading areas. They control width, inner spacing, and horizontal centering.

### Base Container

```html
<div class="scaffold-container">
  <!-- Content -->
</div>
```

### Container Variants

- `.scaffold-container--narrow` (640px) - For text, articles
- `.scaffold-container--normal` (1200px) - Standard for page content
- `.scaffold-container--wide` (1600px) - For dashboards
- `.scaffold-container--full` (100%) - Edge-to-edge

### Vertical Padding (top/bottom)

Containers have horizontal padding by default. For vertical padding, modifiers can be used:

- `.scaffold-container--padding-vertical` - Responsive vertical padding
- `.scaffold-container--padding-vertical-xs` - Extra small (0.5rem)
- `.scaffold-container--padding-vertical-sm` - Small (1rem)
- `.scaffold-container--padding-vertical-md` - Medium (1.5rem)
- `.scaffold-container--padding-vertical-lg` - Large (2rem)
- `.scaffold-container--padding-vertical-xl` - Extra large (3rem)
- `.scaffold-container--padding-vertical-xxl` - Extra extra large (4rem)

### Example

```html
<!-- Narrow container for articles -->
<article class="scaffold-container scaffold-container--narrow">
  <h1>Article Title</h1>
  <p>Article content...</p>
</article>

<!-- Container with vertical padding -->
<div class="scaffold-container scaffold-container--padding-vertical">
  <p>Content with spacing top and bottom</p>
</div>

<!-- Wide container for dashboard -->
<div class="scaffold-container scaffold-container--wide">
  <!-- Dashboard content -->
</div>
```

## 2. Grid System

The grid organizes content two-dimensionally: columns and rows. Uses CSS Grid for flexible layouts.

### Base Grid

```html
<div class="scaffold-grid scaffold-grid--cols-3">
  <div>Item 1</div>
  <div>Item 2</div>
  <div>Item 3</div>
</div>
```

### Column Variants

- `.scaffold-grid--cols-2` - 2 columns
- `.scaffold-grid--cols-3` - 3 columns
- `.scaffold-grid--cols-4` - 4 columns
- `.scaffold-grid--cols-5` - 5 columns
- `.scaffold-grid--cols-6` - 6 columns
- `.scaffold-grid--cols-12` - 12 columns (for flexible layouts)

### Gap Variants

- `.scaffold-grid--gap-xs` - Extra small
- `.scaffold-grid--gap-sm` - Small
- `.scaffold-grid--gap-md` - Medium (default)
- `.scaffold-grid--gap-lg` - Large
- `.scaffold-grid--gap-xl` - Extra large
- `.scaffold-grid--gap-xxl` - Extra extra large

### Grid Item Spanning

```html
<div class="scaffold-grid scaffold-grid--cols-12">
  <div class="scaffold-grid__item--span-6">Spans 6 columns</div>
  <div class="scaffold-grid__item--span-6">Spans 6 columns</div>
  <div class="scaffold-grid__item--span-4">Spans 4 columns</div>
  <div class="scaffold-grid__item--span-4">Spans 4 columns</div>
  <div class="scaffold-grid__item--span-4">Spans 4 columns</div>
</div>
```

### Example

```html
<div class="scaffold-grid scaffold-grid--cols-3 scaffold-grid--gap-lg">
  <div>Card 1</div>
  <div>Card 2</div>
  <div>Card 3</div>
</div>
```

## 3. Stack System

Stacks solve the most common layout problem: arranging elements cleanly with consistent spacing.

### Base Stack

```html
<div class="scaffold-stack">
  <div>Item 1</div>
  <div>Item 2</div>
  <div>Item 3</div>
</div>
```

### Direction Variants

- `.scaffold-stack--vertical` - Vertical (default)
- `.scaffold-stack--horizontal` - Horizontal

### Spacing Variants

- `.scaffold-stack--spacing-xs` - Extra small
- `.scaffold-stack--spacing-sm` - Small
- `.scaffold-stack--spacing-md` - Medium (default)
- `.scaffold-stack--spacing-lg` - Large
- `.scaffold-stack--spacing-xl` - Extra large
- `.scaffold-stack--spacing-xxl` - Extra extra large

### Alignment (for horizontal stacks)

- `.scaffold-stack--align-start` - Top/left
- `.scaffold-stack--align-center` - Centered
- `.scaffold-stack--align-end` - Bottom/right
- `.scaffold-stack--align-stretch` - Stretched

### Justification (for horizontal stacks)

- `.scaffold-stack--justify-start` - Left
- `.scaffold-stack--justify-center` - Centered
- `.scaffold-stack--justify-end` - Right
- `.scaffold-stack--justify-between` - Between
- `.scaffold-stack--justify-around` - Around

### Example

```html
<!-- Vertical stack for form -->
<form class="scaffold-stack scaffold-stack--spacing-md">
  <input type="text" placeholder="Name">
  <input type="email" placeholder="Email">
  <button type="submit">Submit</button>
</form>

<!-- Horizontal stack for buttons -->
<div class="scaffold-stack scaffold-stack--horizontal scaffold-stack--justify-end">
  <button>Cancel</button>
  <button>Save</button>
</div>
```

## 4. Spacing Utilities

General utility classes for vertical and horizontal spacing. Can be used anywhere, not only in containers/stacks/grids.

### Vertical Spacing (Padding top/bottom)

- `.scaffold-padding-vertical-xs` - Extra small (0.5rem)
- `.scaffold-padding-vertical-sm` - Small (1rem)
- `.scaffold-padding-vertical-md` - Medium (1.5rem)
- `.scaffold-padding-vertical-lg` - Large (2rem)
- `.scaffold-padding-vertical-xl` - Extra large (3rem)
- `.scaffold-padding-vertical-xxl` - Extra extra large (4rem)

### Individual Spacing

- `.scaffold-padding-top-xs` to `.scaffold-padding-top-xxl` - Top only
- `.scaffold-padding-bottom-xs` to `.scaffold-padding-bottom-xxl` - Bottom only
- `.scaffold-padding-left-xs` to `.scaffold-padding-left-xxl` - Left only
- `.scaffold-padding-right-xs` to `.scaffold-padding-right-xxl` - Right only

### Horizontal Spacing (Padding left/right)

- `.scaffold-padding-horizontal-xs` to `.scaffold-padding-horizontal-xxl` - Left and right

### All-Side Padding

- `.scaffold-padding-xs` to `.scaffold-padding-xxl` - All sides (top, right, bottom, left)

### Margin Utilities (external spacing)

- `.scaffold-margin-vertical-xs` to `.scaffold-margin-vertical-xxl` - Top and bottom
- `.scaffold-margin-top-xs` to `.scaffold-margin-top-xxl` - Top only
- `.scaffold-margin-bottom-xs` to `.scaffold-margin-bottom-xxl` - Bottom only
- `.scaffold-margin-horizontal-xs` to `.scaffold-margin-horizontal-xxl` - Left and right
- `.scaffold-margin-xs` to `.scaffold-margin-xxl` - All sides

### Example

```html
<!-- Vertical padding on an element -->
<section class="scaffold-padding-vertical-lg">
  <h2>Heading</h2>
  <p>Content with spacing top and bottom</p>
</section>

<!-- Only spacing on top -->
<div class="scaffold-margin-top-md">
  <p>Element with spacing on top</p>
</div>
```

## 5. Responsive Rules

Responsiveness is explicit and traceable. Breakpoints are clearly named and consistent.

### Breakpoints

- **Mobile**: 0px (Mobile-First)
- **Tablet**: 768px
- **Desktop**: 1024px
- **Wide**: 1440px

### Responsive Grid

```html
<!-- 2 columns on Tablet+ -->
<div class="scaffold-grid scaffold-grid--responsive-2">
  <div>Item 1</div>
  <div>Item 2</div>
</div>

<!-- 3 columns on Desktop+ -->
<div class="scaffold-grid scaffold-grid--responsive-3">
  <div>Item 1</div>
  <div>Item 2</div>
  <div>Item 3</div>
</div>

<!-- 4 columns on Desktop+ -->
<div class="scaffold-grid scaffold-grid--responsive-4">
  <div>Item 1</div>
  <div>Item 2</div>
  <div>Item 3</div>
  <div>Item 4</div>
</div>
```

### Responsive Stack

```html
<!-- Horizontal on Tablet+, vertical on Mobile -->
<div class="scaffold-stack scaffold-stack--responsive-horizontal">
  <div>Item 1</div>
  <div>Item 2</div>
  <div>Item 3</div>
</div>
```

### Automatic Responsive Behavior

**Grid:** All grids with multiple columns automatically become 1 column on Mobile.

**Stack:** Horizontal stack with `.scaffold-stack--responsive` automatically becomes vertical on Mobile.

## Combined Examples

### Card Layout

```html
<div class="scaffold-container">
  <div class="scaffold-grid scaffold-grid--responsive-3 scaffold-grid--gap-lg">
    <div class="scaffold-stack scaffold-stack--spacing-sm">
      <h3>Card Title</h3>
      <p>Card content</p>
    </div>
    <div class="scaffold-stack scaffold-stack--spacing-sm">
      <h3>Card Title</h3>
      <p>Card content</p>
    </div>
    <div class="scaffold-stack scaffold-stack--spacing-sm">
      <h3>Card Title</h3>
      <p>Card content</p>
    </div>
  </div>
</div>
```

### Form Layout

```html
<div class="scaffold-container scaffold-container--narrow">
  <form class="scaffold-stack scaffold-stack--spacing-md">
    <div class="scaffold-stack scaffold-stack--spacing-sm">
      <label>Name</label>
      <input type="text">
    </div>
    <div class="scaffold-stack scaffold-stack--spacing-sm">
      <label>Email</label>
      <input type="email">
    </div>
    <div class="scaffold-stack scaffold-stack--horizontal scaffold-stack--justify-end">
      <button type="button">Cancel</button>
      <button type="submit">Submit</button>
    </div>
  </form>
</div>
```



## Expected Result

> If a project is ugly, the design is to blame.  
> If it's broken, the layout is to blame.  
> Scaffold ensures that the latter rarely happens.

## License

MIT