Layout Decision Tree

Use this when the pattern name is not obvious yet.

Before Adding A Pattern

Add a new pattern only when the spatial responsibility is not already covered by an existing pattern or recipe.

• If the problem is composition, update or add a recipe.
• If the problem is visual treatment, keep it outside reusable pattern CSS.
• If the problem is repeated layout failure, document the smallest reusable pattern that prevents it.
• If scroll, sizing, or wrapping ownership is unclear, clarify ownership before writing CSS.

Examples:

• Settings page with side navigation, readable form width, and action rows: recipe composition, not one large pattern.
• Premium card treatment with shadows, color accents, and larger headings: product styling, not reusable pattern CSS.
• Repeated action row that wraps badly across screens: candidate pattern if the wrapping responsibility is not covered by cluster or wrap-row.

Code-level distinction:

<div class="action_row">
    <button type="button">Save changes</button>
    <button type="button">Preview</button>
    <button type="button">Discard draft</button>
</div>

.action_row {
    display: flex;
    flex-wrap: wrap;
    gap: var(--action-gap);
}

This can be a reusable layout pattern only if the wrapping responsibility is not already covered by an existing pattern. Button colors, borders, shadows, and typography belong to the consuming product or demo layer.

Viewport versus container-local example:

/* Avoid for component-local layout: the parent container may be narrower than the viewport. */
@media (min-width: 48rem) {
    .action_row {
        flex-wrap: nowrap;
    }
}

/* Prefer when the component should respond to its own available space. */
.action_region {
    container-type: inline-size;
}

@container (min-width: 32rem) {
    .action_row {
        flex-wrap: nowrap;
    }
}

Start With Scope

Is the layout controlled by the viewport?

Choose a viewport or shell pattern when the whole page frame matters.

• Header, footer, side navigation, or utility panels frame the page: Viewport / Shell patterns
• Only one body region should scroll: scroll-body-shell
• Side navigation should stay stable while the main region scrolls: fixed-sidenav-shell

Related recipes:

• SaaS settings
• Command surface

Is the layout local to a component or section?

Choose a local pattern when the component should adapt inside whatever parent owns it.

• Items stack vertically with consistent rhythm: stack
• Actions wrap in a row: cluster or wrap-row
• A region needs readable width constraints: content-limiter

Identify Content Shape

Is content repeated?

• Cards, tiles, metrics, or repeated panels: Grid / Repetition patterns
• Unknown number of columns based on available space: ram-grid
• Rows and columns should align: card-grid

Related recipe:

• Dashboard

Is there primary and supporting content?

• Supporting content should sit beside primary content when space allows: sidebar
• List and detail regions are peers: list-detail
• Supporting content should stay visible during long reading: sticky-aside

Related recipes:

• Article page
• List detail

Is the layout mostly one flow?

• Prose or form content needs readable width: content-limiter
• Groups need vertical rhythm: stack
• Footer actions should stay reachable: sticky-footer

Related recipe:

• Form flow

Decide Scroll Ownership

Ask what scrolls before selecting fixed or sticky patterns.

• The document scrolls normally: use local composition patterns first.
• A single page body scrolls inside fixed shell regions: scroll-body-shell
• A horizontal row should scroll instead of wrapping: reel
• Sticky content follows document scroll: sticky-aside

Avoid multiple nested scroll containers unless each one has a named responsibility.

Check Media And Exceptions

• Media should preserve aspect ratio: frame
• Icons need a stable square slot: icon-frame
• Overlay should not change document order: imposter
• Regions intentionally occupy the same grid cell: overlay-stack

Rejected Alternatives

Rejected alternatives:

• Record any recipe or pattern rejected because it weakens source order, focus order, scroll ownership, constraints, or content stress behavior.
• Keep the reason in the Layout brief so the rejected option is visible during harmony evaluation and implementation handoff.