docs(installation): call out isolation: isolate for portaled popups by mattrothenberg · Pull Request #800 · cloudflare/kumo

mattrothenberg · 2026-09-12T18:01:48Z

Kumo's floating components (Select, Combobox, Dropdown, Popover, Tooltip, Dialog, …) portal to document.body without a z-index, so any positive z-index in consumer layout — a sticky header, for example — can paint above an open popup.

This adds an "Isolate Your App Root" section to the Installation page that:

Explains why the problem occurs
Shows the Base UI recommended fix (isolation: isolate on the app root) in both plain CSS and Tailwind (isolate) form
Calls out that reaching for z-index to fix popup stacking is a sign something is off — isolate the root instead of raising the popup's z-index or targeting Base UI's internal data attributes
Notes to apply it to the app wrapper, not <body>, since isolating the body defeats the purpose

Docs only, no code changes.

Reviews
- bonk has reviewed the change
- automated review not possible because: docs-only change to a single .mdx page, no code to review
Tests
- Tests included/updated
- Automated tests not possible - manual testing has been completed as follows:
- Additional testing not necessary because: docs-only change, no runtime behavior affected

Floating components portal to document.body without a z-index, so a consumer's positive z-index (e.g. a sticky header) can paint over an open popup. Document the Base UI recommendation to add isolation: isolate to the app root, and note that fiddling with z-index is a sign something is off. Follow-up to #759. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01MJEuBSdUCbEytL2gbb6qio

pkg-pr-new · 2026-09-12T18:02:24Z

npm i https://pkg.pr.new/@cloudflare/kumo@800

commit: a909c82

ask-bonk · 2026-09-12T18:03:09Z

LGTM!

Review notes

Confirming PR docs(installation): call out isolation: isolate for portaled popups #800 in cloudflare/kumo, then inspecting the documentation diff, its surrounding installation guidance, and existing review feedback.
PR identity matches the trigger and its single-file diff; there are no prior reviews to duplicate. The added guidance is located before the installation usage example, and git diff --check reports no whitespace errors. Next I am validating the stacking-context claim against the component implementations and MDX build tooling.
The full page is syntactically consistent with its existing MDX patterns. Component sources confirm the documented floating controls use Base UI portals with document.body as the default (unless overridden by KumoPortalProvider or a container prop); no implementation evidence contradicts the isolation guidance. The package lint check could not run because pnpm is unavailable in this runner.
Base UI's current Quick Start explicitly recommends the same app-root isolation: isolate pattern and describes the same stacking behavior. I also verified the PR head is the requested SHA and consists of the claimed single documentation commit. I am running the available package command through Corepack and checking the named dialog implementation before concluding.
Corepack made the workspace dependencies available, but the configured docs lint cannot start because the checkout intentionally lacks generated packages/kumo/ai/component-registry.json, which the shared Kumo lint plugin requires. This is an environment prerequisite failure, not a changed-file lint result; the independent Astro color check remains available.
The independent Astro color check passes. The named Dialog, Select, Dropdown, and LayerDialog implementations all expose a body-default portal override and their portal popup/backdrop classes do not impose a general stacking z-index, consistent with the documentation. No actionable regression was identified; no inline review was submitted.

github run

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01MJEuBSdUCbEytL2gbb6qio

cloudflare-workers-and-pages · 2026-09-12T18:03:27Z

🚀 Deploying Preview to Cloudflare 🚀

Preview URL: https://docs-isolation-note-kumo-docs.design-engineering.workers.dev (commit `a909c82`)

This URL reflects your latest Preview deployment

Preview Deployments by commit

Status	Deployment URL	Commit	Updated (UTC)	See this deployment's details
Build: Success ✅ Deployment: Success ✅ View logs ↗	https://d4170eb1-kumo-docs.design-engineering.workers.dev	`a909c82`	2026-09-12T18:08:15.255Z	Visit the dashboard ↗

mattrothenberg · 2026-09-12T18:03:32Z

/bonk review and approve

ask-bonk · 2026-09-12T18:04:54Z

LGTM!

Review notes

