page-composition

name	page-composition
description	Use when defining how pages are assembled from components, when establishing layout grids, when deciding responsive collapse strategies, or when multiple routes have inconsistent layouts.

Page Composition

Overview

Decide how pages are assembled from components: layout grid, page templates, responsive collapse strategy, navigation transformation per breakpoint, and content priority rules. Output is .forge/page-composition.md. Reads component-library (available pieces), design-system (breakpoints + spacing), and interaction-patterns (scroll, sticky, overlay behavior).

When to Use

• A product is about to start building pages and there's no named template vocabulary
• Routes have drifted into one-off layouts with no shared structure
• The sidebar collapses inconsistently on mobile (or doesn't collapse at all)
• A new responsive breakpoint is being added and nobody knows what should change
• A second product is joining the design system and needs to inherit layout conventions

When NOT to Use

• A single one-off marketing page — that's content, not composition
• Backend-only services with no UI
• A trivial layout fix inside one route — incremental-implementation

Common Rationalizations

Thought	Reality
"Every page is different"	Every page feels different, but most follow 3–4 templates. Name them and variation becomes predictable.
"We'll figure out responsive as we go"	"As we go" means the first 5 pages are desktop-only and mobile is retrofitted on day 10 under deadline pressure.
"Just make it responsive with Tailwind"	Tailwind handles the mechanics (sm:, md:, lg:). It doesn't decide what to do at each breakpoint. That's a design decision.
"Mobile can wait"	If field users open the product on phones, mobile IS the product. Desktop is the secondary experience.
"Sticky elements just work"	A sticky header that covers content on mobile is a bug. Sticky needs a rule.

Red Flags

• A route with no defined template (a one-off layout)
• A sidebar that doesn't collapse on mobile (or hides instead of relocating)
• Content that disappears on small screens rather than relocating to a secondary tab/accordion
• Inconsistent grid usage across routes (12-col on one, free-flow on another)
• Scroll behavior differing between similar pages (infinite on one list, paginated on the next)
• Sticky element that covers content on mobile (header overlapping first row of a list)

Core Process

Step 1: Read upstream artifacts

Read .forge/component-library.md (available components), .forge/design-system.md (breakpoints + spacing scale + max content width), .forge/interaction-patterns.md (scroll, sticky, overlay rules). Confirm the breakpoint set before defining templates against it.

Step 2: Layout system

Define the grid that every template inherits:

• Grid: 12-column, 8-column, or flexbox-based. Pick one product-wide.
• Gutter: from the design-system spacing scale (e.g., 16px mobile, 24px desktop).
• Max content width: the cap beyond which content doesn't grow on ultra-wide screens (e.g., 1280px for dashboards, 1440px for tables, 640px for forms).
• Edge padding per breakpoint: how much breathing room from the viewport edge at each size.

Step 3: Name page templates

List the recurring page shapes the product uses. Common templates (include only what's needed):

• Dashboard: metrics row → charts grid → activity feed. Sidebar on desktop, bottom nav on mobile.
• Detail: hero/header → key metrics → content tabs → action footer. Full-width on mobile.
• List: filter bar → sortable table or card list → pagination. Cards on mobile, table on desktop.
• Form: section groups → inputs → sticky action bar. Single column always.
• Settings: sidebar nav → content panel. Tabs on mobile.
• Empty: illustration + headline + description + CTA. Centered always.

Step 4: Define each template

For every template, document:

• Section hierarchy — what comes first, second, third
• Information density per breakpoint — desktop shows 3 columns of cards, tablet 2, mobile 1
• Sticky elements — header, action bar, sidebar; offsets so they don't cover content
• Scroll behavior — infinite scroll vs pagination vs load-more, per template (not per page)
• Responsive collapse strategy — what happens to the sidebar, what happens to the grid, what gets hidden vs stacked vs tabified

Step 5: Responsive philosophy (per product)

Decide once, product-wide:

• Mobile-first (field reps, consumer apps): design at 380px first, enhance for desktop. Mobile is THE product.
• Desktop-first (SaaS managers, admin tools): design at 1280px first, adapt for mobile. Desktop is THE product.

This is a per-product decision, not a per-page decision. State it explicitly in the artifact.

Step 6: Navigation transformation

Document how navigation changes across breakpoints:

Breakpoint	Primary nav	Secondary nav
Desktop (lg+)	Sidebar (expanded) + topbar	Inline in topbar
Tablet (md)	Sidebar (collapsed to icons) + topbar	Inline in topbar
Mobile (sm)	Bottom tabs (3–5 items)	Hamburger overflow menu

Define each breakpoint transition explicitly. No implicit "the sidebar will figure it out."

Step 7: Content priority rules

On mobile, content does not disappear — it relocates. Document the rules:

• Primary content stays in the main flow
• Secondary content collapses into an expandable section or moves to a separate tab
• Tertiary content moves to a "More" overflow menu
• Decorative content (avatars in tables, illustrations) shrinks or hides — explicitly mark which

The principle: every piece of information has a home at every breakpoint. Nothing vanishes.

Step 8: Write .forge/page-composition.md

Sections in this order: upstream-read confirmation, layout system, template catalog, per-template specs, responsive philosophy, navigation transformation, content priority rules. Prepend a forge:meta header (generated_by: page-composition, generated_at: <ISO 8601 UTC with Z>, depends_on: [.forge/component-library.md, .forge/design-system.md, .forge/interaction-patterns.md] — paths only, never hashes, generated_from: {.forge/component-library.md: <hash>, .forge/design-system.md: <hash>, .forge/interaction-patterns.md: <hash>} — each upstream's content_hash AT generation time, content_hash: <sha256 first 8 of THIS file's body>).

Verification

• Every route in the product maps to a named template (or is documented as one-off with reason)
• Every template has responsive behavior at all design-system breakpoints
• Navigation transformation is documented per breakpoint
• Content priority rules exist — nothing disappears, it relocates
• Mobile-first vs desktop-first decided once, product-wide
• Layout grid, gutter, max content width, and edge padding documented
• Sticky elements have offsets that don't cover content on the smallest breakpoint
• Scroll behavior is template-level, not per-page
• .forge/page-composition.md written with forge:meta header