v1.2

Color System

Our color palette defines the visual identity of Andiron. Use CSS variables for consistency.

Brand Colors

Aa
Accent (Lime)
#C7F027
--accent
Aa
Secondary (Navy)
#152332
--bg-sidebar
Aa
Accent Soft
#f8ffbf
--accent-soft

Backgrounds

Aa
App Background
#f3f4f6
--bg-app
Aa
Surface
#ffffff
--bg-surface
Aa
Surface Soft
#f9fafb
--bg-surface-soft
Aa
Sidebar
#05060b
--bg-sidebar

Text Colors

Aa
Text Main
#111827
--text-main
Aa
Text Muted
#6b7280
--text-muted
Aa
Text on Dark
#f9fafb
--text-on-dark
Aa
Text on Accent
#0f172a
--text-on-accent

Status Colors

Aa
Success
#22c55e
--color-success
Aa
Error
#ef4444
--color-error
Aa
Warning
#f97316
--color-warning
Aa
Info
#3b82f6
--color-info

Extended Palette

Aa
Purple
#8b5cf6
Aa
Cyan
#06b6d4
Aa
Pink
#ec4899
Aa
Yellow
#eab308

Typography

Manrope is our primary typeface, providing excellent readability across all sizes.

Display
26px / 900 / 1.1
$1,234,567
Heading 1
22px / 600 / 1.2
Dashboard Overview
Heading 2
20px / 600 / 1.25
Sales Performance
Heading 3
18px / 600 / 1.3
Monthly Revenue
Heading 4
16px / 600 / 1.4
Top Products
Body
15px / 400 / 1.5
The quick brown fox jumps over the lazy dog. This is the primary body text style.
Body Small
14px / 400 / 1.5
Secondary body text for less prominent content and descriptions.
Caption
13px / 500 / 1.4
Labels, timestamps, and helper text
Micro
11px / 600 / 1.3
Tags · Badges · Metadata

Font Stack

CSS
--font-sans: 'Manrope', system-ui, -apple-system, BlinkMacSystemFont,
  'SF Pro Text', 'Segoe UI', sans-serif;

Iconography

We use Font Awesome 6 as our primary icon library, with custom hover icons for key interactions.

Icon Library

Package: @fortawesome/react-fontawesome + @fortawesome/free-solid-svg-icons

Navigation & UI Icons

faTimes
faChevronDown
faChevronRight
faCog
faSearch
faEllipsisV

Status & Feedback Icons

faCheckCircle
faExclamationTriangle
faExclamationCircle
faSpinner
faCheck

Data & Analytics Icons

faDollarSign
faBoxes
faReceipt
faChartLine
faArrowUp
faArrowDown

Action Icons

faPlus
faTrash
faEdit
faDownload
faShareNodes
faWandMagicSparkles
faLightbulb

Icon Sizing

Context Size Example
Inline with text 12-13px Completed
Buttons 14-16px
Card headers 16-18px
Feature icons 20-24px
Empty states 32-48px

Custom Hover Icons (Andi Icons)

Located in src/components/icons/hover/. These are custom SVG icons with micro-interactions on hover.

Component Animation Usage
MenuHoverIconLines shiftHamburger menu
CloseHoverIconRotates 90°Close buttons
BellHoverIconRingsNotifications
SearchHoverIconSparkle revealsSearch inputs
SendHoverIconPlane fliesChat send
DownloadHoverIconArrow dropsDownload buttons
SettingsHoverIconRotatesSettings gear
TSX
import { MenuHoverIcon } from '@/components/icons/hover';

// Wrap parent in group class for hover trigger
<button className="group">
  <MenuHoverIcon width={16} height={16} />
</button>

Spacing & Layout

Consistent spacing creates visual rhythm. We use an 8px base scale.

xs
4px
sm
8px
md
16px
lg
24px
xl
32px
2xl
48px

Common Padding Patterns

Component Padding
Modal header24px horizontal, 24px top, 18px bottom
Modal body24px horizontal, 28px bottom
Card20px (or 16px compact)
Button (primary)10px 20px
Button (small)8px 16px
Input12px 14px
Table cell10px 12px

Border Radius

Rounded corners add softness and friendliness to our UI.

0
none
0px
4
sm
4px
8
md
8px
10
lg
10px
12
xl
12px
16
2xl
16px
28
4xl
28px
full
9999px

Component-Specific Radii

