# OSHUN V1 Grid, Gutter, and Max-Width Rules

Status: Accepted v1.0  
Owner: OSHUN Design + Product + Engineering  
Last Updated: March 26, 2026  
Implements: `V1-UX-056`  
Related:

- `docs/releases/v1/specs/layout-density-tiers.md`
- `docs/releases/v1/scope/minimal-chrome-rules.md`
- `docs/releases/v1/scope/immersive-vs-utilitarian-posture-rules.md`
- `docs/adr/ADR-0017-oshun-studio-spacing-and-layout-grid.md`
- `docs/releases/v1/specs/studio-spacing-layout-dependency-and-data-contract-map.md`
- `apps/oshun/web/src/design-system/tokens.ts`
- `apps/oshun/web/src/design-system/globals-v2.css`
- `docs/releases/v1/specs/todos.md`

## 1. Purpose

This document defines the canonical breakpoint, grid, gutter, and max-width
behavior for OSHUN V1 across customer web, PWA, mobile, and admin web surfaces.

The repo already has the beginnings of a shared layout system:

- `apps/oshun/web/src/design-system/tokens.ts` defines the canonical web
  breakpoints
- `apps/oshun/web/src/design-system/globals-v2.css` defines the default
  `.container` max width and responsive inline padding
- `docs/adr/ADR-0017-oshun-studio-spacing-and-layout-grid.md` requires
  deterministic breakpoint, column, and gutter rules for Studio
- `docs/releases/v1/specs/studio-spacing-layout-dependency-and-data-contract-map.md`
  already models `GridProfileSpec`

What is still missing is one product-wide interpretation of those primitives.
Without that interpretation, surfaces drift into route-by-route layout logic,
legacy CSS exceptions, and inconsistent shell padding.

## 2. Core Doctrine

### 2.1 One Grid Language Across Customer And Operator Surfaces

OSHUN may vary in mood, density, and posture, but it should not vary in its
basic responsive grammar.

Customer and admin surfaces should share:

- the same breakpoint families
- the same container-padding ladder
- the same expectation that layouts become simpler, not busier, as width drops

### 2.2 Width Expansion Must Increase Capability, Not Line Length

When a viewport grows, OSHUN should add:

- more columns
- more contextual side space
- more simultaneous panels when warranted

It should not simply stretch reading content or generic cards wider and wider.

### 2.3 Gutters Are Structural, Not Decorative

Gutters exist to preserve scan paths, target separation, and layout rhythm.

They must stay deterministic by breakpoint. Ad hoc local gutter values are
allowed only for highly specialized visual media crops or legacy exception
migration work.

### 2.4 Breakpoint Behavior Must Be Semantic

The raw breakpoint tokens remain implementation primitives. Product and design
reviews should reason in semantic classes:

- mobile
- tablet
- laptop
- desktop

That semantic model is the canonical one for OSHUN V1.

## 3. Canonical Breakpoint Map

OSHUN V1 uses the existing shared breakpoint tokens in
`apps/oshun/web/src/design-system/tokens.ts` and interprets them as follows.

| Semantic class  | Token band         | Width range   | Canonical job                                                                                                 |
| --------------- | ------------------ | ------------- | ------------------------------------------------------------------------------------------------------------- |
| `mobile-narrow` | below `sm`         | `0-479px`     | smallest phones; prioritize reachability, single-column continuity, and calm compression                      |
| `mobile`        | `sm` to below `md` | `480-767px`   | phones and large phones; preserve one dominant column and compact utility actions                             |
| `tablet`        | `md` to below `lg` | `768-1023px`  | tablets and small landscape canvases; allow wider browse/research layouts without desktop chrome expectations |
| `laptop`        | `lg` to below `xl` | `1024-1279px` | compact desktop and laptop windows; default multi-column shell and split-view territory                       |
| `desktop`       | `xl` and above     | `1280px+`     | wide desktop and external-display work; supports full multi-panel operator and browse layouts                 |

Interpretation rules:

- `2xl` remains an implementation token for very wide desktop surfaces, but it
  is not a new semantic class.
- `mobile-narrow` is a sub-case inside mobile, included because current web CSS
  already changes container behavior below `480px`.
