material-kit-design/design-system.md

# MK Design System

## Overview

- **Framework**: Vue 3.5+
- **Styling**: Tailwind CSS v4 (CSS-first config, no tailwind.config.js)
- **Font**: Roboto variable (self-hosted woff2), Roboto Slab, Material Icons Round
- **Icons**: Material Icons Round via `.material-icons` class
- **Color mode**: Light (CSS custom properties ready for dark mode extension)
- **Token source**: `tokens.json` — `src/style.css` `@theme` block is the live source of truth

---

## Visual Tokens

### Colors
| Token | CSS var | Hex | Usage |
|-------|---------|-----|-------|
| primary | `--color-primary` | #e91e63 | Buttons, links, key UI (pink/rose) |
| secondary | `--color-secondary` | #7b809a | Secondary actions, muted text |
| success | `--color-success` | #4caf50 | Positive states |
| warning | `--color-warning` | #fb8c00 | Warning states |
| danger | `--color-danger` | #f44335 | Error / destructive |
| info | `--color-info` | #1a73e8 | Informational |
| light | `--color-light` | #f0f2f5 | Page backgrounds |
| dark | `--color-dark` | #344767 | Dark text / navy |

All generate `bg-*`, `text-*`, `border-*`, `ring-*` utilities automatically.

### Gradients
195° linear gradients — this angle is the signature of the kit. **Do not change it.**

| Class | Direction |
|-------|-----------|
| `bg-gradient-primary` | #EC407A → #D81B60 |
| `bg-gradient-success` | #66bb6a → #43a047 |
| `bg-gradient-info` | #49a3f1 → #1a73e8 |
| `bg-gradient-dark` | #42424a → #191919 |
| …and 4 more (secondary/warning/danger/light) | |

Pair gradient classes with their colored shadow for the floating-card effect:
```html
<div class="bg-gradient-primary shadow-primary rounded-xl p-4 text-white">
```

### Shadows

| Class | Use |
|-------|-----|
| `shadow-soft-xs` | Subtle hover feedback |
| `shadow-soft-sm` | Default card lift |
| `shadow-soft-md` | Standard card |
| `shadow-soft-lg` | Elevated panels |
| `shadow-blur` | Frosted-glass containers |
| `shadow-primary` / `shadow-success` / … | Colored glow — always paired with matching gradient |

### Typography

| Class | Value | Use |
|-------|-------|-----|
| `font-sans` | Roboto variable | Body and UI |
| `font-serif` | Roboto Slab variable | Display/editorial |
| `font-mono` | SFMono / system | Code |
| `font-light` | 300 | Large display headings |
| `font-normal` | 400 | Body copy |
| `font-medium` | 500 | Labels, nav |
| `font-bold` | 700 | Headings, emphasis |
| `font-black` | 900 | Counter cards, hero numbers |

### Spacing
Use Tailwind's default scale. Common values: `p-4` (1rem), `p-6` (1.5rem), `py-16` (4rem) for section padding. No custom spacing tokens.

### Border Radius
| Class | Value | Use |
|-------|-------|-----|
| `rounded-xs` | 0.1rem | Micro elements |
| `rounded-lg` | 0.5rem | Inputs, small cards |
| `rounded-xl` | 0.75rem | Card images, avatars |
| `rounded-2xl` | 1rem | Cards, panels |
| `rounded-full` | 9999px | Badges (pill), avatars (circle) |

---

## Component Patterns

### Button
```html
<!-- Via component (recommended) -->
<MkButton variant="gradient" color="primary">Get Started</MkButton>
<MkButton variant="outline" color="primary" size="sm">Learn More</MkButton>

<!-- Manual (dark sections) -->
<button class="bg-white text-dark rounded-lg px-6 py-2.5 text-sm font-medium">
  Contact
</button>
```
**Variants**: `contained` (flat fill) · `gradient` (195° gradient + colored shadow) · `outline`  
**Colors**: primary / secondary / success / warning / danger / info / light / white / dark  
**Sizes**: sm · md (default) · lg  
**Do**: Use `variant="gradient"` for primary CTAs. Use `color="white"` on dark/gradient backgrounds.  
**Don't**: Use `bg-primary` manually when `MkButton` is available.

### Card (marketing)
```html
<div class="rounded-2xl bg-white shadow-soft-md">
  <!-- Floating image header (overlaps card top) -->
  <div class="-mt-6 mx-4 z-10 overflow-hidden rounded-xl shadow-soft-lg">
    <img src="..." class="h-48 w-full object-cover" />
  </div>
  <div class="px-6 pb-6 pt-4">
    <h5 class="font-semibold text-dark">Title</h5>
    <p class="text-sm text-secondary">Body text.</p>
  </div>
</div>
```

