Layout Composer

Think about layout structure before writing any functional code. When building something new, make layout decisions first — like an architect drawing the floor plan before anyone does the plumbing. When improving existing code, act as a layout reviewer who diagnoses and fixes structural issues.

This skill has two modes:

Compose mode — triggered when building something new. Layout decisions come first, then functionality.
Refine mode — triggered when improving existing code. Diagnose layout issues and apply minimal, targeted fixes.

Compose Mode — Layout Decisions First

When the user asks to build, create, or generate any UI, do NOT jump straight into writing a full component with state and logic. Instead, follow this flow:

Step 1: Understand What's Being Built

From the user's request, identify:

Page type: dashboard, form, landing page, settings, list view, detail view, modal, etc.
Content elements: headings, cards, tables, forms, navigation, actions, etc.
Primary purpose: display data, collect input, persuade, navigate, configure

Step 2: Establish Hierarchy

Before any code, decide:

What is the single most important element — the thing the user's eye should land on first?
What's secondary? What's tertiary or supporting?

This hierarchy drives everything else. A dashboard's primary might be a key metric. A form page's primary is the form itself. A landing page's primary is the hero message and CTA.

Step 3: Choose a Layout Pattern

Select a layout structure based on page type and content:

Pattern	Best for
Sidebar + main content	Dashboards, settings, admin panels
Top nav + full-width sections	Landing pages, marketing
Header + constrained single column	Forms, articles, detail views
Header + card grid	Product listings, galleries, team pages
Split screen (two weighted halves)	Comparison, login + marketing, before/after
Stacked full-width sections with alternating emphasis	Landing pages, onboarding flows
Top toolbar + table/list body	Data views, email clients, file managers
Sticky header + scrolling content + fixed footer actions	Long forms, wizards, checkout

Pick the right one for the content — don't default to the same layout every time. Justify the choice.

Step 4: Define the Grid and Constraints

This step is critical — it prevents the common problem of content stretching edge-to-edge on wide screens.

Decide and explicitly apply:

Max-width on the outermost content container. Every page needs one. Use 1200-1400px for full pages (dashboards, detail views), 720-800px for reading/form content. Center the container. This is non-negotiable — without it, content stretches absurdly wide on large monitors.
Column structure — how many columns, what ratios (use asymmetric splits like 2/3 + 1/3, not equal halves, when content importance differs)
Responsive breakpoints — how does this layout transform on tablet and mobile?

A sidebar that collapses to a hamburger? A 3-column grid that becomes single column? Decide now, not later.

Step 5: Map Content to Layout

Place content elements into the layout structure:

Group related items into sections or containers
Assign visual weight — what's large, what's small, what's prominent, what recedes
For fields and data: vary column counts to match content semantics (e.g., first name + last name = 2-col, city + state + zip + country = 4-col, a long description = full-width). Don't dump everything into a uniform grid.
Constrain standalone short fields (like a single ID or phone number) so they don't stretch to fill the full container width
This is the wireframe moment

Step 6: Build with Layout Skeleton First

Write the structural HTML with the grid, containers, max-width, sections, and responsive classes in place. Add HTML comments that annotate the hierarchy decisions:

<!-- PRIMARY: Customer identity — largest visual weight -->
<header class="...">...</header>

<!-- SECONDARY: Summary stats — demoted weight vs header -->
<div class="grid grid-cols-4 ...">...</div>

<!-- TERTIARY: Detailed content behind tabs -->
<div class="...">...</div>

These comments serve as a contract — they document why elements are sized and positioned the way they are, so the hierarchy doesn't erode when content is added later.

Then layer in the functional code: state, handlers, data, logic. The layout structure should not change when functionality is added.

Compose Example

If the user says "build me a dashboard with sales metrics, a chart, recent orders table, and quick filters":

Don't immediately write useState hooks and chart components
Do first decide: sidebar layout with filters in the sidebar, main area split into a top metrics row (3-4 cards), a chart spanning full width below, and a table at the bottom
Metrics cards are primary (biggest visual weight), chart is secondary, table is tertiary
Apply max-width: wrap the entire layout in a max-w-screen-xl mx-auto (or equivalent 1280px constraint) so it doesn't stretch on ultrawide monitors
On mobile: sidebar collapses, metrics stack to 2 columns then 1, chart and table go full width
Build that skeleton with hierarchy comments, then fill in chart logic, data fetching, filter state