- Product acceptance should be checked against the semantic classes above, not
  only raw token names.

## 4. Canonical Grid And Padding Behavior

### 4.1 Universal Container Padding Ladder

The repo already establishes the correct base inline-padding ladder in
`apps/oshun/web/src/design-system/globals-v2.css`. That ladder becomes the
canonical OSHUN rule:

| Semantic class  | Inline padding per side | Source alignment                                            |
| --------------- | ----------------------- | ----------------------------------------------------------- |
| `mobile-narrow` | `12px`                  | `--oshun-space-3` current small-screen `.container` rule    |
| `mobile`        | `16px`                  | `--oshun-space-4` current default `.container` rule         |
| `tablet`        | `24px`                  | `--oshun-space-6` current `@media (min-width: 768px)` rule  |
| `laptop`        | `32px`                  | `--oshun-space-8` current `@media (min-width: 1024px)` rule |
| `desktop`       | `32px` minimum          | continues the current large-screen baseline                 |

Rules:

- Desktop may add more visual breathing room through empty outer space or shell
  rail offset, but the base content inset should not drop below `32px`.
- Mobile and tablet should not use desktop insets just because space exists.
- Sticky bars, drawers, and sheets should inherit the same breakpoint ladder
  unless the component is intentionally edge-to-edge.

### 4.2 Canonical Column And Gutter Model

| Semantic class  | Canonical columns | Canonical gutter | Intended layout behavior                                                                            |
| --------------- | ----------------- | ---------------- | --------------------------------------------------------------------------------------------------- |
| `mobile-narrow` | `4`               | `12px`           | one dominant column; stacked modules; no peer-primary dual columns                                  |
| `mobile`        | `4`               | `16px`           | single-column by default; two-column micro-grids only for lightweight controls or chips             |
| `tablet`        | `8`               | `20px`           | balanced browse and research layouts; limited split views; sidecars may appear if clearly secondary |
| `laptop`        | `12`              | `24px`           | full shell layouts; primary plus secondary columns; durable split-view workspaces                   |
| `desktop`       | `12`              | `24-32px`        | wide multi-panel layouts, stronger side breathing room, and operator-grade panel separation         |

Rules:

- The canonical grid is `4 / 8 / 12`, not a different column count for every
  route.
- Desktop keeps a `12`-column grid. More width should produce more breathing
  room or additional governed panels, not a `16`-column free-for-all.
- `24px` is the default desktop gutter. `32px` is reserved for wide desktop
  layouts that need stronger visual separation between major panels.
- Tablet may use asymmetrical spans, but must still resolve to an `8`-column
  grid.
- Customer mobile should almost always render as one dominant content lane even
  when small two-up modules appear locally.

## 5. Max-Width Modes

OSHUN V1 uses three canonical max-width modes. This avoids a false choice
between "everything is full bleed" and "everything is hard-capped at one
number."

### 5.1 Standard Content Container

Use for:

- home modules
- explore and activity surfaces
- profile, settings, and continuity views
- most customer research surfaces outside specialized compare layouts

Rule:

- `1200px` is the canonical standard content max width on web, matching the
  current `--oshun-content-max-width` token.

Behavior by breakpoint:

- mobile and tablet: effectively full width inside the breakpoint padding
- laptop: may reach the `1200px` cap
- desktop: stays capped at `1200px`, with extra width turning into negative
  space, shell context, or governed side structure

### 5.2 Edge-To-Edge Workspace Canvas

Use for:

- admin cockpits
- queue and table surfaces
- dual-pane research or compare workflows
- visualization-heavy domain work
- any layout where extra width clearly increases simultaneous capability

Rules:

- The workspace may use the full available shell width.
- Inner regions must still align to the canonical breakpoint padding and
  `4 / 8 / 12` grid.
- Additional width should become panels, inspectors, evidence rails, or
  denser-but-governed tables, not stretched prose blocks.

### 5.3 Full-Bleed Visual Field

Use for:

- welcome or landing heroes
- immersive domain moments
- media-led canvases

Rules:

- Backgrounds, imagery, and ambient visual fields may run edge to edge.
- The actionable text column inside that field must still align to the
  breakpoint padding ladder.
- Full bleed is a visual exception, not permission to ignore the grid for
  interactive content.

