# Layout guidance

Package: @commenda/pathfinder@0.1.0
Page: /docs/foundations/layout

Source: [Layout sheet](https://www.figma.com/design/dn7BkGYEfIyP0o2zfesfVh/The-System?node-id=237-2), frame `238:2`, reviewed **2026-10-12**.

Use these layout principles when composing application screens. Pathfinder supplies [Sheet](/docs/components/sheet), [Dialog](/docs/components/dialog), and [Side nav](/docs/components/side-nav); the application owns the complete shell. Component pages define supported sizes and defaults.

## Viewports and design review [#viewports-and-design-review]

Design at 1440×900, then check widths 1280 and 1024. The client product shows its desktop-only message below 768px; partner pages are excepted. Widths 768–1023 work but are not a design target. This is an application policy: standalone Pathfinder components must still accommodate narrow containers and enlarged text.

| Breakpoint | Minimum viewport width |
| ---------- | ---------------------- |
| sm         | 640px                  |
| md         | 768px                  |
| lg         | 1024px                 |
| xl         | 1280px                 |
| 2xl        | 1536px                 |

Figma also mentions an `md-h` minimum-height query of 768px for tall modals. It is source guidance, not an exported Pathfinder breakpoint. Do not invent a `--pf-breakpoint-md-h` variable.

## App shell [#app-shell]

Start screens from the Figma Layout / App shell composition.

| Region           | Geometry                                      |
| ---------------- | --------------------------------------------- |
| Sidebar          | 208px expanded; 56px collapsed                |
| Gutters          | 8px                                           |
| Main card        | White background; 12px radius; 0.5px hairline |
| Breadcrumb strip | Optional; 44px high                           |
| Content padding  | 24px; do not override per page                |
| Aside            | Optional; 400px; detached or bordered         |

The sheet describes migration from older 270/72px sidebars to 208/56px, and 408/340px auxiliary panels to 400px. These are intended migrations, not verified current measurements of every repository screen.

## Column grid [#column-grid]

Use 12 fluid columns inside content, with 24px gutters. Asides and sheets use 16px gutters. Existing half/third form layouts map to spans 6 and 4.

| Composition                  | Column spans  |
| ---------------------------- | ------------- |
| Full row                     | 12            |
| Two equal cards              | 6 + 6         |
| Three equal cards            | 4 + 4 + 4     |
| Four equal cards             | 3 + 3 + 3 + 3 |
| Main and summary             | 8 + 4         |
| Wide main and narrow summary | 9 + 3         |

Lay out by spans rather than fixed per-screen pixel widths. Use 8px gaps within groups, 16px or 24px between cards, and 32px or 48px between page sections.

## Content widths [#content-widths]

| Mode    | Width and alignment      | Use                                                                          |
| ------- | ------------------------ | ---------------------------------------------------------------------------- |
| Full    | Fluid; default           | Tables, dashboards, lists                                                    |
| Wide    | Centered, maximum 1200px | Overview pages; usually behaves like Full until the viewport is about 1480px |
| Reading | Centered, maximum 720px  | Home, onboarding, settings, checklists, chat                                 |

Choose one content mode rather than overriding the 24px shell padding. Reading replaces inconsistent centered columns in the source design. It is distinct from the generic `width/2xl` token's 1024px document-width description.

## Panels, sheets and dialogs [#panels-sheets-and-dialogs]

| Surface | Source size names and widths                                       |
| ------- | ------------------------------------------------------------------ |
| Aside   | 400px                                                              |
| Sheet   | sm 400px; md 520px; lg 720px                                       |
| Dialog  | sm 400px; md 480px; lg 600px; xl 800px; full 95vw capped at 1200px |

Choose the component size for the task and available viewport. Prefer a dedicated page for flows that need sustained reading or extensive navigation. Generic container-width tokens and named component sizes serve different purposes.