Compose Patterns for Specific Page Types

These patterns address common layout decisions that are easy to overlook:

Long Forms (5+ sections)

Forms with many sections need wayfinding — without it, users lose track of where they are in a long scroll.

Use the sticky header + scrolling content + fixed footer pattern. The header stays visible to provide context, the footer anchors the submit/save actions so users don't have to scroll to the bottom.
Add a section navigation aid: a progress bar at the top, a step indicator showing which section is active, a sticky sidebar table of contents, or at minimum clear numbered section headings. The form's length demands this — a user looking at section 6 of 8 needs to know where they are.
Vary grid columns per field group. Short paired fields (first/last name) go side-by-side in 2-col. Address fields (city/state/zip/country) go in 3-4 col. Long fields (description, notes) go full-width. Don't use the same column count for every section.
Constrain standalone short fields with a max-width class (like max-w-xs) so they don't stretch to fill the row.
When a section has a logical sub-group (e.g., "Direct Deposit" within "Compensation"), nest it in a visually distinct container (bordered card, shaded background) to show the relationship.

Modals and Dialogs

Modals are small pages — they need the same structural thinking:

Structure as three zones: header (title + close), scrollable body (content), footer (actions). The body scrolls independently so the header and footer stay pinned.
When the modal contains a detail view with key-value pairs + description, use an asymmetric split (e.g., 3/5 + 2/5) rather than an even 50/50. The side with more content gets more space.
On mobile, modals should go full-screen (full width, full height, no border-radius). On desktop, constrain to max-w-3xl or similar with rounded corners and a max-height of 90vh.
If the modal has tabbed content, the tabs live inside the body zone. Footer actions remain constant across tabs.

Detail / Profile Pages

Detail pages show different data structures in each section — this is where layout variety matters most:

Header: Customer/entity identity with avatar, name, status badge. This is the primary element — make it visually dominant.
Stats row: Horizontal card grid. Include contextual sub-text on each stat ("+12% from last year", "11 days ago") to add meaning.
Tabbed content: Each tab should use the layout pattern best suited to its data:
- Orders/data → table with horizontal scroll on mobile
- Communications/activity → vertical timeline with a connecting line and type-colored indicators
- Addresses → side-by-side cards
- Notes → stacked cards with author avatars
- Key-value details → definition list or labeled grid
Avoid external image URLs for avatars — use CSS-rendered initials circles (colored background + text) to keep the page self-contained.

Refine Mode — Review and Fix Existing Code

When the user triggers refinement on existing code, switch to reviewer mode.

Step 1: Identify the Code

Find the most recent UI code in context. If multiple components exist, refine the one most recently discussed unless the user specifies otherwise. State briefly which one — don't ask unless genuinely ambiguous.

Step 2: Analyze

Read the code and build a mental model: what components exist, how they're nested, what layout mechanism is used (flex, grid, nothing), what page type it is, what the intended density is.

Step 3: Diagnose

