# Amevia UI Guidelines

## Visual language

Amevia's visual language is clean, premium, and human-centered. It should feel like a flagship SaaS product — generous whitespace, soft shapes, subtle gradients, and refined typography.

**Avoid:** Generic robots, brains, circuitry, humanoid avatars, neon effects, crypto aesthetics, and cliché AI imagery.

**Prefer:** Abstract conversation flows, soft intelligence signals, connected actions, website interfaces, product discovery, and helpful UI interactions.

## Shape language

- Soft, rounded forms that echo the logo's ribbon curves
- Generous padding and breathing room
- Cards and containers with subtle borders, not heavy outlines
- Asymmetric layouts only when they improve readability — default to structured grids

## Corner radius system

| Token | Value | Usage |
|-------|-------|-------|
| `--radius-sm` | 8px | Buttons, inputs, badges |
| `--radius-md` | 12px | Cards, alerts |
| `--radius-lg` | 16px | Modals, large cards |
| `--radius-xl` | 20px | Hero cards, chat widget |
| `--radius-2xl` | 24px | Feature sections |
| `--radius-full` | 9999px | Pills, avatars, toggles |

## Spacing system

Based on a 4px grid:

| Token | Value |
|-------|-------|
| `--space-1` | 4px |
| `--space-2` | 8px |
| `--space-3` | 12px |
| `--space-4` | 16px |
| `--space-6` | 24px |
| `--space-8` | 32px |
| `--space-12` | 48px |
| `--space-16` | 64px |
| `--space-section` | 64–104px |

## Grid

- Max content width: 1200px
- 12-column grid for dashboard layouts
- Single-column for mobile (< 768px)
- Two-column for tablet (768–1024px) where appropriate

## Shadows

| Token | Usage |
|-------|-------|
| `--shadow-xs` | Subtle elevation, inputs |
| `--shadow-sm` | Cards at rest |
| `--shadow-md` | Dropdowns, popovers |
| `--shadow-lg` | Modals, chat widget |
| `--shadow-glow` | Hero accents (sparingly) |

Shadows use navy-tinted rgba, not pure black.

## Borders

- Default: 1px solid `var(--border-default)`
- Focus: 2px solid `var(--border-focus)` with offset
- Dividers: 1px solid `var(--border-subtle)`

## Gradient usage

- Brand gradient for symbol, primary CTAs, and accent highlights
- Soft gradient washes (12% opacity) for hero backgrounds and cards
- Dark gradient for contrast sections and dark-mode heroes
- Never use gradients on body text
- Keep gradients subtle and premium — no neon or harsh transitions

## Glass effects

Use sparingly:

- Sticky navigation: `backdrop-filter: blur(12px)` with 92% opacity background
- Overlays: semi-transparent navy with blur
- Do not use glass on primary content areas or form fields

## Illustration style

- Abstract flows and connected nodes (not robots or brains)
- Soft geometric shapes with brand gradient accents
- Website interface mockups as context
- Line-based diagrams for integrations and workflows
- Muted backgrounds with one or two accent colors

## Icon style

- 24px grid, 1.75px stroke weight
- Rounded line caps and joins
- Outlined default; filled for active/selected states
- Brand colors for active; `--text-secondary` for inactive
- See iconography section in the brand book

## Product screenshot style

- Clean browser chrome or device frame
- Light or dark mode matching the context
- Realistic Amevia UI, not lorem ipsum
- Subtle shadow beneath the frame
- Optional soft gradient background behind the frame

## Photography guidance

- Real people in professional, warm contexts (when used)
- Avoid stock "pointing at screen" clichés
- Prefer website/product context over abstract tech
- Apply navy overlay (60–80% opacity) when placing logo on photos
- Do not use robot, brain, or circuit board imagery

## Background patterns

- Subtle wave lines (inspired by mockup hero backgrounds)
- Soft dot grids at 5% opacity
- Gradient washes using brand soft gradient
- No busy or high-contrast patterns behind text

## Motion principles

- Restrained, purposeful animation
- Duration: 150ms (fast), 250ms (normal), 400ms (slow)
- Easing: `cubic-bezier(0.4, 0, 0.2, 1)`
- Fade and slide for modals and chat widget
- Typing indicator: gentle pulse
- Respect `prefers-reduced-motion: reduce` — disable animations

## Loading states

- Skeleton screens with `--neutral-200` / `--neutral-800` pulse
- Spinner: brand gradient arc, 24px
- Button loading: spinner replaces label, maintain button width
- Never block the entire page unless initial load

## Chat and agent visual language

- Chat widget: rounded corners (20px), soft shadow, white/dark surface
- Agent avatar: symbol on gradient or navy circle
- Message bubbles: rounded (12px), agent messages on soft gray, visitor messages on brand soft gradient
- Typing indicator: three dots with gentle pulse
- Product cards: image, title, price, action button — compact and scannable
- Suggested questions: pill buttons, outlined style
- Online status: green dot (success color) with "Online" label
- Powered-by: small, muted "Powered by Amevia" at widget footer

## Component states

Every interactive component supports:

| State | Behavior |
|-------|----------|
| Default | Resting appearance |
| Hover | Subtle background or border shift |
| Active / Pressed | Slightly darker or inset |
| Focus | Visible focus ring (2px + offset) |
| Disabled | 50% opacity, no pointer events |
| Loading | Spinner or skeleton, disabled interaction |
| Error | Red border/text with helper message |
| Success | Green confirmation with icon |

## UI components

See the interactive brand book at `/brandbook` for live component demos including:

- Header, navigation, buttons, inputs, selects, toggles
- Cards, badges, tooltips, tabs, tables
- Empty states, alerts, modals, side navigation
- Dashboard cards, analytics widgets
- Website connection, agent status, knowledge source cards
- Conversation interface, product recommendation, lead capture, integration cards
- Chat widget (collapsed, welcome, active, typing, product card, lead form, handoff, error, offline)

All components support light and dark mode via design tokens.

---

*Amevia is a product by Dioartis.*