# AMSOIL CMS Design System

_CMS and dashboard design system: colors, spacing, and component patterns. For fonts and responsive breakpoints, see [STYLING_GUIDE.md](./STYLING_GUIDE.md)._

## Overview

This style guide establishes the visual and interaction standards for the AMSOIL Dealer Lead Pages CMS dashboard. It ensures consistency across the platform while allowing dealers limited customization through color variant presets.

**Scope:** CMS Dashboard interface styling only (not dealer output pages).

---

## 1. Color System

### Primary Colors (AMSOIL Brand)

| Color            | Hex Value | Usage                                       |
| ---------------- | --------- | ------------------------------------------- |
| Primary Accent   | `#38bdf8` | CTAs, highlights, interactive states, links |
| Primary Dark     | `#003366` | Headers, primary text (when needed)         |
| Secondary Accent | `#FF6B35` | Warnings, alerts, secondary actions         |
| Accent Gold      | `#FFD700` | Success states, premium features            |

### Neutrals (UI System)

| Color          | Hex Value / RGB             | Usage                             |
| -------------- | --------------------------- | --------------------------------- |
| Background     | `#0f172a`                   | Page background, main container   |
| Surface        | `#1e293b`                   | Cards, panels, elevated surfaces  |
| Borders        | `rgba(148, 163, 184, 0.25)` | Subtle dividers, input borders    |
| Text Primary   | `#f8fafc`                   | Main content, headings            |
| Text Secondary | `rgba(203, 213, 225, 0.9)`  | Secondary content, descriptions   |
| Text Tertiary  | `rgba(148, 163, 184, 0.85)` | Labels, helper text, placeholders |

### Feedback Colors

| Status  | Hex Value | Usage                            |
| ------- | --------- | -------------------------------- |
| Success | `#34d399` | Confirmations, positive actions  |
| Error   | `#f87171` | Errors, destructive actions      |
| Warning | `#FF6B35` | Warnings, alerts, caution states |
| Info    | `#38bdf8` | Informational messages           |

### CSS Variables Implementation

Define all colors as CSS custom properties in `globals.css`:

```css
:root {
  /* Primary Colors */
  --color-primary-accent: #38bdf8;
  --color-primary-dark: #003366;
  --color-secondary-accent: #ff6b35;
  --color-accent-gold: #ffd700;

  /* Neutrals */
  --color-bg: #0f172a;
  --color-surface: #1e293b;
  --color-border: rgba(148, 163, 184, 0.25);
  --color-text-primary: #f8fafc;
  --color-text-secondary: rgba(203, 213, 225, 0.9);
  --color-text-tertiary: rgba(148, 163, 184, 0.85);

  /* Feedback */
  --color-success: #34d399;
  --color-error: #f87171;
  --color-warning: #ff6b35;
  --color-info: #38bdf8;
}

/* Dealer Theme Variants */
body[data-theme='default'] {
  /* Uses default :root colors */
}

body[data-theme='warm'] {
  --color-primary-accent: #ff6b35;
  /* Other accent colors shift warmth */
}

body[data-theme='cool'] {
  --color-primary-accent: #0ea5e9;
  /* Other accent colors shift coolness */
}
```

---

## 2. Spacing & Layout System

### Base Spacing Scale

All spacing uses 8px as the fundamental unit:

| Scale | Value | Usage                                             |
| ----- | ----- | ------------------------------------------------- |
| `xs`  | 4px   | Micro spacing (icon padding, tight gaps)          |
| `sm`  | 8px   | Small spacing (element padding, form spacing)     |
| `md`  | 16px  | Medium spacing (component gaps, field spacing)    |
| `lg`  | 24px  | Large spacing (card padding, section margins)     |
| `xl`  | 32px  | Extra large spacing (page sections, major breaks) |
| `2xl` | 48px  | Double XL (layout breaks, hero sections)          |

### Layout Grid

- **Container max-width:** `1200px` (dashboard content area)
- **Gutter:** `16px` (space between grid columns)
- **Sidebar width:** `280px` (fixed left navigation)
- **Main content:** Flexible, fills remaining space

### Common Padding

| Component     | Horizontal  | Vertical    |
| ------------- | ----------- | ----------- |
| Cards/Panels  | `lg` (24px) | `lg` (24px) |
| Form inputs   | `sm` (8px)  | `sm` (8px)  |
| Buttons       | `md` (16px) | `sm` (8px)  |
| Page sections | `xl` (32px) | `xl` (32px) |
| Modals        | `xl` (32px) | `xl` (32px) |

