ddtcorex/maestro-skills/maestro-design

Maestro Design

Professional UI/UX implementation — design tokens, Figma→code, Tailwind + shadcn/Radix component system, a11y, responsive and motion.

When to Use

Trigger keywords: figma, tailwind, shadcn, design system, a11y, responsive, component, landing page, dashboard, scaffold UI, UI/UX.

Use this skill when you need to scaffold a design system, generate a component or page, convert a Figma file or image mockup to code, or audit UI for accessibility and responsive quality. Pairs with verification-before-completion for visual/Lighthouse/axe checks and with magento2-hyva-dev when theme.xml parent is Hyvä.

Design System Generator

Every generation starts by emitting a Design System Box for user approval before writing code. Adapted from ui-ux-pro-max v2.0, Maestro-opinionated:

+----------------------------------------------------------------------------------------+
|  TARGET: <Project Name> - RECOMMENDED DESIGN SYSTEM                                    |
+----------------------------------------------------------------------------------------+
|  PATTERN: <e.g., Hero-Centric + Social Proof>                                          |
|     Sections: Hero -> Features -> Testimonials -> Pricing -> FAQ -> CTA                |
|  STYLE: <e.g., Minimalism + Bento Grid>                                                |
|     Keywords: clean, grid, whitespace, soft shadows, rounded 16px                      |
|     Best For: SaaS, dashboards                                                         |
|     Performance: cost:low | Accessibility: risk:low                                    |
|  COLORS:                                                                               |
|     Primary: #...  Secondary: #...  CTA: #...                                          |
|     Background: #...  Text: #...  Muted: #...                                          |
|     Notes: <contrast rationale, 4.5:1 verified>                                       |
|  TYPOGRAPHY: <Heading / Body> — e.g., Inter / Inter                                   |
|     Mood: professional, readable                                                       |
|     Google Fonts: https://fonts.google.com/...                                         |
|  KEY EFFECTS: subtle hover 200ms, soft shadow, focus ring 2px                          |
|  AVOID (Anti-patterns): neon gradients for finance, emoji-as-icon, no focus ring      |
|  PRE-DELIVERY CHECKLIST: [ ] 8 items (see Pre-delivery Checklist)                      |
+----------------------------------------------------------------------------------------+

Pattern/style/colors/typography come from curated catalogs below and Figma extraction when available. See references/figma-workflow.md for the hybrid extract flow and references/tokens.md for token definitions. Do not write code until the user approves the Box or asks to proceed.

Curated Styles (15)

Fifteen Tailwind and shadcn viable styles distilled from ui-ux-pro-max 79. Each maps directly to Tailwind classes and shadcn variants with clear best for and do not use for guidance. Prefer these names in the Design System Box STYLE field so the style choice remains reviewable and searchable.

Each style in the Box should include keywords, performance cost, accessibility risk, and implementation checklist. For Tailwind details see references/tokens.md.

Industry Rules (12)

Twelve vertical rules curated for Maestro client work. The agent matches the prompt to the closest rule, refines with Figma tokens if present, and records conflicts in the Box AVOID field. If the user insists on an anti-pattern combination such as brutalism for banking, emit a warning and proceed only after explicit confirmation.

Typography mood links to Google Fonts. For token mapping see references/tokens.md.

Workflows

Scaffold vs Generate

Scaffold creates a durable design system that future generations reuse. Use when starting a project or when design-system/MASTER.md does not exist.

Steps:

1. Emit Design System Box and await confirmation.
2. Run npx shadcn@latest add for required primitives (Button, Card, Input, etc.).
3. Write tailwind.config.ts with tokens from references/tokens.md (colors, fontFamily, borderRadius, boxShadow).
4. Write app/globals.css CSS variables (--background, --foreground, --primary, --radius).
5. Write components/ui/* primitives and design-system/MASTER.md via the runtime's file-write tool.
6. Optionally scaffold stories/ for Storybook.

// tailwind.config.ts — scaffold output
export default {
  theme: { extend: { colors: { primary: "hsl(var(--primary))" }, borderRadius: { lg: "var(--radius)" } } }
}

Generate creates a single component or page and reuses the existing system. Use when design-system/MASTER.md exists or for one-off pages.

Steps:

1. Read design-system/MASTER.md and design-system/pages/<page>.md if it exists; page rules override master.
2. Emit Design System Box referencing the master so drift is visible.
3. Write the component or page file importing from @/components/ui/* with cursor-pointer on clickable and focus-visible:ring-2 on focusable elements.
4. Ensure responsive at 375, 768, 1024, 1440 and no horizontal scroll.
5. Run the Pre-delivery Checklist before handoff.

Hierarchical retrieval prompt for Generate:

I am building [Page]. Read design-system/MASTER.md, check design-system/pages/[page].md, prioritize page rules over master, and emit the Design System Box before coding.

See references/components.md for primitive variant tables and references/figma-workflow.md for Figma mapping.

Persist Pattern

Persisted design decisions live in design-system/ so future sessions and sub-agents share the same source.

design-system/
├── MASTER.md           # Global Source of Truth (pattern, style, colors, typography, spacing, effects, avoid, checklist)
└── pages/
    ├── dashboard.md    # Page-specific overrides (only deviations from MASTER.md)
    └── checkout.md

Workflow:

1. First generation in a project writes design-system/MASTER.md via the runtime's file-write tool after Box approval.
2. Per-page generation reads MASTER.md plus pages/<page>.md if it exists; page rules override master.
3. The hierarchical retrieval prompt above governs every Generate turn. The directory is git-ignored by default unless the team commits it.

Example MASTER.md header:

# MASTER — <Project> Design System
Pattern: Hero + Features + Pricing
Style: Minimalism + Bento Grid
Colors: primary #3B82F6, background #FFFFFF, text #0F172A (4.5:1)
Typography: Inter / Inter — https://fonts.google.com/specimen/Inter

Pre-delivery Checklist

Run this checklist verbatim before handing off any generated UI. Block delivery until every item passes; suggest an accessible alternative palette when contrast fails.

• [ ] No emoji as icons (use lucide-react/heroicons SVG)
• [ ] cursor-pointer on all clickable, focus-visible ring visible (2px)
• [ ] prefers-reduced-motion respected (motion tokens, motion prop)
• [ ] Text contrast 4.5:1 minimum (7:1 for enhanced), verified against chosen palette
• [ ] Text/chips/badges reflow without clipping at 375px, 200% zoom, user spacing overrides
• [ ] Responsive: 375, 768, 1024, 1440 tested (no horizontal scroll)
• [ ] Touch targets: 44pt iOS / 48dp Android / 24px web minimum + 8px gap (WCAG Target Size)
• [ ] Images have alt, icons have aria-label or aria-hidden, form has label + aria-describedby for errors

For the 20 resilient rules behind items 5 and 7 see references/a11y-motion.md.

Hyva Adapter

When the project has a Hyvä theme (detect via app/design/frontend/<Vendor>/<theme>/theme.xml parent Hyva/default or tailwind.config.js with Hyvä preset), adapt React and shadcn patterns to Alpine and Tailwind: