From e02acaadc4a5b6477fa1a358d3014e8d1bbaca4c Mon Sep 17 00:00:00 2001 From: Matt Rothenberg Date: Mon, 14 Sep 2026 09:32:33 -0400 Subject: [PATCH 1/2] docs: guide portal stacking isolation --- .changeset/portal-stacking-guidance.md | 5 +++++ AGENTS.md | 9 +++++++++ packages/kumo/src/utils/portal-provider.tsx | 4 ++++ 3 files changed, 18 insertions(+) create mode 100644 .changeset/portal-stacking-guidance.md diff --git a/.changeset/portal-stacking-guidance.md b/.changeset/portal-stacking-guidance.md new file mode 100644 index 000000000..1aed4928f --- /dev/null +++ b/.changeset/portal-stacking-guidance.md @@ -0,0 +1,5 @@ +--- +"@cloudflare/kumo": patch +--- + +Document app-root CSS isolation for reliable stacking of portaled components. diff --git a/AGENTS.md b/AGENTS.md index fe5881146..a97f598ad 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -47,6 +47,15 @@ kumo/ - **Surface hierarchy**: `bg-kumo-base` → `bg-kumo-elevated` → `bg-kumo-recessed` - **Mode/theme**: `data-mode="light"|"dark"` + `data-theme="fedramp"` on parent element +### Portal stacking (CRITICAL) + +- Kumo floating components portal to `document.body` without a `z-index`. + Consumers should create an app-root stacking context with `isolation: isolate` + (Tailwind: `className="isolate"`). +- Do **not** fix a popup that appears below consumer content by adding `z-index` + to Kumo popup components, targeting Base UI internal data attributes, or + applying `isolation` to ``. + ### Components - **Scaffold new**: `pnpm --filter @cloudflare/kumo new:component` (never create manually) diff --git a/packages/kumo/src/utils/portal-provider.tsx b/packages/kumo/src/utils/portal-provider.tsx index d3f6d8b64..4c4b1eea1 100644 --- a/packages/kumo/src/utils/portal-provider.tsx +++ b/packages/kumo/src/utils/portal-provider.tsx @@ -23,6 +23,10 @@ const PortalContainerContext = createContext(null); * When not provided, overlays portal to `document.body` (default browser behavior). * Individual components can override this via their own `container` prop. * + * For app-wide portal stacking, consumers should set `isolation: isolate` on + * their app root (not ``). Do not add z-index workarounds to Kumo's + * portaled components or target Base UI internal data attributes. + * * @example Shadow DOM usage * ```tsx * function WebComponent() { From bf3a23c4e1f207d2638b3f584e3b720bcbb32885 Mon Sep 17 00:00:00 2001 From: Matt Rothenberg Date: Mon, 14 Sep 2026 10:31:40 -0400 Subject: [PATCH 2/2] Update AGENTS.md Co-authored-by: ask-bonk[bot] <249159057+ask-bonk[bot]@users.noreply.github.com> --- AGENTS.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index a97f598ad..07aafa487 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -49,9 +49,9 @@ kumo/ ### Portal stacking (CRITICAL) -- Kumo floating components portal to `document.body` without a `z-index`. - Consumers should create an app-root stacking context with `isolation: isolate` - (Tailwind: `className="isolate"`). +- Kumo floating components portal to `document.body`. Consumers should create an + app-root stacking context with `isolation: isolate` (Tailwind: + `className="isolate"`). - Do **not** fix a popup that appears below consumer content by adding `z-index` to Kumo popup components, targeting Base UI internal data attributes, or applying `isolation` to ``.