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:

<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

<!-- 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)

<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

<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

<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

<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

<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)

<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