How Red Hat Refactored Their Design System Without Stopping the Site

It was an ordinary afternoon when someone asked a seemingly simple question:

"How modular is our design? We'd like to share small parts of the theme with other company sites."

The honest answer? Nervous laughter.

Because those who knew the code intimately knew the truth: that design was the antithesis of modular.

The Context

The redhat.com site had just launched. By all metrics, it was a success:

• Efficient UI
• Fast loading
• Visually appealing

But under the hood, the code told a different story.

The Problems

1. Dependency Bloat

To render a single content section, you needed to load:

And that was just for styles. JavaScript wasn't even in the picture yet.

Bootstrap wasn't even really used — the site was built assuming it had already "washed" all the markup. Removing Bootstrap broke everything.

2. Location-Dependent Nightmare

Look at this actual CSS selector from the project:

This style:

• Only works on the "about-contact" page
• Requires an exact HTML structure
• Depends on direct descendancy (>)
• Has extremely high specificity

Each change required even longer and more specific selectors.

3. Top-Down Styling

The approach was to style "from the band down". Each section type (hero, testimonials, blog teasers) had its own Sass folder, and all styles were scoped under the band name.

It worked in a sense — you generally knew where to look. But:

• Each new variation required a new band
• Content couldn't be reorganized
• Markup order was strict
• Nothing was portable

The Honest Answer

When asked about modularity, the answer was:

"We'd need to completely rewrite the markup and CSS of anything we wanted to share. And since we're at it, we should update the markup on the site too."

They expected laughter. Instead, they heard: "Okay. When do we start?"

The Action Plan

With the site in "code freeze" post-launch, the team had a few weeks to create a new system. The plan:

1. Break the Design into the Smallest Possible Parts

The previous approach was top-down: from band to elements. The new approach would be bottom-up: from atoms to pages.

They mapped all visual elements:

• Buttons and their variations
• Typography (headings, body, captions)
• Spacing
• Cards
• Forms
• Icons

2. Catalog Components

Each element received:

• Standardized name
• Documented use cases
• Allowed variations
• Example code

3. Create Clear Rules

Inspired by the "Road Runner Rules" concept (simple rules that guide complex decisions), they defined principles:

Single Responsibility Principle Each class does one thing.

Single Source of Truth Each style is defined in one place only.

Opt-in Modifiers Variations are explicit, not implicit.

Opt-in Context Components work anywhere by default.

4. One Selector for Everything

The most radical rule: one single selector per component.

The Execution

Gradual Migration

They didn't rewrite everything at once. The process was:

1. Create new component in modular system
2. Document in style guide
3. Test in isolation
4. Replace one instance on the site
5. Validate in production
6. Repeat until all instances replaced
7. Remove old code

Coexistence

During migration, new and old code coexisted. This required:

• Careful namespacing
• Visual regression tests
• Constant team communication

Real-Time Documentation

Each new component was born documented. It wasn't "document later" — it was part of the creation process.

The Results

After refactoring:

But more important than numbers was the cultural change:

• New devs were productive in days, not weeks
• Changes were made with confidence
• The system could grow without becoming a mess

Lessons Learned

1. It's Never Too Early

If they had thought about modularity from the start, they would have saved months of rework.

2. It's Never Too Late

Even with a site in production, refactoring was possible. The post-launch code freeze created the perfect window.

3. Refactoring is Investment

The "lost" time refactoring paid for itself in future development speed.

4. Documentation is Code

Components without documentation don't really exist. Documenting alongside development avoids technical debt.

5. Simple Rules > Complex Rules

Principles like "one selector per component" are easy to remember and apply. 50-page guides nobody reads.

Applying to Your Project

If you're in a similar situation:

1. Audit your current CSS — What's the average specificity? How many !importants?
2. Identify the biggest offenders — Which components are most problematic?
3. Start small — One well-made component is better than ten half-baked ones
4. Document as you go — Don't leave it for later
5. Define clear rules — And follow them religiously

The journey from "div soup" to modular design system is long, but each step brings you closer to code you're not afraid to touch.