Imagine this scenario: It's almost time to meet, and there's only a little space left on your phone. Someone opens a website they know all too well. Just as their finger is about to press the button as usual, they notice the text has wrapped and is slightly off-center. What should have been a quick action suddenly requires them to find it again.
"Hey, it was right here yesterday."
This hypothetical complaint probably illustrates what users care about more than any architecture diagram. A website can have many things changed behind it, but users only see the current screen and a small task they want to complete quickly. If a technical redesign accidentally disrupts that rhythm, even if the internal structure is beautifully organized, the user experience will be momentarily disrupted.
Therefore, there is a type of engineering achievement that is particularly quiet: a lot has clearly been done, yet people who open the website use it smoothly without even realizing that a migration is underway. This kind of "as if nothing has happened" routine is actually worth taking a closer look at.
You usually don't pay attention to how the buttons are styled when you open the same website every day. But if one day the text is pushed out of the box or the menu spacing suddenly changes, you'll notice it very quickly. For those who maintain a website, changing the underlying style architecture while keeping it usable is a very real challenge.
GitHub's Primer design system faces this problem. In a post published on September 25, 2026, GitHub explained its approach to migrating from CSS-in-JS to CSS Modules: a gradual approach, adding translated archives, switching styles using feature flags, and using visual regression testing to maintain the existing user experience. [S1]
Imagine it as a library moving books; then you can picture it.
Imagine a library that remains open as usual, and the librarians want to change the way the back office is organized. Readers still need to find books, borrow them, and sit in their familiar spots to read a few pages. Books can't all be piled up in the aisles with a sign saying, "We're busy lately, please feel free to do what you need." The organization plan must consider the people using the space.
The migration of a website's style and architecture can also be understood through this analogy. Readers see bookshelves and signs, but librarians also have to manage categorization, labeling, and where to put new books each time they arrive. The clearer the shared rules are organized, the easier it is for subsequent staff to maintain the same practices.
But "completing the transfer" is just one milestone in the engineering process. For readers, what truly matters is whether familiar books can be found, whether instructions are consistent, and whether the borrowing process suddenly becomes convoluted. On a website, this translates to whether the interface and user experience are seamlessly integrated.
This analogy has another advantage: it naturally evokes the idea of a transition period. A library can organize one section first, confirming that the markings are correct, before moving on to the next section. Allowing space for inspection at each step makes it easier to know which row to refer back to when questions arise.
First, understand where the changes occurred.
To better understand this change, think of the design system as a set of shared interface components for a website. Readers see buttons, text, and various blocks, while the engineering team maintains the style rules behind them. When these shared rules change, the scope of concern extends beyond individual screens.
According to the official documentation, CSS Modules allow developers to write styles in a CSS file that coexists with the JavaScript source code, and by default restricts category names to local scope, reducing the risk of global selector conflicts. [S1] As you can imagine, different interfaces all want to use the same short name; the purpose of localization is to avoid styles from accidentally affecting other places when names are the same.
For the average user, these kinds of changes are difficult to see directly. Therefore, judging the success of a migration cannot stop at simply changing the code format. We must also ask: Did the familiar interface maintain its original presentation? Was the team able to identify the differences early on? Are the benefits of the new architecture enough to justify the conversion costs?
A hypothetical scenario: The bookshelves have been replaced, but will readers be able to find them?
Next, we have a fictional library meeting where the engineering problems are replaced with everyday language.
Xiaohe: "The new categories are organized, and the tags are all affixed."
Amu: "Can the regular readers still find that original row of books?"
Xiaohe: "The classification logic has become very neat."
Amu: "But the arrow at the entrance still points to the old location."
Xiao He: "Okay, let's go through the reader route first."
In this little theater, no one was truly against tidying up. It's just that the desire for "easier internal maintenance" and "better external usability" needed someone to bridge the gap. When changing a website's style and code, you could ask: What differences will this change cause for users? Which differences are expected, and which need further review?
If the problem is clear enough, there's no need to keep going back and forth with "it feels a bit strange." For example, if text that was originally in the same column has now wrapped to the next line, first confirm whether it was supposed to be adjusted; if not, then find the rules that are affecting it. Describing the strange feeling as a comparable phenomenon will make the discussion much easier.
Break down a major switchover into verifiable steps.
The official incremental strategy includes three approaches: translating files, functional flags, and visual regression testing. [S1] From this arrangement, it can be inferred that the team focuses on how to compare and switch during the transition period, rather than simply rewriting the files. This approach also makes engineering decisions easier to discuss: process a portion at a time, confirm the results, and then decide whether to move to the next step.
Function flags can be understood as switches that control whether a function or behavior is enabled. In this official description, it is used to switch styles. [S1] This allows "the new style has been written" and "start using the new style" to be considered separately. To use this approach, the team should first clarify the unit of switching and the method of checking in order to know exactly where each change affects.
Visual regression testing focuses on the differences between the image before and after modifications. Assuming changes in text length, white space, or position of elements, comparisons can pinpoint areas requiring inspection. GitHub incorporates this type of testing into its migration strategy as part of its official documentation. [S1] When using this method, it's essential to first list the images and states worthy of comparison and decide who will determine whether the differences meet expectations.
Therefore, the most valuable aspect of this case study for other teams is that it breaks down "whether it can be modified" into "whether the modification results can be confirmed step by step." When using a similar approach, you can first select components with a clearly defined scope, list the presentation that needs to be maintained, and then check the differences before and after the switch. This is a practical suggestion based on the case study. The clearer the scope, the easier it is to return to the corresponding changes when problems are discovered, reducing the burden of searching back and forth among a large number of components.
Little-known facts about tools: Even the most inconspicuous "name" can cause trouble.
One easily overlooked key point about CSS Modules is that category names are localized by default. [S1] It sounds like small print in a document, but imagine each reading area has a card called "Notes," and you'll understand why it's useful. Children's sections and self-study sections can use the same headings, but that doesn't mean the content should be interchangeable.
Putting this analogy back to styles, it means giving names their own scope of application. The official documentation lists preventing global selector conflicts as a purpose of this approach. [S1] The name itself can be very ordinary; the important thing is knowing where it belongs when using it. For example, before calling out "team leader," it's best to first see which team is having a meeting.
Another small detail is that CSS Modules allows CSS files and JavaScript source code to coexist. [S1] So when you read "switch to CSS Modules", you can first focus on how the styles are arranged and how the names are managed. This makes it easier to match the actual changes and avoids being overwhelmed by a bunch of abbreviations, ending up only remembering a term that sounds new.
Another easily misunderstood word is "flag". In this description, the functional flag is responsible for switching styles. [S1] You don't have to actually imagine a flag planted on the screen; think of it as a control switch that decides which behavior to use, and it will be much easier to understand. The preparation and the actual switch are separated into different steps, which adds a point for discussion and inspection during the transition period.
Common misunderstandings: First, let go of the mental shortcuts.
The first common misconception is: "If the writing style changes, shouldn't the visuals also be drastically altered?" This case focuses precisely on maintaining the existing user experience during the migration. [S1] Just like a library updating its classification system, readers don't necessarily need to learn a new way of finding books. Internal organization can have its own goals, and external familiarity should also be preserved.
The second thought was: "The two screenshots look similar, so it should be fine." We can go a step further and change the context of the screen. What if the text becomes longer? What if the content is short? What will users encounter when they want to operate using the keyboard? By writing down the scenarios, the discussion will move from a beautiful static image to the actual user experience.
The third quick conclusion is: "Large companies adopt this, other teams can just copy it." A more practical approach is to first copy how it raises questions: how to batch, how to switch, and how to compare. As for whether to adopt the same writing style, it still depends on the scale of your product, your daily modification methods, and your maintenance burden.
Another tempting idea is: "Since we're going to make changes anyway, let's redesign the whole thing." However, if you cram architectural migration and major interface overhauls into a single project, it can be harder to pinpoint the reasons for the differences when discussing them. When planning your projects, start by writing down your goals and deciding which changes are essential and which can be postponed. Clearly defining your tasks often provides a better sense of progress than simply piling them up.
Image stabilization is just one piece of evidence.
Visual testing has a clear purpose, but just because the visuals look identical doesn't answer all user experience questions. For example, keyboard smoothness and proper display of content of varying lengths can be included in the team's own verification checklist. Connecting the checks to actual usage scenarios makes it easier to clarify whether a difference is merely a cosmetic adjustment or has already impacted the user's ability to complete tasks.
Performance is also an issue worth tracking. A GitHub article is titled "Improving Website Performance." [S1] For teams considering similar migrations, they can first select representative pages and measurement methods, and then compare the results before and after the switch. In this way, the architecture choice can be linked back to the experience that the product truly cares about, and it is also easier to decide how much effort to put in afterwards.
To determine which new data will change the decision to migrate, consider three specific things: whether performance has improved before and after, whether interface issues are easier to identify, and how much time is spent on subsequent maintenance. A smooth transition in the short term and ease of modification even six months later are worth noting separately. Looking at both together helps to understand the costs and benefits of the transition.
Furthermore, whether developers can understand the existing rules after importing the new syntax is a practical issue. Other teams can follow suit by observing how many files need to be consulted when adding new components, whether the same questions are repeatedly encountered, and then adding the answers back to the examples. These kinds of routine tasks often better reflect whether the architecture is easy to maintain.
The questions worth asking about large design systems become very specific: Can this transition method help problems be detected earlier? Will it be easier to maintain consistency when adding components later? As these answers become clearer, other teams will have sufficient evidence to determine which practices are suitable for their products.
Weekend Mini-Exercise: Play Interface Moving Game with Paper Cards
This exercise only requires paper, pen, or any blank document that can type. First, create an imaginary activity card with a title, date, and a "View Details" button. No programming or website login is required. This card is a miniature version of the shared components.
Next, copy several cards and change the content. One has a very short title, and one is intentionally very long; one has a simple date, and one includes more complete time information. Keep the original appearance of each card as a reference for later comparison. You'll then find that the same template can require completely different attention to detail depending on the content.
Now pick one rule to change, such as the spacing between buttons and text. Change only one item at a time, and then compare the before and after versions side by side. Which card still looks good? Which one looks cramped? Suddenly, the question "What does this change affect?" has a concrete answer, instead of just a simple "the layout has been slightly adjusted."
Here's another small challenge: Imagine one of the cards as a narrow section on a phone screen, and try rearranging the content. Is the important information still accessible? Has the button text become difficult to read? The purpose of these questions is to practice leaving room for usage scenarios, not to create a design that's perfect for immediate submission.
Finally, have another person look at only the two sets of cards and ask them to point out the differences. If they say "something feels off," ask them to point to the specific location. Write down the answer as a single, actionable description, such as "The long title pushed the button to the next line." This clear description is much more effective than ten "let's fix it" statements in ensuring the next revision addresses the problem.
After practicing, you can also create a small rule card for this set of cards: which spacings are fixed, which content can be wrapped to a new line, and where to check first when encountering long text. When another person can produce similar results by following the rules, the purpose of designing a system to "keep different people consistent" becomes very meaningful.
Postscript: The best modified version ever; it's sometimes really quiet.
Imagine a library that has just finished organizing a section; readers can easily find their books by following familiar paths, and librarians can more easily handle newly arrived materials. There are no particularly grand opening sound effects, but daily operations are less prone to glitches. Adjustments to a website's architecture can also be envisioned through such a simple and straightforward lens.
The best way to take this case study from Primer is to look at it from before and after the switch: How were the rules organized? How were the differences discovered? Did users need to readjust? When these questions are addressed, the technical terms can be connected to the small, everyday actions that actually happen.
Next time you see a button still obediently in its place, you can easily remember the book-moving project to come. There are no surprises on the screen; sometimes it's just the result of a very careful organization. Making it easier for people to search and stop less is a worthwhile improvement.
source
- [S1] Improving site performance by shipping more CSS｜GitHub Blog｜Published: 2026-09-25T15:00:00+00:00｜Retrieve: 2026-09-26T00:02:04.055040+00:00｜https://github.blog/engineering/architecture-optimization/improving-site-performance-by-shipping-more-css