Eve library

OSHUN V1 Grid, Gutter, and Max-Width Rules

Guide

Revision 1

On this page

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