Smart Support UX Design System

This document outlines the core User Experience (UX) and User Interface (UI) design standards for the Smart Support platform. Our visual identity departs from the generic "tech cold blue/white" default, leaning into a premium, trustworthy, and organic "Warm Beige" aesthetic targeted at high-end B2B SaaS buyers.

1. Core Philosophy

Trust Through Warmth: Customer support tools need to inspire confidence. We use an organic "Rich Warm Beige" canvas paired with "Deep Slate/Walnut" typography to feel more like a premium workspace (e.g., Notion, high-end interior design) rather than a sterile terminal.
Action over Text: This is an Action Layer, not just a chatbot. Destructive or high-risk actions (refunds, cancellations) must visually "jump out" from the conversation flow via elevated cards.
Expansive Workspace: Leverage horizontal screen space. Instead of a narrow 800px ChatGPT-style centered column, our workspace flows fluidly to the edges, similar to Slack or Zendesk.

2. Color Palette (Design Tokens)

All colors are strictly mapped to CSS Variables in index.css. Do not use hardcoded hex values in components.

Backgrounds & Surfaces

Token	Hex	Usage
`App Wrapper`	`#DBD2C6`	The absolute outermost canvas (the "Dribbble presentation frame"). Visible only on large screens as a dark beige border.
`--bg-app`	`#F4EFE7`	The primary background color for the application shell and main content areas.
`--bg-surface`	`#EBE4D8`	Slightly darker beige. Used for elevated cards, the sidebar, and inputs to create depth.
`--bg-surface-inner`	`#F6F2EC`	A lighter inner container fill, often used as table headers or secondary nested boxes.
`--bg-hover`	`#E1D9CC`	Hover state backgrounds, active navigation item pills, and disabled button states.

Typography & Ink

Token	Hex	Usage
`--text-primary`	`#1C1917`	Primary text (Headings, body copy). A deep brownish-slate, entirely avoiding harsh #000000 black.
`--text-secondary`	`#5C554D`	Secondary UI text, metadata, table column headers, and timestamps.

Brand & Interactive Elements

Token	Hex	Usage
`--brand-primary`	`#3B342D`	Primary buttons, brand icons, and active UI states.
`--brand-hover`	`#26211C`	Hover states for primary interactive elements.
`--border-light`	`#D5CCC0`	Dividers, subtle borders around cards and tables.

3. Typography

Font Family: 'Inter', system-ui, -apple-system, sans-serif
Scale: We rely on sharp, structural typography rather than excess lines to create hierarchy.
- Headers (h2/h3): 700 (Bold), tight letter-spacing (-0.01em).
- Nav & Buttons: 600 (Semi-bold), 0.9375rem (15px) or 0.875rem (14px).
- Micro-text (Badges/Labels): 0.75rem (12px), uppercase, generous letter-spacing (0.05em).

4. The "Framed Window" Layout Paradigm

Rather than a UI that bleeds indefinitely to the edges of an ultrawide monitor, the Smart Support UI employs a Responsive Window Frame, while maintaining a flat visual hierarchy:

Small Screens / Mobile (< 768px): The .app-layout merges with the browser edges (100vw/100vh, 0px border-radius).
Large Screens (>= 768px): The App shrinks slightly, creating a 1.5rem (24px) margin on all sides against a slightly darker background. The app window gets a luxury 20px border-radius and a soft, diffused drop shadow.
Flat Visual Hierarchy: The Sidebar background is slightly darker (--bg-surface) than the main work area (--bg-app). They sit adjacent to each other without inner dividing boxed margins. The border line is implicitly created by the tone difference.
Content Alignment: The main app-main area does not center its content in a narrow channel. It uses full-width fluid layouts with standard left and right paddings (e.g., 3rem).

5. Component Signatures

Micro-interactions & Loading States (New)

Skeleton Loading: Never use harsh unstyled "Loading..." text strings. Utilize the .skeleton-box and .skeleton-text CSS classes which provide a smooth 1.5s pulse animation looping between --bg-hover and --border-light.
Graceful Rendering: Content blocks should be replaced fully by matching structured skeletons outlining the UI during any data fetch or mock delay.

Information Visual Hierarchy & Audit Trails (New)

Visual Noise Reduction: Do not treat all logs equally. On Audit or Timeline screens (e.g. Conversation Replay), raw system logs like Tool Calls or Intent extractions must be rendered quietly as muted, italic text without background bubbles.
Focus Highlighting: The highest visual weight in logs is reserved strictly for Human-to-AI interaction messages, Human-in-the-Loop Interventions, and critical overrides. Use distinctive background panels (e.g. pale red, soft lavender) only for these elevated actions.

The Sidebar (Nav)

Tone-on-Tone: Active navigation item pills should rely strictly on capsule background fills (--bg-hover) rather than font color switches or jarring left-bars.

Action Cards (Human-in-the-Loop)

When an agent stops to ask for human confirmation (e.g., "This refund is >$1,000"):

Isolate: It must render as a distinct UI card (.action-card), jumping out from the standard Markdown text flow.
Color Stripe: It uses a high-contrast left border (e.g., Red #DC2626 for security approvals) to signal importance.
Shadows: Elevated using box-shadow: var(--shadow-lg) to hover above the conversation.

Data Tables & Analytics

No Vertical Borders: Tables should only use horizontal lines (border-bottom) to separate rows. Vertical lines feel too rigid and clunky.
Hover Rows: Wrap standard rows in a hover transition (background-color: var(--bg-hover)) to help the eye track long data strings.
Metric Boxes: Important KPI statistics (like those on Dashboard) are housed in thick, rounded boxes (--radius-xl) to look like physical widgets.

6. CSS Best Practices for the Project

Avoid Inline Styles: All recurring UI patterns (like btn, page-header, metricsGrid) should map to CSS classes in index.css.
Use REM for Spacing/Sizing: Prefer rem over px for paddings, margins, and font sizes to ensure accessibility scaling.
Soft Shadows Only: Shadows should have high blur radiuses and low opacity. Bad: rgba(0,0,0,0.5) 0px 5px. Good: rgba(0,0,0,0.06) 0px 10px 30px.

6.5 KiB Raw Blame History