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..07aafa487 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`. 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() {