Component Boundaries

Purpose: Guidelines for determining what constitutes a component.

Referenced by: Design system router, assessment flow

The Core Question

"Is this one component or multiple components?"

This is the most common design system challenge.

Guiding Principles

Principle 1: Single Responsibility

A component should do one thing well.

✅ Good: Button component triggers actions ❌ Bad: Button component that also handles forms, navigation, and modals

Principle 2: Reusability

A component should be reusable across contexts.

✅ Good: Input Field used in login, signup, profile forms ❌ Bad: Login-Specific Input Field that only works on login page

Principle 3: Independence

A component should work independently.

✅ Good: Card component that can contain any content ❌ Bad: Card component that requires specific parent container

Common Boundary Questions

Q1: Icon in Button

Question: Is the icon part of the button or separate?

Answer: Depends on usage:

Part of Button (Variant):

Button Component:
  variants:
    - with-icon-left
    - with-icon-right
    - icon-only

When: Icon is always the same type (e.g., always arrow for navigation)

Separate Components:

Button Component: (text only)
Icon Component: (standalone)
Composition: Button + Icon

When: Icons vary widely, button can exist without icon

Recommendation: Start with variant, split if complexity grows.

Q2: Label with Input

Question: Is the label part of the input or separate?

Answer: Usually part of Input Field component:

Input Field Component:
  includes:
    - Label
    - Input element
    - Helper text
    - Error message

Reason: These always appear together in forms, form a semantic unit.

Q3: Card with Button

Question: Is the button part of the card?

Answer: Usually separate:

Card Component: (container)
Button Component: (action)
Composition: Card contains Button

Reason: Card is a container, button is an action. Different purposes.

Q4: Navigation Bar Items

Question: Is each nav item a component?

Answer: Depends on complexity:

Simple (Single Component):

Navigation Bar Component:
  includes: All nav items as configuration

Complex (Composition):

Navigation Bar: (container)
Navigation Item: (individual item)
Composition: Nav Bar contains Nav Items

Threshold: If nav items have complex individual behavior, split them.

Decision Framework

Step 1: Ask These Questions

Can it exist independently?
- Yes → Probably separate component
- No → Probably part of parent
Does it have its own states/behaviors?
- Yes → Probably separate component
- No → Probably part of parent
Is it reused in different contexts?
- Yes → Definitely separate component
- No → Could be part of parent
Does it have a clear single purpose?
- Yes → Good component candidate
- No → Might need to split further

Step 2: Consider Complexity

Low Complexity: Keep together

Icon in button
Label with input
Simple list items

High Complexity: Split apart

Complex nested structures
Independent behaviors
Different lifecycle

Step 3: Think About Maintenance

Together:

✅ Easier to keep consistent
❌ Component becomes complex

Apart:

✅ Simpler components
❌ More components to manage

Composition Patterns

Pattern 1: Container + Content

Container provides structure, content is flexible.

Card Component: (container)
  - Can contain: text, images, buttons, etc.
  - Provides: padding, border, shadow

Pattern 2: Compound Component

Multiple parts that work together.

Accordion Component:
  - Accordion Container
  - Accordion Item
  - Accordion Header
  - Accordion Content

Pattern 3: Atomic Component

Single, indivisible unit.

Button Component:
  - Cannot be broken down further
  - Self-contained

Red Flags

Too Many Variants

Warning: Component has 10+ variants

Problem: Probably multiple components disguised as variants

Solution: Split into separate components based on purpose

Conditional Complexity

Warning: Component has many "if this, then that" rules

Problem: Component doing too many things

Solution: Split into simpler, focused components

Context-Specific Behavior

Warning: Component behaves differently in different contexts

Problem: Not truly reusable

Solution: Create context-specific components or use composition

Examples

Example 1: Button

One Component:

Button:
  variants: primary, secondary, ghost
  states: default, hover, active, disabled, loading

Reason: All variants serve same purpose (trigger action), share behavior

Example 2: Input Types

Multiple Components:

Text Input: (text entry)
Select Dropdown: (choose from list)
Checkbox: (toggle option)
Radio: (choose one)

Reason: Different purposes, different behaviors, different HTML elements

Example 3: Modal

Compound Component:

Modal: (overlay + container)
Modal Header: (title + close button)
Modal Body: (content area)
Modal Footer: (actions)

Reason: Complex structure, but parts always used together

When in Doubt

Start simple:

Create as single component
Add variants as needed
Split when complexity becomes painful

It's easier to split later than merge later.

Company Customization

Companies can define their own boundary rules:

# Acme Corp Component Boundaries

**Rule 1:** Icons are always separate components
**Rule 2:** Form fields include labels (never separate)
**Rule 3:** Cards never include actions (composition only)

Consistency within a company matters more than universal rules.

Use this guide when the design system router detects similarity and you need to decide: same component, variant, or new component?

component-boundaries.md 6.1 KB História Raw