Custom Theming

ggui uses DTCG design tokens for theming. All primitives use CSS custom properties with sensible defaults — override them to match your brand.

CSS Variable Override

:root {
  /* Primary brand color */
  --ggui-color-primary-50: #eff6ff;
  --ggui-color-primary-100: #dbeafe;
  --ggui-color-primary-200: #bfdbfe;
  --ggui-color-primary-300: #93c5fd;
  --ggui-color-primary-400: #60a5fa;
  --ggui-color-primary-500: #3b82f6;
  --ggui-color-primary-600: #2563eb;
  --ggui-color-primary-700: #1d4ed8;
  --ggui-color-primary-800: #1e40af;
  --ggui-color-primary-900: #1e3a8a;

  /* Typography */
  --ggui-font-family-sans: "Inter", system-ui, sans-serif;
  --ggui-font-family-mono: "JetBrains Mono", monospace;

  /* Spacing, shadows, radii */
  --ggui-spacing-md: 1rem;
  --ggui-shadow-md: 0 4px 6px -1px rgba(0, 0, 0, 0.1);
  --ggui-radius-md: 0.375rem;
}

Dark Mode

Override variables under a dark mode selector:

[data-theme="dark"],
.dark {
  --ggui-color-primary-600: #60a5fa;
  --ggui-color-neutral-50: #111827;
  --ggui-color-neutral-100: #1f2937;
  --ggui-color-neutral-900: #f9fafb;
  --ggui-shadow-sm: 0 1px 2px rgba(0, 0, 0, 0.3);
}

function ThemeToggle() {
  const [dark, setDark] = useState(false);

  return (
    <div data-theme={dark ? "dark" : "light"}>
      <button onClick={() => setDark(!dark)}>Toggle {dark ? "Light" : "Dark"} Mode</button>
      <GguiProvider appId="app_...">{/* All ggui components inherit the theme */}</GguiProvider>
    </div>
  );
}

Scoped Theming

Apply different themes to different sections:

<GguiProvider appId="app_...">
  {/* Default theme */}
  <GguiSession sessionId="session_main">
    {(api) => <StackItemRenderer stackItem={mainItem} />}
  </GguiSession>

  {/* Brand-specific theme for embedded widget */}
  <div
    style={
      {
        "--ggui-color-primary-600": "#8b5cf6",
        "--ggui-radius-md": "1rem",
      } as React.CSSProperties
    }
  >
    <GguiSession sessionId="session_widget">
      {(api) => <StackItemRenderer stackItem={widgetItem} />}
    </GguiSession>
  </div>
</GguiProvider>

Agent-Side: Requesting Themed UI

Include brand context when pushing UIs:

await ggui.push({
  story: {
    intent: "Pricing table — branded",
    prompt: "Show a pricing table with 3 tiers",
    context: {
      brandColors: { primary: "#8b5cf6", accent: "#f59e0b" },
      fontFamily: "Inter",
      borderRadius: "rounded",
    },
  },
});

Available Design Tokens

Category	Token Pattern	Example
Colors (primary)	--ggui-color-primary-{50-900}	--ggui-color-primary-600
Colors (neutral)	--ggui-color-neutral-{50-900}	--ggui-color-neutral-200
Colors (semantic)	--ggui-color-{success,warning,error}-{base,light}	--ggui-color-success-base
Typography	--ggui-font-{family,size,weight}-*	--ggui-font-size-lg
Spacing	--ggui-spacing-{xs,sm,md,lg,xl}	--ggui-spacing-md
Shadows	--ggui-shadow-{sm,md,lg}	--ggui-shadow-md
Radii	--ggui-radius-{sm,md,lg,full}	--ggui-radius-lg