mk:ui-design-system

Data-driven design intelligence: curated palettes, font pairings, product recommendations, UX guidelines, accessibility standards, and quality checklists.

What This Skill Does

Provides a comprehensive design intelligence system backed by data — not opinion. Uses 5 CSV data files (160+ color palettes, 73 font pairings, 161 product types, 98 UX guidelines, 25 chart types) to make evidence-based design decisions. Enforces WCAG 2.1 AA compliance through automated quality checklists.

When to Use

• Creating or reviewing UI components
• Setting up a design system for a new project
• Checking WCAG accessibility compliance
• Selecting color palettes, typography, or UI styles
• Choosing chart types for data visualization
• Responsive design review
• Product-type-specific design direction

Auto-activates when ui-ux-designer agent is working.

Explicit: /mk:ui-design-system [concern]

Core Capabilities

• Color palettes — 161 WCAG-verified palettes filtered by product type with hex values
• Font pairings — 73 pairings with mood, Google Fonts URLs, and Tailwind config snippets
• Product direction — 161 product types with recommended styles, landing patterns, and color focus
• UX guidelines — 98 Do/Don't rules across 15 categories with severity ratings
• Chart selection — 25 chart types with data-type matching and accessibility grades
• Design patterns — 8 style categories (minimalism, glassmorphism, neumorphism, brutalism, etc.)
• Accessibility — WCAG 2.1 AA standards for contrast, touch targets, keyboard nav, screen readers
• Quality checklist — visual, responsive, accessibility, performance, and interaction gates

Arguments

Argument	Type	Description
concern	string	Optional. Focus area: palette, typography, product, ux, charts, accessibility, review

Workflow

Loaded by ui-ux-designer agent during Phase 3 (Build). Also used by developer agent for frontend work.

Process

