testio-tailwind 3.19.0 → 3.20.0

package/CLAUDE_DESIGN_SYSTEM_REFERENCE.md

@@ -0,0 +1,1978 @@
+# Test IO Tailwind Design System - Claude Reference Guide
+
+**Version:** 3.12.0
+**Framework:** Tailwind CSS 4.x
+**Package:** `testio-tailwind`
+**Last Updated:** October 2025
+**Node Version:** v23.11.0
+
+This document serves as a comprehensive reference for Claude AI to utilize the Test IO Tailwind design system when building pages and components in other projects.
+
+## Recent Updates (October 2025)
+
+- ✨ **Page Header Component**: New responsive layout component for dashboard and session pages with chart integration
+- 🌙 **Dark Mode Tables**: Comprehensive dark theme support for all table variants
+- 📐 **Updated Breakpoints**: Refined responsive breakpoints (lg: 70rem, xl: 90rem, 2xl: 100rem)
+- 🎨 **Dark Theme Enhancements**: Border radius increased to 12px, larger grid gutters (40px) in dark mode
+- 🔧 **Splitview Improvements**: Better alignment with page header grids, new status and button classes
+- 💬 **Chat Components**: Full dark mode support with adjusted layouts
+- 🔄 **Status Stepper**: New multi-step process visualization component for AgenticQA
+- 🎯 **List Item Badge Fix**: Improved vertical centering for badges
+
+---
+
+## Table of Contents
+1. [Installation & Setup](#installation--setup)
+2. [Color System](#color-system)
+3. [Typography](#typography)
+4. [Spacing & Layout](#spacing--layout)
+5. [Button Components](#button-components)
+6. [Card Components](#card-components)
+7. [Form Components](#form-components)
+8. [Page Layout Components](#page-layout-components) ⭐ NEW
+9. [Navigation Components](#navigation-components)
+10. [Feedback Components](#feedback-components)
+11. [Data Display Components](#data-display-components)
+12. [Chat Components](#chat-components) ⭐ NEW
+13. [Status & Progress Components](#status--progress-components) ⭐ NEW
+14. [Dark Mode](#dark-mode)
+15. [Utility Patterns](#utility-patterns)
+16. [Best Practices for Claude](#best-practices-for-claude)
+
+---
+
+## Installation & Setup
+
+### NPM Installation
+```bash
+npm install testio-tailwind
+```
+
+### CSS Import
+```css
+@import 'testio-tailwind/dist/static/app.compiled.css';
+```
+
+### JavaScript Import
+```javascript
+import 'testio-tailwind/dist/static/app.bundled.js';
+```
+
+---
+
+## Color System
+
+### Semantic Colors
+Use these color utilities for consistent semantic meaning:
+
+```html
+<!-- Primary Actions -->
+<div class="bg-primary text-white">Primary action</div>
+<div class="bg-link text-white">Link color</div>
+
+<!-- Status Colors -->
+<div class="bg-success text-white">Success state</div>
+<div class="bg-danger text-white">Error/danger state</div>
+<div class="bg-info text-white">Information</div>
+<div class="bg-blocked text-white">Warning/blocked</div>
+<div class="bg-pending text-gray-darker">Pending state</div>
+
+<!-- Functional Colors -->
+<div class="bg-appbody text-appbody-textcolor">App background</div>
+<div class="bg-card">Card background</div>
+<div class="bg-header text-white">Header background</div>
+<div class="bg-listitem">List item background</div>
+<div class="border-bordercolor">Standard border</div>
+```
+
+### Color Palette
+
+**Grays:** `gray-100` through `gray-900`, plus `gray-lightest`, `gray-lighter`, `gray-light`, `gray-dark`, `gray-darker`, `gray-darkest`
+
+**Brand Colors:**
+- **Primary (Petrol):** `petrol` (#236a84 light, #78eac1 dark)
+- **Success:** `green` (#8cbd24 light, #33BA9E dark)
+- **Danger/Critical:** `red` (#ec0404 light, #FF3131 dark)
+- **Warning:** `orange` (#f48d21)
+- **Info:** `blue` (#326dd1)
+- **Accent Colors:** `teal`, `purple`, `pink`, `yellow`
+
+**Priority Levels:**
+- `critical` - Red (#ec0404)
+- `high` - Yellow (#d8ce0d)
+- `low` - Gray (#9fa2a8)
+
+**Issue Types:**
+- `visual` - Orange (#f48d21)
+- `content` - Blue (#326dd1)
+- `usability` - Petrol dark (#263340)
+
+---
+
+## Typography
+
+### Font Families
+- **Body/Sans:** `font-sans` - Source Sans 3
+- **Monospace:** `font-mono` - Source Code Pro
+
+### Headings
+Use semantic heading classes with proper visual hierarchy:
+
+```html
+<h1 class="text-heading-1 font-light">Main Title (2.25rem)</h1>
+<h2 class="text-heading-2 font-light">Section Title (1.875rem)</h2>
+<h3 class="text-heading-3 font-light">Subsection (1.563rem)</h3>
+<h4 class="text-heading-4 font-light">Sub-heading (1.375rem)</h4>
+<h5 class="text-heading-5 font-light">Minor heading (1.125rem)</h5>
+<h6 class="text-heading-6 font-light">Smallest heading (1rem)</h6>
+```
+
+### Display Text
+For hero sections and large emphasis:
+
+```html
+<h1 class="text-display-1 font-extralight">Hero Text (3.25rem)</h1>
+<h2 class="text-display-2 font-extralight">Large Display (3rem)</h2>
+<h3 class="text-display-3 font-extralight">Medium Display (2.75rem)</h3>
+<h4 class="text-display-4 font-extralight">Small Display (2.5rem)</h4>
+```
+
+### Body Text Sizes
+```html
+<p class="text-base">Base text (0.875rem - default)</p>
+<p class="text-lg">Large text (1.25rem)</p>
+<p class="text-sm">Small text (0.813rem)</p>
+<p class="text-xs">Extra small (0.6875rem)</p>
+<p class="text-xxs">Tiny text (0.625rem)</p>
+```
+
+### Labels & Special Text
+```html
+<label class="text-label">Form Label (0.8125rem, 0.75rem in dark)</label>
+<label class="text-label-sm">Small Label (0.75rem)</label>
+<h3 class="text-card-header">Card Header (1.125rem in dark)</h3>
+```
+
+---
+
+## Spacing & Layout
+
+### Spacing Scale
+The design system uses a custom spacing scale:
+
+- `xxs` - 0.3125rem (5px)
+- `xs` - 0.625rem (10px)
+- `sm` - 0.9375rem (15px)
+- `md` - 1.25rem (20px)
+- `spacing` - 1.875rem (30px) - **base unit**
+- `lg` - 3.125rem (50px)
+- `xl` - 3.75rem (60px)
+- `xxl` - 5.625rem (90px)
+- `spacing-2xl` through `spacing-8xl` for larger gaps
+
+### Common Spacing Patterns
+```html
+<!-- Padding -->
+<div class="p-md">Standard padding (20px)</div>
+<div class="p-card-padding">Card padding (30px)</div>
+<div class="px-md py-sm">Mixed padding</div>
+
+<!-- Margins -->
+<div class="mb-spacing">Standard margin bottom (30px)</div>
+<div class="mt-xxs">Tiny margin top (5px)</div>
+
+<!-- Gaps (for flexbox/grid) -->
+<div class="flex gap-xs">Flex with 10px gap</div>
+<div class="grid gap-grid-gutter">Grid with gutter (20px light, 40px dark)</div>
+```
+
+### Breakpoints
+```css
+xs: 30rem (480px)
+sm: 640px (default Tailwind)
+md: 768px (default Tailwind)
+lg: 70rem (1120px)        ← Updated
+xl: 90rem (1440px)        ← Updated
+2xl: 100rem (1600px)      ← Updated
+3xl: 1930px
+```
+
+### Responsive Patterns
+```html
+<div class="grid grid-cols-1 md:grid-cols-2 lg:grid-cols-3 gap-grid-gutter">
+  <!-- Responsive grid -->
+</div>
+```
+
+---
+
+## Button Components
+
+### Basic Buttons
+```html
+<!-- Primary button -->
+<button class="btn btn-primary">Primary Action</button>
+
+<!-- Secondary (outline) button -->
+<button class="btn btn-secondary">Secondary Action</button>
+
+<!-- Ghost button (no border/background) -->
+<button class="btn btn-ghost">Ghost Action</button>
+
+<!-- Ghost inverted (white text) -->
+<button class="btn btn-ghost-inverted">Ghost Inverted</button>
+```
+
+### Semantic Button Variants
+```html
+<button class="btn btn-success">Success Action</button>
+<button class="btn btn-danger">Delete/Danger</button>
+<button class="btn btn-warning">Warning Action</button>
+<button class="btn btn-info">Info Action</button>
+```
+
+### Button Sizes
+```html
+<!-- Small button -->
+<button class="btn btn-sm btn-primary">Small</button>
+
+<!-- Default button (h-btn = 2.5rem/40px) -->
+<button class="btn btn-primary">Default</button>
+
+<!-- Large square button (5.625rem) -->
+<button class="btn btn-lg btn-primary">
+  <i class="icon icon-star"></i>
+</button>
+
+<!-- Extra large button with label (9.375rem) -->
+<div class="btn-lg-wrapper">
+  <button class="btn btn-xl btn-primary">
+    <i class="icon icon-upload"></i>
+    Upload
+  </button>
+  <span class="btn-label">Upload files</span>
+</div>
+```
+
+### Button Shapes
+```html
+<!-- Square icon button -->
+<button class="btn btn-square btn-primary">
+  <i class="icon icon-search"></i>
+</button>
+
+<!-- Circle button -->
+<button class="btn btn-circle btn-primary">
+  <i class="icon icon-add"></i>
+</button>
+
+<!-- Block button (full width) -->
+<button class="btn btn-block btn-primary">Full Width</button>
+```
+
+### Button States
+```html
+<!-- Disabled button -->
+<button class="btn btn-primary" disabled>Disabled</button>
+
+<!-- Inverted button (white bg) -->
+<button class="btn btn-primary-inverted">Inverted</button>
+
+<!-- Dashed border button -->
+<button class="btn btn-dashed">Add New</button>
+```
+
+### Buttons with Icons
+```html
+<button class="btn btn-primary">
+  <i class="icon icon-save mr-xs"></i>
+  Save Changes
+</button>
+
+<button class="btn btn-secondary">
+  <i class="icon icon-download mr-xs"></i>
+  Download
+</button>
+```
+
+---
+
+## Card Components
+
+### Basic Card Structure
+```html
+<div class="card">
+  <div class="card-header">
+    <h3 class="card-title">Card Title</h3>
+  </div>
+  <div class="card-body">
+    <p>Card content goes here</p>
+  </div>
+  <div class="card-footer">
+    <button class="btn btn-primary">Action</button>
+    <button class="btn btn-secondary">Cancel</button>
+  </div>
+</div>
+```
+
+### Card Sizes
+```html
+<!-- Small card (11.25rem on sm+ screens) -->
+<div class="card card-sm">
+  <div class="card-header">
+    <h3 class="card-title">Small Card</h3>
+  </div>
+  <div class="card-body">Content</div>
+</div>
+
+<!-- Medium card (17.5rem) -->
+<div class="card card-md">
+  <div class="card-header">
+    <h3 class="card-title">Medium Card</h3>
+  </div>
+  <div class="card-body">Content</div>
+</div>
+
+<!-- Large card (23.75rem) -->
+<div class="card card-lg">
+  <div class="card-header">
+    <h3 class="card-title">Large Card</h3>
+  </div>
+  <div class="card-body">Content</div>
+</div>
+```
+
+### Card Variants
+```html
+<!-- Highlighted card (info blue background) -->
+<div class="card highlight">
+  <div class="card-header">
+    <h3 class="card-title">Featured Card</h3>
+  </div>
+  <div class="card-body">Important content</div>
+</div>
+
+<!-- Card with highlighted header only -->
+<div class="card">
+  <div class="card-header highlight">
+    <h3 class="card-title">Highlighted Header</h3>
+  </div>
+  <div class="card-body">Regular content</div>
+</div>
+
+<!-- Card with image -->
+<div class="card">
+  <img src="image.jpg" alt="Card image" class="card-image">
+  <div class="card-header">
+    <h3 class="card-title">Card with Image</h3>
+  </div>
+  <div class="card-body">Content</div>
+</div>
+
+<!-- Card with icon header -->
+<div class="card">
+  <div class="card-icon-header">
+    <i class="icon icon-star"></i>
+  </div>
+  <div class="card-body">
+    <h3 class="card-title">Icon Card</h3>
+    <p>Content below icon</p>
+  </div>
+</div>
+```
+
+### Card Layouts
+```html
+<!-- Grid of cards (responsive) -->
+<div class="grid-cards">
+  <div class="card">...</div>
+  <div class="card">...</div>
+  <div class="card">...</div>
+</div>
+
+<!-- List of cards (horizontal wrap) -->
+<div class="list-cards">
+  <div class="card card-sm">...</div>
+  <div class="card card-sm">...</div>
+</div>
+
+<!-- Achievements grid (6 columns on 2xl screens) -->
+<div class="grid-cards-achievements">
+  <div class="card">...</div>
+  <div class="card">...</div>
+</div>
+```
+
+---
+
+## Form Components
+
+### Form Group Structure
+```html
+<div class="form-group">
+  <label class="form-label">Email Address</label>
+  <input type="email" class="form-control" placeholder="Enter email">
+</div>
+
+<!-- Optional field -->
+<div class="form-group">
+  <label class="form-label optional">Phone Number</label>
+  <input type="tel" class="form-control">
+</div>
+```
+
+### Form Inputs
+```html
+<!-- Text input -->
+<input type="text" class="form-control" placeholder="Enter text">
+
+<!-- Textarea -->
+<textarea class="form-control" rows="4" placeholder="Enter description"></textarea>
+
+<!-- Disabled input -->
+<input type="text" class="form-control" disabled value="Read only">
+
+<!-- With validation error -->
+<div class="form-group">
+  <label class="form-label">Username</label>
+  <div class="field_with_errors">
+    <input type="text" class="form-control">
+  </div>
+  <div class="form-hint error">Username is required</div>
+</div>
+```
+
+### Form Hints
+```html
+<!-- Standard hint -->
+<div class="form-hint">This field is optional</div>
+
+<!-- Error hint -->
+<div class="form-hint error">Please enter a valid email</div>
+```
+
+### Select Inputs
+```html
+<!-- Standard select -->
+<select class="form-control">
+  <option>Choose an option</option>
+  <option value="1">Option 1</option>
+  <option value="2">Option 2</option>
+</select>
+```
+
+### Checkboxes and Radios
+```html
+<!-- Checkbox -->
+<div class="form-check">
+  <input type="checkbox" id="check1" class="form-check-input">
+  <label for="check1" class="form-check-label">Accept terms</label>
+</div>
+
+<!-- Radio button -->
+<div class="form-radio">
+  <input type="radio" id="radio1" name="option" class="form-radio-input">
+  <label for="radio1" class="form-radio-label">Option 1</label>
+</div>
+```
+
+### Toggle Switch
+```html
+<div class="toggle-switch">
+  <input type="checkbox" id="toggle1" class="toggle-input">
+  <label for="toggle1" class="toggle-label">Enable notifications</label>
+</div>
+```
+
+### Form with Addon
+```html
+<div class="form-group with-addon">
+  <label class="form-label">Price</label>
+  <input type="number" class="form-control" placeholder="0.00">
+  <div class="form-addon">USD</div>
+</div>
+```
+
+### Inverted Forms (for dark backgrounds)
+```html
+<div class="form-group inverted">
+  <label class="form-label">Email</label>
+  <input type="email" class="form-control" placeholder="Enter email">
+  <div class="form-hint">We'll never share your email</div>
+</div>
+```
+
+---
+
+## Page Layout Components
+
+### Page Header Component ⭐ NEW
+
+A responsive grid layout component for dashboard and session management pages.
+
+#### Basic Page Header
+```html
+<div class="page-header">
+  <div class="card page-maincard p-card-padding">
+    <h1 class="text-card-header">Session Details</h1>
+    <h2 class="page-session-title">Test Session Title</h2>
+
+    <dl class="page-meta-info">
+      <dt class="label">Created on:</dt>
+      <dd>2025-10-21 10:45 AM</dd>
+
+      <dt class="label">Last test:</dt>
+      <dd>2025-10-21 11:30 AM</dd>
+
+      <dt class="label">ID:</dt>
+      <dd>321456987</dd>
+
+      <dt class="label">URL:</dt>
+      <dd class="row-testsuite">
+        <a href="#" class="label">Test Suite Name</a>
+      </dd>
+
+      <dt class="label">Status:</dt>
+      <dd class="text-white">Active</dd>
+    </dl>
+  </div>
+
+  <div class="page-actions">
+    <a href="#" class="btn btn-primary btn-main">
+      <span class="icon icon-test-running-xl"></span>
+      Start Test
+    </a>
+  </div>
+</div>
+```
+
+**Responsive Grid Behavior:**
+- **Mobile (default):** 1 column
+- **sm:** 2 columns
+- **md:** 3 columns
+- **lg:** 4 columns
+- **xl:** 5 columns
+
+**Key Classes:**
+- `.page-header` - Main grid container with responsive columns
+- `.page-maincard` - Primary content card (spans 2-4 columns based on screen size)
+- `.page-actions` - Action buttons column (vertical on md+, horizontal on mobile)
+- `.page-session-title` - Session/test title with bottom margin
+- `.page-meta-info` - Metadata grid (2 cols mobile, 6 cols xl)
+- `.row-testsuite` - Special metadata row that spans 5 columns on xl
+
+#### Page Header with Chart
+```html
+<div class="page-header with-chart">
+  <div class="card page-maincard p-card-padding">
+    <h1 class="text-card-header">Session Details</h1>
+    <h2 class="page-session-title">Test Session Title</h2>
+    <dl class="page-meta-info">
+      <dt class="label">Created on:</dt>
+      <dd>2025-10-21 10:45 AM</dd>
+      <dt class="label">Status:</dt>
+      <dd class="text-white">Running</dd>
+    </dl>
+  </div>
+
+  <div class="page-chart card p-card-padding">
+    <div class="echarts-container" id="chart"></div>
+  </div>
+
+  <div class="page-actions">
+    <a href="#" class="btn btn-primary btn-main">
+      <span class="icon icon-review-xl"></span>
+      Show Report
+    </a>
+    <a href="#" class="btn btn-secondary">Re-run All Checks</a>
+  </div>
+</div>
+```
+
+**Layout with `.with-chart`:**
+- Main card spans: md:1 col, lg:2 cols, xl:3 cols (reduced to fit chart)
+- Chart card gets its own column
+- Actions column spans: sm:2 cols, md:1 col
+
+#### Page Header with Forms
+```html
+<div class="page-header">
+  <div class="card page-maincard p-card-padding">
+    <div class="form-grid">
+      <div class="form-group">
+        <label class="form-label">Test Name</label>
+        <input type="text" class="form-control" placeholder="Enter test name">
+      </div>
+      <div class="form-group">
+        <label class="form-label">URL for Testing</label>
+        <input type="url" class="form-control" placeholder="https://example.com">
+      </div>
+      <!-- More form groups -->
+    </div>
+  </div>
+
+  <div class="page-actions">
+    <a href="#" class="btn btn-primary btn-xl">
+      <span class="icon icon-test-running-xl"></span>
+      Save and Run Test
+    </a>
+    <a href="#" class="btn btn-secondary">Save Draft</a>
+    <a href="#" class="btn btn-secondary">Cancel</a>
+  </div>
+</div>
+```
+
+**Action Buttons Behavior:**
+- Horizontal layout on mobile with `ml-xxs` spacing (except first), `mr-xxs` spacing (except last)
+- Vertical stack on md+ screens with `mb-xs` spacing (except last)
+- Changed from `lg:flex-col` to `md:flex-col` for earlier responsive stacking
+- `.btn-main` class for primary action (grows to fill available space, uses `md:flex-col`)
+- `.btn-xl` icons are hidden below lg, shown on lg+ with `lg:block`, height changes to `md:h-btn-xl`
+- Border color: `border-bordercolor`
+- Actions column spans: `sm:col-span-2 md:col-span-1`
+
+### Splitview Component ⭐ UPDATED
+
+Two-pane layout for list and detail views with responsive behavior. Recently enhanced with status and button classes.
+
+#### Basic Splitview
+```html
+<div class="splitview">
+  <div class="splitview-list">
+    <div class="list-item">
+      <h4 class="list-item-title">Item 1</h4>
+      <p class="list-item-description">Description</p>
+    </div>
+  </div>
+  <div class="splitview-detail">
+    <h2>Detail View</h2>
+    <p>Selected item details</p>
+  </div>
+</div>
+```
+
+#### Splitview with Status Groups (NEW)
+```html
+<div class="splitview">
+  <div class="splitview-list">
+    <details class="splitview-group" open>
+      <summary class="splitview-group-header">
+        <h3 class="splitview-group-title">Test Group 1</h3>
+        <i class="icon icon-chevron-down"></i>
+      </summary>
+
+      <!-- Status stepper in group -->
+      <div class="splitview-group-status">
+        <div class="status-stepper">
+          <div class="status-step completed">
+            <i class="icon icon-check-thick-centered"></i>
+            3 done
+          </div>
+          <div class="status-step active">
+            <i class="icon icon-sync"></i>
+            Executing
+          </div>
+          <div class="status-step">
+            + 3 to do
+          </div>
+        </div>
+      </div>
+
+      <!-- List items -->
+      <div class="list-item">...</div>
+      <div class="list-item">...</div>
+
+      <!-- Show dismissed button -->
+      <button class="splitview-btn">
+        Show 5 dismissed items
+      </button>
+    </details>
+  </div>
+</div>
+```
+
+**New Splitview Classes:**
+- `.splitview-group-status` - Status display area within groups (bg-listitem, border-bottom, padding)
+- `.splitview-btn` - Full-width button for showing/hiding items (text-label-color, centered text)
+- `.splitview-group .splitview-btn` - Button within groups (rounded bottom corners, bg-listitem)
+
+**Splitview Group Status Styling:**
+```css
+.splitview-group-status {
+  padding-left: lg;
+  padding-right: md;
+  padding-top/bottom: xs;
+  background: listitem color;
+  border-bottom: 1px solid appbody;
+}
+```
+
+---
+
+## Navigation Components
+
+### Header
+```html
+<header class="header">
+  <div class="header-logo">
+    <img src="logo.svg" alt="Logo">
+  </div>
+  <nav class="header-nav">
+    <a href="#" class="nav-link">Dashboard</a>
+    <a href="#" class="nav-link active">Projects</a>
+    <a href="#" class="nav-link">Settings</a>
+  </nav>
+  <div class="header-actions">
+    <button class="btn btn-sm btn-primary">New Project</button>
+  </div>
+</header>
+```
+
+### Sidebar
+```html
+<aside class="sidebar">
+  <nav class="sidebar-nav">
+    <a href="#" class="sidebar-link active">
+      <i class="icon icon-home"></i>
+      Dashboard
+    </a>
+    <a href="#" class="sidebar-link">
+      <i class="icon icon-folder"></i>
+      Projects
+    </a>
+    <a href="#" class="sidebar-link">
+      <i class="icon icon-settings"></i>
+      Settings
+    </a>
+  </nav>
+</aside>
+```
+
+### Tabs
+```html
+<div class="tabs">
+  <button class="tab tab-active">Overview</button>
+  <button class="tab">Details</button>
+  <button class="tab">Settings</button>
+</div>
+
+<div class="tab-content">
+  <div class="tab-pane active">Overview content</div>
+  <div class="tab-pane">Details content</div>
+  <div class="tab-pane">Settings content</div>
+</div>
+```
+
+### Dropdown
+```html
+<div class="dropdown">
+  <button class="btn btn-secondary dropdown-toggle">
+    Actions
+    <i class="icon icon-chevron-down"></i>
+  </button>
+  <div class="dropdown-menu">
+    <a href="#" class="dropdown-item">Edit</a>
+    <a href="#" class="dropdown-item">Duplicate</a>
+    <div class="dropdown-divider"></div>
+    <a href="#" class="dropdown-item text-danger">Delete</a>
+  </div>
+</div>
+```
+
+---
+
+## Feedback Components
+
+### Alerts
+```html
+<!-- Success alert -->
+<div class="alert alert-success">
+  <i class="icon icon-check-circle"></i>
+  Changes saved successfully!
+</div>
+
+<!-- Error alert -->
+<div class="alert alert-danger">
+  <i class="icon icon-exclamation-circle"></i>
+  An error occurred. Please try again.
+</div>
+
+<!-- Info alert -->
+<div class="alert alert-info">
+  <i class="icon icon-info-circle"></i>
+  New features are available.
+</div>
+
+<!-- Warning alert -->
+<div class="alert alert-warning">
+  <i class="icon icon-exclamation-triangle"></i>
+  Your trial expires in 3 days.
+</div>
+```
+
+### Notifications
+```html
+<div class="notification notification-success">
+  <div class="notification-icon">
+    <i class="icon icon-check"></i>
+  </div>
+  <div class="notification-content">
+    <h4 class="notification-title">Success</h4>
+    <p class="notification-message">Your changes have been saved.</p>
+  </div>
+  <button class="notification-close">
+    <i class="icon icon-close"></i>
+  </button>
+</div>
+```
+
+### Loading Spinner
+```html
+<div class="loading-spinner">
+  <div class="spinner"></div>
+  <p class="loading-text">Loading...</p>
+</div>
+```
+
+### Empty State
+```html
+<div class="emptystate-message">
+  <i class="icon icon-inbox text-icon-xl"></i>
+  <h3 class="text-heading-4">No items found</h3>
+  <p class="text-sm text-gray-dark">Get started by creating your first item.</p>
+  <button class="btn btn-primary mt-md">Create Item</button>
+</div>
+```
+
+### Progress Bar
+```html
+<!-- Thick progress bar -->
+<div class="progress">
+  <div class="progress-bar" style="width: 75%">75%</div>
+</div>
+
+<!-- Thin progress bar -->
+<div class="progress progress-thin">
+  <div class="progress-bar bg-success" style="width: 60%"></div>
+</div>
+```
+
+### Badges
+```html
+<span class="badge badge-primary">New</span>
+<span class="badge badge-success">Active</span>
+<span class="badge badge-danger">Urgent</span>
+<span class="badge badge-warning">Pending</span>
+<span class="badge badge-info">Info</span>
+```
+
+### Tags
+```html
+<div class="tag">Design</div>
+<div class="tag tag-success">Completed</div>
+<div class="tag tag-danger">High Priority</div>
+```
+
+---
+
+## Data Display Components
+
+### Tables ⭐ UPDATED
+
+The design system includes several table variants with comprehensive dark mode support.
+
+#### Basic Table
+```html
+<table class="table">
+  <thead>
+    <tr>
+      <th>Name</th>
+      <th>Status</th>
+      <th>Actions</th>
+    </tr>
+  </thead>
+  <tbody>
+    <tr>
+      <td>John Doe</td>
+      <td>
+        <span class="badge badge-success">Active</span>
+      </td>
+      <td>
+        <button class="btn btn-sm btn-ghost">Edit</button>
+      </td>
+    </tr>
+  </tbody>
+</table>
+```
+
+**Dark Mode Features:**
+- Increased padding (`dark:py-md` on cells vs `py-xs` in light mode)
+- Dark background on cells (`dark:bg-black` for td, `dark:bg-appbody` for th)
+- Row borders (`dark:border-b-4 dark:border-appbody` instead of cell borders)
+- Uppercase header text (`dark:uppercase`)
+- No top/side borders in dark mode (`dark:border-0` on cells)
+
+#### Table Variants
+
+**Bordered Table:**
+```html
+<table class="table table-bordered">
+  <!-- Full borders around all cells -->
+  <!-- Dark mode: 2px border with appbody color -->
+</table>
+```
+
+**Borderless Table:**
+```html
+<table class="table table-borderless">
+  <!-- No borders on any cells -->
+</table>
+```
+
+**Small/Compact Table:**
+```html
+<table class="table table-sm">
+  <!-- Reduced padding (pr-spacing), more compact -->
+</table>
+```
+
+**Standard Table (Key-Value Style):**
+```html
+<table class="table-standard">
+  <thead>
+    <tr>
+      <th>Property</th>
+      <th>Value</th>
+    </tr>
+  </thead>
+  <tbody>
+    <tr>
+      <td>Name</td>
+      <td>John Doe</td>
+    </tr>
+    <tr>
+      <td>Email</td>
+      <td>john@example.com</td>
+    </tr>
+  </tbody>
+  <tfoot>
+    <tr>
+      <td>Total</td>
+      <td>2 items</td>
+    </tr>
+  </tfoot>
+</table>
+```
+- No wrapping by default (`md:whitespace-nowrap`)
+- First column minimal width, last column fills space (`.cell-full-width` to override)
+- Add `.wrap` or `.pre` to cells for text wrapping
+
+#### Cell Style Table (Status Tracking)
+```html
+<table class="table-cellstyle">
+  <thead>
+    <tr>
+      <th class="completed">Feature A</th>
+      <th class="inprogress">Feature B</th>
+      <th class="missing">Feature C</th>
+    </tr>
+  </thead>
+  <tbody>
+    <tr>
+      <td class="completed">Implementation done</td>
+      <td class="inprogress">Working on it...</td>
+      <td class="missing">Not started</td>
+    </tr>
+  </tbody>
+</table>
+```
+
+**Status Classes:**
+- `.completed` - Green checkmark icon (after pseudo-element)
+- `.inprogress` - Clock icon, gray background, italic text
+- `.missing` - Exclamation icon (on th), transparent bg, italic disabled text (on td)
+
+**Editable Cells:**
+```html
+<td class="cell-editable">
+  <a href="#edit" class="cell-content-editable">
+    Click to edit this content
+  </a>
+</td>
+
+<!-- Edit state (shown when editing) -->
+<td class="cell-editable">
+  <div class="cell-edit-state">
+    <form class="edit-form">
+      <textarea>Content being edited</textarea>
+      <div class="cell-actions">
+        <button class="btn btn-success"><i class="icon icon-check"></i></button>
+        <button class="btn btn-danger"><i class="icon icon-close"></i></button>
+      </div>
+    </form>
+  </div>
+</td>
+```
+
+**Selectable Cells:**
+```html
+<td class="cell-selectable completed">
+  <input type="checkbox" id="cell1">
+  <label for="cell1">Option text with completion status</label>
+</td>
+```
+- Checkbox appears on the left
+- Hover highlights the entire cell
+- Status icons (completed/inprogress) appear on the right
+- Selected state: primary background with white text
+
+#### Grid Table (CSS Grid Layout)
+```html
+<table class="table-grid">
+  <thead>
+    <tr>
+      <th>Col 1</th>
+      <th>Col 2</th>
+      <th>Col 3</th>
+    </tr>
+  </thead>
+  <tbody>
+    <tr>
+      <td>Data 1</td>
+      <td>Data 2</td>
+      <td>Data 3</td>
+    </tr>
+  </tbody>
+</table>
+```
+- Uses CSS Grid (`display: grid; grid-flow-col`)
+- Better for complex responsive tables
+- `thead`, `tbody`, `tr` use `display: contents`
+
+#### Table Cell Utilities
+```html
+<!-- Fixed width cell -->
+<td class="td-fixed-width">Limited to 150px</td>
+
+<!-- Actions cell (right-aligned, constrained width) -->
+<td class="action-cell">
+  <button class="btn btn-sm btn-ghost">Edit</button>
+  <button class="btn btn-sm btn-ghost">Delete</button>
+</td>
+
+<!-- Title cell (max 500px) -->
+<td class="title">Very long title that will be constrained</td>
+
+<!-- Full width cell in table-standard -->
+<td class="cell-full-width">Takes all available space</td>
+
+<!-- Text wrapping in table-standard -->
+<td class="wrap">This text will wrap normally</td>
+<td class="pre">This text preserves   whitespace</td>
+```
+
+#### Interactive Table Rows
+```html
+<!-- Hover to highlight entire row (blue background) -->
+<tr class="linked-row">
+  <td>Click anywhere on this row</td>
+  <td>More data</td>
+</tr>
+
+<!-- Hover to highlight just this cell -->
+<td class="linked-cell">Click this specific cell</td>
+
+<!-- Highlight parent row when child element is hovered -->
+<tr>
+  <td>
+    <a class="highlight-parent-row" href="#">Hover this link to highlight row</a>
+  </td>
+  <td>Other data</td>
+</tr>
+```
+
+### List Items
+
+#### Basic List
+```html
+<div class="lists">
+  <div class="list-item">
+    <div class="list-item-content">
+      <h4 class="list-item-title">Item Title</h4>
+      <p class="list-item-description">Item description text</p>
+    </div>
+    <div class="list-item-actions">
+      <button class="btn btn-sm btn-ghost">View</button>
+    </div>
+  </div>
+</div>
+```
+
+#### List Item with Badge ⭐ UPDATED
+```html
+<div class="list-item">
+  <div class="listitem-badge">
+    <i class="icon icon-check text-success"></i>
+  </div>
+  <div class="list-item-content">
+    <h4 class="list-item-title">Completed Item</h4>
+    <p class="list-item-description">This item has been completed</p>
+  </div>
+</div>
+```
+
+**Badge Styling (Updated):**
+- Changed from `items-start` to `items-center` for better vertical alignment
+- Changed from `p-xxs pt-xs` to `px-xxs py-xxs` for consistent padding
+- Width: `w-btn`, Background: `bg-black` (light), `bg-gray-750` (dark)
+- Text color: white, with bold font in dark mode
+- Rounded left corners (`rounded-l`)
+
+### User Item
+```html
+<div class="user-item">
+  <div class="user-item-avatar">
+    <img src="avatar.jpg" alt="User">
+  </div>
+  <div class="user-item-info">
+    <h4 class="user-item-name">Jane Smith</h4>
+    <p class="user-item-email">jane@example.com</p>
+  </div>
+  <div class="user-item-actions">
+    <button class="btn btn-sm btn-secondary">Message</button>
+  </div>
+</div>
+```
+
+### Task/Issue Item
+```html
+<div class="task-item">
+  <div class="task-item-header">
+    <h4 class="task-item-title">Fix login bug</h4>
+    <span class="badge badge-danger">High</span>
+  </div>
+  <div class="task-item-body">
+    <p class="task-item-description">Users unable to login with SSO</p>
+  </div>
+  <div class="task-item-footer">
+    <span class="task-item-meta">Due: Oct 25, 2025</span>
+    <span class="task-item-meta">Assigned to: John</span>
+  </div>
+</div>
+```
+
+---
+
+## Chat Components ⭐ NEW
+
+Comprehensive chat interface components with full dark mode support.
+
+### Chat Message List
+```html
+<div class="list-chat-messages">
+  <div class="chat-message-item">
+    <img src="avatar.jpg" alt="User" class="chat-avatar">
+
+    <div class="chat-header">
+      <span class="chat-title">
+        <span class="chat-author">John Doe</span>
+      </span>
+      <span class="chat-time">2 hours ago</span>
+    </div>
+
+    <div class="chat-message">
+      <p>This is a chat message with some content.</p>
+    </div>
+
+    <div class="chat-actions">
+      <button class="btn btn-ghost btn-sm">
+        <i class="icon icon-reply"></i>
+      </button>
+    </div>
+  </div>
+</div>
+```
+
+**Grid Layout:**
+- Uses CSS Grid with named areas: `chat-avatar`, `chat-header`, `chat-message`, `chat-actions`
+- Light mode: 3 columns (avatar, header/message, actions)
+- Dark mode: 2 columns (avatar, header/message) - actions are hidden
+
+**Component Classes:**
+- `.list-chat-messages` - Container grid with gap-md
+- `.chat-message-item` - Individual message (max-w-capped by default)
+- `.chat-avatar` - Avatar image (w-spacing h-spacing, rounded-full, mr-xs light / mr-md dark)
+- `.chat-header` - Message header (text-label-color, dark: bg-listitem rounded-t)
+- `.chat-author` - Author name (ml-xxs font-semibold)
+- `.chat-message` - Message body (p-xs rounded bg-card, dark: full width, rounded-t-none)
+- `.chat-actions` - Action buttons column (hidden in dark mode via grid template)
+
+### Full Width Chat
+```html
+<div class="list-chat-messages full-width">
+  <!-- Messages span full container width (max-w-full) -->
+  <div class="chat-message-item">...</div>
+</div>
+```
+
+### Chat Message Variants
+
+#### Announcement Message
+```html
+<div class="chat-message">
+  <div class="message-banner announcement">
+    System Announcement: Maintenance scheduled
+  </div>
+  <p>The system will be down for maintenance on Saturday.</p>
+</div>
+```
+- Blue banner at top of message (`bg-info text-white`)
+- Speaker icon before text
+- Border-bottom separator
+
+#### Mentioned Message
+```html
+<div class="chat-message">
+  <div class="message-banner mentioned">
+    <span class="text-mentioned">@YourName</span> mentioned you
+  </div>
+  <p>Hey, can you take a look at this?</p>
+</div>
+```
+- Blue banner with @ icon
+- Bolded mention (`font-bold`)
+
+### Dark Mode Chat Behavior
+
+In dark mode (`.dark` class on parent):
+- Grid changes to 2 columns (actions hidden)
+- Chat header gets background (`bg-listitem`) and full rounded-top
+- Chat message background darker (`bg-listitem`) with no top border radius
+- Avatar margin increased to `mr-md`
+- Message full width (`dark:w-full`)
+
+---
+
+## Status & Progress Components ⭐ NEW
+
+### Status Stepper
+
+A horizontal stepper component for visualizing multi-step processes, particularly useful in AgenticQA workflows.
+
+#### Icon-based Status Stepper
+```html
+<div class="status-stepper">
+  <div class="status-step completed">
+    <i class="icon icon-check-thick-centered"></i>
+    3 done
+  </div>
+  <div class="status-step active">
+    <i class="icon icon-sync"></i>
+    Executing checks
+  </div>
+  <div class="status-step">
+    + 3 to do
+  </div>
+</div>
+```
+
+#### Counter-based Status Stepper
+```html
+<div class="status-stepper">
+  <div class="status-step completed">
+    <span class="counter">99</span>
+    Completed
+  </div>
+  <div class="status-step active">
+    <span class="counter">12</span>
+    Active
+  </div>
+  <div class="status-step">
+    <span class="counter">5</span>
+    Pending
+  </div>
+</div>
+```
+
+**Component Classes:**
+- `.status-stepper` - Container (flex row, items-stretch, full width)
+- `.status-step` - Individual step (flex row, centered, rounded, px-md py-xs, bg-black)
+- `.status-step.active` - Active step (grow-1, white text, bg-gray-750)
+- `.status-step.completed` - Add for completed state (can combine with custom styling)
+- `.status-step .icon` - Icon within step (mr-xs, text-label-color)
+- `.status-step .counter` - Numeric counter (pr-xs, text-lg, font-bold, leading-none)
+
+**Styling Details:**
+```css
+.status-stepper:
+  - Full width flex container
+  - Items stretch to fill height
+  - Horizontal layout
+
+.status-step:
+  - Shrink: 0, Grow: 0 (except .active)
+  - Margin-right: xs (except last)
+  - Padding: md horizontal, xs vertical
+  - Background: black, Text: label-color
+  - Rounded corners
+  - Leading: none
+
+.status-step.active:
+  - Grow: 1 (takes available space)
+  - Text: white
+  - Background: gray-750
+```
+
+**Usage Tips:**
+- Use `.completed` class with success icons for finished steps
+- Use `.active` class for current step (automatically expands to fill space)
+- Default styling for pending/future steps
+- Works great within splitview groups (see `.splitview-group-status`)
+- Icons should use descriptive names like `icon-check-thick-centered`, `icon-sync`
+- Counter variant useful for showing numeric progress
+
+**Common Patterns:**
+```html
+<!-- In a splitview group -->
+<div class="splitview-group-status">
+  <div class="status-stepper">
+    <!-- Steps here -->
+  </div>
+</div>
+
+<!-- As standalone progress indicator -->
+<div class="mb-md">
+  <div class="status-stepper">
+    <!-- Steps here -->
+  </div>
+</div>
+```
+
+---
+
+## Dark Mode
+
+The design system includes comprehensive dark mode support with customized theme variables.
+
+### Dark Mode Color Palette
+```css
+/* Apply .dark class to enable dark mode */
+.dark {
+  /* Core Colors */
+  --color-appbody: #181818;              /* Very dark gray background */
+  --color-appbody-textcolor: #f2f2f2;    /* Light gray text */
+  --color-header: #1d1d1d;
+  --color-card: #1D1D1D;                 /* Dark card background */
+  --color-listitem: #262626;             /* List item background */
+
+  /* Interactive Colors */
+  --color-primary: #78eac1;              /* Teal (was petrol) */
+  --color-link: #8988eb;                 /* Purple links */
+  --color-link-hover: #7954ff;           /* Darker purple hover */
+
+  /* Status Colors */
+  --color-success: #33BA9E;              /* Teal success */
+  --color-danger: #FF3131;               /* Brighter red */
+  --color-bordercolor: #2E2E2E;          /* Dark borders */
+
+  /* Spacing & Style Adjustments */
+  --radius: 12px;                        /* Increased from 5px */
+  --spacing-grid-gutter: 40px;           /* Increased from 20px */
+  --card-padding: 30px;
+  --fontsize-card-header: 1.125rem;      /* Slightly larger */
+  --font-size-label: 0.75rem;            /* Smaller labels */
+}
+```
+
+### Using Dark Mode
+```html
+<!-- Apply dark class to container -->
+<div class="dark">
+  <!-- All children inherit dark mode styles -->
+  <div class="bg-appbody text-appbody-textcolor">
+    <div class="card p-card-padding">
+      <!-- Card automatically has dark background (#1D1D1D) -->
+      <!-- Border radius automatically 12px -->
+      <p>Content with dark mode styling</p>
+    </div>
+  </div>
+</div>
+
+<!-- Conditional dark mode classes on specific elements -->
+<div class="bg-card dark:bg-listitem">
+  <!-- Light mode: #e6e6e6, Dark mode: #262626 -->
+</div>
+
+<table class="table">
+  <!-- Tables automatically apply comprehensive dark mode styles -->
+  <!-- Increased padding, dark backgrounds, adjusted borders -->
+</table>
+```
+
+### Components with Dark Mode Support
+
+**Fully Optimized:**
+- ✅ **Tables:** Increased padding (`dark:py-md`), dark backgrounds, row borders instead of cell borders
+- ✅ **Chat Messages:** Adjusted grid layout, background colors, rounded corners
+- ✅ **Cards:** Dark backgrounds (`#1D1D1D`), larger border radius (12px)
+- ✅ **Forms:** Dark input backgrounds, adjusted borders and placeholders
+- ✅ **Navigation:** Dark sidebar and header variants
+- ✅ **Buttons:** Inverted color schemes for dark backgrounds
+
+**Dark Mode Differences:**
+- Border radius: `5px` → `12px`
+- Grid gutters: `20px` → `40px`
+- Table cell padding: `py-xs` → `py-md`
+- Chat layout: 3 columns → 2 columns (actions hidden)
+- Link colors: Petrol → Purple, Hover: Blue → Dark Purple
+
+### Testing Dark Mode
+
+```html
+<!-- Toggle between light and dark -->
+<body class="bg-appbody text-appbody-textcolor">
+  <!-- Light mode -->
+</body>
+
+<body class="dark bg-appbody text-appbody-textcolor">
+  <!-- Dark mode -->
+</body>
+```
+
+---
+
+## Utility Patterns
+
+### Common Layout Patterns
+```html
+<!-- Centered container -->
+<div class="max-w-centered-content mx-auto">
+  <!-- Content constrained to 1600px -->
+</div>
+
+<!-- Capped content width (for readability) -->
+<div class="max-w-capped">
+  <!-- Content constrained to 43.75rem (700px) -->
+</div>
+
+<!-- Flex layout with gap -->
+<div class="flex items-center gap-xs">
+  <i class="icon icon-user"></i>
+  <span>User Name</span>
+</div>
+
+<!-- Grid layout -->
+<div class="grid grid-cols-2 md:grid-cols-4 gap-grid-gutter">
+  <div>Item 1</div>
+  <div>Item 2</div>
+  <div>Item 3</div>
+  <div>Item 4</div>
+</div>
+```
+
+### Icon Usage
+```html
+<!-- Standard icon (20px) -->
+<i class="icon icon-star"></i>
+
+<!-- Icon sizes -->
+<i class="icon icon-star text-icon-xxxs"></i>  <!-- 10px -->
+<i class="icon icon-star text-icon-xxs"></i>   <!-- 0.625rem -->
+<i class="icon icon-star text-icon-xs"></i>    <!-- 16px -->
+<i class="icon icon-star text-icon-sm"></i>    <!-- 18px -->
+<i class="icon icon-star text-icon"></i>       <!-- 20px - default -->
+<i class="icon icon-star text-icon-lg"></i>    <!-- 40px -->
+<i class="icon icon-star text-icon-xl"></i>    <!-- 60px -->
+<i class="icon icon-star text-icon-xxl"></i>   <!-- 90px -->
+
+<!-- Colored icons -->
+<i class="icon icon-check text-success"></i>
+<i class="icon icon-close text-danger"></i>
+<i class="icon icon-info text-info"></i>
+```
+
+### Border Utilities
+```html
+<!-- Standard border -->
+<div class="border border-bordercolor rounded">Content</div>
+
+<!-- Border widths -->
+<div class="border-1">1px border</div>
+<div class="border-2">2px border</div>
+<div class="border-4">4px border</div>
+<div class="border-6">6px border</div>
+<div class="border-10">10px border</div>
+
+<!-- Border radius (5px light, 12px dark) -->
+<div class="rounded">Rounded corners</div>
+<div class="rounded-t">Top corners rounded</div>
+<div class="rounded-b">Bottom corners rounded</div>
+<div class="rounded-full">Fully rounded (circle/pill)</div>
+```
+
+### Shadow
+```html
+<!-- Standard shadow -->
+<div class="shadow">
+  <!-- 0 3px 6px 0 rgba(0, 0, 0, 0.2), 0 0px 0px 0 rgba(0, 0, 0, 0.05) -->
+</div>
+```
+
+---
+
+## Best Practices for Claude
+
+### When Building Pages:
+
+1. **Start with Layout Structure**
+   - Use semantic HTML5 elements
+   - Apply layout classes: `header`, `sidebar`, `main`, `section`
+   - Use grid or flex utilities for responsive layouts
+   - Consider using `.page-header` for dashboard pages
+
+2. **Component Selection**
+   - Choose the appropriate component variant for the use case
+   - Use semantic button/alert types (primary, success, danger, etc.)
+   - Apply consistent spacing using the spacing scale
+   - Use `.page-header` with chart variant when displaying metrics
+
+3. **Responsive Design**
+   - Use responsive grid classes: `grid-cols-1 md:grid-cols-2 lg:grid-cols-3`
+   - Apply responsive utilities: `hidden md:block`, `flex-col md:flex-row`
+   - Consider mobile-first approach
+   - Remember breakpoints: lg (70rem), xl (90rem), 2xl (100rem)
+
+4. **Accessibility**
+   - Include proper ARIA labels
+   - Use semantic HTML elements
+   - Ensure proper heading hierarchy
+   - Include alt text for images
+   - Use `<label>` elements with `for` attributes
+
+5. **Color Usage**
+   - Use semantic colors for consistent meaning
+   - Apply `bg-card` for card backgrounds
+   - Use `bg-listitem` for list item backgrounds
+   - Use `border-bordercolor` for standard borders
+   - Text color defaults are handled by parent classes
+   - Remember colors change in dark mode (petrol → teal, red → brighter red)
+
+6. **Typography**
+   - Use heading classes (`text-heading-1` through `text-heading-6`)
+   - Apply `font-light` for headings (weight: 300)
+   - Use `text-label` for form labels
+   - Default body text is `text-base` (0.875rem)
+   - Card headers use `text-card-header` (1.125rem in dark mode)
+
+7. **Spacing Consistency**
+   - Use `gap-grid-gutter` for grid/flex gaps (20px light, 40px dark)
+   - Apply `p-md` for standard padding (20px)
+   - Use `p-card-padding` for card padding (30px)
+   - Use `mb-spacing` for section spacing (30px)
+   - Icons typically need `mr-xs` or `ml-xs` when next to text
+   - Page headers use `gap-md xl:gap-grid-gutter`
+
+8. **Dark Mode Considerations**
+   - Border radius is larger in dark mode (12px vs 5px)
+   - Grid gutters are larger in dark mode (40px vs 20px)
+   - Tables have increased padding in dark mode (`dark:py-md`)
+   - Chat layouts adjust grid template in dark mode (2 cols vs 3)
+   - Always test components with `.dark` class applied to parent
+   - Use `dark:` prefix for conditional dark mode styles
+
+9. **Table Best Practices**
+   - Use `.table` for standard data tables
+   - Use `.table-standard` for key-value style tables
+   - Use `.table-cellstyle` for status tracking tables
+   - Use `.table-grid` for complex responsive layouts
+   - Add status classes (`.completed`, `.inprogress`, `.missing`) for task tracking
+   - Use `.action-cell` for right-aligned action buttons
+   - Remember tables have comprehensive dark mode styles built-in
+
+10. **Page Header Best Practices**
+    - Use `.page-header` for dashboard/session pages
+    - Main card should have `.page-maincard` and `p-card-padding`
+    - Main card now uses `sm:col-span-2` for better small screen layout
+    - Use `.page-meta-info` for metadata grid (automatically responsive)
+    - Add `.with-chart` modifier when including charts
+    - Actions go in `.page-actions` (vertical on **md+**, horizontal mobile)
+    - Action stacking changed from `lg:` to `md:` breakpoint for earlier responsive behavior
+    - Use `.btn-main` for primary action button (uses `md:flex-col`)
+    - Special metadata that spans wide use `.row-testsuite`
+
+11. **Status Stepper Best Practices** ⭐ NEW
+    - Use `.status-stepper` for multi-step process visualization
+    - Apply `.active` class to current step (will expand to fill space)
+    - Use `.completed` class with success icons for finished steps
+    - Default state (no class) for pending/future steps
+    - Include `.icon` within steps for visual indicators
+    - Use `.counter` for numeric progress indicators
+    - Works well within `.splitview-group-status` containers
+    - Keep step text concise (3-4 words max)
+
+12. **Splitview Best Practices** ⭐ UPDATED
+    - Use `.splitview-group-status` to show status within collapsible groups
+    - Add `.splitview-btn` for show/hide toggle buttons
+    - Status steppers fit naturally in `.splitview-group-status`
+    - Buttons in groups automatically get rounded bottom corners
+    - Use `bg-listitem` for consistent group backgrounds
+
+### Example Page Structure:
+
+```html
+<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1.0">
+  <title>Test Dashboard</title>
+  <link rel="stylesheet" href="app.compiled.css">
+</head>
+<body class="bg-appbody text-appbody-textcolor">
+
+  <!-- Page Header Component -->
+  <div class="page-header with-chart">
+    <div class="card page-maincard p-card-padding">
+      <h1 class="text-card-header">Test Session Details</h1>
+      <h2 class="page-session-title">Accessibility Audit - Homepage</h2>
+
+      <dl class="page-meta-info">
+        <dt class="label">Created:</dt>
+        <dd>Oct 21, 2025 10:00 AM</dd>
+
+        <dt class="label">Last Run:</dt>
+        <dd>Oct 21, 2025 2:30 PM</dd>
+
+        <dt class="label">ID:</dt>
+        <dd>987654321</dd>
+
+        <dt class="label">Test Suite:</dt>
+        <dd class="row-testsuite">
+          <a href="#" class="label">WCAG 2.1 Level AA</a>
+        </dd>
+
+        <dt class="label">Status:</dt>
+        <dd class="text-white">Completed</dd>
+      </dl>
+    </div>
+
+    <div class="page-chart card p-card-padding">
+      <div class="echarts-container" id="results-chart"></div>
+    </div>
+
+    <div class="page-actions">
+      <a href="#" class="btn btn-primary btn-main">
+        <span class="icon icon-review-xl"></span>
+        View Full Report
+      </a>
+      <a href="#" class="btn btn-secondary">Re-run Tests</a>
+      <a href="#" class="btn btn-secondary">Export Results</a>
+    </div>
+  </div>
+
+  <!-- Main Content -->
+  <main class="p-md md:p-lg">
+    <section class="mb-spacing">
+      <h2 class="text-heading-3 font-light mb-md">Test Results</h2>
+
+      <table class="table">
+        <thead>
+          <tr>
+            <th>Test Name</th>
+            <th>Status</th>
+            <th>Issues Found</th>
+            <th class="action-cell">Actions</th>
+          </tr>
+        </thead>
+        <tbody>
+          <tr>
+            <td>Color Contrast</td>
+            <td><span class="badge badge-success">Passed</span></td>
+            <td>0</td>
+            <td class="action-cell">
+              <button class="btn btn-sm btn-ghost">View</button>
+            </td>
+          </tr>
+          <tr>
+            <td>Keyboard Navigation</td>
+            <td><span class="badge badge-danger">Failed</span></td>
+            <td>3</td>
+            <td class="action-cell">
+              <button class="btn btn-sm btn-ghost">View</button>
+            </td>
+          </tr>
+        </tbody>
+      </table>
+    </section>
+
+    <section>
+      <h2 class="text-heading-3 font-light mb-md">Discussion</h2>
+
+      <div class="list-chat-messages">
+        <div class="chat-message-item">
+          <img src="/avatars/jane.jpg" alt="Jane" class="chat-avatar">
+
+          <div class="chat-header">
+            <span class="chat-title">
+              <span class="chat-author">Jane Smith</span>
+            </span>
+            <span>2 hours ago</span>
+          </div>
+
+          <div class="chat-message">
+            <p>Found some keyboard navigation issues on the main menu. Users can't tab through all the options.</p>
+          </div>
+
+          <div class="chat-actions">
+            <button class="btn btn-ghost btn-sm">
+              <i class="icon icon-reply"></i>
+            </button>
+          </div>
+        </div>
+      </div>
+    </section>
+  </main>
+
+  <script src="app.bundled.js"></script>
+</body>
+</html>
+```
+
+---
+
+## Product-Specific Variants
+
+The design system includes variants for different products:
+
+### Customer Portal
+- Navigation: `customer_header`, `customer_sidebar`
+- Hover color: Teal (`navlink-customer-hover-color`)
+- Product cards: `customer_productcards`
+
+### Tester Portal
+- Navigation: `tester_header`, `tester_sidebar`
+- Hover color: Purple (`navlink-tester-hover-color`)
+- Cards: `tester_cards`
+
+### Manager Portal
+- Navigation: `manager_header`, `manager_sidebar`
+- Hover color: Teal on light background
+- Navigation on white background
+
+### AgenticQA
+- Navigation: `agenticqa_header`, `agenticqa_sidebar`
+- Page headers: `agenticqa_pageheader`
+- Status visualization: `agenticqa_status_stepper`
+
+---
+
+## Additional Components Available
+
+- **Modals/Drawers:** For overlays and side panels
+- **Popovers:** For contextual tooltips
+- **Radio Tabs:** For radio button styled as tabs
+- **Rating Scale:** For rating inputs
+- **Selectable Tokens:** For tag/token selection
+- **File Uploads:** Dropzone integration with styling
+- **Gallery:** Image grid layouts
+- **Metrics:** Metric display components
+- **Device Selector:** For device/platform selection
+
+Refer to the live documentation site for visual examples of all components.
+
+---
+
+## JavaScript Features
+
+The bundled JavaScript includes:
+
+- **Tom-Select:** Enhanced multi-select dropdowns
+- **Select2:** Enhanced select inputs with search (custom "testio" theme)
+- **Autosize:** Auto-expanding textareas
+- **Dropzone:** Drag-and-drop file uploads with preview
+- **Trix:** Rich text editor with custom configuration
+- **ECharts:** Data visualization charts
+  - Bar charts (vertical/horizontal)
+  - Donut charts
+  - Gauge charts
+  - Area charts
+  - Line charts
+  - Custom theming with design system colors
+  - Integration with page-header component
+
+---
+
+## Version & Support
+
+**Current Version:** 3.12.0
+**Tailwind Version:** 4.1.11
+**Node Version:** v23.11.0 (specified in `.nvmrc`)
+
+For updates and examples, refer to:
+- NPM: `npm install testio-tailwind@latest`
+- Documentation: Included in package under `/dist/`
+- Source: GitHub repository (test-IO/testio-tailwind)
+
+---
+
+## Quick Reference: Common Patterns
+
+```html
+<!-- Page Header with Session Info -->
+<div class="page-header">
+  <div class="card page-maincard p-card-padding">
+    <h1 class="text-card-header">Session Details</h1>
+    <h2 class="page-session-title">My Test Session</h2>
+    <dl class="page-meta-info">
+      <dt class="label">Created:</dt>
+      <dd>Oct 21, 2025</dd>
+      <dt class="label">Status:</dt>
+      <dd class="text-white">Running</dd>
+    </dl>
+  </div>
+  <div class="page-actions">
+    <a href="#" class="btn btn-primary btn-main">
+      <span class="icon icon-test-running-xl"></span>
+      Start Test
+    </a>
+  </div>
+</div>
+
+<!-- Form Layout -->
+<form class="space-y-md">
+  <div class="form-group">
+    <label class="form-label">Field Name</label>
+    <input type="text" class="form-control" placeholder="Placeholder">
+    <div class="form-hint">Helper text</div>
+  </div>
+</form>
+
+<!-- Responsive Card Grid -->
+<div class="grid grid-cols-1 sm:grid-cols-2 lg:grid-cols-3 xl:grid-cols-4 gap-grid-gutter">
+  <!-- Cards here -->
+</div>
+
+<!-- Dark Mode Data Table -->
+<table class="table">
+  <thead>
+    <tr>
+      <th>Test Name</th>
+      <th>Status</th>
+      <th>Results</th>
+    </tr>
+  </thead>
+  <tbody>
+    <tr>
+      <td>Login Flow</td>
+      <td><span class="badge badge-success">Passed</span></td>
+      <td class="action-cell">
+        <button class="btn btn-sm btn-ghost">View</button>
+      </td>
+    </tr>
+  </tbody>
+</table>
+
+<!-- Chat Messages -->
+<div class="list-chat-messages">
+  <div class="chat-message-item">
+    <img src="avatar.jpg" class="chat-avatar" alt="User">
+    <div class="chat-header">
+      <span class="chat-author">Jane Doe</span>
+      <span>10 mins ago</span>
+    </div>
+    <div class="chat-message">
+      <p>Here's my feedback on the latest changes.</p>
+    </div>
+  </div>
+</div>
+
+<!-- Action Bar -->
+<div class="flex items-center justify-end gap-xs bg-actionbar text-white p-md">
+  <button class="btn btn-ghost-inverted">Cancel</button>
+  <button class="btn btn-primary-inverted">Confirm</button>
+</div>
+
+<!-- Empty State -->
+<div class="emptystate-message text-center py-xxl">
+  <i class="icon icon-inbox text-icon-xxl text-gray-light mb-md"></i>
+  <h3 class="text-heading-4 mb-xs">No Items Yet</h3>
+  <p class="text-sm text-gray-dark mb-md">Get started by creating your first item</p>
+  <button class="btn btn-primary">Create Item</button>
+</div>
+
+<!-- Status Stepper (NEW) -->
+<div class="status-stepper">
+  <div class="status-step completed">
+    <i class="icon icon-check-thick-centered"></i>
+    3 done
+  </div>
+  <div class="status-step active">
+    <i class="icon icon-sync"></i>
+    Executing checks
+  </div>
+  <div class="status-step">
+    + 3 to do
+  </div>
+</div>
+
+<!-- Splitview with Status (NEW) -->
+<details class="splitview-group" open>
+  <summary>Test Group</summary>
+  <div class="splitview-group-status">
+    <div class="status-stepper">
+      <div class="status-step completed">Done</div>
+      <div class="status-step active">In Progress</div>
+      <div class="status-step">Pending</div>
+    </div>
+  </div>
+  <button class="splitview-btn">Show 5 dismissed items</button>
+</details>
+```
+
+---
+
+## Design System Change Log
+
+### Version 3.12.0 - October 21, 2025
+
+**New Components:**
+- Status Stepper component for multi-step process visualization
+- Splitview status groups with `.splitview-group-status`
+- Splitview buttons with `.splitview-btn`
+
+**Enhancements:**
+- Page header responsive improvements (added `sm:col-span-2` to main card)
+- Page actions now stack at md breakpoint instead of lg (`lg:flex-col` → `md:flex-col`)
+- Better button icon visibility (changed breakpoint from lg to md for some instances)
+- List item badge vertical alignment fix (`items-start` → `items-center`)
+- List item badge padding consistency (`p-xxs pt-xs` → `px-xxs py-xxs`)
+- Splitview integration with status tracking
+- Node version specified in `.nvmrc` (v23.11.0)
+
+### Version 3.11.0 - October 20, 2025
+
+**New Components:**
+- Page Header component with responsive grid layout
+- Chart integration capability in page headers
+- Form grid layouts within page headers
+- Comprehensive chat message components
+
+**Enhancements:**
+- Dark mode support for all table variants with increased padding
+- Updated breakpoints: lg (70rem), xl (90rem), 2xl (100rem)
+- Increased border radius in dark mode: 5px → 12px
+- Larger grid gutters in dark mode: 20px → 40px
+- Improved chat component dark mode layouts (3 col → 2 col)
+- Better splitview alignment with page header grids
+- Table cell style improvements (editable, selectable cells)
+- Grid table layout for complex responsive tables
+
+**Bug Fixes:**
+- Button XL responsive behavior in page headers
+- Forms gap spacing consistency
+- Chat avatar spacing in dark mode
+- Table border styling in dark mode
+
+---
+
+**END OF REFERENCE GUIDE**