UI & App Design Guide

Implementation-specific design rules for CatWing interfaces

For core brand identity, see the Brand Identity Guide

1. Design Contexts

CatWing interfaces serve two distinct purposes, each requiring different visual treatment.

Website & Marketing

Public-facing: catwing.ai, brand guide, presentations, investor materials. Dark theme with vivid accents for impact and technical credibility.

Dark backgrounds (#0f1923)
Brand gradient headers
Vivid status colors for visual impact
Designed for brief, focused engagement

Admin Applications

Internal tools: Assortment Review, dashboards, data browsers. Light theme with muted accents for all-day comfort and readability.

Light backgrounds (#f5f7fa)
Solid color headers (no gradient)
Muted status colors to reduce eye strain
Designed for 8+ hours of daily use

Principle: Marketing should impress. Admin tools should disappear. The interface recedes so the data can speak.

2. Color Palettes by Context

The Brand Guide defines the canonical CatWing palette. Below are the context-specific adaptations for each deployment type.

Header Treatment

Global Assortment Review

Website: Brand gradient (135deg). Eye-catching, establishes identity.

Global Assortment Review

Admin: Solid CW Blue. Professional, recedes, zero visual noise.

Status Colors

Admin variants are desaturated for comfort during extended use. Zone dots remain vivid (10px — need to be scannable at a glance).

Website (vivid)

Stock / Success #4CAF50

Not-Stock / Error #D32F2F

Warning / Drift #FF9800

Info #42A5F5

Admin (muted)

Stock / Success #3d8b52

Not-Stock / Error #c85a54

Warning / Drift #c98a2d

Info #4a7fb5

Full Comparison

Property	Website	Admin
Theme	Dark	Light
Background	#0f1923	#f5f7fa
Surface	#1a2332	#ffffff
Header	Gradient (135deg)	Solid #336699
Text	#e2e8f0	#1c1c1c
Muted text	#94a3b8	#666666
Border	#2a3a4a	#dce3ed
Stock	#4CAF50	#3d8b52
Not-Stock	#D32F2F	#c85a54
Warning	#FF9800	#c98a2d
Info	#42A5F5	#4a7fb5

Background Tints (Admin)

Used for status row highlighting and product labels. Shared across both contexts.

Confirmed #E8F5E9

Drift #FFF3E0

Danger #FFEBEE

Info #E3F2FD

Launch #E8F5E9

Discontinued #ECEFF1

Old #FFEBEE

Gold #FFF8E1

CSS Custom Properties

Website Context

:root {
  --cw-bg: #0f1923;
  --cw-surface: #1a2332;
  --cw-text: #e2e8f0;
  --cw-text-muted: #94a3b8;
  --cw-border: #2a3a4a;
  --cw-header-bg: linear-gradient(135deg, #336699 0%, #20b0a5 100%);
  --status-stock: #4CAF50;
  --status-notstock: #D32F2F;
  --status-warning: #FF9800;
  --status-info: #42A5F5;
}

Admin Context

:root {
  --cw-bg: #f5f7fa;
  --cw-surface: #ffffff;
  --cw-text: #1c1c1c;
  --cw-text-muted: #666666;
  --cw-border: #dce3ed;
  --cw-header-bg: #336699;
  --status-stock: #3d8b52;
  --status-notstock: #c85a54;
  --status-warning: #c98a2d;
  --status-info: #4a7fb5;
}

8. Components

Buttons

Variant	When to Use
Primary (gradient)	Main action: Save, Confirm, Submit
Secondary (#e8edf4)	Alternative actions: Cancel, Close, Filter
Danger (#ffebee)	Destructive: Delete, Unconfirm, Reset
Locked (#999)	Supplier-discontinued products (not clickable)

Padding: 0.5rem 0.8rem · Radius: 6px · Font: 0.8rem/600 Poppins · Transition: 0.2s

Button States

State	Primary	Secondary	Danger
Default
Hover
Focus
Disabled

Input States

Default

Search products…

Focused

T-Sport

Error

-5

Quantity must be positive

Status Badges

STOCK NOT-STOCK STOCK NOT-STOCK STOCK (locked)

Solid = client status (click to toggle) · Outlined = CW recommendation (read-only) · Locked = opacity 0.5, cursor not-allowed

Product Labels

LAUNCH DISC. OLD GOLD

Padding: 1px 6px · Radius: 3px · Font: 0.65rem/700 · Responsive: full text → abbreviation on phone

Cards

1,247

TOTAL PRODUCTS

892

STOCK

355

NOT-STOCK

Form Inputs

Border: 1px solid #cdd5e0 · Radius: 6px · Focus: CW Blue border + shadow · Error: red border + shadow

Table

Product	Status	Revenue	Zone
Tissot PRX 35mm	STOCK	€12,450	A
Certina DS Action	STOCK	€8,320	B
Swatch Gent	NOT-STOCK	€1,890	D

Header: CW Blue bg, white text, sticky · Confirmed: #E8F5E9 + 4px green border · Drift: #FFF3E0 + 4px orange border

Toast Notifications

Changes saved

Failed to save changes

Loading data…

Bottom-right fixed · z-index: 1000 · Slide-up 0.3s ease-out · Undo button: 5s window · Auto-dismiss

Modal

Overlay: rgba(0,0,0,0.4) · Card: white, 10px radius, max-width 420px · z-index: 2000

Progress Bar

72% reviewed

Phase-out Bar

Phase-out:

73/100

Gradient: orange → red (linear-gradient(90deg, #FF9800, #D32F2F)) · 120px wide, 6px tall

Coverage Bar (Segmented Availability)

Product	Stock Availability	Days’ Supply
T-Sport XL		180
PRX Powermatic		9
Gentleman Quartz		3
Seastar 1000		0

Each segment = 1 week of supply · Green #4CAF50 (covered) · Orange #FF9800 (at risk) · Red #D32F2F (shortage) · 18px tall, 1px gap

9. Interaction Patterns

Keyboard Navigation

JNext product

KPrevious product

EnterToggle confirm

SToggle status

IToggle thumbnails

EscDeselect / close

Keyboard shortcuts disabled when typing in input/textarea/select fields.

Click Patterns

Action	Gesture	Timing
Select product	Single click on row	Immediate
Toggle confirm	Double click on row	200ms disambiguation
Toggle status badge	Click badge	300ms throttle (cooldown)
Expand subcollection	Click sub-row	Immediate

Optimistic Updates

Pattern: Immediate UI update → server call → reconcile on response → revert on failure + error toast. Undo toast visible for 5 seconds.

Hover Previews

Delay: 300ms before showing
Size: 200×200px product image
Positioning: Viewport-aware (avoids going off-screen)
Touch: Disabled on touch devices via @media (hover: none)

Debounced Saves

Notes textarea: 500ms debounce on input + save on blur
Filter changes: Immediate (no debounce)

Sidebar Behavior

Breakpoint	Behavior
Desktop (>768px)	Always visible, 260px fixed
Tablet (≤768px)	Hamburger button + overlay slide-in
Phone (≤480px)	Full-width slide-in

10. State Patterns

24px · 3px border · CW Blue top · 0.8s linear infinite

Empty

No products match.
Try broadening filters.

Error (inline)

Failed to load: network timeout

Success (row)

Certina DS Action — STOCK

Drift / Warning (row)

Swatch Gent — ⚠ Re-review needed

Disabled

opacity: 0.5 · cursor: not-allowed

Image Placeholder

No image

180×180px · grey bg · rounded

State Transition Rules

Never flash loading for <200ms responses. If the server responds within 200ms, skip the loading state entirely and go straight to the result.

Error tiers: Red toast (transient, auto-dismiss) → Inline red border (validation) → Modal (critical/destructive)
Success: Green toast (auto-dismiss) + row highlight (persistent)
Drift: Orange row highlight + re-review badge (persistent until confirmed)

11. Layout & Spacing

Spacing Scale

4px

8px

12px

16px

20px

24px

Base unit: 4px (0.25rem at 16px root). Application uses rem for all spacing.

Token	px	rem	Usage
xs	4px	0.25rem	Badge padding, tight gaps
sm	8px	0.5rem	Button padding, table cell spacing
md	12px	0.75rem	Card inner padding
base	16px	1rem	Section gaps, standard padding
lg	20px	1.25rem	Component spacing
xl	24px	1.5rem	Section spacing, large gaps

Border Radius Scale

4pxBadges

6pxInputs, buttons

8pxCards (default)

10pxHeaders, modals

12pxElevated cards

Shadow Scale

Standard0 2px 8px rgba(0,0,0,0.08)

Elevated0 4px 16px rgba(0,0,0,0.15)

Modal0 8px 32px rgba(0,0,0,0.15)

Z-Index Scale

Layer	Value	Usage
Base content	auto	Default stacking
Sticky header	10	Table thead
Sidebar overlay	99	Background dimmer
Sidebar	100	Mobile slide-in sidebar
Hamburger button	110	Always above sidebar
Hover preview	500	Image preview tooltip
Toast	1000	Notification toasts
Modal	2000	Confirm dialogs

App Layout

Header (gradient, 10px radius)

Content area (flex column, 1rem gap)

Responsive Breakpoints

Breakpoint	Width	Changes
Desktop	>768px	Full sidebar + content, all columns visible
Tablet	≤768px	Hamburger menu, overlay sidebar, hide Age column
Phone	≤480px	Full-width sidebar, hide Revenue/Qty/Zone, 2-line product cell

Column Progressive Disclosure

Column	Desktop	Tablet	Phone
Product	Visible	Visible	Visible (+ meta row)
Revenue	Visible	Visible	Hidden
Qty	Visible	Visible	Hidden
Age	Visible	Hidden	Hidden
Zone	Visible	Visible	Hidden
Status	Visible	Visible	Visible

“Show more, annotate less. Tables over cards. Numbers over charts. Context on demand.”

Responsive Testing Checklist

Check	Desktop >768px	Tablet ≤768px	Phone ≤480px
Sidebar	Fixed 260px, always visible	Hamburger + overlay slide	Full-width overlay
Table scroll	No overflow	Horizontal scroll if needed	Horizontal scroll, key cols only
Hover previews	300ms delay, 200×200px	Disabled	Disabled
Detail panel	Right panel 400px	Full-width modal	Full-width modal
Keyboard nav	J/K/Enter/S/Escape	Touch + swipe	Touch + swipe
Font size	14px base	14px base	14px base (no reduction)

12. Motion & Animation

Transition Durations

Duration	Use Case	Example
0.15s	Micro-interactions	Chevron rotation, button state, badge hover
0.25s	Navigation	Sidebar slide in/out, overlay fade
0.3s	Feedback	Toast slide-up, progress bar fill

Easing Functions

Function	Use
`ease-out`	Entrances (toast in, sidebar open)
`ease`	State changes (hover, focus, color transitions)
`linear`	Continuous motion (spinner rotation)

Keyframes

@keyframes toast-in {
  from { transform: translateY(20px); opacity: 0; }
  to   { transform: translateY(0); opacity: 1; }
}

@keyframes spin {
  to { transform: rotate(360deg); }
}

/* Hamburger morph: 3 bars → ✕ */
.open .hamburger::before  { transform: translateY(6px) rotate(45deg); }
.open .hamburger span     { opacity: 0; }
.open .hamburger::after   { transform: translateY(-6px) rotate(-45deg); }

Live Demos

▶ Click to rotate (0.15s)

Rule: Every animation serves a purpose. No decorative motion, no bouncing, no parallax.

UI & App Design Guide

1. Design Contexts

Website & Marketing

Admin Applications

2. Color Palettes by Context

Header Treatment

Status Colors

Website (vivid)

Admin (muted)

Full Comparison

Background Tints (Admin)

CSS Custom Properties

Website Context

Admin Context

8. Components

Buttons

Button States

Input States

Status Badges

Product Labels

Cards

Form Inputs

Table

Toast Notifications

Modal

Confirm Status Change

Progress Bar

Phase-out Bar

Coverage Bar (Segmented Availability)

9. Interaction Patterns

Keyboard Navigation

Click Patterns

Optimistic Updates

Hover Previews

Debounced Saves

Sidebar Behavior

10. State Patterns

State Transition Rules

11. Layout & Spacing

Spacing Scale

Border Radius Scale

Shadow Scale

Z-Index Scale

App Layout

Responsive Breakpoints

Column Progressive Disclosure

Responsive Testing Checklist

12. Motion & Animation

Transition Durations

Easing Functions

Keyframes

Live Demos