1. Understand requirements — what product type? audience? style direction?
2. Look up design data — read references/data-lookup.md for how to query:
   • Color palette -> assets/colors.csv (161 WCAG-verified palettes by product type)
   • Font pairing -> assets/typography.csv (73 pairings with Google Fonts URLs)
   • Product direction -> assets/products.csv (161 types with style/dashboard/color recs)
   • UX check -> assets/ux-guidelines.csv (98 Do/Don't rules with severity)
   • Chart type -> assets/charts.csv (25 types with accessibility grades)
3. Apply design rules — load from references/ based on task:
   • Visual design -> references/design-patterns.md
   • Accessibility -> references/accessibility-standards.md
   • Quality check -> references/quality-checklist.md
4. Validate — run quality-checklist.md before handoff

Data Assets

File	Rows	Content
assets/colors.csv	160	WCAG-verified palettes by product type (hex values)
assets/typography.csv	73	Font pairings with mood, Google Fonts URLs, Tailwind config
assets/products.csv	161	Product type -> style, landing pattern, dashboard, color focus
assets/ux-guidelines.csv	98	Do/Don't pairs with category + severity
assets/charts.csv	25	Data type -> best chart, accessibility grade, library

Lookup Priority

1. Start with products.csv — get overall design direction
2. Then colors.csv — get specific hex values
3. Then typography.csv — get font stack
4. Then ux-guidelines.csv — verify against common mistakes
5. charts.csv — only if data visualization needed

Example Lookups

"Need colors for a fintech dashboard"
-> Filter colors.csv rows where product type contains "fintech"
-> Get: #F59E0B gold primary + #8B5CF6 purple accent

"Need fonts for a tech startup landing page"
-> Filter typography.csv where mood contains "bold" or "innovative"
-> Get: Space Grotesk (heading) + DM Sans (body)
-> Copy the Google Fonts URL and Tailwind config

"Building a mental health app"
-> Read products.csv, find "mental health" row
-> Get: calming style, lavender palette, soft animations, accessibility-first

"Need to show trends over time"
-> Read charts.csv, find "time series" or "trend"
-> Get: Line chart (primary), Area chart (secondary), use Recharts or D3

Design Patterns

Style Categories

Style	Key Traits	Best For
Minimalism	White space, limited palette, thin typography	SaaS, portfolios, docs
Glassmorphism	Frosted glass, blur, transparency, subtle borders	Dashboards, modals, cards
Neumorphism	Soft shadows, extruded/inset, monochrome base	Settings panels, controls
Brutalism	Raw, bold type, harsh colors, exposed structure	Creative agencies, portfolios
Bento Grid	Card-based grid, mixed sizes, clean gaps	Feature showcases, dashboards
Dark Mode	Dark backgrounds, high-contrast accents, reduced blue light	Dev tools, media, productivity
Flat Design	No shadows, solid colors, simple shapes	Mobile apps, icons, infographics
Skeuomorphism	Real-world textures, depth, realistic elements	Games, music apps, niche tools

Color Palette by Product Type

Product Type	Primary Direction	Accent Direction
SaaS / Business	Blue, Indigo	Green for success, Orange for CTA
E-commerce	Brand-specific	Red/Orange for urgency, Green for trust
Healthcare	Teal, Blue	Soft green for positive, warm gray for neutral
Finance	Navy, Dark blue	Gold/amber for premium, green for growth
Creative / Portfolio	Flexible — match brand personality	High-contrast accent
Developer tools	Dark bg, cool grays	Cyan/green for syntax, warm for warnings

Typography Principles

• Heading + Body: contrast weight/style (e.g., bold geometric heading + regular humanist body)
• Max 2 families: one for headings, one for body. More = visual noise
• Scale: use a modular scale (1.25 or 1.333 ratio) for consistent hierarchy
• Line height: 1.5-1.75 for body text, 1.1-1.3 for headings
• Line length: 65-75 characters for readability

Accessibility Standards (WCAG 2.1 AA)

Color Contrast

Element	Minimum Ratio
Normal text (<18px)	4.5:1
Large text (>=18px or >=14px bold)	3:1
UI components & graphical objects	3:1
Decorative elements	No requirement

Rule: Never use color alone to communicate information. Always pair with icon, text, or pattern.

Touch Targets

Element	Minimum Size	Minimum Spacing
Buttons, links, controls	44x44px	8px gap
Icon-only buttons	48x48px	8px
Form inputs	44px height	-

Keyboard Navigation

• All interactive elements reachable via Tab
• Visible focus indicator (2px+ outline, 3:1 contrast)
• Escape closes modals/dropdowns
• Arrow keys navigate within groups (tabs, menus, lists)
• No keyboard traps (can always Tab out)

Screen Readers

• All images: meaningful alt text or aria-hidden="true" for decorative
• Heading hierarchy: h1 -> h2 -> h3 (no skipping levels)
• Form inputs: associated LABEL or aria-label
• ARIA landmarks: MAIN, NAV, ASIDE, FOOTER
• Dynamic content: aria-live="polite" for updates

Motion & Animation

• Respect prefers-reduced-motion — disable non-essential animations
• Animation duration: 150-300ms for micro-interactions
• No auto-playing video/audio without user control
• Loading spinners: include aria-busy="true" on container

Forms

• Error messages adjacent to field (not just top of form)
• Required fields: visual indicator + aria-required="true"
• Inline validation on blur (not keystroke)
• Clear error recovery path (what went wrong + how to fix)

Quality Checklist

Run through before any design handoff. All items must pass.

Visual Quality

• [ ] No emoji used as icons — use SVG or icon library
• [ ] Consistent spacing (8px rhythm: 8, 16, 24, 32, 48)
• [ ] Color palette limited to 1 primary + 1 accent + neutrals
• [ ] Typography uses max 2 font families
• [ ] All interactive elements have hover, active, focus, disabled states
• [ ] Dark mode: backgrounds use true dark (not pure black), text has sufficient contrast

Responsive

• [ ] Works at 320px width (no horizontal scroll)
• [ ] Touch targets >= 44x44px on mobile
• [ ] Navigation collapses to hamburger/bottom nav on mobile
• [ ] Images scale without distortion
• [ ] Tables scroll horizontally or restructure on mobile

Accessibility

• [ ] Color contrast passes WCAG 2.1 AA (4.5:1 normal, 3:1 large)
• [ ] All images have alt text (or aria-hidden for decorative)
• [ ] Keyboard navigation works for all interactive elements
• [ ] Focus indicators visible (2px+ outline)
• [ ] Form fields have labels
• [ ] Error messages are descriptive and adjacent to field

Performance

• [ ] Images optimized (WebP/AVIF, appropriate dimensions)
• [ ] Fonts loaded with font-display: swap
• [ ] No layout shift from loading content (CLS < 0.1)
• [ ] Critical CSS inlined or preloaded
• [ ] Lazy load below-fold images

Interaction

• [ ] Loading states for async actions (spinners, skeletons)
• [ ] Empty states designed (not just blank screens)
• [ ] Error states have recovery path
• [ ] Success feedback for completed actions (toast, checkmark)
• [ ] Confirmation for destructive actions (delete, discard)

Gotchas

• Aesthetic over accessibility: beautiful design that fails WCAG — check contrast (4.5:1 normal, 3:1 large) before shipping
• Desktop-first design: designing for large screens then cramming into mobile — start from 320px
• Color-only communication: red/green for status — pair with icon or text label
• Ignoring the data: guessing palette when colors.csv has WCAG-verified values — always look up first
• Generic product assumptions: all SaaS looks the same — check products.csv for product-specific recommendations

Common Use Cases

• Bootstrapping a design system for a new SaaS product
• Auditing an existing UI for WCAG 2.1 AA compliance
• Selecting a color palette and font pairing based on product type
• Reviewing UX patterns against 98 established guidelines
• Choosing the right chart type for dashboard data visualization
• Running the quality checklist before production deployment

Example Prompt

/mk:ui-design-system palette I'm building a fintech dashboard. Based on the data assets, what color palette, font pairing, and UX patterns do you recommend? Pull from colors.csv and typography.csv for WCAG-verified combinations.

Pro Tips

• Always start with products.csv for overall direction — it informs all other decisions
• Every palette in colors.csv is WCAG-verified — no need to manually check contrast for recommended combinations
• Use the UX guidelines CSV to catch mistakes before they reach review
• The quality checklist is your last gate — nothing ships without all checkboxes marked
• Filter ux-guidelines.csv by severity first (CRITICAL -> HIGH -> MEDIUM) for efficient reviews