### Common Gaps

| Element                | Gap Size    |
| ---------------------- | ----------- |
| Form fields (vertical) | `md` (16px) |
| Component groups       | `md` (16px) |
| Layout sections        | `xl` (32px) |
| Sidebar items          | `sm` (8px)  |
| Tab content            | `md` (16px) |

### CSS Variables Implementation

```css
:root {
  /* Spacing */
  --spacing-xs: 4px;
  --spacing-sm: 8px;
  --spacing-md: 16px;
  --spacing-lg: 24px;
  --spacing-xl: 32px;
  --spacing-2xl: 48px;

  /* Layout */
  --layout-container-max-width: 1200px;
  --layout-gutter: 16px;
  --layout-sidebar-width: 280px;
}
```

---

## 3. Typography & Text Styles

### Font Stack

```css
/* Primary (body, UI) */
font-family:
  'Inter',
  system-ui,
  -apple-system,
  BlinkMacSystemFont,
  'Segoe UI',
  sans-serif;

/* Headlines (for distinction) */
font-family: 'Open Sans', 'Inter', system-ui, sans-serif;

/* Monospace (code, IDs) */
font-family: 'Monaco', 'Courier New', monospace;
```

### Text Styles Reference

| Style                   | Size | Weight | Line Height | Letter Spacing | Usage                          |
| ----------------------- | ---- | ------ | ----------- | -------------- | ------------------------------ |
| **H1 (Page Title)**     | 44px | 700    | 1.05        | -0.88px        | Dashboard page headers         |
| **H2 (Section Header)** | 32px | 600    | 1.1         | -0.64px        | Major sections, modals         |
| **H3 (Subsection)**     | 24px | 600    | 1.2         | -0.48px        | Card titles, form sections     |
| **H4 (Label/Category)** | 18px | 600    | 1.3         | -0.36px        | Form labels, component groups  |
| **Body (Regular)**      | 16px | 400    | 1.6         | normal         | Main content, descriptions     |
| **Body Small**          | 14px | 400    | 1.5         | normal         | Secondary text, helper text    |
| **Label/Caption**       | 12px | 500    | 1.4         | 0.5px          | Form labels, badges, UI labels |
| **Button Text**         | 16px | 600    | 1.4         | 0.02em         | Interactive elements           |
| **Code/Monospace**      | 13px | 400    | 1.5         | normal         | IDs, API keys, technical info  |

### Text Color Guidelines

| Text Type          | Color Value                 | CSS Variable                  |
| ------------------ | --------------------------- | ----------------------------- |
| Primary headings   | `#f8fafc`                   | `var(--color-text-primary)`   |
| Body text          | `#f8fafc`                   | `var(--color-text-primary)`   |
| Secondary text     | `rgba(203, 213, 225, 0.9)`  | `var(--color-text-secondary)` |
| Labels/Helper text | `rgba(148, 163, 184, 0.85)` | `var(--color-text-tertiary)`  |
| Links              | `#38bdf8`                   | `var(--color-primary-accent)` |

### CSS Classes Implementation

Define reusable text style classes in `globals.css`:

```css
h1 {
  font-size: 44px;
  font-weight: 700;
  line-height: 1.05;
  letter-spacing: -0.88px;
}

h2 {
  font-size: 32px;
  font-weight: 600;
  line-height: 1.1;
  letter-spacing: -0.64px;
}

h3 {
  font-size: 24px;
  font-weight: 600;
  line-height: 1.2;
  letter-spacing: -0.48px;
}

.text-body {
  font-size: 16px;
  font-weight: 400;
  line-height: 1.6;
}

.text-body-small {
  font-size: 14px;
  font-weight: 400;
  line-height: 1.5;
}

.text-label {
  font-size: 12px;
  font-weight: 500;
  line-height: 1.4;
  letter-spacing: 0.5px;
}

.text-secondary {
  color: var(--color-text-secondary);
}

.text-tertiary {
  color: var(--color-text-tertiary);
}
```

---

## 4. Component Library

### Buttons

#### Primary Button

