# Primitives

Source: https://iriscss.com/documentation/layout/primitives/

Four classes that cover most layouts without a single media query.

Each primitive replaces the margins of its children with a gap, and adapts to the space it has rather than the screen size. That makes them work the same in a sidebar, a card or the full page.

## Stack

`.stack` spaces its children vertically.

```html
<div class="stack">
  <div>One</div>
  <div>Two</div>
  <div>Three</div>
</div>
```

## Cluster

`.cluster` puts its children in a row that wraps, for tags, buttons and toolbars.

```html
<div class="cluster">
  <div>HTML</div>
  <div>CSS</div>
  <div>Custom properties</div>
  <div>Cascade layers</div>
  <div>Container queries</div>
</div>
```

## With sidebar

`.with-sidebar` puts a fixed width first child next to fluid content. When the content would get narrower than half the row, the two stack. This docs page uses it for the menu.

```html
<div class="with-sidebar" style="--i-sidebar-width: 10rem">
  <div>Sidebar</div>
  <div>Content</div>
</div>
```

`.end` puts the sidebar last.

```html
<div class="with-sidebar end" style="--i-sidebar-width: 10rem">
  <div>Content</div>
  <div>Sidebar</div>
</div>
```

## Switcher

`.switcher` shows its children in one row while it is wider than `--i-switcher-threshold` (40rem), and in one column below it. There is never a two plus one wrap. More than four children always stack.

```html
<div class="switcher">
  <div>One</div>
  <div>Two</div>
  <div>Three</div>
</div>
```

## Nesting

Primitives nest freely. A common page: a stack of sections, with a cluster of buttons inside.

```html
<div class="stack">
  <h3>Ready to start?</h3>
  <p>Link one stylesheet and write HTML.</p>
  <div class="cluster">
    <button class="primary">Get started</button>
    <button class="outlined">Read the docs</button>
  </div>
</div>
```

## Variables

| Variable | Default | Note |
| --- | --- | --- |
| `--i-stack-gap` | `var(--i-spacing)` |  |
| `--i-cluster-gap` | `calc(var(--i-spacing) * 0.5)` |  |
| `--i-sidebar-gap` | `var(--i-spacing)` |  |
| `--i-sidebar-width` | `16rem` |  |
| `--i-sidebar-content-min-width` | `50%` | The content wraps below the sidebar once it would be narrower than this |
| `--i-switcher-gap` | `var(--i-spacing)` |  |
| `--i-switcher-threshold` | `40rem` | Container width below which a switcher stacks its children |