Style extension UI

GlobalStacks extensions render inside sandboxed console iframes. Extension views can style approved layout components with GlobalStacks tokens, while interactive and semantic components keep preset styles so extension UI continues to match the console.

This page describes the extension styling API. Use the design system page for product-level visual rules and the component library for per-component props.

Styling model

Extension style is intentionally narrower than browser CSS:

• Style only approved layout primitives such as Box, Inline, and Stack.
• Use token values instead of arbitrary colors, fonts, shadows, or breakpoints.
• Use preset component props for buttons, badges, alerts, inputs, tables, and data grids.
• Keep all style props serializable.
• Do not rely on parent DOM access, global stylesheets, custom fonts, or browser storage.

<Box
  style={{
    backgroundColor: "surface",
    border: "soft",
    padding: "medium",
    radius: "md",
  }}
>
  <Text variant="heading">Cluster storage</Text>
</Box>

Custom styles

Box, Inline, and Stack can accept a limited style object. The renderer validates this object before applying it in the iframe.

Unsupported CSS is ignored or rejected by the SDK validator. Do not use custom selectors, pseudo-classes, keyframes, media queries, global CSS, or arbitrary style strings.

Color

Use semantic tokens so dark mode, light mode, and future themes can render extension UI consistently.

Backgrounds

Borders

Text and icons

Typography

Extensions use the console typography scale. Do not import custom fonts.

Use fontWeight only when hierarchy needs it. Avoid oversized headings inside compact extension viewports.

Text overflow

Generated values often exceed the viewport. Use explicit overflow behavior:

<Text variant="mono" style={{ overflowWrap: "anywhere" }}>
  gssbx_01JZ8Z3Y8QK7V6M2R9B4X5N0PA
</Text>

Use ellipsis only when the full value is available in a tooltip, details row, or copy action.

Layout

GlobalStacks layouts are stack-based. Use layout props instead of hand-written CSS grids unless the component specifically supports columns.

Horizontal stack

<Stack direction="x" gap="small" alignY="center" wrap>
  <Badge tone="success">ready</Badge>
  <Badge tone="muted">private</Badge>
</Stack>

Vertical stack

<Stack direction="y" gap="medium">
  <Text variant="heading">Storage backend</Text>
  <Text tone="muted">R2-backed storage for this cluster.</Text>
</Stack>

Layout properties

Spacing

Use spacing tokens for margin, padding, and layout gaps.

Compact extension panes should usually use small or medium. Reserve large spacing for full-page extension views.

Sizing

Use fractions and content-based sizing tokens. Avoid viewport-relative font sizing.

Radius

Use radius tokens consistently:

Preset component styles

Most components do not accept custom visual styles. They expose constrained props instead.

Preset styles preserve keyboard behavior, accessibility, theme mapping, and consistent visual hierarchy.

Restrictions

Extension style props are serialized across the iframe bridge, so the following are unsupported:

• Arbitrary HTML elements inside GlobalStacks UI components.
• React refs on renderer-owned components.
• DOM measurement, direct focus management, or parent-window DOM access.
• Custom CSS classes, external stylesheets, keyframes, or global selectors.
• Render functions as component props.
• Non-serializable prop values such as Map, Set, class instances, or circular data.
• Event propagation control from extension handlers.

Use uncontrolled form fields when possible. Controlled inputs can feel laggy because input data crosses the iframe bridge asynchronously.

See also

• Design System
• Extension Component Library
• Building Extensions