Chat Styling Guide

This guide provides a comprehensive overview of how to style the chat components in Gen8. We use a specific architectural approach to ensure maintainability, consistency, and flexibility.

1. Philosophy: The G8 CUBE System

We follow a hybrid methodology inspired by CUBE CSS (Composition, Utility, Block, Exception). This approach balances high-level consistency with component isolation.

Core Principles

1. CSS Variables are the API: All theming (colors, spacing, radii, fonts) is controlled via CSS variables. We avoid hardcoding values like 16px or #ccc in component styles.
2. Composition over Rigid Grids: We use flexible composition classes (like .g8-stack, .g8-cluster) to handle layout, rather than rigid 12-column grids inside components.
3. Data Attributes for State: We use data-* attributes (e.g., data-status="error", data-role="user") to handle state changes. This provides a clear, high-specificity hook for customization without fighting class specificity.
4. No Utility Classes in HTML: Inside our core chat components, we avoid polluting the HTML with Bootstrap utility classes (like p-3, d-flex). Styles are defined in the CSS or via semantic composition classes.

The 4 Layers

1. Composition (Layout): Defines the macro layout.
   • Example: .g8-stack (vertical list), .g8-cluster (horizontal group).
2. Utility (Overrides): High-specificity, single-purpose helpers. Use sparingly.
   • Example: .g8-u-hidden-visually.
3. Block (Component): The core component styling.
   • Example: .g8-chat, .g8-chat__message.
4. Exception (State): Variations based on state.
   • Example: [data-role="user"], [data-status="running"].

---

2. Examples

Basic Theming via Variables

To change the look of the chat, you simply override the CSS variables. This can be done globally or scoped to a specific container.

/* Global override */
:root {
	--chat-bg: #f0f2f5;
	--chat-message-radius: 1rem;
}

/* Scoped override */
.my-custom-chat-container {
	--chat-message-user-bg: #0056b3;
	--chat-font-family: 'Roboto', sans-serif;
}

Styling Specific States

Use data attributes to target specific states or roles.

/* Style user messages */
.g8-chat__message[data-role='user'] {
	border-bottom-right-radius: 0;
}

/* Style error messages */
.g8-chat__message[data-status='error'] {
	border: 1px solid var(--g8-error);
	background-color: var(--g8-bg-error-light);
}

Using External CSS

For public templates (mvp1-public), you can inject an external CSS file via the Branding settings. This allows for complete visual overhauls without changing the codebase.

You can also inject an external CSS file via the URL by adding the cssFile query parameter. This is particularly useful for iframes where you want to match the parent site's styling.

Example: .../public/token/template?cssFile=https://mysite.com/styles.css

Using Custom CSS

You can also write CSS directly in the Branding settings. This is injected as a <style> tag in the head of the document.

/* Example custom CSS */
.g8-chat__message[data-role='assistant'] {
	background-color: #f0f8ff;
	border: 1px solid #b0c4de;
}

---

3. Components to Style

Here are the main blocks and elements you can target.

Main Chat Container

• .g8-chat: The main wrapper.
• .g8-chat__message-list: The scrollable area containing messages.
• .g8-chat__input-area: The fixed bottom area for user input.

Messages

• .g8-chat__message: The message bubble wrapper.
  • [data-role="user"]: User message.
  • [data-role="assistant"]: AI message.
  • [data-role="system"]: System message.
• .g8-chat__message-header: Contains the sender name and timestamp.
• .g8-chat__message-body: The actual content of the message.
• .g8-chat__message-footer: Contains attachments, stop reasons, etc.

Content Blocks

• .g8-block: Generic wrapper for content blocks (tools, thinking, etc.).
• .g8-thinking-block: Displays the AI's thought process.
  • [data-status="running"]: When the AI is currently thinking.
• .g8-tool-block: Displays tool calls.
  • [data-status="completed"]: Successfully executed tool.
  • [data-status="failed"]: Failed tool execution.

Forms & Inputs

• .g8-form-input: Wrapper for form inputs.
• .g8-input: Base class for text inputs.
• .g8-textarea: Base class for textareas.
• .g8-btn: Base class for buttons.

---

4. Variables Reference

Global Primitives (Branding)

These are the foundational variables derived from the organization's branding.

Variable	Description
--g8-primary	Primary brand color.
--g8-secondary	Secondary brand color.
--g8-bg-primary	Primary background (usually white).
--g8-bg-secondary	Secondary background (usually light gray).
--g8-text-primary	Main text color.
--g8-text-muted	Muted text color.
--g8-border-color	Default border color.
--g8-radius-md	Default border radius (approx 6px).
--g8-spacing-md	Default spacing (1rem / 16px).

Chat-Specific Variables

These variables map to the global primitives but can be overridden specifically for the chat.

Colors

Variable	Default	Description
--chat-bg	--g8-bg-secondary	Background of the chat area.
--chat-message-user-bg	--g8-bg-primary	Background of user messages.
--chat-message-assistant-bg	--g8-primary-opacity-10	Background of AI messages.
--chat-input-bg	white	Background of the input area.
--chat-input-border	--g8-border-color	Border color of the input area.

Layout & Spacing

Variable	Default	Description
--chat-max-width	56rem	Max width of the message content.
--chat-message-padding	--g8-spacing-md	Padding inside message bubbles.
--chat-message-radius	--g8-radius-md	Border radius of message bubbles.
--chat-input-max-height	25rem	Max height of the input textarea before scrolling.

Blocks & Tools

Variable	Default	Description
--block-border	--g8-border-color	Border for content blocks.
--block-radius	--g8-radius-md	Radius for content blocks.
--block-tool-running-color	--g8-info	Color for running tools.
--block-tool-completed-color	--g8-success	Color for completed tools.
--block-tool-failed-color	--g8-error	Color for failed tools.

Typography

Variable	Default	Description
--g8-font-sans	Inter, system-ui...	Main sans-serif font.
--g8-font-mono	Fira Code, monospace	Monospace font for code.
--g8-font-size-base	1rem (16px)	Base font size.

---

5. Best Practices for Customization

1. Prefer Variables: Always try to achieve your design by overriding variables first. This ensures your changes scale and adapt to future updates.
2. Use Specificity Wisely: If you must write custom CSS, use the provided classes and data attributes. Avoid using !important.
3. Test Responsiveness: The chat is designed to be responsive. Ensure your custom styles don't break the layout on mobile devices.
4. Accessibility: Ensure sufficient color contrast when changing background or text colors.