Layout

WHEN TO USE

• Any time you need to arrange content — inside a component's slot, inside a page section, or around a whole page. There is no second answer to this question in the system.
• A page needs a measure: variant="constrained" puts children in a centred column capped at size, with fluid gutter tracks either side.
• A child needs to break out of that measure edge-to-edge: give it the bleed attribute and it spans the gutters.
• You need a track list the props cannot name — a sidebar shell, an asymmetric split. Set --al-layout-template on a grid layout; three dashboard apps already do exactly this.

WHEN NOT TO USE

• What you actually need is a bounded content surface with a heading, body and actions. That is a container with regions, not an arrangement.USE CARD →
• You are grouping form controls that share a label, a required state and a validation message. That grouping is semantic, and it needs the component that owns the semantics — which then nests its own layout inside.USE CHECKBOX-GROUP →
• You need a visual break between sections rather than space between them.USE DIVIDER →
• You are positioning something against a trigger — a floating panel anchored to a control. That is not flow arrangement.USE POPOVER →

DO

• Reach for <al-layout> FIRST when a new component needs its slotted children arranged. Nesting the slot content in a layout is the pattern al-checkbox-group and al-radio-group both use.
• Use --al-layout-padding for the layout's own inset. :host is display: contents, so padding set on <al-layout> from outside is dropped — the custom property is the supported way in. It reaches the shadow box by INHERITANCE, which display: contents does not interrupt, so it needs no display override and no wrapper element. The four demo-app shells and the homepage hero all set it this way.
• Span grid children with the shared .al-u-grid__item.col:N classes. There is deliberately no second span system.
• Prefer the gap prop over --al-layout-gap. The prop is on the design scale and wins over the custom property; the custom property exists for the value the scale cannot name.

DON’T

• Don't create a new *-group wrapper component. A wrapper that owns no behaviour, no ARIA relationship and no state is this component with props — that rule is a blocker in the contributor contract, not a preference.
• Don't add a direction, orientation, gap, align, justify or wrap property to a new component, and don't hand-roll display: flex or display: grid to arrange SLOTTED children. Internal shadow structure — an icon against a label inside an atom — is exempt; content the consumer provides is not.
• Don't look for al-button-group, al-layout-container, al-layout-section, al-bento-grid, al-split-content, al-chip-group or al-toast-group. All seven were removed. The first five owned only arrangement; the last two did own behaviour, but nothing in the system used it, so they were cut rather than carried.
• Don't use --al-layout-padding for inline insets under variant="constrained". The inline space there is the gutter tracks — use it for block padding only.
• Don't wrap an <al-layout> in a <div> just to pad it, and don't force display: block on the host to make padding stick. Both are the workaround for a hook that already exists; five call sites had independently invented them, each with its own comment re-deriving the display: contents trap. Set --al-layout-padding on the layout itself instead.