Customization

ForgeUI components are intentionally unopinionated at the token level.

Rather than enforcing a predefined theme or design-token system, ForgeUI focuses on providing strong structural defaults that can be adapted to a wide range of visual identities.

Customization is expected.
What ForgeUI optimizes for is predictable customization.

---

Tailwind-first approach

ForgeUI relies on Tailwind utility classes for all visual decisions.

That means:

• spacing is defined via utilities
• color choices are visible in class names
• typography is applied explicitly in markup

There are no hidden configuration layers controlling how components look.

This makes customization straightforward:

• change utilities
• extend classes
• remove what you don’t need

If you can read the JSX, you can understand how the component is styled.

---

Customizing safely

The safest way to customize ForgeUI components is through local overrides.

Common patterns include:

• wrapping a component to apply additional classes
• replacing utility classes with project-specific tokens
• composing a new variant from existing primitives

These approaches keep changes localized and reduce the risk of breaking behavior elsewhere.

---

Working with design tokens

ForgeUI does not define its own token system, but it works well with existing ones.

Teams often introduce tokens using:

• CSS variables
• Tailwind theme extensions
• application-level utility abstractions

ForgeUI components can consume these tokens naturally through class names without additional configuration.

This keeps ForgeUI flexible while allowing teams to standardize visual decisions where it makes sense.

---

Avoiding over-customization

ForgeUI intentionally discourages excessive configuration.

Highly configurable components often:

• become difficult to reason about
• require extensive documentation
• introduce subtle edge cases

Instead of adding more props, ForgeUI encourages creating new compositions that reflect real usage.

---

Explicitness over magic

ForgeUI favors explicitness over magic.

If a component is doing something:

• it should be visible in the markup
• it should be traceable to a specific class or element
• it should be easy to change or remove

This philosophy reduces surprise and makes components easier to maintain over time.

---

Customization at scale

As teams grow, customization needs change.

ForgeUI supports scaling by:

• keeping component APIs small
• encouraging composition over configuration
• avoiding global side effects

These patterns make it easier for multiple developers to work on the same codebase without stepping on each other’s changes.

---

In practice

When customizing ForgeUI components:

• start with small, local changes
• avoid global overrides unless necessary
• document non-obvious decisions

Over time, these practices help keep the system coherent even as visual requirements evolve.

---

Final thought

Customization should feel deliberate, not accidental.

ForgeUI provides the structure.
Your design system provides the identity.