UI Design Intelligence — Tvastar v4.0

18 libraries · 24 styles · 86 lint rules · 14 intelligent slots · March 2026

The /design Workflow — 7 Steps (follow in exact order)

Step 1 — Scan the stack

python3 .claude/skills/ui-design-intelligence/scripts/detect_stack.py

Detects: framework, Tailwind v3/v4, all 18 libraries (React Bits, Aceternity, Magic UI, Tremor, Animata, Motion Primitives, Cult UI, Eldora UI, Kibo UI, Origin UI, etc.)

READ NOW based on detection:

• has_react_bits: true → read references/react-bits-catalog.md
• Any new 2026 lib detected → read references/component-library-catalog.md
• Next.js detected → read references/nextjs-guidelines.md (Next.js 15 + React 19)
• shadcn/tailwind detected → read references/shadcn-tailwind-guidelines.md
• Vue/Nuxt detected → read references/vue-svelte-guidelines.md

Step 2 — Understand the request

Extract: What (page/component), Aesthetic (style keywords), Constraints, Existing colors. Ask ONE clarifying question only if completely blocked. Never ask multiple questions.

Step 3 — Live Research (always run)

READ NOW: references/resources-blogs.md — full search routing brain with 2026-updated sources.

Run at minimum 2 web searches:

1. "[product type] design inspiration 2026 site:dribbble.com"
2. "[aesthetic] UI site:godly.website OR site:awwwards.com"
3. (if new library needed) "[library name] component examples site:github.com"

Extract from results: dominant visual treatment, typography scale, ONE unexpected interaction.

Step 4 — Generate design system

python3 .claude/skills/ui-design-intelligence/scripts/design_system.py \
  --product "[type]" --style "[keywords]" [--dark] [--persist] \
  --page landing|dashboard|auth|pricing|portfolio|feature

The output contains ALL of these — read every section:

• PALETTE + COLOR SCIENCE — WCAG ratios, failing colors with suggested fixes
• TYPOGRAPHY — pairing + Fontshare/Google URL + weights
• TYPE SCALE — display→caption with exact px/rem values
• ANIMATION TOKENS + MOTION DURATION TABLE — exact ms + easing per context
• STYLE PROFILE — effects to use, anti-patterns to avoid
• COMPONENT LIBRARY SELECTIONS — 14 slots, each mapped to the RIGHT library:
  • background, hero_text, sub_text, cta_button, feature_cards, stats
  • testimonials, logos, borders, mobile_menu, navigation
  • delight (cursor/wow effect), forms (if form present), charts/kpi_cards (if dashboard)
  • advanced_ui (kanban/datepicker if enterprise)
• INSTALL COMMANDS — exact npx/npm/copy commands per library
• INSPIRATION BENCHMARKS — product-type-specific reference sites
• SENIOR DESIGNER EYE TEST — 8-point quality checklist
• GESTALT CHECKS — 7 principles applied to this specific palette
• REACT BITS INSTALL — TS+TW variants for TypeScript
• PSYCHOLOGY LAWS — 3 UX laws applied to this product
• PAGE PATTERN — section-by-section layout blueprint
• CHART TYPE GUIDANCE — appears for dashboard/analytics
• PRE-DELIVERY CHECKLIST — 15 must-pass gates

READ NOW (framework-specific):

• Next.js → references/nextjs-guidelines.md (Next.js 15, React 19, Turbopack, PPR, params awaiting)
• shadcn/Tailwind → references/shadcn-tailwind-guidelines.md
• React/Vite → references/react-guidelines.md
• Vue/Nuxt → references/vue-svelte-guidelines.md
• SwiftUI/Flutter → references/native-guidelines.md

Step 5 — Design plan (WAIT for approval — never skip this)

Show this exact format:

╔══ TVASTAR DESIGN PLAN ═════════════════════════════════════════╗
║ Building:        [what exactly]                                 ║
║ Style:           [name + 1-line why it fits]                    ║
║ Research:        [2 sites studied + key insight from each]      ║
║                                                                 ║
║ PALETTE          Primary — CTA — Bg   [WCAG ratios]            ║
║ TYPOGRAPHY       [Heading] / [Body]   [scale name]             ║
║                                                                 ║
║ STATEMENT PIECE  [lib: component] — the one wow moment         ║
║ SUPPORTING       [slot: lib/component] × 4-5 key slots         ║
║                                                                 ║
║ UX LAWS          [law 1 + how applied]                         ║
║                  [law 2 + how applied]                         ║
║ GESTALT          [principle + application]                      ║
║                                                                 ║
║ MISSING LIBS?    [install commands if anything not installed]   ║
╚═════════════════════════════════════════════════════════════════╝
Build with this plan? (yes / change [what])

Step 6 — Build production code

Output order: globals.css/@theme → install commands → component code.

READ NOW during code generation:

• Page patterns → references/page-patterns.md (section order, mobile-first, empty states)
• Icons/charts → references/charts-icons-reference.md (chart matrix, Lucide lookup)
• Animations → references/motion-principles.md (library-specific patterns, duration table)
• UX laws → references/ux-principles.md (Gestalt, psychology laws)

Cover every state: default → hover → focus → active → loading → disabled → error → empty state

2026 code standards:

• Next.js 15: await params and await searchParams — they are Promises
• React 19: useActionState not useFormState | use() hook for async | useFormStatus
• Tailwind v4: @theme {} not tailwind.config.ts extend | bg-linear-to-r not gradient
• Framer Motion: useReducedMotion() on EVERY animation component
• React Bits: TS+TW variant — https://reactbits.dev/r/ComponentName-TS-TW
• No raw <img> in Next.js — always next/image
• No key={index} — always key={item.id} or stable string
• All <button> and icon-only elements have aria-label
• focus-visible:ring-2 ring-primary on every interactive element

Step 7 — Lint + heal

python3 scripts/framework_lint.py [file] --stack-check   # 86 rules, auto-detects all frameworks
python3 scripts/heal.py [file]                           # auto-fix Critical+High

Fix ALL 🔴 High immediately. Report 🟡 Medium with specific fixes.

18-Library Tier System

Tier 1 — Foundation (always present)

shadcn/ui + Tailwind CSS — accessible base, keyboard navigation, theming

Tier 2 — Statement Visual WOW (1-2 per design, chosen by style)

Tier 3 — Structural Sections

Tier 4 — Data & Forms

Tier 5 — Framework-Specific

Intelligence Rules (select_compon