docs(showcase/shell): custom-look-and-feel — CSS first, Slots (Subcomponents), align unselected tree

- Reorder meta.json so CSS is the first sub-page (easiest rung of the
  customization ladder), then Slots, Headless UI, Reasoning Messages.
- Retitle slots.mdx frontmatter to "Slots (Subcomponents)" so the sidebar
  nav reads the user-facing term people actually search for.
- css.mdx: demonstrate the new file+lines Snippet by pulling the
  user/assistant bubble block straight from the cell's theme.css.
- headless-ui.mdx: expand from a bare IntegrationGrid stub into a full
  page with minimal + complete examples, the three core hooks, and
  Snippet pulls from both headless-simple and headless-complete cells.
- Mirror the css/slots changes into unselected/custom-look-and-feel/ so
  the framework-agnostic tree stays in step (add css.mdx, reorder
  meta.json, retitle slots nav).

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: ataibarkai

showcase/shell/src/content/docs/custom-look-and-feel/css.mdx

@@ -90,6 +90,16 @@ can target specific pieces of the UI from your own stylesheet:
 }
 ```
 
+The demo's `theme.css` wraps every selector under `.chat-css-demo-scope` so
+the overrides don't leak out — here's the user/assistant bubble block from
+that file:
+
+<Snippet
+  file="src/app/demos/chat-customization-css/theme.css"
+  lines="30-57"
+  title="frontend/src/app/theme.css — user + assistant message bubbles"
+/>
+
 ### Reference
 
 | CSS Class | Description |

showcase/shell/src/content/docs/custom-look-and-feel/headless-ui.mdx

@@ -1,18 +1,82 @@
 ---
 title: "Fully Headless UI"
-description: "Fully customize your Copilot's UI from the ground up using headless UI"
+description: "Build any UI — chat or not — on top of the CopilotKit primitives with zero UI opinions."
 icon: "lucide/Settings"
 hideTOC: true
+snippet_framework: langgraph-python
+snippet_cell: headless-complete
 ---
 
 ## What is this?
 
-A headless UI gives you full control over the chat experience — you bring your own components, layout, and styling while CopilotKit handles agent communication, message management, and streaming.
+A headless UI gives you **full control** over the chat experience — you bring your own components, layout, and styling while CopilotKit handles agent communication, message management, tool-call rendering, and streaming. No `<CopilotChat>`, no slot overrides, just your components composed on top of the low-level hooks.
 
 ## When should I use this?
 
-Use headless UI when the [slot system](/custom-look-and-feel/slots) isn't enough — for example, when you need a completely different layout, want to embed the chat into an existing UI, or are building a non-chat interface that still communicates with an agent.
+Use headless UI when:
 
-## Get started by choosing your AI backend
+- The [slot system](/custom-look-and-feel/slots) isn't enough — you need a completely different layout.
+- You're embedding chat into an existing UI with its own patterns.
+- You're building a **non-chat surface** that still talks to an agent (a dashboard, a canvas, an inspector) and want `useRenderToolCall` / `useRenderActivityMessage` on their own.
+- You want to render generative UI primitives outside of a chat entirely.
 
-<IntegrationGrid path="custom-look-and-feel/headless-ui" />
+<InlineDemo integration="langgraph-python" demo="headless-complete" />
+
+## The core hooks
+
+Three hooks do the heavy lifting — they're the same primitives `<CopilotChat>` uses internally.
+
+- `useAgent({ agentId })` — exposes the current conversation (`messages`, `isRunning`) and the run-state object.
+- `useCopilotKit()` — returns the runtime handle you call `runAgent({ agent })` on.
+- `useRenderToolCall()` — returns a function that paints any registered tool call inline.
+
+## Minimal example
+
+Start small — a hand-rolled message list and composer built from `useAgent` + `useCopilotKit`:
+
+<Snippet cell="headless-simple" region="use-agent-simple" title="frontend/src/app/page.tsx — useAgent + useCopilotKit" />
+
+The message list is a plain `.map()` over `agent.messages` — user messages render as right-aligned bubbles, assistant messages render streamed text plus inline tool calls via `renderToolCall({ toolCall })`:
+
+<Snippet cell="headless-simple" region="message-list-simple" title="frontend/src/app/page.tsx — message list" />
+
+No `<CopilotChat />`, no slots. The trade-off: you only get text + tool calls. Reasoning messages, activity messages, and custom before/after slots won't show up unless you wire them in yourself — which is exactly what the complete example covers.
+
+## Complete example
+
+The `headless-complete` cell rebuilds the **full** generative-UI composition — text, tool calls, reasoning cards, A2UI + MCP Apps activity messages, custom before/after message slots — from the low-level hooks directly, without importing `<CopilotChatMessageView>`.
+
+### The `useRenderedMessages` hook
+
+The cell's central piece is a hand-rolled `useRenderedMessages(messages, isRunning)` that returns the same flat list of messages, each augmented with a `renderedContent: ReactNode` field. This hook is a **manual recreation of what `<CopilotChatMessageView>` does**:
+
+<Snippet region="use-rendered-messages-hook" title="frontend/src/app/use-rendered-messages.tsx — composition hook" />
+
+Three low-level hooks feed it:
+
+- `useRenderToolCall()` — returns the renderer for any registered tool call (per-tool via `useRenderTool` / `useComponent`, plus the wildcard from `useDefaultRenderTool`).
+- `useRenderActivityMessage()` — renders A2UI + MCP Apps activity messages for the current agent scope.
+- `useRenderCustomMessages()` — invokes `renderCustomMessage` hooks registered against the active `CopilotChatConfigurationProvider`, emitting `"before"` and `"after"` slots around every message.
+
+### Per-role dispatch
+
+The role-switch mirrors `CopilotChatMessageView`'s `renderMessageBlock` exactly — assistant bodies get text + tool calls, user bodies get their text content, reasoning messages go through the `<CopilotChatReasoningMessage>` leaf, and activity messages route through `renderActivityMessage`:
+
+<Snippet region="manual-activity-message-rendering" title="frontend/src/app/use-rendered-messages.tsx — per-role dispatch" />
+
+### Tool-call composition
+
+For each `toolCall` on an assistant message, we look up the sibling `tool`-role message (keyed by `toolCallId`) and hand both to `renderToolCall`:
+
+<Snippet region="manual-tool-call-rendering" title="frontend/src/app/use-rendered-messages.tsx — assistant + tool calls" />
+
+### Bubble chrome
+
+The `UserBubble` and `AssistantBubble` components are **pure chrome** — they receive the pre-rendered node from `useRenderedMessages` and drop it into a styled container. No chat primitives are imported here:
+
+<Snippet region="custom-bubbles" title="frontend/src/app/{user,assistant}-bubble.tsx — pure chrome" />
+
+## Next steps
+
+- [Slots](/custom-look-and-feel/slots) — less work than going fully headless, often enough.
+- [CSS customization](/custom-look-and-feel/css) — when you just need to re-skin the defaults.

showcase/shell/src/content/docs/custom-look-and-feel/meta.json

@@ -1,5 +1,5 @@
 {
   "title": "Custom Look and Feel",
   "icon": "lucide/LayoutDashboard",
-  "pages": ["slots", "css", "headless-ui"]
+  "pages": ["css", "slots", "headless-ui", "reasoning-messages"]
 }

showcase/shell/src/content/docs/custom-look-and-feel/slots.mdx

@@ -1,5 +1,5 @@
 ---
-title: "Slots"
+title: "Slots (Subcomponents)"
 icon: "lucide/Brush"
 description: "Customize any part of the chat UI by overriding individual sub-components via slots."
 hideTOC: true

showcase/shell/src/content/docs/unselected/custom-look-and-feel/css.mdx

@@ -0,0 +1,145 @@
+---
+title: "CSS Customization"
+icon: "lucide/Palette"
+description: "Theme CopilotKit components via CSS variables and class overrides — the quickest path to a custom look."
+hideTOC: true
+---
+
+## What is this?
+
+CopilotKit's chat UI components can be re-skinned purely via CSS — no component overrides, no headless rewrites. This is the **fastest** rung on the customization ladder: keep every built-in feature, change every color.
+
+You can:
+
+- Override CopilotKit CSS variables (`--copilot-kit-primary-color`, etc.) to re-tint the whole UI
+- Target the built-in `.copilotKit...` class names for structural tweaks
+- Swap fonts per surface (messages, input, bubbles)
+- Replace icons and labels via component props
+
+If you need to change **behavior** — not just look — see
+[slots](/custom-look-and-feel/slots) or
+[fully headless UI](/custom-look-and-feel/headless-ui).
+
+## CSS variables (easiest)
+
+The easiest way to change the colors used in the Copilot UI components is to
+override CopilotKit CSS variables on a wrapper element around your chat:
+
+```tsx title="page.tsx"
+import { CopilotKitCSSProperties } from "@copilotkit/react-core/v2";
+
+<div
+  style={
+    {
+      "--copilot-kit-primary-color": "#222222",
+    } as CopilotKitCSSProperties
+  }
+>
+  <CopilotSidebar />
+</div>
+```
+
+Or apply them from a scoped stylesheet:
+
+```css title="theme.css"
+.chat-css-demo-scope {
+  --copilot-kit-primary-color: #ff006e;
+  --copilot-kit-contrast-color: #ffffff;
+  --copilot-kit-background-color: #fff5f9;
+}
+```
+
+### Reference
+
+| CSS Variable | Description |
+|-------------|-------------|
+| `--copilot-kit-primary-color` | Main brand/action color — used for buttons, interactive elements |
+| `--copilot-kit-contrast-color` | Color that contrasts with primary — used for text on primary elements |
+| `--copilot-kit-background-color` | Main page/container background color |
+| `--copilot-kit-secondary-color` | Secondary background — used for cards, panels, elevated surfaces |
+| `--copilot-kit-secondary-contrast-color` | Primary text color for main content |
+| `--copilot-kit-separator-color` | Border color for dividers and containers |
+| `--copilot-kit-muted-color` | Muted color for disabled/inactive states |
+
+## Custom CSS
+
+In addition to customizing the colors, the CopilotKit CSS is structured to
+allow customization via CSS classes. Target specific pieces of the UI from
+your own stylesheet:
+
+```css title="globals.css"
+.copilotKitButton {
+  border-radius: 0;
+}
+
+.copilotKitMessages {
+  padding: 2rem;
+}
+
+.copilotKitUserMessage {
+  background: #007AFF;
+}
+```
+
+### Reference
+
+| CSS Class | Description |
+|-----------|-------------|
+| `.copilotKitMessages` | Main container for all chat messages |
+| `.copilotKitInput` | Text input container with typing area and send button |
+| `.copilotKitUserMessage` | Styling for user messages |
+| `.copilotKitAssistantMessage` | Styling for AI responses |
+| `.copilotKitHeader` | Top bar of chat window containing title and controls |
+| `.copilotKitButton` | Primary chat toggle button |
+| `.copilotKitWindow` | Root container defining overall chat window dimensions |
+| `.copilotKitMarkdown` | Styles for rendered markdown content |
+| `.copilotKitCodeBlock` | Code snippet container with syntax highlighting |
+| `.copilotKitSidebar` | Styles for sidebar chat mode |
+| `.copilotKitPopup` | Styles for popup chat mode |
+
+## Custom fonts
+
+Customize the fonts by updating the `fontFamily` property on the
+relevant CopilotKit classes:
+
+```css title="globals.css"
+.copilotKitMessages {
+  font-family: "Arial, sans-serif";
+}
+
+.copilotKitInput {
+  font-family: "Arial, sans-serif";
+}
+```
+
+## Custom icons
+
+Customize icons by passing the `icons` prop to `CopilotSidebar`, `CopilotPopup`,
+or `CopilotChat`:
+
+```tsx
+<CopilotChat
+  icons={{
+    openIcon: <YourOpenIconComponent />,
+    closeIcon: <YourCloseIconComponent />,
+  }}
+/>
+```
+
+## Custom labels
+
+Customize all user-facing copy via the `labels` prop:
+
+```tsx
+<CopilotChat
+  labels={{
+    welcomeMessageText: "Hello! How can I help you today?",
+    modalHeaderTitle: "My Copilot",
+    chatInputPlaceholder: "Ask me anything!",
+  }}
+/>
+```
+
+## Get started by choosing your AI backend
+
+<IntegrationGrid path="custom-look-and-feel/css" />

showcase/shell/src/content/docs/unselected/custom-look-and-feel/meta.json

@@ -1,5 +1,5 @@
 {
   "title": "Custom Look and Feel",
   "icon": "lucide/LayoutDashboard",
-  "pages": ["slots", "headless-ui"]
+  "pages": ["css", "slots", "headless-ui"]
 }

showcase/shell/src/content/docs/unselected/custom-look-and-feel/slots.mdx

@@ -1,5 +1,5 @@
 ---
-title: Slots
+title: Slots (Subcomponents)
 icon: "lucide/Brush"
 description: Customize any part of the chat UI by overriding individual sub-components via slots.
 hideTOC: true