Refinement levers

Bounded composition vocabulary for adjusting layout without inventing new primitives.

Pluma exposes a narrow set of props per component. Most of the layout nuance designers reach for — padding shifts, image placement, panel weighting, edge treatments — is not a prop on the component. It is a composition recipe built from primitives Pluma already ships (Box, ModalSplit, ModalInset, Stack, Grid, spacing tokens).

This pattern defines the only sanctioned vocabulary for refinement. Outside this list, the refinement is a new pattern, not a recipe — and belongs in a design conversation.

The five levers

Every refinement is one of these five. Name the lever before composing.

• Padding scale — inner spacing of a surface. Three steps only: compact, default, relaxed. Compose with sprinkle padding props or by wrapping content in Box with a spacing token. Never apply arbitrary pixel values.
• Media placement — where an image, illustration, or visual sits relative to body content. Four slots only: top, leading, trailing, bleed (edge-to-edge). Compose with ModalSplit, ModalInset, or a Box with the inheritPadding pattern.
• Panel proportion — for split layouts, the relative weight of the two columns. Three ratios only: 50/50 (balanced, default), 40/60 (narrative leads), 60/40 (form leads). Express via ModalSplit width tokens, never as a flex override.
• Density — vertical and horizontal rhythm. Three steps only: compact, default, relaxed. Maps to the spacing-token scale. Set at the surface root and inherit downward.
• Edge treatment — how content meets the surface boundary. Three modes only: inset (full padding, default), flush (zero padding on one or more edges), bleed (content extends to the full surface bounds). Compose with ModalInset, Box with negative-margin tokens, or inheritPadding={false}.

How to compose

Start from the base component, then layer one or two levers at most. Composing more than two on a single surface is a flag that the layout has outgrown the component.

• Adjust padding — wrap or replace the default body with <Box padding={spacingToken}>. Use space-100 (compact), space-200 (default), space-300 (relaxed).
• Add a top image — place the media inside <ModalInset inheritPadding={false}> above ModalBody. The image bleeds to the surface edges; body padding resumes below.
• Add a side image — use <ModalSplit> before <ModalBody> for a leading panel, after for a trailing panel. Side is set by DOM order, not a prop.
• Mix inset and standard content — ModalInset accepts content alongside padded body content within the same ModalBody. Use this for full-width banners or dividers inside an otherwise-padded modal.
• Tighten density inside a surface — apply density at the surface root; descendants inherit. Do not set density on individual rows or fields.

Ship solo vs. design review

Each lever has a range that ships without review and a threshold that requires it. The threshold is the line where the refinement stops being a recipe and starts being a new pattern.

table

Lever	Ships solo (no review)	Requires design review
Padding scale	One step from default (compact or relaxed) using sanctioned spacing tokens	Custom padding values, or stepping more than one level in the same surface
Media placement	Any of the four sanctioned slots, single image per surface	Multiple media slots on one surface, or media that overlaps non-media content
Panel proportion	Any of the three sanctioned ratios using ModalSplit	Custom ratios, three-column layouts, or proportion changes mid-flow
Density	One step from default	Mixed density within a single surface, or density applied per-field rather than per-surface
Edge treatment	inset (default) or single-side flush	Full-bleed content that crosses navigation chrome, or bleed combined with shadows

When a refinement crosses into the right column, do not ship it. Open the conversation with #design-systems or attach a design review to the PR. The right column is where new patterns are born — and new patterns belong in Pluma, not in a one-off composition.

When the levers aren't enough

If the layout needs something the levers don't name, that's the signal — not the gap. A new requirement means the design system is missing a pattern, not that the recipes are too tight. Flag it in #design-systems rather than composing around the bounds in code.