# Soft UI Dashboard Tailwind Design System

## Overview
- **Source project**: soft-ui-dashboard-tailwind
- **Styling approach**: Tailwind CSS utility-first (JIT mode) with extensive custom theme, soft shadows, gradient accents, and a frosted glass aesthetic
- **Key dependencies**: tailwindcss (JIT), @popperjs/core, Font Awesome, Nucleo Icons, custom soft-ui CSS
- **Color mode**: both (dark mode via `class` strategy)

## Visual Tokens

### Colors
Custom palette replacing Tailwind defaults — based on Bootstrap-inspired naming with custom values.

| Token | Value | Usage |
|-------|-------|-------|
| slate-700 | #344767 | Primary dark text, headings |
| slate-800 | #3a416f | Sidebar gradient end |
| cyan-500 | #17c1e8 | Primary action, info |
| purple-700 | #7928ca | Gradient accent (from) |
| pink-500 | #ff0080 | Gradient accent (to) |
| fuchsia-500 | #cb0c9f | Online builder button |
| green-600 | #17ad37 | Success |
| lime-500 | #82d616 | Success alternative |
| red-600 | #ea0606 | Error/danger |
| amber-500 | #f59e0b | Warning |
| gray-50 | #f8f9fa | Page background |
| gray-100 | #ebeff4 | Card backgrounds |
| gray-800 | #252f40 | Dark backgrounds |
| blue-600 | #2152ff | Blue accent |

### Typography
| Token | Value |
|-------|-------|
| Font (sans) | Open Sans, sans-serif |
| Font (body) | Roboto, sans-serif |
| size-xs | 0.75rem |
| size-sm | 0.875rem |
| size-base | 1rem |
| size-lg | 1.125rem |
| size-xl | 1.25rem |
| weight-normal | 400 |
| weight-semibold | 600 |
| weight-bold | 700 |

### Spacing
Custom extended scale (px-based fractions). Key values: my-4 ml-4 (sidebar offset), px-8 py-6 (card header), px-4 py-2.7 (sidebar nav items).

### Shadows
| Token | Value |
|-------|-------|
| soft-sm | 0 .25rem .375rem -.0625rem hsla(0,0%,8%,.12),0 .125rem .25rem -.0625rem hsla(0,0%,8%,.07) |
| soft-md | 0 4px 7px -1px rgba(0,0,0,.11),0 2px 4px -1px rgba(0,0,0,.07) |
| soft-lg | 0 2px 12px 0 rgba(0,0,0,.16) |
| soft-xl | 0 20px 27px 0 rgba(0,0,0,0.05) |
| soft-2xl | 0 .3125rem .625rem 0 rgba(0,0,0,.12) |

### Borders
| Token | Value |
|-------|-------|
| rounded-lg | 0.5rem |
| rounded-xl | 0.75rem |
| rounded-2xl | 1rem |
| rounded-full | 9999px |
| border-default | 1px |

## Component CSS Classes

All component classes are defined via `@layer components` in `src/styles/main.css`. Use these instead of repeating raw utility strings.

### Card
```html
<!-- base card -->
<div class="card">
  <!-- optional: card-header and card-body -->
  <div class="card-header">
    <h6>Title</h6>
    <p class="text-sm leading-normal">Subtitle</p>
  </div>
  <div class="card-body">...</div>
</div>

<!-- card without border (most content cards) -->
<div class="card border-0">...</div>

<!-- stat card (uses p-4 not card-body) -->
<div class="card">
  <div class="flex-auto p-4">...</div>
</div>
```

### Button
Add display (`inline-block` / `inline-flex`) and sizing (`px-* py-* w-*`) as utilities alongside the button class.
```html
<!-- primary gradient CTA -->
<button class="inline-block px-6 py-3 btn-primary">Save</button>

<!-- full-width primary (login) -->
<button class="inline-block w-full px-6 py-3 btn-primary">Sign In</button>

<!-- white/solid (OAuth, secondary) -->
<a class="inline-flex items-center justify-center w-full px-6 py-2.5 btn-white">
  <i class="fab fa-github mr-2"></i> Sign in with GitHub
</a>

<!-- fuchsia outlined -->
<button class="inline-block px-8 py-2 btn-outlined">Cancel</button>
```

