From db2ddadff3146cee927f15526abac00d4a88e2d3 Mon Sep 17 00:00:00 2001
From: Brian Rogers <captbrogers@protonmail.ch>
Date: Mon, 1 Jun 2026 17:32:42 -0600
Subject: [PATCH] finished up the components, added showcase view, and
 documentation

---
 conformity.md                   |  38 +++
 design-system.md                | 212 +++++++++++++++
 src/layouts/DashboardLayout.vue |   1 +
 src/router/index.js             |   1 +
 src/views/ShowcaseView.vue      | 460 ++++++++++++++++++++++++++++++++
 tokens.json                     | 121 +++++++++
 6 files changed, 833 insertions(+)
 create mode 100644 conformity.md
 create mode 100644 design-system.md
 create mode 100644 src/views/ShowcaseView.vue
 create mode 100644 tokens.json

diff --git a/conformity.md b/conformity.md
new file mode 100644
index 0000000..bc1e120
--- /dev/null
+++ b/conformity.md
@@ -0,0 +1,38 @@
+# MK Design System — Conformity Checklist
+
+## How to Use
+Provide this file plus the code to review to Claude with this prompt:
+"Review the following code against the conformity checklist below. For each rule, output PASS or FAIL with a specific code callout. Then provide a conformity score."
+
+## Rules
+
+### Visual Token Conformity
+- [ ] **C-V1**: Colors use semantic Tailwind classes (`bg-primary`, `text-success`, `border-danger`) — no raw hex values in HTML class attributes or `:class` bindings
+- [ ] **C-V2**: No hardcoded hex in inline `:style` attributes or `@layer` CSS rules; use `var(--color-*)` or Tailwind classes instead
+- [ ] **C-V3**: Spacing uses Tailwind scale classes (`mt-4`, `px-6`, `py-16`) — no inline `style="margin: ..."` or `style="padding: ..."`
+- [ ] **C-V4**: Shadows use `shadow-soft-*` or `shadow-{color}` utilities — no custom `box-shadow` values in class attributes
+- [ ] **C-V5**: Border radius uses `rounded-*` utilities (`rounded-lg`, `rounded-2xl`, `rounded-full`) — no inline `border-radius` style values
+
+### Component Conformity
+- [ ] **C-C1**: All buttons use `MkButton` component or the manual gradient pattern (`bg-gradient-{color} shadow-{color} text-white rounded-lg px-6 py-2.5`); dark-section buttons use `color="white"`; icon-only buttons are square with `p-2`
+- [ ] **C-C2**: Cards follow `rounded-2xl bg-white shadow-soft-md` base; card image headers use `-mt-6 mx-4 overflow-hidden rounded-xl` floating pattern; interactive cards use `move-on-hover`
+- [ ] **C-C3**: Form inputs use `MkInput` with `v-model`; raw `<input>` elements (if used) must have `rounded-lg border border-gray-200 px-3 py-2 focus:border-primary focus:ring-1 focus:ring-primary`
+- [ ] **C-C4**: Navigation uses `MkNavbar` with `navItems` prop; custom navbars must replicate scroll-blur behavior (`bg-white/90 backdrop-blur-sm`) and responsive collapse
+- [ ] **C-C5**: Alerts use `MkAlert` component or `rounded-lg px-4 py-3 text-sm bg-{color} text-white` — no plain unstyled `<div role="alert">`
+
+### Layout Conformity
+- [ ] **C-L1**: Marketing pages use `max-w-7xl mx-auto px-4` as the page container — not full-bleed or custom `max-width` values
+- [ ] **C-L2**: Responsive breakpoints use Tailwind prefixes (`sm:`, `md:`, `lg:`, `xl:`) — no CSS media queries in `<style>` blocks unless unavoidable
+- [ ] **C-L3**: Content grids use `grid gap-6` with `grid-cols-{n}` and responsive column modifiers — not `flex flex-wrap` with manual width percentages
+- [ ] **C-L4**: Flex layouts use Tailwind utilities (`flex`, `items-center`, `justify-between`, `gap-4`) — no `display: flex` in inline styles
+
+### Naming Conformity
+- [ ] **C-N1**: CSS custom properties follow the `@theme` naming convention: `--color-*`, `--shadow-*`, `--radius-*`, `--font-*`, `--background-image-*`
+- [ ] **C-N2**: No Bootstrap class names present (`.container`, `.row`, `.col-*`, `.btn`, `.badge`, `.card`, `.navbar`, `.form-control`, etc.)
+- [ ] **C-N3**: Vue components use PascalCase with `Mk` prefix (`MkButton`, `MkNavbar`, `MkDefaultCounterCard`); custom utility classes use kebab-case (`move-on-hover`, `text-gradient`)
+
+## Scoring Guide
+- 15–17 rules pass → **Fully conformant** — ready for production
+- 12–14 rules pass → **Mostly conformant** — minor cleanup needed
+- 8–11 rules pass → **Partially conformant** — significant drift, review required
+- Below 8 → **Non-conformant** — major rework needed before shipping
diff --git a/design-system.md b/design-system.md
new file mode 100644
index 0000000..f7df957
--- /dev/null
+++ b/design-system.md
@@ -0,0 +1,212 @@
+# 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
diff --git a/src/layouts/DashboardLayout.vue b/src/layouts/DashboardLayout.vue
index b0e8464..037bc35 100644
--- a/src/layouts/DashboardLayout.vue
+++ b/src/layouts/DashboardLayout.vue
@@ -12,6 +12,7 @@ const navItems = [
   { label: 'Icons',         path: '/icons',        icon: 'auto_awesome' },
   { label: 'Maps',          path: '/maps',         icon: 'map' },
   { label: 'Notifications', path: '/notifications',icon: 'notifications' },
+  { label: 'Showcase',      path: '/showcase',      icon: 'widgets' },
 ]
 
 function isActive(path) {
diff --git a/src/router/index.js b/src/router/index.js
index 270e404..a1d7166 100644
--- a/src/router/index.js
+++ b/src/router/index.js
@@ -11,5 +11,6 @@ export default createRouter({
     { path: '/maps',         component: () => import('../views/MapsView.vue'),           meta: { title: 'Maps' } },
     { path: '/notifications',component: () => import('../views/NotificationsView.vue'),  meta: { title: 'Notifications' } },
     { path: '/profile',      component: () => import('../views/ProfileView.vue'),        meta: { title: 'Profile' } },
+    { path: '/showcase',     component: () => import('../views/ShowcaseView.vue'),       meta: { title: 'Component Showcase' } },
   ],
 })