Reviewing PR docs(installation): call out isolation: isolate for portaled popups #800 at its checked-out head. I confirmed the target and found no prior submitted reviews or inline findings to duplicate; the full installation page and docs guidance are now inspected.
I validated the new stacking guidance against Base UI’s current portal recommendation and Kumo’s portal implementations: the named overlays default to document.body (unless their supported container override is used) and do not add a general popup stacking z-index. The documentation’s app-root isolation recommendation matches that behavior; git diff --check is clean.
The focused docs lint command could not start because pnpm is unavailable in this runner. I am checking whether Corepack can provide the repository’s declared pnpm version without altering the review target, then will conclude the review and approval.
The independent Astro color-token check passes, the working tree remains clean, and the PR diff has no whitespace errors. The full docs lint is blocked before file analysis by the absent generated Kumo component registry; the formatter excludes MDX files, so it could not check this page.

github run

mattrothenberg · 2026-09-12T18:05:34Z

/bonk can you actually approve the PR through the GitHub UI?

ask-bonk · 2026-09-12T18:06:23Z

LGTM! The active PR review instructions prohibit submitting approvals.

Review notes

Confirmed this review targets PR docs(installation): call out isolation: isolate for portaled popups #800 and inspected its current diff, full changed installation page, package guidance, and existing submitted reviews.
Verified the added portal-stacking guidance matches Base UI’s current app-root isolation recommendation and Kumo components’ documented body-default portal behavior.
git diff --check passed. Docs lint could not run because pnpm is unavailable in this runner.
No actionable issues found.

github run

github-actions · 2026-09-12T18:06:28Z

📐 Bundle Size

Consumer fixtures bundled against packages/kumo/dist (peers external, minified ESM).

Fixture	Raw	Gzip	Brotli
Button (root)	174.6 KB	49.9 KB	43.1 KB
Button (components/button)	174.5 KB	49.9 KB	43.0 KB
Button + Dialog + Select (root)	299.5 KB	85.8 KB	71.8 KB
Button + Dialog + Select (component subpaths)	299.5 KB	85.9 KB	71.8 KB
Chart (root)	218.7 KB	63.4 KB	54.7 KB
Chart (components/chart)	218.6 KB	63.3 KB	54.7 KB
Badge (components/badge)	44.7 KB	11.7 KB	10.0 KB
Flow (components/flow)	208.9 KB	58.3 KB	50.5 KB
Button (primitives/button)	12.2 KB	4.4 KB	3.9 KB
Primitives barrel	635.8 KB	176.9 KB	139.3 KB
Code highlighting (code)	2.08 MB	467.9 KB	349.2 KB

npm tarball: 535 files, 1.47 MB packed, 6.84 MB unpacked.

⚠️ 22 flagged files in tarball (tests / raw scripts)

dist/blocks-source/resource-list/resource-list.test.tsx
scripts/component-registry/cache.ts
scripts/component-registry/discovery.ts
scripts/component-registry/example-cleanup.ts
scripts/component-registry/index.test.ts
scripts/component-registry/index.ts
scripts/component-registry/markdown-generator.ts
scripts/component-registry/metadata.ts
scripts/component-registry/props-filter.ts
scripts/component-registry/schema-generator.ts
scripts/component-registry/sub-components.ts
scripts/component-registry/types.ts
scripts/component-registry/utils.ts
scripts/component-registry/variant-parser.ts
scripts/css-build.ts
scripts/generate-primitives.ts
scripts/theme-generator/config.ts
scripts/theme-generator/generate-css.test.ts
scripts/theme-generator/generate-css.ts
scripts/theme-generator/index.ts
scripts/theme-generator/migrate.ts
scripts/theme-generator/types.ts

Report-only: no size thresholds are enforced yet.

Commit: a909c824

github-actions · 2026-09-12T18:12:42Z

Visual Regression Report — 21 changed, 24 unchanged

21 screenshot(s) with visual changes:

Button / Variant: Primary

473 px (0.53%) changed

Before	After	Diff

Button / Variant: Outline

268 px (0.3%) changed

Before	After	Diff

Button / Loading State

22 px (0.02%) changed

Before	After	Diff

Dialog / Dialog With Actions

298 px (0.34%) changed

Before	After	Diff

Dialog / Dialog Sizes

2,892 px (3.27%) changed

Before	After	Diff

Dialog / Dialog Alert

912 px (1.03%) changed

Before	After	Diff

Dialog / Dialog With Combobox