### Navbar
```html
<MkNavbar
  :brand="{ name: 'My App', route: '/' }"
  :nav-items="[
    { label: 'Home', href: '/' },
    { label: 'Pages', icon: 'dashboard', children: [
      { label: 'About', href: '/about', description: 'Our story' },
    ]},
  ]"
  :action="{ label: 'Get Started', href: '/signup', color: 'primary' }"
  :transparent="true"
/>
```
Scroll-triggered frosted glass is automatic in transparent mode.

### Form Inputs
```html
<MkInput label="Full Name" v-model="name" placeholder="e.g. Jane Doe" />
<MkInput label="Email" type="email" v-model="email" :error="true" />
<MkInput label="Search" icon="search" v-model="query" />
<MkTextArea label="Message" v-model="msg" :rows="4" />
<MkCheckbox id="terms" v-model="agreed" color="primary">I agree</MkCheckbox>
<MkSwitch id="notify" v-model="notify" color="primary">Email notifications</MkSwitch>
```

### Hero Section
```html
<MkHeader
  image="/img/hero.jpg"
  :title="{ text: 'Build Faster', variant: 'h1' }"
  description="A design system for Vue 3 and Tailwind v4."
  mask="dark"
  :mask-opacity="0.55"
  :center="true"
  min-height="80vh"
>
  <MkButton variant="gradient" color="primary" class="mt-6">Get Started</MkButton>
</MkHeader>
```

### Gradient text
```html
<h1 class="text-gradient bg-gradient-primary text-5xl font-black">42,000+</h1>
```
`text-gradient` clips the background image to the text shape. Always pair with a `bg-gradient-*` class.

### Move-on-hover (interactive cards)
```html
<div class="move-on-hover rounded-2xl bg-white shadow-soft-md p-6">
  <!-- Lifts 4px on hover with ease transition -->
</div>
```

---

## Layout & Grid

| Element | Classes |
|---------|---------|
| Page container | `max-w-7xl mx-auto px-4` |
| Section spacing | `py-16` (4rem) or `py-24` (6rem) for hero |
| Grid (3-col) | `grid grid-cols-1 gap-6 md:grid-cols-2 lg:grid-cols-3` |
| Grid (4-col) | `grid grid-cols-1 gap-6 sm:grid-cols-2 xl:grid-cols-4` |
| Flex row | `flex items-center gap-4` |
| Flex wrap | `flex flex-wrap gap-3` |

Breakpoints (Tailwind v4 defaults): `sm` 640px · `md` 768px · `lg` 1024px · `xl` 1280px.

---

## Naming Conventions

- **CSS custom properties**: `--color-*`, `--shadow-*`, `--radius-*`, `--font-*`, `--background-image-*`
- **Vue components**: PascalCase with `Mk` prefix — `MkButton`, `MkNavbar`, `MkDefaultCounterCard`
- **Custom CSS classes**: kebab-case — `move-on-hover`, `text-gradient`, `rotating-card-container`
- **No Bootstrap class names** anywhere in the codebase

---

## Quick-Start Rules for Code Generation

When generating code using this design system:

1. Use Tailwind v4 utility classes only — no Bootstrap, no custom SCSS
2. Reference colors via semantic class names (`bg-primary`, `text-success`) — never raw hex in HTML
3. Spacing: use Tailwind scale (`mt-4`, `px-6`, `py-16`) — no inline `style` for spacing
4. Primary CTAs: `MkButton variant="gradient" color="primary"` or `bg-gradient-primary shadow-primary text-white rounded-lg px-6 py-2.5`
5. Dark-section buttons: `color="white"` (white background, dark text) — not `color="light"`
6. Cards: `rounded-2xl bg-white shadow-soft-md` as the base; floating headers use `-mt-6 mx-4 rounded-xl overflow-hidden`
7. Page layout: `max-w-7xl mx-auto px-4` container with `grid gap-6` inside
8. Form fields: always use `MkInput`, `MkTextArea`, `MkCheckbox`, `MkSwitch` — not raw `<input>`
9. Images inside cards: `rounded-xl object-cover` for consistent soft appearance
10. Interactive cards: add `move-on-hover` class for hover lift effect
11. Use `Mk*` components throughout — consult `src/components/` for available primitives
12. Navbar scroll blur is automatic; pass `navItems` as data, not hardcoded HTML