Composition

Composition is the primary extension mechanism in ForgeUI.

Rather than relying on configuration flags or variant props, ForgeUI encourages building complexity by combining simple parts.

This keeps APIs small and behavior explicit.

---

Why composition matters

Composition allows components to:

• remain focused
• avoid over-generalization
• adapt to new use cases without API changes

A composable system is easier to grow and harder to misuse.

---

Building up, not out

ForgeUI prefers building upward through composition instead of expanding components horizontally with more options.

Instead of adding:

• new variants
• conditional behavior
• complex configuration objects

ForgeUI encourages:

• wrapping components
• composing primitives into patterns
• creating application-specific abstractions

---

Local composition

Composition should happen close to where components are used.

Local composition:

• keeps logic discoverable
• avoids global coupling
• makes refactoring safer

This approach also makes it easier for different teams to evolve patterns independently.

---

Composition at scale

At scale, composition helps teams share patterns without enforcing rigid abstractions.

Common strategies include:

• extracting repeated compositions into shared components
• documenting common patterns instead of formalizing them too early
• allowing divergence when requirements differ

ForgeUI supports gradual standardization rather than enforced uniformity.

---

Final thought

Composition is a discipline.

ForgeUI provides the pieces, but meaningful composition requires judgment and restraint.