diff --git a/src/views/ShowcaseView.vue b/src/views/ShowcaseView.vue
new file mode 100644
index 0000000..8d22b11
--- /dev/null
+++ b/src/views/ShowcaseView.vue
@@ -0,0 +1,460 @@
+<script setup>
+import { ref } from 'vue'
+import DashboardLayout from '../layouts/DashboardLayout.vue'
+
+// Core
+import MkButton          from '../components/MkButton.vue'
+import MkBadge           from '../components/MkBadge.vue'
+import MkAlert           from '../components/MkAlert.vue'
+import MkAvatar          from '../components/MkAvatar.vue'
+import MkProgress        from '../components/MkProgress.vue'
+import MkCheckbox        from '../components/MkCheckbox.vue'
+import MkSwitch          from '../components/MkSwitch.vue'
+import MkInput           from '../components/MkInput.vue'
+import MkTextArea        from '../components/MkTextArea.vue'
+import MkPagination      from '../components/MkPagination.vue'
+import MkPaginationItem  from '../components/MkPaginationItem.vue'
+import MkTable           from '../components/MkTable.vue'
+
+// Cards
+import MkBackgroundBlogCard  from '../components/cards/MkBackgroundBlogCard.vue'
+import MkCenteredBlogCard    from '../components/cards/MkCenteredBlogCard.vue'
+import MkTransparentBlogCard from '../components/cards/MkTransparentBlogCard.vue'
+import MkDefaultInfoCard     from '../components/cards/MkDefaultInfoCard.vue'
+import MkFilledInfoCard      from '../components/cards/MkFilledInfoCard.vue'
+import MkDefaultCounterCard  from '../components/cards/MkDefaultCounterCard.vue'
+import MkDefaultReviewCard   from '../components/cards/MkDefaultReviewCard.vue'
+import MkHorizontalTeamCard  from '../components/cards/MkHorizontalTeamCard.vue'
+import MkRotatingCard        from '../components/cards/MkRotatingCard.vue'
+import MkRotatingCardFront   from '../components/cards/MkRotatingCardFront.vue'
+import MkRotatingCardBack    from '../components/cards/MkRotatingCardBack.vue'
+
+// Layout
+import MkBreadcrumbs    from '../components/layout/MkBreadcrumbs.vue'
+import MkNavbar         from '../components/layout/MkNavbar.vue'
+import MkHeader         from '../components/layout/MkHeader.vue'
+import MkFooterCentered from '../components/layout/MkFooterCentered.vue'
+
+// ── Reactive state ────────────────────────────────────────────
+const checkbox1 = ref(true)
+const checkbox2 = ref(false)
+const switch1   = ref(true)
+const switch2   = ref(false)
+const inputVal  = ref('')
+const textareaVal = ref('')
+const activePage  = ref(3)
+
+// ── Data ──────────────────────────────────────────────────────
+const colors = ['primary','secondary','success','warning','danger','info','dark']
+
+const img = (seed, w = 600, h = 400) => `https://picsum.photos/seed/${seed}/${w}/${h}`
+
+const tableRows = [
+  { initials:'EC', color:'primary',   name:'Esthera Carter',  email:'e.carter@mk.dev', position:['Lead Designer','Creative'],       status:true,  date:'23/04/18', action:{label:'Edit', route:'#'} },
+  { initials:'JD', color:'info',      name:'James Donovan',   email:'j.donovan@mk.dev',position:['Developer','Engineering'],         status:true,  date:'11/01/19', action:{label:'Edit', route:'#'} },
+  { initials:'SR', color:'success',   name:'Sofia Reyes',     email:'s.reyes@mk.dev',  position:['Product Manager','Operations'],    status:false, date:'19/09/20', action:{label:'Edit', route:'#'} },
+  { initials:'ML', color:'warning',   name:'Marco Lin',       email:'m.lin@mk.dev',    position:['QA Engineer','Quality'],           status:true,  date:'24/12/21', action:{label:'Edit', route:'#'} },
+  { initials:'AM', color:'secondary', name:'Ally Maria',      email:'a.maria@mk.dev',  position:['UX Researcher','Design'],          status:false, date:'04/10/22', action:{label:'Edit', route:'#'} },
+]
+
+const navItems = [
+  { label:'Home', href:'#', icon:'home' },
+  { label:'Components', icon:'widgets', children:[
+    { label:'Buttons',   href:'#', description:'Variants, sizes and states' },
+    { label:'Cards',     href:'#', description:'Blog, info, counter, review' },
+    { label:'Forms',     href:'#', description:'Inputs, selects, checkboxes' },
+  ]},
+  { label:'Docs', href:'#', icon:'article' },
+]
+
+const breadcrumbRoutes = [
+  { route:'/', label:'Dashboard' },
+  { route:'/showcase', label:'Components' },
+  { route:'#', label:'Showcase' },
+]
+</script>
+
+<template>
+  <DashboardLayout>
+    <div class="space-y-12">
+
+      <!-- ── SECTION HELPER ──────────────────────────────────── -->
+      <!-- Each section follows: title / subtitle / content card  -->
+
+      <!-- ① Buttons ─────────────────────────────────────────── -->
+      <section>
+        <h2 class="text-lg font-bold text-dark mb-0.5">Buttons</h2>
+        <p class="text-sm text-secondary mb-4">variant × color × size</p>
+
+        <div class="rounded-2xl bg-white p-6 shadow-soft-md space-y-6">
+          <!-- Gradient -->
+          <div>
+            <p class="mb-3 text-xs font-medium uppercase tracking-wide text-secondary">Gradient</p>
+            <div class="flex flex-wrap gap-3">
+              <MkButton v-for="c in colors" :key="c" variant="gradient" :color="c">{{ c }}</MkButton>
+            </div>
+          </div>
+          <!-- Contained -->
+          <div>
+            <p class="mb-3 text-xs font-medium uppercase tracking-wide text-secondary">Contained</p>
+            <div class="flex flex-wrap gap-3">
+              <MkButton v-for="c in colors" :key="c" variant="contained" :color="c">{{ c }}</MkButton>
+            </div>
+          </div>
+          <!-- Outline -->
+          <div>
+            <p class="mb-3 text-xs font-medium uppercase tracking-wide text-secondary">Outline</p>
+            <div class="flex flex-wrap gap-3">
+              <MkButton v-for="c in colors" :key="c" variant="outline" :color="c">{{ c }}</MkButton>
+            </div>
+          </div>
+          <!-- Sizes + states -->
+          <div>
+            <p class="mb-3 text-xs font-medium uppercase tracking-wide text-secondary">Sizes & states</p>
+            <div class="flex flex-wrap items-center gap-3">
+              <MkButton variant="gradient" color="primary" size="sm">Small</MkButton>
+              <MkButton variant="gradient" color="primary" size="md">Medium</MkButton>
+              <MkButton variant="gradient" color="primary" size="lg">Large</MkButton>
+              <MkButton variant="gradient" color="primary" :disabled="true">Disabled</MkButton>
+              <MkButton variant="outline" color="primary" :full-width="true" class="max-w-xs">Full width</MkButton>
+            </div>
+          </div>
+        </div>
+      </section>
+
+      <!-- ② Badges ────────────────────────────────────────────── -->
+      <section>
+        <h2 class="text-lg font-bold text-dark mb-0.5">Badges</h2>
+        <p class="text-sm text-secondary mb-4">fill · gradient · sizes · rounded</p>
+
+        <div class="rounded-2xl bg-white p-6 shadow-soft-md space-y-4">
+          <div class="flex flex-wrap gap-2">
+            <MkBadge v-for="c in colors" :key="c" variant="fill" :color="c">{{ c }}</MkBadge>
+          </div>
+          <div class="flex flex-wrap gap-2">
+            <MkBadge v-for="c in colors" :key="c" variant="gradient" :color="c">{{ c }}</MkBadge>
+          </div>
+          <div class="flex flex-wrap items-center gap-2">
+            <MkBadge color="primary" size="sm" :rounded="true">sm pill</MkBadge>
+            <MkBadge color="primary" size="md" :rounded="true">md pill</MkBadge>
+            <MkBadge color="primary" size="lg" :rounded="true">lg pill</MkBadge>
+          </div>
+        </div>
+      </section>
+
+      <!-- ③ Alerts ─────────────────────────────────────────────── -->
+      <section>
+        <h2 class="text-lg font-bold text-dark mb-0.5">Alerts</h2>
+        <p class="text-sm text-secondary mb-4">all colors · dismissible</p>
+
+        <div class="rounded-2xl bg-white p-6 shadow-soft-md space-y-3">
+          <MkAlert color="success">Success — action completed.</MkAlert>
+          <MkAlert color="info">Info — something you should know.</MkAlert>
+          <MkAlert color="warning">Warning — check before proceeding.</MkAlert>
+          <MkAlert color="danger" :dismissible="true">Danger (dismissible) — click × to close.</MkAlert>
+          <MkAlert color="dark">Dark — a neutral message.</MkAlert>
+        </div>
+      </section>
+
+      <!-- ④ Avatars ────────────────────────────────────────────── -->
+      <section>
+        <h2 class="text-lg font-bold text-dark mb-0.5">Avatars</h2>
+        <p class="text-sm text-secondary mb-4">xxs → xxl · borderRadius variants</p>
+
+        <div class="rounded-2xl bg-white p-6 shadow-soft-md">
+          <div class="flex flex-wrap items-end gap-4">
+            <div v-for="s in ['xxs','xs','sm','md','lg','xl','xxl']" :key="s" class="flex flex-col items-center gap-2">
+              <MkAvatar :image="img('av1',200,200)" alt="Avatar" :size="s" />
+              <span class="text-xs text-secondary">{{ s }}</span>
+            </div>
+            <div class="flex flex-col items-center gap-2">
+              <MkAvatar :image="img('av2',200,200)" alt="Circle" size="lg" border-radius="full" />
+              <span class="text-xs text-secondary">circle</span>
+            </div>
+          </div>
+        </div>
+      </section>
+
+      <!-- ⑤ Progress ───────────────────────────────────────────── -->
+      <section>
+        <h2 class="text-lg font-bold text-dark mb-0.5">Progress</h2>
+        <p class="text-sm text-secondary mb-4">contained · gradient</p>
+
+        <div class="rounded-2xl bg-white p-6 shadow-soft-md space-y-3">
+          <div v-for="c in colors" :key="c" class="flex items-center gap-4">
+            <span class="w-20 shrink-0 text-xs text-secondary">{{ c }}</span>
+            <div class="flex-1"><MkProgress variant="gradient" :color="c" :value="Math.round(30 + colors.indexOf(c) * 10)" /></div>
+          </div>
+        </div>
+      </section>
+
+      <!-- ⑥ Form Controls ──────────────────────────────────────── -->
+      <section>
+        <h2 class="text-lg font-bold text-dark mb-0.5">Form Controls</h2>
+        <p class="text-sm text-secondary mb-4">input · textarea · checkbox · switch</p>
+
+        <div class="grid gap-6 lg:grid-cols-2">
+          <!-- Inputs -->
+          <div class="rounded-2xl bg-white p-6 shadow-soft-md space-y-4">
+            <MkInput label="Default input" v-model="inputVal" placeholder="Type something…" />
+            <MkInput label="With icon" icon="search" v-model="inputVal" placeholder="Search…" />
+            <MkInput label="Error state" v-model="inputVal" :error="true" placeholder="Required field" />
+            <MkInput label="Success state" v-model="inputVal" :success="true" placeholder="Looks good" />
+            <MkInput label="Disabled" v-model="inputVal" :is-disabled="true" placeholder="Not editable" />
+            <MkTextArea v-model="textareaVal" placeholder="Your message…" :rows="3">Message</MkTextArea>
+          </div>
+
+          <!-- Toggles -->
+          <div class="rounded-2xl bg-white p-6 shadow-soft-md">
+            <p class="mb-4 text-xs font-medium uppercase tracking-wide text-secondary">Checkboxes</p>
+            <div class="space-y-3 mb-6">
+              <MkCheckbox id="c1" v-model="checkbox1" color="primary">Primary (checked)</MkCheckbox>
+              <MkCheckbox id="c2" v-model="checkbox2" color="success">Success (unchecked)</MkCheckbox>
+              <MkCheckbox id="c3" v-model="checkbox1" color="danger">Danger</MkCheckbox>
+            </div>
+            <p class="mb-4 text-xs font-medium uppercase tracking-wide text-secondary">Switches</p>
+            <div class="space-y-3">
+              <MkSwitch id="s1" v-model="switch1" color="primary">Primary (on)</MkSwitch>
+              <MkSwitch id="s2" v-model="switch2" color="success">Success (off)</MkSwitch>
+              <MkSwitch id="s3" v-model="switch1" color="info">Info</MkSwitch>
+            </div>
+          </div>
+        </div>
+      </section>
+
+      <!-- ⑦ Pagination ─────────────────────────────────────────── -->
+      <section>
+        <h2 class="text-lg font-bold text-dark mb-0.5">Pagination</h2>
+        <p class="text-sm text-secondary mb-4">color variants · active state</p>
+
+        <div class="rounded-2xl bg-white p-6 shadow-soft-md space-y-4">
+          <div v-for="c in ['primary','success','info','danger']" :key="c">
+            <MkPagination :color="c">
+              <MkPaginationItem :prev="true" @click="activePage > 1 && activePage--" />
+              <MkPaginationItem v-for="n in 5" :key="n" :label="String(n)" :active="activePage === n" @click="activePage = n" />
+              <MkPaginationItem :next="true" @click="activePage < 5 && activePage++" />
+            </MkPagination>
+          </div>
+        </div>
+      </section>
+
+      <!-- ⑧ Blog Cards ─────────────────────────────────────────── -->
+      <section>
+        <h2 class="text-lg font-bold text-dark mb-0.5">Blog Cards</h2>
+        <p class="text-sm text-secondary mb-4">background · centered · transparent</p>
+
+        <div class="grid gap-6 md:grid-cols-3">
+          <MkBackgroundBlogCard
+            :image="img('bg1')"
+            title="Background Blog Card"
+            description="Full-bleed image with gradient overlay. Content sits above the image."
+            :action="{ route:'#', label:'Read more', color:'white' }"
+          />
+          <MkCenteredBlogCard
+            :image="img('cb1')"
+            title="Centered Blog Card"
+            description="Floating image header overlaps the card top edge for a layered effect."
+            :action="{ color:'success', label:'Find Out More', route:'#' }"
+          />
+          <MkTransparentBlogCard
+            :image="img('tb1')"
+            title="Transparent Blog Card"
+            description="No card background — just the image with a soft shadow and plain text below."
+            :action="{ route:'#', color:'primary', label:'Read more' }"
+          />
+        </div>
+      </section>
+
+      <!-- ⑨ Info Cards ─────────────────────────────────────────── -->
+      <section>
+        <h2 class="text-lg font-bold text-dark mb-0.5">Info Cards</h2>
+        <p class="text-sm text-secondary mb-4">default · filled</p>
+
+        <div class="grid gap-6 md:grid-cols-2">
+          <div class="rounded-2xl bg-white p-6 shadow-soft-md">
+            <div class="grid gap-6 sm:grid-cols-2">
+              <MkDefaultInfoCard
+                v-for="item in [
+                  {icon:{component:'bolt',color:'primary',size:'3xl'},title:'Fast Build',description:'Zero-config Vite setup with Tailwind v4.'},
+                  {icon:{component:'palette',color:'success',size:'3xl'},title:'Design Tokens',description:'All values live in @theme CSS custom properties.'},
+                  {icon:{component:'widgets',color:'info',size:'3xl'},title:'30+ Components',description:'Buttons, cards, forms, navbars and more.'},
+                  {icon:{component:'devices',color:'warning',size:'3xl'},title:'Responsive',description:'Mobile-first layouts using Tailwind breakpoints.'},
+                ]"
+                :key="item.title"
+                :icon="item.icon"
+                :title="item.title"
+                :description="item.description"
+              />
+            </div>
+          </div>
+
+          <div class="space-y-4">
+            <MkFilledInfoCard
+              :color="{ background:'primary', text:'white' }"
+              :icon="{ component:'rocket_launch', color:'white' }"
+              title="Ship faster"
+              description="Pre-built components mean less time on UI and more time on features."
+              :action="{ route:'#', label:{ text:'Learn More', color:'white' } }"
+            />
+            <MkFilledInfoCard
+              :color="{ background:'', text:'' }"
+              :icon="{ component:'verified', color:'success' }"
+              title="Design conformity"
+              description="The conformity checklist helps keep every PR on-brand."
+              :action="{ route:'#', label:{ text:'View Checklist', color:'success' } }"
+            />
+          </div>
+        </div>
+      </section>
+
+      <!-- ⑩ Counter · Review · Team ───────────────────────────── -->
+      <section>
+        <h2 class="text-lg font-bold text-dark mb-0.5">Counter, Review & Team Cards</h2>
+        <p class="text-sm text-secondary mb-4">animated counters · star ratings · horizontal profile</p>
+
+        <div class="grid gap-6 lg:grid-cols-3">
+          <!-- Counter cards -->
+          <div class="rounded-2xl bg-white p-8 shadow-soft-md">
+            <div class="grid grid-cols-2 gap-6">
+              <MkDefaultCounterCard :count="240"    suffix="+"  color="primary"   title="Projects"   description="Completed this year" divider="horizontal" />
+              <MkDefaultCounterCard :count="4500"   suffix="+"  color="success"   title="Users"      description="Active accounts"     divider="horizontal" />
+              <MkDefaultCounterCard :count="99"     suffix="%"  color="info"      title="Uptime"     description="Last 12 months"      divider="horizontal" />
+              <MkDefaultCounterCard :count="18"             color="warning"   title="Countries"  description="Worldwide reach"     divider="horizontal" />
+            </div>
+          </div>
+
+          <!-- Review card -->
+          <MkDefaultReviewCard
+            :image="img('rev1',200,200)"
+            name="Sofia Reyes"
+            date="2 days ago"
+            review="This design system saved us weeks of setup. The components are clean and the token system makes theming trivial."
+            :rating="5"
+          />
+
+          <!-- Team card -->
+          <MkHorizontalTeamCard
+            :image="img('team1',400,500)"
+            :profile="{ name:'James Donovan', link:'#' }"
+            :position="{ label:'Lead Engineer', color:'primary' }"
+            description="James leads the frontend platform team and maintains the component library. Open source contributor and design systems enthusiast."
+          />
+        </div>
+      </section>
+
+      <!-- ⑪ Rotating Card ─────────────────────────────────────── -->
+      <section>
+        <h2 class="text-lg font-bold text-dark mb-0.5">Rotating Card</h2>
+        <p class="text-sm text-secondary mb-4">hover to flip — CSS 3D, no JS</p>
+
+        <div class="max-w-xs">
+          <div style="height: 22rem">
+            <MkRotatingCard color="primary" min-height="22rem">
+              <MkRotatingCardFront
+                :image="img('rot-front',600,800)"
+                icon="layers"
+                label="Design System"
+                title="Material Kit 2"
+                description="Vue 3 + Tailwind v4"
+              />
+              <MkRotatingCardBack
+                :image="img('rot-back',600,800)"
+                title="Get Started"
+                description="Build beautiful interfaces with a consistent, token-driven system."
+                :action="[
+                  { route:'#', label:'Docs', color:'white' },
+                  { route:'#', label:'GitHub', color:'white' },
+                ]"
+              />
+            </MkRotatingCard>
+          </div>
+        </div>
+      </section>
+
+      <!-- ⑫ Table ──────────────────────────────────────────────── -->
+      <section>
+        <h2 class="text-lg font-bold text-dark mb-0.5">Table</h2>
+        <p class="text-sm text-secondary mb-4">avatar + status badge + action</p>
+
+        <MkTable :rows="tableRows">
+          <template #header>
+            <div class="flex items-center justify-between">
+              <h6 class="text-sm font-bold text-dark">Authors</h6>
+              <MkBadge color="success" :rounded="true">5 active</MkBadge>
+            </div>
+          </template>
+          <template #footer>
+            <MkPagination color="primary" size="sm">
+              <MkPaginationItem :prev="true" />
+              <MkPaginationItem label="1" :active="true" />
+              <MkPaginationItem label="2" />
+              <MkPaginationItem label="3" />
+              <MkPaginationItem :next="true" />
+            </MkPagination>
+          </template>
+        </MkTable>
+      </section>
+
+      <!-- ⑬ Layout Components ──────────────────────────────────── -->
+      <section>
+        <h2 class="text-lg font-bold text-dark mb-0.5">Layout Components</h2>
+        <p class="text-sm text-secondary mb-4">navbar · header · breadcrumbs · footer</p>
+
+        <div class="space-y-6">
+
+          <!-- Breadcrumbs -->
+          <div class="rounded-2xl bg-white p-6 shadow-soft-md">
+            <p class="mb-3 text-xs font-medium uppercase tracking-wide text-secondary">MkBreadcrumbs</p>
+            <MkBreadcrumbs :routes="breadcrumbRoutes" />
+          </div>
+
+          <!-- Navbar preview -->
+          <div class="rounded-2xl shadow-soft-md overflow-hidden">
+            <p class="bg-gray-50 px-4 py-2 text-xs font-medium text-secondary border-b border-gray-100">MkNavbar — light mode (hover items for dropdown)</p>
+            <MkNavbar
+              :brand="{ name:'MK Design', route:'#' }"
+              :nav-items="navItems"
+              :action="{ label:'Get Started', href:'#', color:'primary' }"
+              :sticky="false"
+            />
+          </div>
+
+          <!-- Header preview -->
+          <div class="rounded-2xl shadow-soft-md overflow-hidden">
+            <p class="bg-gray-50 px-4 py-2 text-xs font-medium text-secondary border-b border-gray-100">MkHeader — background image + gradient mask</p>
+            <MkHeader
+              :image="img('header1',1200,600)"
+              :title="{ text:'Build Something Beautiful', variant:'h2' }"
+              description="A design system for Vue 3 and Tailwind v4."
+              mask="dark"
+              :mask-opacity="0.6"
+              :center="true"
+              min-height="200px"
+            />
+          </div>
+
+          <!-- Footer preview -->
+          <div class="rounded-2xl shadow-soft-md overflow-hidden">
+            <p class="bg-gray-50 px-4 py-2 text-xs font-medium text-secondary border-b border-gray-100">MkFooterCentered</p>
+            <MkFooterCentered
+              :links="[
+                { name:'Company', href:'#' },
+                { name:'About', href:'#' },
+                { name:'Blog', href:'#' },
+                { name:'License', href:'#' },
+              ]"
+              :socials="[
+                { icon:'language', link:'#', label:'Website' },
+                { icon:'code',     link:'#', label:'GitHub' },
+                { icon:'mail',     link:'#', label:'Email' },
+              ]"
+              :copyright="`© ${new Date().getFullYear()} MK Design System`"
+            />
+          </div>
+
+        </div>
+      </section>
+
+    </div>
+  </DashboardLayout>
+</template>
diff --git a/tokens.json b/tokens.json
new file mode 100644
index 0000000..5c25734
--- /dev/null
+++ b/tokens.json
@@ -0,0 +1,121 @@
+{
+  "meta": {
+    "project": "mk-design-system",
+    "sourceApproach": "tailwindcss-v4",
+    "primaryFont": "Roboto",
+    "fontType": "variable-woff2",
+    "colorMode": "light",
+    "version": "0.1.0"
+  },
+  "colors": {
+    "primary":   { "DEFAULT": "#e91e63", "gradientStart": "#EC407A", "gradientEnd": "#D81B60" },
+    "secondary": { "DEFAULT": "#7b809a", "gradientStart": "#747b8a", "gradientEnd": "#495361" },
+    "semantic": {
+      "success": { "DEFAULT": "#4caf50", "gradientStart": "#66bb6a", "gradientEnd": "#43a047" },
+      "warning": { "DEFAULT": "#fb8c00", "gradientStart": "#ffa726", "gradientEnd": "#fb8c00" },
+      "danger":  { "DEFAULT": "#f44335", "gradientStart": "#ef5350", "gradientEnd": "#e53935" },
+      "info":    { "DEFAULT": "#1a73e8", "gradientStart": "#49a3f1", "gradientEnd": "#1a73e8" }
+    },
+    "neutrals": {
+      "white": "#ffffff",
+      "black": "#000000",
+      "light": "#f0f2f5",
+      "dark":  "#344767",
+      "gray": {
+        "100": "#f8f9fa",
+        "200": "#f0f2f5",
+        "300": "#dee2e6",
+        "500": "#adb5bd",
+        "600": "#6c757d",
+        "900": "#212529"
+      }
+    }
+  },
+  "typography": {
+    "fontFamilies": {
+      "sans":  "Roboto, Helvetica, Arial, sans-serif",
+      "serif": "Roboto Slab, serif",
+      "mono":  "SFMono-Regular, Menlo, Monaco, Consolas, 'Liberation Mono', 'Courier New', monospace"
+    },
+    "fontFiles": {
+      "roboto":     "public/fonts/roboto/Roboto-VariableFont_wdth-wght.woff2",
+      "robotoItalic":"public/fonts/roboto/Roboto-Italic-VariableFont_wdth-wght.woff2",
+      "robotoSlab": "public/fonts/roboto-slab/RobotoSlab-VariableFont_wght.woff2",
+      "materialIcons":"public/fonts/material-icons-round/material-icons-round-latin-400-normal.woff2"
+    },
+    "weightRange": "100–900 (variable font)",
+    "sizes": {
+      "xs":   "0.75rem",
+      "sm":   "0.875rem",
+      "base": "1rem",
+      "lg":   "1.125rem",
+      "xl":   "1.25rem",
+      "2xl":  "1.5rem",
+      "3xl":  "1.875rem",
+      "4xl":  "2.25rem",
+      "5xl":  "3rem"
+    },
+    "lineHeights": { "base": "1.5", "tight": "1.25", "relaxed": "1.75" }
+  },
+  "spacing": {
+    "note": "Tailwind v4 default scale — rem-based, no custom overrides needed",
+    "common": {
+      "1": "0.25rem",  "2": "0.5rem",  "3": "0.75rem",
+      "4": "1rem",     "6": "1.5rem",  "8": "2rem",
+      "12": "3rem",    "16": "4rem",   "24": "6rem"
+    }
+  },
+  "shadows": {
+    "soft": {
+      "xs": "0 2px 9px -5px rgba(0,0,0,0.15)",
+      "sm": "0 0.3125rem 0.625rem 0 rgba(0,0,0,0.12)",
+      "md": "0 4px 6px -1px rgba(0,0,0,0.1), 0 2px 4px -1px rgba(0,0,0,0.06)",
+      "lg": "0 10px 15px -3px rgba(0,0,0,0.1), 0 4px 6px -2px rgba(0,0,0,0.05)"
+    },
+    "blur": "0 20px 27px rgba(0,0,0,0.05)",
+    "colored": {
+      "note": "0 4px 20px 0 rgba(0,0,0,0.14), 0 7px 10px -5px rgba({r},{g},{b},0.4)",
+      "primary":   "0 4px 20px 0 rgba(0,0,0,0.14), 0 7px 10px -5px rgba(233,30,99,0.4)",
+      "secondary": "0 4px 20px 0 rgba(0,0,0,0.14), 0 7px 10px -5px rgba(210,210,210,0.4)",
+      "success":   "0 4px 20px 0 rgba(0,0,0,0.14), 0 7px 10px -5px rgba(76,175,80,0.4)",
+      "warning":   "0 4px 20px 0 rgba(0,0,0,0.14), 0 7px 10px -5px rgba(251,140,0,0.4)",
+      "danger":    "0 4px 20px 0 rgba(0,0,0,0.14), 0 7px 10px -5px rgba(244,67,54,0.4)",
+      "info":      "0 4px 20px 0 rgba(0,0,0,0.14), 0 7px 10px -5px rgba(26,115,232,0.4)",
+      "dark":      "0 4px 20px 0 rgba(0,0,0,0.14), 0 7px 10px -5px rgba(64,64,64,0.4)"
+    }
+  },
+  "borders": {
+    "radius": {
+      "xs":  "0.1rem",
+      "sm":  "0.125rem",
+      "md":  "0.375rem",
+      "lg":  "0.5rem",
+      "xl":  "0.75rem",
+      "2xl": "1rem",
+      "full":"9999px"
+    },
+    "width": { "default": "1px" }
+  },
+  "gradients": {
+    "angle": "195deg",
+    "note": "All gradients use the 195deg angle — do not change",
+    "variants": {
+      "primary":   "linear-gradient(195deg, #EC407A, #D81B60)",
+      "secondary": "linear-gradient(195deg, #747b8a, #495361)",
+      "success":   "linear-gradient(195deg, #66bb6a, #43a047)",
+      "warning":   "linear-gradient(195deg, #ffa726, #fb8c00)",
+      "danger":    "linear-gradient(195deg, #ef5350, #e53935)",
+      "info":      "linear-gradient(195deg, #49a3f1, #1a73e8)",
+      "dark":      "linear-gradient(195deg, #42424a, #191919)",
+      "light":     "linear-gradient(195deg, #ebeff4, #ced4da)"
+    }
+  },
+  "breakpoints": {
+    "note": "Tailwind v4 defaults",
+    "sm":  "640px",
+    "md":  "768px",
+    "lg":  "1024px",
+    "xl":  "1280px",
+    "2xl": "1536px"
+  }
+}