- **Background:** `var(--color-primary-accent)` (#38bdf8)
- **Text:** `#0f172a` (Dark)
- **Padding:** `12px 24px`
- **Border radius:** `8px`
- **Font:** Button Text style (16px, weight 600)

**States:**

- **Default:** Full opacity, normal shadow
- **Hover:** `transform: translateY(-2px)`, enhanced shadow `0 16px 40px -15px rgba(14, 165, 233, 0.95)`
- **Active:** `transform: translateY(0)`, shadow `0 8px 20px -12px rgba(14, 165, 233, 0.9)`
- **Disabled:** Background `rgba(71, 85, 105, 0.4)`, text `rgba(226, 232, 240, 0.65)`, `cursor: not-allowed`

#### Secondary Button

- **Background:** `transparent`
- **Border:** `1px solid var(--color-primary-accent)`
- **Text:** `var(--color-primary-accent)` (#38bdf8)
- **Padding:** `12px 24px`
- **Border radius:** `8px`

**States:**

- **Hover:** Background `rgba(56, 189, 248, 0.1)`
- **Active:** Background `rgba(56, 189, 248, 0.2)`

#### Danger Button

- **Background:** `var(--color-error)` (#f87171)
- **Text:** `#ffffff`
- **Padding:** `12px 24px`
- **Border radius:** `8px`

**States:** Similar to Primary button, error color shadow on hover

#### Icon Button

- **Width/Height:** `40px`
- **Background:** `transparent` (default), `rgba(148, 163, 184, 0.15)` (hover)
- **Icon color:** `var(--color-primary-accent)` or contextual
- **Border radius:** `8px`
- **Hover:** Background `rgba(148, 163, 184, 0.25)`

---

### Form Inputs & Fields

#### Text Input / Textarea

- **Background:** `rgba(15, 23, 42, 0.75)`
- **Border:** `1px solid var(--color-border)`
- **Text color:** `var(--color-text-primary)` (#f8fafc)
- **Padding:** `12px 16px`
- **Border radius:** `8px`
- **Font:** Body text (16px)
- **Placeholder color:** `var(--color-text-tertiary)`

**States:**

- **Focus:** Border `rgba(56, 189, 248, 0.55)`, box-shadow `0 0 0 3px rgba(56, 189, 248, 0.15)`, outline `none`
- **Error:** Border `var(--color-error)`, box-shadow `0 0 0 3px rgba(248, 113, 113, 0.15)`
- **Disabled:** `opacity: 0.65`, `cursor: not-allowed`

#### Select Dropdown

- Same styling as text input
- Arrow icon: `var(--color-primary-accent)`
- Option highlight: `rgba(56, 189, 248, 0.2)`

#### Checkbox & Radio

- **Accent color:** `var(--color-primary-accent)`
- **Checkbox size:** `20px × 20px`
- **Radio size:** `16px × 16px`
- **Label spacing:** `8px` to the right
- **Label color:** `var(--color-text-primary)`

#### Toggle Switch

- **Background (off):** `rgba(148, 163, 184, 0.3)`
- **Background (on):** `var(--color-primary-accent)`
- **Knob:** `#ffffff`
- **Size:** `48px × 28px`
- **Transition:** `background 0.2s ease`

---

### Cards & Panels

#### Standard Card

- **Background:** `rgba(15, 23, 42, 0.75)` or `rgba(30, 41, 59, 0.6)`
- **Border:** `1px solid var(--color-border)`
- **Border radius:** `20px`
- **Padding:** `var(--spacing-lg)` (24px)
- **Box shadow:** `0 30px 50px -40px rgba(8, 47, 73, 0.8)`

#### Highlighted Card (Featured, Selected)

- **Border color:** `var(--color-primary-accent)` (#38bdf8)
- **Box shadow:** `0 35px 60px -35px rgba(14, 165, 233, 0.8)`

#### Surface Panel (Lighter background)

- **Background:** `rgba(30, 41, 59, 0.6)`
- **Border:** `1px solid rgba(148, 163, 184, 0.2)`
- **Border radius:** `16px`
- **Padding:** `var(--spacing-lg)` (24px)

---

### Badges & Labels

#### Standard Badge

- **Background:** `rgba(56, 189, 248, 0.16)`
- **Border:** `1px solid rgba(56, 189, 248, 0.35)`
- **Text color:** `var(--color-primary-accent)` (#38bdf8)
- **Padding:** `var(--spacing-xs) var(--spacing-md)` (4px 12px)
- **Border radius:** `999px`
- **Font:** Label/Caption (12px, weight 600)

#### Badge Variants

**Success Badge**

- **Background:** `rgba(52, 211, 153, 0.16)`
- **Border:** `rgba(52, 211, 153, 0.35)`
- **Text:** `var(--color-success)` (#34d399)

**Error Badge**

- **Background:** `rgba(248, 113, 113, 0.16)`
- **Border:** `rgba(248, 113, 113, 0.35)`
- **Text:** `var(--color-error)` (#f87171)

**Warning Badge**

- **Background:** `rgba(255, 107, 53, 0.16)`
- **Border:** `rgba(255, 107, 53, 0.35)`
- **Text:** `var(--color-warning)` (#FF6B35)

---

### Modals & Dialogs

#### Modal Container

- **Overlay background:** `rgba(0, 0, 0, 0.5)` (semi-transparent, fixed position)
- **Modal background:** `rgba(30, 41, 59, 0.95)`
- **Border:** `1px solid var(--color-border)`
- **Border radius:** `24px`
- **Padding:** `var(--spacing-xl)` (32px)
- **Box shadow:** `0 40px 60px -40px rgba(15, 23, 42, 0.8)`
- **Max width:** `600px` (standard), `800px` (wide)
- **Z-index:** `1000`

#### Modal Header

- **Title style:** H2
- **Close button:** Icon button, positioned top-right
- **Divider:** `1px solid rgba(148, 163, 184, 0.15)` below header
- **Padding bottom:** `var(--spacing-lg)` (24px)

#### Modal Body

- **Padding:** `var(--spacing-lg)` (24px) top
- **Color:** `var(--color-text-primary)`

#### Modal Footer

- **Button alignment:** Right-aligned
- **Gap between buttons:** `var(--spacing-sm)` (8px)
- **Padding top:** `var(--spacing-lg)` (24px)
- **Border top:** `1px solid rgba(148, 163, 184, 0.15)`

---

### Alerts & Toasts

#### Alert Box

- **Padding:** `var(--spacing-md)` (16px)
- **Border radius:** `12px`
- **Border left:** `4px solid` (color matches alert type)
- **Background:** Semi-transparent variant of alert color

#### Alert Types

**Info Alert**

- **Border color:** `var(--color-info)` (#38bdf8)
- **Background:** `rgba(56, 189, 248, 0.1)`
- **Text:** `#e0f2fe`

**Success Alert**

- **Border color:** `var(--color-success)` (#34d399)
- **Background:** `rgba(52, 211, 153, 0.1)`
- **Text:** `#d1fae5`

**Warning Alert**

- **Border color:** `var(--color-warning)` (#FF6B35)
- **Background:** `rgba(255, 107, 53, 0.1)`
- **Text:** `#ffedd5`

**Error Alert**

- **Border color:** `var(--color-error)` (#f87171)
- **Background:** `rgba(248, 113, 113, 0.1)`
- **Text:** `#fee2e2`

#### Toast (Notification)

- **Styling:** Same as alerts
- **Position:** Bottom-right corner
- **Auto-dismiss:** 4-5 seconds
- **Animation:** Slide in from bottom-right, slide out upward
- **Z-index:** `999` (below modals)

---

### Tabs

#### Tab Container

- **Background:** `transparent`
- **Border bottom:** `1px solid var(--color-border)`
- **Display:** `flex`
- **Gap:** `0` (tabs are adjacent)

#### Tab Button (Inactive)

- **Background:** `transparent`
- **Text color:** `var(--color-text-tertiary)`
- **Padding:** `var(--spacing-md) var(--spacing-lg)` (12px 20px)
- **Border bottom:** `3px solid transparent`
- **Font:** Button Text (16px, weight 500)
- **Cursor:** `pointer`

**States:**

- **Hover:** Text `var(--color-text-primary)`, background `rgba(148, 163, 184, 0.05)`
- **Active (via .active class):** See below

#### Tab Button (Active)

- **Background:** `transparent`
- **Text color:** `var(--color-primary-accent)` (#38bdf8)
- **Border bottom:** `3px solid var(--color-primary-accent)`
- **Padding:** `var(--spacing-md) var(--spacing-lg)` (12px 20px)
- **Font weight:** `600`

#### Tab Content Panel

- **Padding:** `var(--spacing-lg)` (24px) top
- **Display:** `none` (hidden by default)
- **Opacity transition:** `0.2s ease` on show
- **Show with .active class:** `display: block`, `opacity: 1`

---

### Breadcrumbs

#### Breadcrumb Container

- **Display:** `flex`
- **Align items:** `center`
- **Gap:** `var(--spacing-xs)` (8px)
- **Padding:** `var(--spacing-md) 0` (12px vertical, 0 horizontal)
- **Font size:** `14px`
- **Color:** `var(--color-text-tertiary)`

#### Breadcrumb Link (Clickable Item)

- **Text color:** `var(--color-primary-accent)` (#38bdf8)
- **Padding:** `var(--spacing-xs) var(--spacing-sm)` (4px 8px)
- **Border radius:** `6px`
- **Cursor:** `pointer`
- **Text decoration:** `none`

**States:**

- **Hover:** Background `rgba(56, 189, 248, 0.1)`, text `var(--color-primary-accent)`
- **Active/Current:** Text `var(--color-text-tertiary)`, cursor `default`, no hover effect

#### Breadcrumb Separator

- **Text:** `/` or `>`
- **Color:** `rgba(148, 163, 184, 0.5)`
- **Margin:** `0 var(--spacing-xs)` (0 4px)
- **Font size:** `12px`

**Example Structure:**

```
Dashboard / Slider Editor / Edit Slide 3
```

Where:

- "Dashboard" = clickable link
- "Slider Editor" = clickable link
- "Edit Slide 3" = current page (non-interactive, muted color)

---

## 5. Dealer Theme Customization

### Color Variant Presets

Dealers can choose from pre-defined color schemes for their published pages. The CMS dashboard always uses the default AMSOIL brand colors.

#### Theme: Default (AMSOIL Brand)

- Primary Accent: `#38bdf8` (Cyan)
- Secondary: `#FF6B35` (Orange)
- Accent: `#FFD700` (Gold)

#### Theme: Warm

- Primary Accent: `#FF6B35` (Orange)
- Secondary: `#FFD700` (Gold)
- Accent: `#ff9800` (Warm Orange)

#### Theme: Cool

- Primary Accent: `#0ea5e9` (Sky Blue)
- Secondary: `#38bdf8` (Cyan)
- Accent: `#06b6d4` (Teal)

### Implementation

Theme switching occurs at the page level when dealers preview/publish their pages:

```html
<!-- Default (Dashboard) -->
<body>
  <!-- Uses :root colors -->
</body>

<!-- Dealer Page with Warm Theme -->
<body data-theme="warm">
  <!-- Uses warm color overrides -->
</body>
```

---

## 6. Accessibility & Best Practices

### Color Contrast

- All text meets WCAG AA standards (4.5:1 for normal text, 3:1 for large text)
- Never rely on color alone to convey information (use icons, patterns, text)

### Focus States

- All interactive elements have visible focus states (outline or highlight)
- Focus outline: `2px solid var(--color-primary-accent)` with `2px` offset
- Keyboard navigation fully supported

### Motion & Animation

- Animations should respect `prefers-reduced-motion` media query
- Use `transition` for state changes (max 200-300ms)
- Avoid auto-playing animations

### Responsive Design

- Mobile-first approach
- Breakpoints:
  - Small: `640px`
  - Medium: `768px`
  - Large: `1024px`
  - XL: `1280px`

---

## 7. File Organization

### CSS Structure

```
/app
  /styles
    globals.css          # All CSS variables, base styles, utility classes
    components/
      Button.module.css
      Input.module.css
      Card.module.css
      Modal.module.css
      Badge.module.css
      Tabs.module.css
      Breadcrumbs.module.css
```

### Usage in Components

```typescript
// Import both globals (for CSS variables) and component-specific module
import '@/app/styles/globals.css'
import styles from '@/app/styles/components/Button.module.css'

export function Button({ variant = 'primary', ...props }) {
  return (
    <button className={styles[`button--${variant}`]} {...props} />
  )
}
```

---

## 8. Implementation Checklist

- [ ] CSS variables added to `globals.css`
- [ ] Base typography styles defined
- [ ] Component CSS modules created
- [ ] Button component built and tested
- [ ] Form input component built and tested
- [ ] Card/Panel components built and tested
- [ ] Badge component built and tested
- [ ] Modal component built and tested
- [ ] Alert/Toast system implemented
- [ ] Tabs component built and tested
- [ ] Breadcrumbs component built and tested
- [ ] Theme color variants working
- [ ] Accessibility testing completed
- [ ] Responsive design verified across breakpoints
- [ ] Cross-browser testing completed

---

## 9. References & Resources

- Color palette: See Section 1 (Color System)
- Spacing scale: See Section 2 (Spacing & Layout System)
- Typography: See Section 3 (Typography & Text Styles)
- Component specs: See Section 4 (Component Library)
- Theme customization: See Section 5 (Dealer Theme Customization)

---

**Last Updated:** 2025-11-07
**Status:** Design Complete - Ready for Implementation