Design System, Cascade Layers and @scope
On this page
Consistency doesn't happen by itself
Split a frontend across five teams and, six months later, you'll have five slightly different blues, three button heights and two date formats. Each choice was reasonable. Together they make the product feel stitched together.
A design system prevents that. It has three layers, and each travels differently:
| Layer | Example | How it's shared |
|---|---|---|
| Design tokens | --ds-primary, spacing, radii, fonts | CSS custom properties, loaded once by the shell |
| Components | Button, Dialog, DatePicker | A versioned package, usually React components |
| Guidelines | When to use a dialog, tone of error messages | Documentation and review |
Tokens as CSS custom properties
Tokens are the foundation, and CSS custom properties are the right way to ship them. The shell loads one stylesheet that defines them on :root:
:root {
--ds-primary: rgb(37, 99, 235);
--ds-radius: 6px;
--ds-space-2: 8px;
--ds-font: system-ui, sans-serif;
}
@media (prefers-color-scheme: dark) {
:root { --ds-primary: rgb(96, 165, 250); }
}Every micro-frontend uses var(--ds-primary), whatever its framework. Custom properties even pass into shadow DOM, as Day 7 showed: a component inside a shadow root picked up the page's --shop-border value. Theming, dark mode and a brand refresh become changes to one stylesheet, deployed once, and every team picks them up on the next page load.
Components as a versioned package
Share components as a normal npm package, @shop/design-system, installed and bundled by each team. This is the one place where build-time sharing is right (Day 3): a button doesn't need to deploy independently of the screen that uses it.
Versioning keeps teams independent. The catalog can be on design system 4.2 while the cart moves to 4.3. Because every version reads the same tokens, they still look alike. Set a policy for how far behind a team may fall, for example one minor version per quarter, and enforce it in CI.
Should the component package be shared at run time through the import map, like React? Only if it holds state that must be single, such as a toast manager or a theme context. Usually it's better bundled per team. Mind Day 9's rule: if the design system's React components are shared at run time, they must use the same React copy as the micro-frontends that render them.
Cascade layers set the order
Even with good habits, teams' CSS meets on one page. Cascade layers (@layer) let the shell declare, once, which group of styles wins:
/* shell.css: declared first, before any other CSS loads */
@layer reset, ds, teams;Then the design system writes into ds, and each team writes into its own sub-layer, like @layer teams.catalog { ... }. Between layers, order decides, not specificity. A plain button rule in teams beats .ds-button in ds.
That cuts both ways, and the lab shows it. The catalog team deliberately padded their buttons, which worked. But the cart team also wrote a careless global rule in its layer:
@layer teams.cart { button { background: rgb(200, 0, 0); } }catalog button: bg rgb(200, 0, 0) (the cart's rule reached the catalog)
other button: bg rgb(200, 0, 0)
after unlayered team CSS: bg rgb(0, 128, 0) (CSS outside any layer beats every layer)Two lessons follow. Layers decide *priority*, but they don't keep a team's rules inside its own area. And any stylesheet loaded without a layer, from a team or a third-party library, overrides everything layered. Require every team's CSS to live in a layer, and lint for it.
@scope keeps rules inside a team's area
To stop the cart's rule from reaching the catalog, scope it to the cart's root element:
@layer teams.cart {
@scope ([data-mfe="cart"]) {
button { background: rgb(200, 0, 0); }
}
}catalog button: rgb(37, 99, 235) (design system color, untouched)
cart button: rgb(200, 0, 0) (the cart's own rule, inside the cart only)@scope is supported in all major browsers since Firefox 146 shipped it in December 2025. With the shell giving each micro-frontend a root element carrying data-mfe, every team can wrap its stylesheet in @scope and stop worrying about selectors leaking. CSS Modules or a team prefix achieve the same by naming. Pick one approach and make it the rule.
Consistency beyond CSS
Visual consistency is the easy part. Users also notice:
- Formatting: dates, numbers and currency. Pass the locale and currency from the shell as props (Day 4), and use
IntlAPIs everywhere. - Language and tone: the design system's guidelines include copy rules, like how errors are phrased.
- Behavior: focus handling, keyboard shortcuts and loading states. Put shared patterns into components, like a
<Skeleton>every team uses while loading. - Accessibility: one skip link and landmark structure from the shell, and accessible components from the design system.
Check yourself
Custom properties work with any framework, pass into shadow DOM, and can change at run time for dark mode or a brand refresh. One stylesheet loaded by the shell defines them, and every micro-frontend reads them with var(...), so a token change ships once and every team picks it up on the next page load.
They turn red, because a later layer beats an earlier one regardless of specificity. Layers set priority; @scope or naming is needed to keep the rule inside the team's area.
Unlayered styles beat every cascade layer, regardless of specificity. In the lab, one unlayered rule turned design system buttons green over every layered style. So a third-party stylesheet loaded outside a layer silently overrides the design system and all team styles; import it into a layer instead.
@scope ([data-mfe="cart"]) { ... } limits the rules inside to the cart's root element and its descendants, so a careless button rule can't reach other teams' buttons. It's supported in all major browsers since Firefox 146 shipped it in December 2025.
Pass the locale and currency from the shell as props, and have every team format with the Intl.NumberFormat API, ideally through a shared helper in the design system. Consistency beyond colors needs shared inputs and shared formatting, not just guidelines.