Alert - Design decisions

What is an ADR?

We use the ADR (Architecture Decision Record) to structure design decision documentation. Each ADR covers three things: the context that prompted the decision, the decision itself, and its consequences — including trade-offs and any open questions.

ADR 001 - Full-width alert

• Date raised: March 3, 2026
• Decision date: March 11, 2026

Context

The design system includes two very similar components: Alert and Banner. Both serve similar purposes for displaying important messaging to users.

Current differences:

The Banner component internally uses the Alert component in the codebase. The Alert component has a fullWidth prop; Banner achieves its full-width behavior through this prop. Figma does not explicitly represent a full-width Alert variant.

This created ambiguity about whether the fullWidth prop should remain on the Alert component, whether full-width behavior should be exclusive to Banner, and whether Figma should support a full-width Alert variant.

Options considered:

Option 1 — Remove fullWidth from Alert and make Banner independent

Banner becomes its own component and no longer depends on Alert.

• Pros: Clear separation of responsibilities, cleaner Alert API, design and code align more closely
• Cons: Refactoring required, potential duplication of code, more maintenance overhead

Option 2 — Keep fullWidth but treat it as an implementation detail for Banner

Alert technically supports fullWidth, but it is not encouraged for direct use outside Banner. Storybook may still expose the prop for transparency because Banner relies on it.

• Pros: Maintains compatibility, avoids refactoring Banner, prevents expanding Alert usage unintentionally
• Cons: Slight API ambiguity, requires documentation guidance

See .

Decision

Option 2 — Keep fullWidth on Alert, but treat Banner as the primary full-width pattern.

Rationale:

• Banner is implemented using Alert, so removing the prop would introduce unnecessary refactoring.
• Keeping the prop ensures compatibility and stability.
• Documentation and Storybook can clarify that Banner is the preferred component for full-width messaging.
• The Figma Alert component will not add a full-width property.

Consequences

Positive

• No breaking changes
• Banner implementation remains simple
• Development velocity is unaffected

Negative

• Alert API includes a prop that may rarely be used directly
• Requires documentation guidance to avoid misuse

Open Questions

None