Verified against Claude · 2026-07-20
Design a component API that won't need a breaking change in six months
Designs a design-system component's prop contract by working backward from real use cases, with explicit composition slots instead of a boolean prop for every variant.
The prompt
Ready to copy — highlighted parts are example details you can swap.
<role> You are designing the public prop API for a design-system component, before implementation. The goal is an API that covers the real use cases below without a prop explosion or a breaking change when the next use case shows up. </role> <component_name> Banner </component_name> <use_cases> 1) An info banner at the top of a page. 2) A dismissible warning banner inline in a form. 3) An error banner with a retry action. 4) A success confirmation that auto-dismisses after a few seconds. </use_cases> <constraints> Must not depend on a specific styling library beyond CSS variables already defined in the design tokens; must work inside a form without stealing focus; must support RTL layouts. </constraints> <api_design_rules> - Start from the use cases, not from a guess at every possible variant. Every prop you propose must trace back to at least one listed use case. - Prefer composition slots (children, a named slot prop, an asChild-style pattern) over a boolean prop per visual variant. If you're about to propose a fourth boolean like isCompact/isCentered/isBordered, stop and ask whether a variant prop with a closed set of string values, or a composition slot, fits better. - Every prop needs a default that makes the component usable with zero configuration for the most common use case in the list. - Name props for what they mean to the consumer, not for the CSS or implementation detail behind them (status, not colorScheme, when the intent is semantic). - Explicitly list what this component will not support — the use cases you're deliberately not designing for — so scope creep in review has something concrete to push against. </api_design_rules> <output_format> 1. The prop table: name, type, default, which use case it serves. 2. A short usage example for the three most common use cases from the list. 3. The explicit out-of-scope list. </output_format>
Customize the highlighted detailsoptional — the prompt above already works
Why this works
Boolean-prop explosion is the single most common way a design-system component's API rots over time — isCompact plus isCentered plus isBordered eventually produce combinations nobody actually tested and some that aren't even valid together — so giving the model a concrete trigger ("about to write a fourth boolean, stop") is more effective than a vague instruction to "keep it simple," which every design system already claims to want and few achieve. Requiring every prop to trace back to a listed use case is what actually prevents speculative generality: the temptation to add a prop for a use case nobody asked for yet is exactly how APIs accumulate surface area no one uses but everyone has to maintain. The explicit out-of-scope list matters specifically because a design-system component is a shared contract other teams build against — writing down what it deliberately doesn't support is the concrete artifact that lets a reviewer six months from now say "that's a new use case, it needs its own review" instead of quietly bolting another prop onto an already-overloaded component.
What you get back
Prop | Type | Default | Use case variant | 'info' | 'warning' | 'error' | 'success' | 'info' | all four dismissible | boolean | false | warning banner (2) onDismiss | () => void | undefined | warning banner (2) action | { label: string; onClick: () => void } | undefined | error banner with retry (3) autoDismissMs | number | undefined | success confirmation (4) Out of scope: stacked/queued multiple banners at once, and a persistent "banner history" log — both deliberately left for a separate NotificationCenter component.
Verified against
Claude Sonnet 4.6 · 2026-07-20
ChatGPT GPT-5.1 · 2026-07-31
Changelog
- 2026-07-20 — Initial publish, verified against Claude (Sonnet 4.6) and ChatGPT (GPT-5.1).
Need this built into your business?
If a prompt isn't enough — custom software, built and maintained for you — that's Scult's day job.
EXPLORE CUSTOM SOFTWARE

