devplacepy/devplacepy/templates/docs/styles-layout.html

<div class="docs-content" data-render>
{% raw %}
# Layout

Layout uses CSS Grid and Flexbox: one shared page shell with a small set of approved content layouts inside it. New pages pick one of these rather than inventing a structure.

## The page shell

Every page is wrapped by `base.html` in the same four-part shell, from top to bottom:

1. **Fixed top nav** (`.topnav`, height `--nav-height` = `56px`, `position: fixed`, `z-index: 1000`). Always on screen, never re-implemented per page.
2. **Breadcrumb** (`.breadcrumb`, optional but expected). It renders only when the page supplies two or more crumbs. Clearing the fixed nav is handled once by `body { padding-top: var(--nav-height) }`, so every page sits below the header whether or not it has a breadcrumb. See [Consistency rules](/docs/styles-consistency.html).
3. **Content root** (`<main class="page">`, `max-width: var(--max-content)` = `1200px`, centred, `padding: 1rem`). All page content lives inside this one element.
4. **Footer** (`.site-footer`), rendered from the `footer` block.

```text
+-----------------------------------------------+  .topnav (fixed, 56px)
|  Dev[Place]   Home Posts News ...   bell user |
+-----------------------------------------------+
|  Home / Feed                                  |  .breadcrumb (clears the nav)
|  +-----------------------------------------+  |
|  |              <main class="page">        |  |  max 1200px, centred
|  |   [ one approved layout goes here ]     |  |
|  +-----------------------------------------+  |
|                  site footer                   |
+-----------------------------------------------+
```

A page never re-declares `max-width: 1200px`, never adds a second centred wrapper, and never rebuilds the nav or footer. It supplies exactly one layout container inside `.page`.

## Approved layouts

### 1. Three-column app layout (the default)

The feed / posts page: a fixed-width left sidebar, a fluid main column, and a fixed-width right rail.

```css
.feed-layout {
    display: grid;
    grid-template-columns: var(--sidebar-width) 1fr 280px; /* 240px | fluid | 280px */
    gap: 1.5rem;
    align-items: start;
}
@media (max-width: 1024px) {
    .feed-layout { grid-template-columns: 1fr; } /* collapse to one column */
    .feed-right  { display: none; }              /* drop the right rail */
}
```

```text
&lt;div class="feed-layout"&gt;
  &lt;aside class="sidebar-card"&gt; ... &lt;/aside&gt;   left: navigation/filters (240px)
  &lt;div class="feed-main"&gt; ... &lt;/div&gt;          centre: primary content (fluid)
  &lt;aside class="feed-right"&gt; ... &lt;/aside&gt;     right: stats/context (280px, sticky)
&lt;/div&gt;
```

Rules for this layout: the two side columns are `<aside>`; the centre column must set `min-width: 0` so long content (code, URLs) cannot blow out the grid; the right rail is `position: sticky; top: calc(var(--nav-height) + 1rem)`; at `1024px` it collapses to a single fluid column and the right rail is hidden.

### 2. Three-column with two equal rails

The leaderboard uses `280px 1fr 280px` with both `<aside>` columns sticky. Same collapse behaviour at `1024px`.

### 3. Single-column list

A vertical stack of cards in a flex column, used inside the main column or on its own:

```css
.feed-posts { display: flex; flex-direction: column; gap: 1rem; }
```

### 4. Card grid

Auto-filling responsive grid for galleries such as projects:

```css
.projects-grid {
    display: grid;
    grid-template-columns: repeat(auto-fill, minmax(260px, 1fr));
    gap: 1rem;
}
```

## Cards

A card is the standard content surface: `--bg-card` background, a `--border` hairline, `--radius-lg` corners, and `1rem` padding. The shared `.card` class encodes that; `.post-card` / `.project-card` use the same recipe. On hover a card lifts its border to `--border-light` and adds `--shadow-sm`, without changing its background.

## Spacing

Use the spacing scale, not arbitrary values. Card padding is `1rem`; the gap between cards is `1rem`; the gap between layout columns is `1.5rem`.

| Token | Value |
|-------|-------|
| `--space-xs` | `0.25rem` |
| `--space-sm` | `0.375rem` |
| `--space-base` | `0.5rem` |
| `--space-md` | `0.75rem` |
| `--space-lg` | `1rem` |
| `--space-xl` | `1.25rem` |
| `--space-2xl` | `1.5rem` |

## Acceptable and not

- **Acceptable:** one layout container inside `.page`; CSS Grid for columns; `<aside>` for side columns; `min-width: 0` on the fluid column; sticky rails; cards built from tokens.
- **Not acceptable:** a second `max-width`/centred wrapper inside `.page`; absolute positioning to fake columns; fixed pixel heights on content; a side column that does not collapse on small screens; a main column without `min-width: 0` (it will overflow on long code lines).
{% endraw %}
</div>

<style>
.sg-layout { display: grid; grid-template-columns: 90px 1fr 110px; gap: 0.75rem; align-items: start; }
.sg-box { border: 1px solid var(--border-light); border-radius: var(--radius); background: var(--bg-card); padding: 0.625rem; color: var(--text-secondary); font-size: 0.75rem; text-align: center; }
.sg-box-main { min-height: 96px; display: flex; align-items: center; justify-content: center; }
.sg-box-accent { border-color: var(--accent); color: var(--accent); }
.sg-stack { display: flex; flex-direction: column; gap: 0.625rem; }
.sg-tag { font-family: var(--font-mono); font-size: 0.6875rem; color: var(--text-muted); display: block; margin-top: 0.25rem; }
@media (max-width: 600px) {
    .sg-layout { grid-template-columns: 1fr; }
    .sg-box-right { display: none; }
}
</style>

<div class="component-demo">
    <div class="component-demo-title">Three-column app layout (resize the window below 600px to see it collapse, mirroring the real 1024px rule)</div>
    <div class="sg-layout">
        <div class="sg-box">Sidebar<span class="sg-tag">&lt;aside&gt; 240px</span></div>
        <div class="sg-box sg-box-main sg-box-accent">Main content<span class="sg-tag">1fr, min-width: 0</span></div>
        <div class="sg-box sg-box-right">Right rail<span class="sg-tag">280px, sticky</span></div>
    </div>
</div>

<div class="component-demo">
    <div class="component-demo-title">Single-column card list</div>
    <div class="sg-stack">
        <div class="card">A card. <code>--bg-card</code>, <code>--border</code>, <code>--radius-lg</code>, padding <code>1rem</code>.</div>
        <div class="card">Another card. Stacked with a <code>1rem</code> gap.</div>
        <div class="card">A third card.</div>
    </div>
</div>