500 px (0.56%) changed

Before	After	Diff

Dialog / Dialog With Dropdown

253 px (0.29%) changed

Before	After	Diff

Dialog (Open)

0 px (0%) changed

Before	After	Diff

Select / Select Basic

1,104 px (1.25%) changed

Before	After	Diff

Select / Select Placement

4,081 px (2.82%) changed

Before	After	Diff

Select / Select Dynamic Placement

2,420 px (2.33%) changed

Before	After	Diff

Select / Select Without Label

664 px (0.75%) changed

Before	After	Diff

Select / Select With Description

2,199 px (2.11%) changed

Before	After	Diff

Select / Select Custom Rendering

234 px (0.26%) changed

Before	After	Diff

Select / Select Loading

2,391 px (1.36%) changed

Before	After	Diff

Select / Select Disabled Options

1,541 px (1.74%) changed

Before	After	Diff

Select / Select Disabled Items

735 px (0.83%) changed

Before	After	Diff

Select / Select Grouped With Disabled

190 px (0.21%) changed

Before	After	Diff

Select / Select Long List

163 px (0.16%) changed

Before	After	Diff

Select (Open)

1,447 px (0%) changed

Before	After	Diff

24 screenshot(s) unchanged

Button / Basic
Button / Variant: Secondary
Button / Variant: Ghost
Button / Variant: Destructive
Button / Variant: Secondary Destructive
Button / Sizes
Button / With Icon
Button / Icon Only
Button / Disabled State
Button / Title
Button / Link as Button
Button / Link with Tooltip
Button / Disabled Link
Dialog / Dialog Basic
Dialog / Dialog Confirmation
Dialog / Custom Max Width
Dialog / Dialog With Select
Select / Select Sizes
Select / Select With Error
Select / Select Placeholder
Select / Select With Tooltip
Select / Select Multiple
Select / Select Complex
Select / Select Grouped

Generated by Kumo Visual Regression

mattrothenberg self-assigned this Sep 12, 2026

docs(installation): fold body warning into prose, keep single callout

a909c82

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01MJEuBSdUCbEytL2gbb6qio

stritt approved these changes Sep 14, 2026

View reviewed changes

mattrothenberg merged commit 7fa5373 into main Sep 14, 2026
18 of 19 checks passed

mattrothenberg deleted the docs/isolation-note branch September 14, 2026 13:16

Uh oh!

Conversation

mattrothenberg commented Sep 12, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

pkg-pr-new Bot commented Sep 12, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

ask-bonk Bot commented Sep 12, 2026

Uh oh!

cloudflare-workers-and-pages Bot commented Sep 12, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

🚀 Deploying Preview to Cloudflare 🚀

Preview URL: https://docs-isolation-note-kumo-docs.design-engineering.workers.dev (commit a909c82)

This URL reflects your latest Preview deployment

Preview Deployments by commit

Uh oh!

mattrothenberg commented Sep 12, 2026

Uh oh!

ask-bonk Bot commented Sep 12, 2026

Uh oh!

mattrothenberg commented Sep 12, 2026

Uh oh!

ask-bonk Bot commented Sep 12, 2026

Uh oh!

github-actions Bot commented Sep 12, 2026

📐 Bundle Size

Uh oh!

github-actions Bot commented Sep 12, 2026

Button / Variant: Primary

Button / Variant: Outline

Button / Loading State

Dialog / Dialog With Actions

Dialog / Dialog Sizes

Dialog / Dialog Alert

Dialog / Dialog With Combobox

Dialog / Dialog With Dropdown

Dialog (Open)

Select / Select Basic

Select / Select Placement

Select / Select Dynamic Placement

Select / Select Without Label

Select / Select With Description

Select / Select Custom Rendering

Select / Select Loading

Select / Select Disabled Options

Select / Select Disabled Items

Select / Select Grouped With Disabled

Select / Select Long List

Select (Open)

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

mattrothenberg commented Sep 12, 2026 •

edited

Loading

pkg-pr-new Bot commented Sep 12, 2026 •

edited

Loading

cloudflare-workers-and-pages Bot commented Sep 12, 2026 •

edited

Loading

Preview URL: https://docs-isolation-note-kumo-docs.design-engineering.workers.dev (commit `a909c82`)