Component Border Radius Tailwind
Modals (center)16pxrounded-2xl
Blade/Drawer panels28pxrounded-l-[28px]
Cards12pxrounded-xl
Buttons (primary)9999pxrounded-full
Buttons (secondary)10pxrounded-[10px]
Inputs10pxrounded-[10px]
Tags/Badges9999pxrounded-full
Tables12pxrounded-xl

Shadows & Elevation

Shadows create depth and hierarchy in our interface.

None
none
Subtle
0 2px 6px rgba(0,0,0,0.08)
Medium
0 4px 12px rgba(0,0,0,0.12)
Elevated
0 8px 20px rgba(15,23,42,0.05)
Modal
0 28px 48px rgba(15,23,42,0.16)

Buttons

Buttons are used for actions. Choose the right variant for the context.

Primary Button

Use for primary actions. One per section max.

HTML
<button class="btn btn-primary">Save Changes</button>
<button class="btn btn-primary btn-sm">Small</button>
<button class="btn btn-primary" disabled>Disabled</button>

Secondary Button

Use for secondary actions alongside primary buttons.

Ghost Button

Use for tertiary actions or in dense UIs.

Icon Button

Use for icon-only actions. Always add aria-label.

Inputs

Form inputs with consistent styling and focus states.

Standard Input

Dark Theme Input

CSS
.input {
  padding: 12px 14px;
  font-size: 15px;
  background: var(--bg-surface-soft);
  border: 1px solid rgba(148, 163, 184, 0.35);
  border-radius: 10px;
  transition: all 200ms;
}

.input:focus {
  border-color: #2563eb;
  background: #ffffff;
  box-shadow: 0 0 0 3px rgba(37, 99, 235, 0.12);
}

Cards

Cards group related content with subtle elevation.

Standard Card

Hover to see the lift effect. Cards have 12px radius and subtle shadow.

Revenue

12%
$45,231

vs last month

Info Panel

Tip: Use info panels for contextual help.

Modals & Blades

Modals appear centered with backdrop; Blades slide in from the right edge for detail views.

Modal Types

Type Width Border Radius Use Case
Center Modalmin(560px, 90vw)16pxConfirmations, forms, settings
Blade Panelmin(720px, 94vw)28px leftDetail views, task panels
Wide Blademin(960px, 94vw)28px leftComplex editors, large forms

Blade Anatomy

Task Details

Description text here

Active
Content area...
Sample content card
Click backdrop to close

Blade Styling

Tailwind
/* Blade Panel */
w-[min(720px,94vw)]
bg-bg-surface
border-l border-border-soft
rounded-l-[28px]
shadow-[-20px_0_44px_rgba(12,18,30,0.35)]
animate-[slideIn_0.22s_ease-out]

/* Mobile: Full width, no radius */
max-[640px]:w-full
max-[640px]:rounded-none

Backdrop Overlay

Tailwind
/* Blade overlay - darker */
bg-black/50

/* Modal overlay - lighter */
bg-slate-900/30 backdrop-blur-sm

Modal UX Requirements

Close on Escape key press
Close on backdrop click (stopPropagation on panel)
Trap focus within modal
Set role="dialog" aria-modal="true"
Return focus to trigger on close

Badges & Tags

Use badges for status indicators and tags for categorization.

Status Badges

Complete Pending Failed Info Premium New

Tags

Default Tag Category Electronics Home & Garden

Accordions

Collapsible panels for settings, filters, and grouped content. Use for progressive disclosure.

Single-Panel Accordion

Use for settings sections, FAQs, and grouped form fields. Chevron rotates on expand. Include aria-expanded and aria-label for accessibility.

Configure how you receive notifications. You can toggle email digests, push alerts, and in-app reminders.

Component
<!-- Use src/components/settings/Accordion.tsx -->
<Accordion title="Section title" defaultOpen={false} description="Optional subtext">
  {children}
</Accordion>

Filter Accordion

Use for workspace filters (date range, dimensions, metrics). Summary shows active filter state; panel contains filter controls.

Date range
Metrics
Component
<!-- Use WorkspaceFiltersAccordion -->
<WorkspaceFiltersAccordion
  title="Filters"
  summary="Last 30 days · 3 metrics"
  sections={filterSections}
  defaultOpen={false}
/>

Accordion UX Guidelines

Use button or summary as trigger; ensure aria-expanded and aria-label
Chevron rotates 90° (right→down) or 180° on expand
Avoid nesting accordions more than 2 levels; consider tabs for deeply nested content

Workflow Steps

Steppers and step lists for onboarding, wizards, integrations, and campaign phase displays.

Horizontal Stepper

