docs: guide portal stacking isolation

[mattrothenberg]

Summary

• add always-loaded agent guidance for isolating consumer app roots when using Kumo portaled components
• document the same portal-stacking convention next to KumoPortalProvider

Validation

• pnpm --filter @cloudflare/kumo lint

• pnpm --filter @cloudflare/kumo validate:changeset

• git diff --check

• Reviews

• bonk has reviewed the change

• automated review not possible because: documentation and comments only; this environment cannot request a Bonk review.

• Tests

• Tests included/updated

• Automated tests not possible - manual testing has been completed as follows: not applicable

• Additional testing not necessary because: documentation and comments only; no runtime behavior changed.

[ask-bonk]

I'm Bonk, and I've done a quick review of your PR.

Posted 1 inline finding.

Review notes

• Confirmed the review target is PR docs: guide portal stacking isolation #803. I’ll inspect the PR diff, applicable package guidance, and existing review feedback before checking the changed documentation against portal behavior.
• Existing PR reviews and conversation contain no comments, and the checked-out source matches the new provider guidance. The local clone does not have origin/main, so I’ll compare the PR head directly with its parent and inspect the overlay portal call sites.
• The PR is a single documentation/comment commit with a valid patch changeset; git diff --check passes. I verified the stated default portal behavior across Kumo overlay implementations and am checking whether their rendered styling or custom-container support contradicts the new universal guidance.
• Overlay implementations either resolve to document.body by default or explicitly use Base UI’s default portal, and their portal containers do not introduce competing high z-index layers. The only component z-index in this area is Toast’s low z-1 viewport, which remains compatible with the app-root isolation guidance. The package lint command could not run because pnpm is unavailable in this runner.
• Found one factual inconsistency in the new root guidance: Toasty, which is explicitly among the affected overlays, uses z-1 on its viewport and calculated z-index values for its toast stack. I’ll post one inline suggestion that removes the inaccurate absolute claim while retaining the isolation recommendation.
• Submitted one inline COMMENT review on PR docs: guide portal stacking isolation #803 with a suggestion. The checked head matches e02acaadc4a5b6477fa1a358d3014e8d1bbaca4c; no repository files were modified. CI currently has passing format, changeset, and CodeQL checks, with build and docs checks still pending.

github run

[pkg-pr-new]

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

commit: bf3a23c

[github-actions]

📐 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.1 KB
Button + Dialog + Select (root)	299.5 KB	85.8 KB	71.9 KB
Button + Dialog + Select (component subpaths)	299.5 KB	85.9 KB	71.9 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.1 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: bf3a23c4

[cloudflare-workers-and-pages]

🚀 Deploying Preview to Cloudflare 🚀

Preview URL: https://docs-guide-portal-stacking-isolation-kumo-docs.design-engineering.workers.dev (commit bf3a23c)

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://413f29c0-kumo-docs.design-engineering.workers.dev	bf3a23c	2026-09-14T14:35:41.667Z	Visit the dashboard ↗
Build: Success ✅ Deployment: Success ✅ View logs ↗	https://bbb7371f-kumo-docs.design-engineering.workers.dev	bcea7b2	2026-09-14T14:17:06.472Z	Visit the dashboard ↗
Build: Success ✅ Deployment: Success ✅ View logs ↗	https://48ca2701-kumo-docs.design-engineering.workers.dev	e02acaa	2026-09-14T13:37:32.490Z	Visit the dashboard ↗

[github-actions]

Visual Regression Report — 26 changed, 19 unchanged

26 screenshot(s) with visual changes:

Button / Variant: Ghost

101 px (0.11%) changed

Before	After	Diff

Button / Loading State

40 px (0.05%) changed

Before	After	Diff

Button / Title

405 px (0.46%) changed

Before	After	Diff

Dialog / Dialog With Actions

298 px (0.34%) changed

Before	After	Diff

Dialog / Dialog Basic

403 px (0.46%) changed

Before	After	Diff

Dialog / Dialog Sizes

964 px (1.09%) changed

Before	After	Diff

Dialog / Dialog Alert

1,581 px (1.79%) changed

Before	After	Diff

Dialog / Custom Max Width

742 px (0.84%) changed

Before	After	Diff

Dialog / Dialog With Select

500 px (0.56%) changed

Before	After	Diff

Dialog / Dialog With Combobox

383 px (0.43%) changed

Before	After	Diff

Select / Select Basic

859 px (0.97%) changed

Before	After	Diff

Select / Select Sizes

3,164 px (1.95%) changed

Before	After	Diff

Select / Select Placement

4,578 px (3.16%) changed

Before	After	Diff

Select / Select Dynamic Placement

3,917 px (3.76%) changed

Before	After	Diff

Select / Select Without Label

664 px (0.75%) changed

Before	After	Diff

Select / Select Placeholder

977 px (1.1%) changed

Before	After	Diff

Select / Select With Tooltip

196 px (0.22%) changed

Before	After	Diff

Select / Select Custom Rendering

1,174 px (1.33%) changed

Before	After	Diff

Select / Select Loading

2,360 px (1.34%) changed

Before	After	Diff

Select / Select Multiple

327 px (0.37%) changed

Before	After	Diff

Select / Select Complex

1,980 px (1.9%) changed

Before	After	Diff

Select / Select Disabled Options

1,217 px (1.37%) changed

Before	After	Diff

Select / Select Disabled Items

103 px (0.12%) changed

Before	After	Diff

Select / Select Grouped With Disabled

1,478 px (1.67%) changed

Before	After	Diff

Select / Select Long List

1,354 px (1.3%) changed

Before	After	Diff

Select (Open)

1,263 px (0%) changed

Before	After	Diff

19 screenshot(s) unchanged

• Button / Basic
• Button / Variant: Primary
• Button / Variant: Secondary
• Button / Variant: Destructive
• Button / Variant: Outline
• Button / Variant: Secondary Destructive
• Button / Sizes
• Button / With Icon
• Button / Icon Only
• Button / Disabled State
• Button / Link as Button
• Button / Link with Tooltip
• Button / Disabled Link
• Dialog / Dialog Confirmation
• Dialog / Dialog With Dropdown
• Dialog (Open)
• Select / Select With Description
• Select / Select With Error
• Select / Select Grouped

---

Generated by Kumo Visual Regression