copilotkit--copilotkit/showcase/STYLING-GUIDE.md

Showcase Integration Package — Styling Guide

Tagline: Tailwind v4 purging traps, CopilotKit class overrides, chat layout wrapper pattern, theme tokens, and Docker-image CSS verification recipe. Externally referenced from per-demo READMEs — preserve path at showcase/STYLING-GUIDE.md.

When building demo pages for integration packages, follow these rules to avoid common pitfalls.

Tailwind v4 Purging

Tailwind v4 aggressively purges CSS classes it can't statically analyze. If your component renders Tailwind classes dynamically (e.g., from state, props, or conditional logic), those classes will be missing from the CSS bundle.

Do: Use inline styles for dynamic components

// GOOD — inline styles always work
<div style={{ padding: "32px", borderRadius: "16px", border: "1px solid #e5e5e0" }}>

Don't: Use Tailwind classes on dynamically rendered content

// BAD — Tailwind may purge these classes
<div className="p-8 rounded-2xl border border-gray-200">

When it's safe to use Tailwind

Tailwind classes work fine on:

• Static JSX in your component (not inside maps, conditionals, or dynamic renders)
• The CopilotKit wrapper divs you write yourself
• Next.js page-level layout elements

Tailwind classes are UNSAFE on:

• Content rendered by useRenderTool, useHumanInTheLoop, useFrontendTool handlers
• Components rendered inside CopilotKit's chat message area
• Any JSX returned from a callback or dynamic render function

CopilotKit Component Overrides

CopilotKit v2 components use cpk: prefixed Tailwind classes internally. To override them:

Do: Use a separate CSS file

/* copilotkit-overrides.css — import in layout.tsx AFTER globals.css */

.copilotKitInput {
  border-radius: 0.75rem;
  border: 1px solid var(--copilot-kit-separator-color) !important;
}

Do NOT hardcode .copilotKitChat { background-color: #fff !important; } in these overrides. It overrides demo-level theming (e.g. beautiful-chat's dark mode toggle) and forces white in every theme. Let the v2 styles + per-demo ThemeProvider handle chat backgrounds.

// layout.tsx
import "./globals.css";
import "./copilotkit-overrides.css"; // AFTER globals

Don't: Put overrides in globals.css

Tailwind v4 processes globals.css and purges anything it doesn't recognize as a utility class. CopilotKit class selectors (.copilotKitChat, .copilotKitInput) will be stripped.

Chat Layout — The Wrapper Pattern

To get proper spacing around the CopilotChat component, wrap it like the Dojo does:

// GOOD — matches Dojo spacing
<div className="flex justify-center items-center h-screen w-full">
  <div className="h-full w-full md:w-4/5 md:h-4/5 rounded-lg">
    <CopilotChat className="h-full rounded-2xl max-w-6xl mx-auto" />
  </div>
</div>

The md:w-4/5 gives 80% width on desktop, creating natural side margins. Don't try to add margins via CSS overrides on CopilotKit's internal classes — use the wrapper div.

Theme

All integration packages should use the light theme to match the showcase shell:

:root {
  --copilot-kit-background-color: #fafaf9;
  --copilot-kit-primary-color: #0d6e3f;
  --copilot-kit-response-button-background-color: #f5f5f3;
  --copilot-kit-response-button-color: #1a1a18;
}

html,
body {
  background: #fafaf9;
  color: #1a1a18;
}

Images

Don't reference local image files from agent-generated content. The agent may generate image_name values that don't exist on disk. Always add an onError fallback:

{
  imageUrl && !imageError && (
    <img src={imageUrl} onError={() => setImageError(true)} alt="..." />
  );
}

SVG Icons

Don't use SVG icons with fill="currentColor" inside CopilotKit chat messages. The currentColor inheritance is unpredictable in the chat context. Use emoji instead:

// GOOD
<span style={{ fontSize: "48px" }}>☀️</span>

// BAD — renders as giant black shapes
<svg fill="currentColor" className="w-14 h-14 text-yellow-200">...</svg>

Testing Locally

Always build and test the Docker image locally before pushing:

cd /proj/cpk/CopilotKit
docker build -f showcase/integrations/<slug>/Dockerfile -t <slug>-local showcase/integrations/<slug>/
docker run -d --name <slug>-local -p 4444:10000 -e PORT=10000 <slug>-local

# Verify CSS overrides survived the build
curl -sf http://localhost:4444/_next/static/css/*.css | grep "copilotKitChat"

# Verify inline styles are in rendered HTML
curl -sf http://localhost:4444/demos/<demo> | grep "padding: 32px"

# Clean up
docker rm -f <slug>-local