Use for multi-step forms (signup, onboarding, task creation). Connect steps with a line; current step uses accent; completed steps show checkmark.

Account
2
Details
3
Review
States
/* States: .completed, .active, (default = upcoming) */
.ds-stepper-item.completed .ds-stepper-dot { /* checkmark, green */ }
.ds-stepper-item.active .ds-stepper-dot { /* accent, current */ }
/* Connector line turns accent when preceding step completed */

Vertical Step List (Sidebar)

Use in wizards (e.g. SignupWizard) as a clickable sidebar. Current step highlighted with accent.

1
Connect your stores
Link Amazon, Shopify, or other channels
2
Add your brands
Create brands and assign to entities
3
Invite team
Add members and set permissions

Phase Accordion (Campaign / Workflow)

Use for campaign phases and workflow steps (e.g. CampaignDetailScreen). Each phase is an accordion; steps nest inside.

Research phase
Keyword discovery
Owner: Andi · Tools: Helium 10
Competitor scan
Owner: Andi · Tools: Jungle Scout
Plan phase
Component
<!-- WhitelabelChatApp: AccordionItem -->
<AccordionItem title="Phase name" isPhase={true}>
  {phase.steps.map(step => <StepRow key={step.id} {...step} />)}
</AccordionItem>

Workflow Steps UX Guidelines

Make steps clickable (where allowed) for non-linear navigation
Show progress: completed (checkmark), current (accent), upcoming (muted)
Avoid more than 7 steps in horizontal steppers; use vertical list for longer flows

Toggle Switch

Toggle switches for binary on/off settings.

Email notifications
Dark mode
Auto-sync

Loading States

Provide visual feedback during async operations to reduce perceived wait time.

Loading Spinner

Use for quick operations (< 3 seconds).

CSS
.spinner {
  width: 28px;
  height: 28px;
  border: 3px solid var(--border-soft);
  border-top-color: var(--accent);
  border-radius: 50%;
  animation: spin 0.6s linear infinite;
}

Skeleton Loader

Use when loading structured content (cards, lists, tables).

CSS
.skeleton {
  background: linear-gradient(90deg, 
    var(--bg-surface-soft) 0%, 
    var(--bg-surface) 50%, 
    var(--bg-surface-soft) 100%);
  background-size: 200% 100%;
  animation: shimmer 1.5s ease-in-out infinite;
  border-radius: 4px;
}

@keyframes shimmer {
  0% { background-position: -200% 0; }
  100% { background-position: 200% 0; }
}

Button Loading State

Loading UX Guidelines

Use spinners for operations < 3 seconds
Use skeletons when content structure is known
Always set aria-label="Loading" on spinner containers
Don't show loaders for operations < 200ms

Empty States

Guide users when there's no data to display with helpful messaging and actions.

Standard Empty State

No items to display

Rich Empty State (with Action)

No projects yet

Create your first project to start organizing your work.

Copy Guidelines

Element Guidelines
IconRelated to content type (inbox, folder, chart, etc.)
TitleDescribe what's missing ("No products", "No results")
DescriptionExplain why it's empty or how to fix it
ActionPrimary action to create/add content (optional)

Error Handling

Gracefully handle errors with clear messaging and recovery options.

Inline Error

Use below form fields or in small UI areas.

Please enter a valid email address

Error Card

Use for section-level or page-level errors.

Something went wrong

We couldn't load your data. Please try again.

Error UX Guidelines

Use human-readable language, not error codes
Always provide a recovery action (retry, go back, contact support)
Keep partial data visible when possible
Don't blame the user ("You made an error")

Toast Notifications

Non-blocking, ephemeral messages for system feedback and confirmations.

Toast Types

Changes saved successfully
Failed to save changes
New features are available

Toast Styling

CSS
.toast {
  min-width: 260px;
  max-width: 360px;
  padding: 10px 12px;
  border-radius: 10px;
  background: var(--bg-surface);
  border: 1px solid var(--border-soft);
  box-shadow: 0 10px 30px rgba(15, 23, 42, 0.35);
  font-size: 13px;
}

