Marcus Andrey Study
Ler em português Library

Design Systems · Step 3 · 6 min read

Composition over configuration

A component with a prop for every case gets harder to use with each request. Composition gives teams small parts that fit together instead. Why props pile up, how Harbour's Ticket card is built from parts, Brad Frost's components, recipes and snowflakes, and where configuration is still the right answer.

Every prop is a request someone made once, and the component has to honour it forever. The Ticket card started with four props. Then the console wanted the QR code inline, marketing wanted the cabin highlighted, and someone needed a second button. A year later it has fourteen, half the combinations have never been seen together, and the docs page is a wall. There's a calmer way to grow: give teams parts, not switches.

What you'll be able to do after reading:

  • Recognise a component that's growing by configuration, and what it costs
  • Rebuild it from smaller parts that compose
  • Tell a system component from a recipe and a snowflake
  • Decide when a prop is right and when a slot or a new part is

1. Two ways to build the same card

Configuration: one component, a prop for every case

<TicketCard
  route="Kestrel Bay → Mara Island"
  status="on-time"
  showStatus={true}
  departure="09:40"
  duration={50}
  passengers="2 adults"
  vehicle={null}
  showVehicle={false}
  primaryLabel="Show ticket"
  secondaryLabel="Get a refund"
  secondaryVariant="ghost"
  compact={false}
  showQrInline={false}   // added for the console
  highlightCabin={true}  // added for one campaign
/>

14 props and growing. Every new screen adds one. Nobody knows which combinations work, and the docs can't show them all.

Composition: small parts that fit together

  • Card
  • Card.Header
  • Heading · Badge
  • Card.Body
  • DepartureLine · DetailList
  • Card.Actions
  • Button · Button
<Card>
  <Card.Header>
    <Heading>Kestrel Bay → Mara Island</Heading>
    <Badge tone="success">On time</Badge>
  </Card.Header>
  <Card.Body>…</Card.Body>
  <Card.Actions>
    <Button size="compact">Show ticket</Button>
  </Card.Actions>
</Card>

Each part has three or four props. A new case is a new arrangement of the same parts, not a new prop.

The same Ticket card built two ways. With configuration, the component knows every case; with composition, the system gives parts and the product team arranges them. The composed version is what Brad Frost calls a recipe: a fixed arrangement of system components that one product reuses.

Configuration means one component that knows every case and exposes a prop for each. It's easy to start: one import, fill in the blanks. It gets harder with each request, because every new prop multiplies the combinations, and the component's code fills with if statements for screens it was never meant to know about.

Composition means small components that fit together: a Card with a Header, a Body and an Actions area, and the Heading, Badge and Buttons that go inside them. Each part has a few props. A new case is a new arrangement, not a new prop.

React's docs describe the second approach in one sentence: a component that takes children has a "hole" that its parent can fill "with arbitrary JSX" (React, Passing JSX as children). Figma's slots, from Variants, properties and slots, are the same idea in the design tool.


2. Components, recipes and snowflakes

Brad Frost gives a vocabulary that helps decide where each piece lives (Frost, Design system components, recipes, and snowflakes, 2021):

Frost's definition In Tidewater
Design system component "shared, content-agnostic, and context-agnostic built for maximal reuse" Card, Badge, Button, Heading: in Harbour
Recipe "specific compositions of design system components" used consistently in a product Ticket card: Card + Badge + Button, owned by the booking app
Snowflake "one-off components that are needed to build a product, but don't really get reused" The deck map for choosing a cabin, on one screen

Frost's own snowflake example comes from an airline: a Seat component that only made sense for the seat selection screen. A ferry has the same thing.

This changes the question "should the Ticket card be in Harbour?". The answer is: the parts are; the card is a recipe. Harbour publishes Card, Badge and Button, plus documented recipes that show how teams put them together. The booking app owns its Ticket card and can change it without a Harbour release.


3. Where configuration is still right

Composition isn't always better. Some things should be a closed list, on purpose:

  • Meaning and importance. variant="danger" should be a prop with four values, not a slot where anyone can put any colour.
  • Size and density. A fixed scale, from tokens.
  • Behaviour the system must guarantee. Focus handling in a dialog, keyboard rules in a combobox. Those stay inside the component, where teams can't break them (see Accessible components).

A useful rule: configure what must be consistent, compose what must be flexible. The Button's variant is configured; the Card's body is composed.


4. Signs a component needs to be split

  • Boolean pairs: showStatus and status, showVehicle and vehicle. The data already says if there's something to show.
  • Props named after a screen or team: consoleMode, campaignHighlight. That's a recipe hiding in the system.
  • Props that only work together: secondaryLabel needs secondaryVariant needs secondaryOnClick. That's a nested Button trying to get out.
  • A docs page that can't show every combination.
  • Detach rates going up in Figma. People detach when the component won't do what they need. Figma notes that slots help "reduce occurrences of detached components so instances will continue receiving updates" (Figma Help, slots).

When you see two or three of these, split: find the parts, give each a small API, and publish the old component as a recipe built from them.


5. Keeping composition consistent

The risk of composition is the opposite of configuration: so much freedom that every team builds the card differently. Harbour uses three guardrails:

  1. Documented recipes. The Ticket card recipe is on the docs site with its code and its Figma version. Copying it is easier than inventing.
  2. Limits on slots. Preferred instances and a maximum number of items in Figma; in code, the Actions area accepts Buttons only, and warns otherwise.
  3. Review, not policing. A new recipe used by two products is a candidate for the system. That conversation is Contribution models.

6. Common mistakes

  • Adding a prop for each request instead of asking what the parts are.
  • Putting product recipes in the system library, then needing a system release to change a product.
  • Going fully composable for things that must be consistent, like a button's meaning.
  • Slots with no guidance, so every team arranges the parts differently.
  • Breaking the old component's API when splitting, instead of keeping it as a recipe for a while (see Deprecation and breaking changes).

7. Vocabulary

Term Meaning
Configuration Changing a component through props, from a list the component knows
Composition Building a component from smaller ones placed inside each other
children In React, the content placed between a component's tags; its "hole"
Recipe A fixed arrangement of system components that a product reuses
Snowflake A one-off component for one screen, not meant for reuse
Prop explosion A component with so many props that nobody knows which combinations work

8. Try it (no tools needed)

  1. Find the component with the most props or variants in a product you know.
  2. List its props. Mark the Boolean pairs, the screen-named props and the props that only work together.
  3. Draw it as a tree of smaller parts, like the right side of the figure.

Reflection questions: Which of its props would disappear if it were composed? Which ones must stay, because they protect consistency?


9. If you already practise

  • Track props per component over time; a steady climb is an early warning.
  • Publish recipes as their own section of the docs, with owners from the product teams.
  • In Figma, check how often each component is detached, and start splitting from the top of that list.
  • When you split, keep the old API as a thin recipe for one release cycle, with a deprecation note.

Checklist

Learn more

Books, courses and videos to go deeper

Book links go to Amazon. As an Amazon Associate I earn from qualifying purchases, at no extra cost to you.

Variants, properties and slots · Accessible components · Anatomy and API of a component · From components to patterns · Contribution models · Deprecation and breaking changes

Saved only on this device.

↑ ↓ to move · Enter to open · Esc to close