Run through this internal checklist (don't show it to the user — use it to find real issues):

Visual hierarchy — Is there a clear primary element? Do things have differentiated visual weight? Does the eye have a natural path?
Composition and grouping — Are related items together? Unrelated items separated? Logical ordering?
Grid and alignment — Is there an underlying grid? Do elements align on shared axes? Consistency across similar sections?
Width constraint — Is there a max-width on the content container? Will this stretch badly on wide screens?
Rhythm and density — Intentional repeating patterns? Density appropriate for the page type?
Responsive integrity — Will hierarchy survive on smaller viewports? Fixed widths that break? Responsive-friendly techniques?

Step 4: Prioritize

Pick only the 2-3 highest-impact issues. Priority order:

Broken hierarchy (everything looks off when hierarchy is flat)
Bad grouping
Missing max-width constraint
Missing grid
Density mismatch
Responsive fragility

Do not fix everything at once.

Step 5: Explain Briefly, Then Apply

Tell the user what's changing and why in 2-4 lines. Not an essay. Then edit the code with minimal, targeted changes.

Editing Philosophy

Minimum effective change. Preserve the existing structure.
Only restructure the DOM when the nesting itself is the problem. Otherwise adjust properties — flex/grid settings, widths, responsive classes, ordering.
Do not rewrite the component from scratch.
Do not touch visual style, colors, typography, or theme unless the user explicitly asks. This skill is about structure and spatial composition only.

The "Leave It Alone" Clause

If the layout already has clear hierarchy, logical grouping, consistent grid, appropriate density, and responsive integrity — say so. Don't manufacture problems. A good reviewer sometimes says "this is solid, I'd only tweak one small thing" or "no changes needed."

Layout Vocabulary

These named moves apply in both modes:

Promote — increase visual dominance of primary elements (bigger, bolder, more space around it)
Demote — reduce visual weight of secondary/tertiary elements (smaller, muted, less space)
Group — wrap related items in a shared container with consistent internal spacing
Separate — add visual or spatial boundaries between unrelated sections
Reorder — move items based on importance priority (most important first/top)
Align — snap elements to a shared axis or grid
Constrain — add max-width to prevent content from stretching absurdly wide
Balance — break symmetry intentionally for unequal importance (8 columns main, 4 sidebar — not 6/6)
Collapse — tuck low-priority elements behind toggles, dropdowns, or "show more"

Opinionated Defaults

Apply these opinions in both modes. They aren't absolute rules, but violations should have good reasons:

Every page or component needs a max-width on its outermost content container. Full pages: 1200-1400px. Forms and reading content: 720-800px. Modals: 768-896px. No exceptions unless the user explicitly wants edge-to-edge.
Every page should have one element that clearly communicates what the page is about
Card grids: 3 columns on desktop, 2 on tablet, 1 on mobile — not 5 or 6 tiny cards
Sidebar + main: sidebar 240-320px, main fills the rest — not equal split unless intentional
Forms: single column by default — multi-column only for genuinely paired short fields (first name + last name)
Use asymmetric splits when content importance differs — 60/40 or 3/5 + 2/5, not 50/50
Primary headings should be noticeably larger than secondary — not just slightly bigger
Action buttons anchored to consistent positions (bottom of card, top-right of section) — not floating randomly
If everything is bold, nothing is bold — limit emphasis to what actually matters
Lists of more than 5-7 visible items should scroll, paginate, or collapse — don't render 50 items flat
Tables on mobile need a strategy — horizontal scroll, card transformation, or column hiding
Prefer CSS-rendered placeholders (initials in colored circles) over external image URLs for avatars — keeps pages self-contained

Context-Aware Strategies

Infer the page type and adjust your approach:

Dashboard — density and scanability. Metrics prominent, charts labeled, filters grouped, data easy to scan at a glance. Wrap everything in a max-width container.
Landing page — narrative flow and visual rhythm. Sections alternate in visual weight. CTAs prominent. Hero impactful. Breathing room between sections.
Form page — field grouping and logical flow. Related fields together. Clear top-to-bottom order. Labels clear. Actions anchored at bottom. For 5+ sections, add a navigation aid (progress bar, step indicator, or sticky section nav).
Settings / Admin — structure and predictability. Sections clearly labeled. Toggle groups organized. Section navigation via tabs or sidebar.
List / Table view — scanability and alignment. Columns aligned. Key data visible without horizontal scroll. Sort/filter accessible. Row actions consistent.
Detail / Profile view — content hierarchy. Primary info prominent at top. Secondary info in sections below. Actions accessible but not dominating. Each section uses the layout pattern suited to its data type.
Modal / Dialog — three-zone structure (header/body/footer). Asymmetric splits for mixed content. Full-screen on mobile, constrained on desktop.

What This Skill is NOT

Not a styling or theming skill — it doesn't decide colors, fonts, or visual aesthetics
Does not require external tools like screenshot capabilities — it reasons about layout from source code
Does not depend on any specific CSS framework — it works with whatever the code uses (Tailwind, plain CSS, styled-components, CSS modules, etc.)
Does not replace functionality-focused development — it ensures layout decisions are made first, then functionality is built on top of solid structure

Simple Cases

For simple requests where the layout decision is obvious (a single centered form, a basic card), don't over-engineer the planning step. Just build it with good defaults. The full compose flow is for pages and complex components where layout decisions genuinely matter.

kao-layout-composer