# Apex Admins — UI/UX Design System

**Version:** 1.0  
**Date:** 2026-06-27

---

## 1. Design Philosophy

**Style:** Modern SaaS × Premium Agency  
**References:** Stripe simplicity, Apple spacing, Linear polish  
**Avoid:** Bootstrap look, generic templates, cramped layouts, CTA spam

---

## 2. Color Tokens (Admin-Editable)

| Token | Default | Usage |
|-------|---------|-------|
| `--color-primary` | #0E9F6E | Primary buttons, links, accents |
| `--color-secondary` | #111827 | Headings, dark sections |
| `--color-accent` | #14B8A6 | Highlights, badges |
| `--color-text` | #111827 | Body text |
| `--color-muted` | #6B7280 | Secondary text, captions |
| `--color-bg` | #FFFFFF | Page background |
| `--color-section` | #F8FAFC | Alternating sections |
| `--color-border` | #E5E7EB | Cards, inputs, dividers |
| `--color-success` | #10B981 | Success states |
| `--color-warning` | #F59E0B | Warnings |
| `--color-danger` | #EF4444 | Errors, destructive |

### Gradients
```css
--gradient-primary: linear-gradient(135deg, var(--color-primary) 0%, var(--color-accent) 100%);
--gradient-dark: linear-gradient(135deg, #111827 0%, #000000 100%);
--gradient-subtle: linear-gradient(180deg, var(--color-section) 0%, var(--color-bg) 100%);
```

Injected via `SettingsService::getThemeCss()` cached in Redis, output in layout `<style>`.

---

## 3. Typography

### Font Stack
```css
--font-primary: "Segoe UI", system-ui, -apple-system, BlinkMacSystemFont, "Helvetica Neue", Arial, sans-serif;
```

Segoe UI renders on Windows; `-apple-system` / `BlinkMacSystemFont` on macOS/iOS.

### Scale (1.25 ratio)

| Token | Size | Line Height | Use |
|-------|------|-------------|-----|
| `--text-display` | 3.5rem / 2.5rem mobile | 1.1 | Hero headlines |
| `--text-h1` | 2.5rem / 2rem | 1.2 | Page titles |
| `--text-h2` | 2rem / 1.75rem | 1.25 | Section titles |
| `--text-h3` | 1.5rem | 1.3 | Card titles |
| `--text-h4` | 1.25rem | 1.4 | Subsections |
| `--text-body` | 1rem | 1.625 | Paragraphs |
| `--text-small` | 0.875rem | 1.5 | Captions, meta |
| `--text-xs` | 0.75rem | 1.5 | Labels, badges |

### Weights
- Regular: 400 (body)
- Medium: 500 (nav, buttons)
- Semibold: 600 (headings, emphasis)
- Bold: 700 (display, stats)

---

## 4. Spacing

Base unit: **4px**

| Token | Value | Use |
|-------|-------|-----|
| `--space-1` | 4px | Tight gaps |
| `--space-2` | 8px | Icon gaps |
| `--space-4` | 16px | Component padding |
| `--space-6` | 24px | Card padding |
| `--space-8` | 32px | Section gaps |
| `--space-12` | 48px | Large gaps |
| `--space-16` | 64px | Section padding mobile |
| `--space-20` | 80px | Section padding tablet |
| `--space-28` | 112px | Section padding desktop |

**Section padding:** `py-20 md:py-28 lg:py-32`  
**Container:** `max-w-7xl mx-auto px-4 md:px-6 lg:px-8`

---

## 5. Breakpoints

| Name | Min Width | Tailwind |
|------|-----------|----------|
| sm | 640px | sm: |
| md | 768px | md: |
| lg | 1024px | lg: |
| xl | 1280px | xl: |
| 2xl | 1536px | 2xl: |

Mobile-first: base styles = mobile.

---

## 6. Components

### Buttons
| Variant | Style |
|---------|-------|
| Primary | Gradient bg, white text, rounded-xl, px-6 py-3, shadow-sm hover:shadow-md |
| Secondary | Border border-primary, text-primary, hover:bg-primary/5 |
| Ghost | Text only, hover:bg-section |
| Dark | bg-secondary text-white |

### Cards
- `rounded-2xl border border-border bg-white p-6 md:p-8`
- Hover: `transition-transform hover:-translate-y-1` (GSAP optional)
- Glass (header only): `backdrop-blur-md bg-white/80 border-white/20`

### Inputs
- `rounded-xl border-border focus:ring-2 focus:ring-primary/20 focus:border-primary`
- Label above, error below in danger color

### Badges
- `rounded-full px-3 py-1 text-xs font-medium`
- Variants: primary, accent, muted, success

---

## 7. Motion

### GSAP Usage
- Counter animations on stats (ScrollTrigger)
- Section fade-up on scroll (stagger children)
- Hero text reveal (split optional, keep lightweight)

### Reduced Motion
```js
const prefersReduced = window.matchMedia('(prefers-reduced-motion: reduce)').matches;
if (prefersReduced) gsap.globalTimeline.clear();
```

### Swiper
- Testimonials, case studies, logo marquee
- `loop: true`, `autoplay: { delay: 5000 }`, pause on hover
- Pagination bullets, no navigation arrows on mobile

---

## 8. Iconography

- Custom SVG icons inline or sprite (`resources/icons.svg`)
- Heroicons-style stroke icons for UI
- No emoji in professional UI

---

## 9. Imagery

- SVG illustrations for empty states, process steps
- Photography: rounded-2xl, aspect-ratio containers
- Lazy load below fold, eager for LCP hero image

---

## 10. Page Layout Patterns

### Homepage
Full-width sections alternating `bg-white` / `bg-section`

### Inner Pages
- Hero band (gradient or image)
- Breadcrumbs
- Content max-w-4xl for prose, max-w-7xl for grids
- Sidebar CTA sticky on desktop (hire pages)

### Hire Conversion Template
1. Hero + dual CTA
2. Benefits grid
3. Social proof video/carousel
4. Process steps
5. FAQ accordion
6. Final CTA band

---

## 11. Accessibility

- Focus visible: `ring-2 ring-primary ring-offset-2`
- Skip link: "Skip to main content"
- Color contrast minimum 4.5:1 body, 3:1 large text
- Touch targets minimum 44×44px
- Form labels always associated
- ARIA on accordion, modal, mobile nav

---

## 12. Anti-Patterns

- Max 3 distinct CTA intents per page
- No autoplay video with sound
- No interstitial ads
- No stock "people shaking hands" hero clichés without brand overlay