Composition Over Modification

Composition over modification is a design principle that prefers assembling UI from existing components rather than altering those components. This approach reduces drift by channeling customization through assembly patterns that preserve component integrity while achieving desired outcomes.

What Is Composition Over Modification

Composition over modification advocates building desired UI by combining existing design system components rather than modifying their internals or overriding their styles. Instead of editing a card component to add a custom header, composition uses the card component alongside a separate header component arranged to achieve the desired result.

This principle originates from object-oriented design where composition is preferred over inheritance for building complex behavior. Applied to design systems, it means preferring component combination over component alteration.

How Composition Over Modification Works

Compositional assembly combines multiple components. Rather than a monolithic component serving all needs, consumers receive component parts they assemble. A complex form is built by composing input, label, button, and layout components rather than using a single form component with extensive configuration.

Container patterns provide structure for composition. Generic container components like cards, panels, and sections provide visual structure into which consumers place content components. Containers do not prescribe content; they provide frames.

Compound component patterns provide coordinated parts. Tab groups provide Tab, TabList, and TabPanel components that consumers combine. The compound components coordinate with each other while consumers control arrangement and content.

Layout utilities enable spatial composition. Grid, stack, and flex components enable consumers to arrange content components spatially without modifying those components. Layout is separated from content.

Higher-order composition wraps components to add functionality. Wrapper components can add behavior like analytics, error boundaries, or access control around design system components without modifying them.

Key Considerations

• Composition requires components designed for composability
• Some needs are difficult to address through composition alone
• Composition can produce verbose component trees
• Performance implications of deep component nesting should be considered
• Documentation should demonstrate compositional patterns

Common Questions

When is modification appropriate despite this principle?

Modification may be appropriate in specific situations. When composition cannot achieve required results and no extension pattern applies, modification may be necessary. When performance requires avoiding compositional overhead, more integrated approaches may be justified. When design system gaps make composition impractical, temporary modification pending design system updates may be warranted. Even when modification is appropriate, it should be localized, documented, and ideally channeled through exception processes. The principle guides default behavior rather than prohibiting all alternatives.

How should design systems enable composition?

Enabling composition requires intentional component design. Components should be single-purpose rather than multi-purpose; complex components should be built from smaller ones. APIs should accept children or slots for content injection. Components should work well when nested within each other. Styling should not assume specific parent-child relationships. Documentation should show compositional patterns alongside basic usage. Component kits can provide starter compositions for common patterns. Design system teams should consider composability during component design review.

Summary

Composition over modification prefers assembling UI from existing components through compositional assembly, container patterns, compound components, layout utilities, and higher-order composition. This approach reduces drift by preserving component integrity while meeting customization needs. Modification may be appropriate when composition cannot achieve requirements, but should remain the exception. Enabling composition requires intentional component design with single-purpose components, content injection APIs, and documentation demonstrating compositional patterns.