Why the Card embed lives in a shadow root

The Glimly Card is the bigger sibling of the Badge — a JavaScript widget that mounts into a host page and renders a multi-service status grid with 90-day history bars and an incident banner. You drop two lines of HTML, and you get a /status section that polls in real time.

The first decision we made when building it was where it would live in the host page DOM. The answer was: behind a wall.

The problem with regular embeds

A widget that renders into a normal <div> is at the mercy of the host page. Every * { box-sizing: border-box } reset, every button { color: red } rule, every utility framework that styles by tag name reaches into your widget and changes how it looks. The widget you tested on a blank page is not the widget your customer sees when they paste it into their Tailwind site that uses a custom font and a different reset.

You can fight it with very specific selectors. You can use !important. You can scope every rule under a hash class. None of those scale — every host page is a new fight.

The reverse problem is the same shape. A widget that ships its own body { margin: 0 } rule into the host page is a hostile guest. The host site never agreed to that.

Shadow DOM as a contract

A shadow root is a browser-supported boundary. CSS inside it does not affect the host page. CSS in the host page does not reach inside. The Card mounts a shadow root on whatever element the host placed the embed snippet in, and renders everything — typography, palette, layout — inside that boundary.

The contract is small and explicit:

• The host gives us a div. That is the only thing we touch in the light DOM.
• We give the host a status surface. Always the same dimensions for a given config, always the same fonts, always the same palette.
• Neither side leaks. No font-family override, no color repaint, no reset collision.

For an embed that customers might drop into a 2009 jQuery page next to a 2026 Tailwind app, that contract is what makes the Card boring to install. Boring is the goal.

The cost

Shadow roots are not free. You have to inline your stylesheet because external <link> rules do not cross the boundary by default. You have to think about font loading, because the host page's fonts are invisible to you — we ship a small system-font stack that reads as "calm and Linear-ish" everywhere, on purpose.

Accessibility takes a second look too. ARIA relationships across shadow boundaries work, but the patterns are slightly different from the light DOM. Forms inside a shadow root used to be a sharp edge; modern browsers have smoothed it.

For a passive status widget the cost is small. For something interactive — a checkout, a comments thread — you would weigh the trade differently.

Polling, visibility, network

Two related choices fall out of the same "be a polite guest" mindset:

• Polling cadence is fixed at 30 seconds. Fast enough that a state change is visible without a refresh, slow enough that the host page does not see a noisy network tab.
• The Card pauses when the tab is in the background. It listens to the Page Visibility API and stops polling when the host page is not visible — a desk full of open tabs should not generate dozens of background requests per minute.

Both are the kind of choices that nobody notices when they are right, and everybody notices when they are wrong.

The taste in the small decisions

A status widget is a tiny surface — a few hundred pixels of UI. The taste shows up in what it does not do: it does not fight your CSS, it does not spam your network tab, it does not assume your fonts are loaded, it does not blink when the data changes. The shadow root is the smallest single decision that buys most of that calm.

If you want to see how it lands on a real page, the Card runs on the Glimly homepage in the Uptime as proof section — same bundle, same shadow root, same 30-second polling as the one you would install yourself.