> ## Oymyakon DS index
> Fetch the full index at: https://super-dollop-pzmo65r.pages.github.io/llms.txt
> HTML preview: https://super-dollop-pzmo65r.pages.github.io/grid.html
> Source: specs/components/grid/grid.md

---

# Grid Web · Oymyakon DS 3

> Responsive column grid for web interfaces. Defines the layout container system used across all web surfaces.

**Version:** 1.0.0 · **Status:** Draft

---

## 1. Overview

The web grid provides a consistent column-based layout system across five breakpoints. It is the foundational spacing structure for all web page layouts in the Oymyakon DS.

Key characteristics:

- **Base unit:** 4px — all column, gutter, and margin values are multiples of 4px
- **Sidebar is outside the grid** — the sidebar (228px) is a fixed overlay; the grid counts from the left edge of `.main`, not the viewport edge
- **No max-width constraint** — content stretches with the grid columns at all breakpoints
- **Responsive by default** — breakpoints are viewport-width thresholds, not container queries

---

## 2. Base unit

All grid values derive from the **4px base unit**:

| Value | Tokens |
|---|---|
| 16px (4 × 4) | `var(--sp-s16)` |
| 24px (6 × 4) | `var(--sp-s24)` |
| 32px (8 × 4) | `var(--sp-s32)` |
| 40px (10 × 4) | `var(--sp-s40)` |

Raw pixel values must never appear in grid implementation. Use SP tokens exclusively.

---

## 3. Breakpoints

| Breakpoint | Viewport width | Columns | Gutter | Margin |
|---|---|---|---|---|
| **xs** | < 600px | 4 | 16px (`--sp-s16`) | 16px (`--sp-s16`) |
| **sm** | 600–899px | 4 | 16px (`--sp-s16`) | 24px (`--sp-s24`) |
| **md** | 900–1199px | 8 | 24px (`--sp-s24`) | 32px (`--sp-s32`) |
| **lg** | 1200–1439px | 12 | 24px (`--sp-s24`) | 32px (`--sp-s32`) |
| **xl** | ≥ 1440px | 12 | 32px (`--sp-s32`) | 40px (`--sp-s40`) |

### Breakpoint thresholds

```
0          600        900        1200       1440
|-- xs ----|--- sm ---|--- md ---|--- lg ---|-- xl -->
 4col/16g   4col/16g   8col/24g  12col/24g  12col/32g
```

---

## 4. Column structure

```
┌─[margin]─┬─[col]─┬─[gutter]─┬─[col]─┬─[gutter]─┬─ … ─┬─[col]─┬─[margin]─┐
│          │       │          │       │          │     │       │          │
└──────────┴───────┴──────────┴───────┴──────────┴─────┴───────┴──────────┘
```

- **Margin** — equal horizontal padding on both sides of the grid container
- **Gutter** — fixed horizontal gap between columns
- **Column** — flexible; fills remaining width after margins and gutters are subtracted

### Column width formula

```
column_width = (container_width − 2 × margin − (columns − 1) × gutter) / columns
```

---

## 5. Sidebar relationship

The sidebar (228px) sits **outside the grid**. It is a fixed-position element that does not participate in the column count or layout math.

| Element | Width | Position |
|---|---|---|
| Sidebar | 228px (`--sidebar-width`) | `position: fixed; left: 0` |
| `.main` | viewport − 228px | `margin-left: var(--sidebar-width)` |
| Grid container | 100% of `.main` | inside `.main` only |

> Grid margins apply to the `.main` content area, not the full viewport width.

On xs and sm breakpoints (mobile), the sidebar is typically hidden or shown as an overlay — the grid container occupies the full viewport width.

---

## 6. CSS implementation

### Grid container

```css
.grid-container {
  display: grid;
  grid-template-columns: repeat(var(--grid-cols), 1fr);
  gap: var(--grid-gutter);
  padding-left: var(--grid-margin);
  padding-right: var(--grid-margin);
}
```

### Breakpoint CSS variables

```css
/* xs — default */
:root {
  --grid-cols: 4;
  --grid-gutter: var(--sp-s16);
  --grid-margin: var(--sp-s16);
}

@media (min-width: 600px) {        /* sm */
  :root {
    --grid-cols: 4;
    --grid-gutter: var(--sp-s16);
    --grid-margin: var(--sp-s24);
  }
}

@media (min-width: 900px) {        /* md */
  :root {
    --grid-cols: 8;
    --grid-gutter: var(--sp-s24);
    --grid-margin: var(--sp-s32);
  }
}

@media (min-width: 1200px) {       /* lg */
  :root {
    --grid-cols: 12;
    --grid-gutter: var(--sp-s24);
    --grid-margin: var(--sp-s32);
  }
}

@media (min-width: 1440px) {       /* xl */
  :root {
    --grid-cols: 12;
    --grid-gutter: var(--sp-s32);
    --grid-margin: var(--sp-s40);
  }
}
```

---

## 7. Column span usage

| Usage | xs (4 col) | sm (4 col) | md (8 col) | lg (12 col) | xl (12 col) |
|---|---|---|---|---|---|
| Full width | 4 | 4 | 8 | 12 | 12 |
| Half width | 2 | 2 | 4 | 6 | 6 |
| One third | — | — | — | 4 | 4 |
| Two thirds | — | — | — | 8 | 8 |
| One quarter | 1 | 1 | 2 | 3 | 3 |

---

## 8. Usage rules

1. **Always use SP tokens** for gutter and margin values — never raw pixel values.
2. **Content must never break out of the grid** — no negative margins that exceed the column boundary without an explicit bleed design intent.
3. **The sidebar is not a grid column** — never include sidebar width in column span calculations.
4. **Minimum column span is 1** — do not create sub-column layouts; use padding within a column instead.
5. **Gutter is horizontal only** — vertical rhythm between rows is controlled by spacing tokens, not the grid gap.
6. **xs and sm share 4 columns** — designs for both breakpoints should be structurally identical unless the margin change alone is sufficient.
7. **lg and xl share 12 columns** — the only difference is gutter (24px → 32px) and margin (32px → 40px).

---

## 9. RTL

The grid is symmetric — column order reverses automatically with `dir="rtl"` on the grid container. No additional rules required.

---

## Changelog

| Version | Date | Change |
|---|---|---|
| 1.0.0 | 2026-05-18 | Initial spec — 5 breakpoints, 4px base unit, sidebar-outside model |