### Form
```html
<label class="form-label">Field Name</label>
<input type="text" class="form-input" placeholder="..." />
```
Note: `form-input` already includes `block w-full` — do not add them again.

### Sidebar nav
```html
<a :class="['nav-item', isActive ? 'nav-item-active' : 'nav-item-inactive']">
  <div :class="['nav-icon', isActive ? 'nav-icon-active' : 'nav-icon-inactive']">
    <i class="fas fa-tachometer-alt text-sm" :class="isActive ? 'text-white' : 'text-slate-700'"></i>
  </div>
  Label
</a>
```

### Navbar / Sidebar (structural)
**Sidebar wrapper**: `max-w-62.5 ease-nav-brand z-990 fixed inset-y-0 my-4 ml-4 block w-full flex-wrap items-center justify-between overflow-y-auto rounded-2xl border-0 bg-white p-0 antialiased shadow-none transition-transform duration-200 xl:left-0 xl:translate-x-0 xl:bg-transparent`
**Navbar wrapper**: `relative flex flex-wrap items-center justify-between px-0 py-2 mx-6 transition-all shadow-none duration-250 ease-soft-in rounded-2xl lg:flex-nowrap`
**Responsive**: Sidebar off-screen on mobile (`-translate-x-full`), visible at xl (`xl:translate-x-0`); main content offset `xl:ml-68.5`

### Search input (navbar — specialized, not form-input)
```
pl-8.75 text-sm focus:shadow-soft-primary-outline ease-soft w-1/100 leading-5.6 relative -ml-px block min-w-0 flex-auto rounded-lg border border-solid border-gray-300 bg-white bg-clip-padding py-2 pr-3 text-gray-700 transition-all placeholder:text-gray-500 focus:border-fuchsia-300 focus:outline-none focus:transition-shadow
```

## Layout & Grid
- **Container**: container center:true padding:1.5rem with custom max-widths (sm:540px md:720px lg:960px xl:1140px 2xl:1320px)
- **Grid**: 12-column grid, custom fractional widths
- **Breakpoints**: sm:576px, md:768px, lg:992px, xl:1200px, 2xl:1320px (Bootstrap-compatible)
- **Sidebar width**: max-w-62.5 = 15.625rem (250px)
- **Navbar height**: ~56px with py-2 mx-6

## Naming Conventions
- **Utility classes**: Custom Tailwind utilities (soft-*, ease-soft-*, ease-nav-brand, etc.)
- **Custom classes**: shadow-soft-{xs|sm|md|lg|xl|2xl|3xl}, bg-gradient-fuchsia, bg-gradient-cyan etc.
- **Component files**: HTML files in build/ directory (dashboard.html, billing.html, profile.html)
- **Color token names**: Custom overrides using Bootstrap-style names (slate, gray) with non-standard values

## Quick-Start Rules for Code Generation
When generating code in this design style, Claude must follow these rules:
1. **Use component classes** — `card`, `card-header`, `card-body`, `btn-primary`, `btn-white`, `btn-outlined`, `form-label`, `form-input`, `nav-item`, `nav-item-active`, `nav-item-inactive`, `nav-icon`, `nav-icon-active`, `nav-icon-inactive` — never repeat raw utility strings for these patterns
2. Always use `shadow-soft-{sm|md|lg|xl|2xl}` shadow tokens — never use standard shadow-sm/md/lg
3. Cards use `.card` (includes `rounded-2xl shadow-soft-xl`); add `border-0` for content cards with a header section
4. Sidebar icons use `nav-icon nav-icon-active` for active state (gradient bg) and `nav-icon nav-icon-inactive` for rest
5. Buttons: add display and padding as utilities alongside the button class (`inline-block px-6 py-3 btn-primary`)
6. Typography uses Open Sans (sans) — ensure Google Fonts link is in HTML head
7. Custom easing tokens: `ease-soft-in`, `ease-soft-out`, `ease-soft-in-out`, `ease-nav-brand` for transitions
8. Page layout: sidebar is `fixed xl:left-0` — main content needs `xl:ml-68.5` offset
9. Gradient accents: use `from-purple-700 to-pink-500` (purple-pink) as the primary brand gradient
10. Breakpoints differ from standard Tailwind: sm=576px lg=992px xl=1200px 2xl=1320px
11. Font Awesome and Nucleo Icons are used for icons — don't substitute with Heroicons or Lucide