## 6. Surface Mapping

| Surface family                                         | Canonical width mode                                                    | Canonical breakpoint posture                                                         |
| ------------------------------------------------------ | ----------------------------------------------------------------------- | ------------------------------------------------------------------------------------ |
| Customer shell home, activity, library, settings       | standard content container                                              | `4 / 8 / 12` with one dominant lane                                                  |
| Explore and blended discovery                          | standard content container                                              | grows breadth at tablet and laptop, but should still present one strongest scan lane |
| Veritas or Nisaba evidence and study flows             | standard container or edge-to-edge workspace depending on compare depth | tablet introduces side context; laptop and desktop may use durable split views       |
| Operator queues, incidents, policy, audit, release     | edge-to-edge workspace canvas                                           | laptop and desktop default to multi-panel `12`-column workspaces                     |
| Welcome, public marketing, and immersive domain heroes | full-bleed visual field                                                 | text remains constrained even when the media is not                                  |

## 7. Breakpoint-Specific Behavior Rules

### 7.1 Mobile

- Default to one dominant column.
- Multi-column behavior is the exception and must only be used for lightweight
  summaries or paired controls.
- Bottom bars, sticky actions, and assistant entry points must respect the
  mobile padding ladder rather than touching screen edges arbitrarily.
- A mobile layout should remove sidecars before it compresses the main content
  lane.

### 7.2 Tablet

- Tablet is not a shrunken desktop.
- It may introduce side context, but should still preserve a clearly dominant
  primary lane.
- Tablet layouts should prefer `8`-column asymmetry over desktop-style
  three-panel complexity.
- If a route needs more than one persistent side region on tablet, it is
  probably over-framed.

### 7.3 Laptop

- Laptop is the default breakpoint for full shell behavior.
- Multi-panel workspace layouts become first-class here.
- Standard content surfaces may hit the `1200px` cap.
- Laptop layouts should be treated as the tightest desktop condition in review,
  because this is where layout cliffs appear first.

### 7.4 Desktop

- Desktop width should reward the user with compositional calm and better
  simultaneous context, not generic sprawl.
- Standard content routes stay capped instead of becoming billboard-width.
- Operator canvases may expand, but the grid should remain disciplined and panel
  count should stay intentional.
- Very wide desktop layouts should use extra width for margin, inspectors,
  evidence rails, or grouped tool regions before adding new decorative modules.

## 8. Anti-Patterns

The following patterns are non-canonical for OSHUN V1:

- route-specific random max widths with no semantic reason
- switching to two equal content columns on phone simply because space barely
  permits it
- desktop layouts that keep adding cards per row without strengthening hierarchy
- edge-to-edge interactive content that ignores shell padding
- operator tables stretched full width while surrounding controls still use
  mobile-scale gutters
- immersive heroes that place text inside a centered boxed container unrelated
  to the visual field

## 9. Implementation Guidance

### 9.1 Existing Sources Of Truth

Current implementation surfaces that should converge on this spec:

- `apps/oshun/web/src/design-system/tokens.ts`
- `apps/oshun/web/src/design-system/globals-v2.css`
- `apps/oshun/web/src/components/ShellLayout.tsx`
- `apps/oshun/web/src/app/globals.css`
- `apps/oshun/mobile/app/(tabs)/index.tsx`
- `apps/oshun/mobile/app/(tabs)/activity.tsx`
- `apps/oshun/mobile/app/(tabs)/explore.tsx`
- `apps/oshun/mobile/app/domain/[domainId].tsx`

### 9.2 Migration Priority

When layout cleanup work happens, fix drift in this order:

1. shell and container padding
2. shared grid utilities and layout primitives
3. high-value customer browse and research routes
4. operator workspaces and legacy page-level CSS exceptions

## 10. Acceptance Standard

A redesigned surface satisfies `V1-UX-056` only when all are true:

- it clearly maps to one of the canonical width modes
- its breakpoint behavior matches the semantic
  `mobile / tablet / laptop / desktop` model
- its gutters and inline padding match the canonical ladder unless a documented
  exception exists
- wider viewports add capability or calm, not arbitrary line length
- review artifacts show the surface at mobile, tablet, laptop, and desktop
  widths