.toast.success { border-color: #16a34a; }
.toast.error { border-color: #dc2626; }
.toast.info { border-color: #2563eb; }

Toast UX Guidelines

Rule Details
PositionBottom-right on desktop, top-center on mobile
DurationSuccess: 3s, Error: 5s (or until dismissed)
DismissalAuto-dismiss or click to close
StackingStack newest on top, max 3 visible

Form Validation

Validate input as users type and on submission for immediate feedback.

Validation Timing

Event Behavior
On blurValidate when field loses focus (first touch)
On changeRe-validate on change after first error shown
On submitValidate all fields, focus first error

Validation States

This field is required

Looks good!

Error Message Placement

HTML
<div class="input-group">
  <label class="input-label">Email</label>
  <input 
    type="email" 
    class="input input--error"
    aria-invalid="true"
    aria-describedby="email-error"
  />
  <p id="email-error" class="field-error">
    Please enter a valid email
  </p>
</div>

Button States During Submission

Left: Ready | Center: Submitting | Right: Disabled (invalid form)

Animations

Consistent motion creates a polished, responsive feel.

Timing & Easing

Type Duration Easing Usage
Fast100mseaseButton press feedback
Normal180-200msease-outHovers, color transitions
Smooth220msease-outModals, panels
Slow300msease-in-outComplex transitions

Animation Previews

fadeIn
fadeInUp
pulse
spin
shimmer

Accessibility (WCAG 2.2 AA)

All components must meet WCAG 2.2 Level AA standards.

Color Contrast Requirements

Element Type Minimum Ratio
Normal text (< 18px)4.5:1
Large text (≥ 18px or 14px bold)3:1
UI components3:1

Critical Rules

NEVER use white text on green backgrounds
NEVER use white icons on green backgrounds
NEVER use green text on light backgrounds
ALWAYS use dark text (#1a1a1a) on green/accent backgrounds
ALWAYS verify contrast at WebAIM Contrast Checker

Contrast Examples

✓ CORRECT
Dark text on green
✗ WRONG
White text on green

Focus States

All interactive elements must have visible focus indicators:

CSS
.focusable:focus-visible {
  outline: none;
  box-shadow: 0 0 0 2px var(--accent), 
              0 0 0 4px rgba(199, 240, 39, 0.3);
}

Keyboard Navigation

All functionality must be operable via keyboard.

Focus Management Rules

Trap focus within modals/dialogs while open
Return focus to trigger element when modal closes
Use logical tab order (visual order = DOM order)
Ensure skip links for main content

Focus Trap Pattern

JavaScript
// Escape key handler for modals
useEffect(() => {
  const handleEscape = (e) => {
    if (e.key === 'Escape') onClose();
  };
  document.addEventListener('keydown', handleEscape);
  return () => document.removeEventListener('keydown', handleEscape);
}, [onClose]);

Standard Keyboard Shortcuts

Key Action
TabMove focus forward
Shift + TabMove focus backward
Enter / SpaceActivate focused element
EscapeClose modal/dropdown/popover
Arrow keysNavigate within components (menus, tabs)

Responsive Breakpoints

Mobile-first breakpoints for responsive design.

Token Width Usage
xs480pxSmall phones
sm600pxLarge phones / small tablets
md768pxTablets
lg960pxSmall desktops
xl1280pxLarge desktops

Media Query Patterns

CSS
/* Mobile-first (min-width) */
@media (min-width: 768px) { /* md and up */ }
@media (min-width: 960px) { /* lg and up */ }

/* Desktop-first (max-width) */
@media (max-width: 767px) { /* below md */ }
@media (max-width: 639px) { /* mobile only */ }

Tailwind Examples

HTML
<!-- Mobile: full width, Desktop: 1/3 width -->
<div class="w-full md:w-1/3">

<!-- Hide on mobile -->
<div class="hidden md:block">

<!-- Mobile-only -->
<div class="block md:hidden">

CSS Variables Reference

Complete list of CSS custom properties for theming.

CSS
:root {
  /* Layout */
  --left-width: 260px;
  --right-width: 360px;
  --divider-width: 10px;
  --min-panel-width: 180px;

  /* Backgrounds */
  --bg-app: #f3f4f6;
  --bg-sidebar: #05060b;
  --bg-surface: #ffffff;
  --bg-surface-soft: #f9fafb;

  /* Borders */
  --border-soft: #e5e7eb;
  --border-strong: #111827;

  /* Accent */
  --accent: #C7F027;
  --accent-soft: #f8ffbf;

  /* Text */
  --text-main: #111827;
  --text-muted: #6b7280;
  --text-on-dark: #f9fafb;
  --text-on-accent: #0f172a;

  /* Status */
  --color-success: #22c55e;
  --color-error: #ef4444;
  --color-warning: #f97316;
  --color-info: #3b82f6;

  /* Font */
  --font-sans: 'Manrope', system-ui, -apple-system, 
    BlinkMacSystemFont, 'SF Pro Text', 'Segoe UI', sans-serif;
}