v1.0.0 to v1.0.1

---

name: ui-design

description: |

The UI/UX quality gate and build guide for every visual output — landing pages, dashboards,

web apps, portfolios, tools, any HTML the user will see. Merges visual-design methodology

(palette, typography, layout, anti-AI-slop) with concrete build guidance, including when and

how to use open-source component libraries (shadcn/ui, HeroUI, coss ui) to reduce work and

raise quality.

MUST USE together with project-builder whenever a project produces visual HTML/CSS/JS.

project-builder owns the engineering workflow; this skill owns how the result looks and feels.

metadata:

starchild:

emoji: 🎨

requires:

bins: []

install: []

---

# UI Design Skill

Make every visual output look like a professional designed it — never generic AI slop — while doing the least hand-work necessary. This skill is the single entry point for all UI/UX decisions; it replaces the older `project-design` and `dashboard` skills.

## When to use

Any time you generate HTML/CSS/JS the user will see: landing page, dashboard, web app, portfolio, internal tool, settings page, a single chart panel — anything visual. If it renders, this skill applies.

---

## Step 1 — Pick the track

Two ways to build a UI. Choose deliberately; they are not interchangeable.

| | **Track A — Hand-built** | **Track B — Component library** |

|---|--------------------------|----------------------------------|

| What | You write the markup + Tailwind/CSS yourself | You pull accessible React components from shadcn/ui, HeroUI, or coss ui |

| Best for | Single-file previews, quick dashboards, emails, anything with **no build step** | Real React/Next/Vite apps with forms, modals, tables, date pickers the user will keep |

| Build step | None — static `preview` | Bundler required (Vite/Next) + `preview` with `command`+`port` |

| Read | `references/design-process.md` (+ aesthetics/components/animations/charts) | `references/component-libraries.md` |

Decision shortcut:

```

No build step / throwaway preview / must be one portable file → Track A

Real app, lots of interactive components, user will extend it → Track B

User named "shadcn" / "HeroUI" / "Cal.com look" / "Origin UI" → Track B (that library)

Just a dashboard? → either track + references/dashboards.md

```

**Taste is required on both tracks.** A component library gives correct, accessible parts — it does NOT give a point of view. The palette / typography / layout-rhythm / anti-slop / copy rules from `design-process.md` apply on top of the library, or every app looks identically generic.

---

## Step 2 — Always-on design discipline (both tracks)

These are the non-negotiables. Full methodology, banned-value lists, and the pre-delivery checklist are in `references/design-process.md` — read it before writing markup on Track A, and for the taste layer on Track B.

1. **Design Read first.** One line: page type · audience · atmosphere · aesthetic family · light/dark/tinted. Every later choice serves it.

2. **Spin the Design Dials** (Track A) to avoid converging on the same dark-blue-card layout every time: Surface · Accent · Typography · Aesthetic Family, derived from the current UTC time. User-stated preferences always override the dials.

3. **Anchor dark surfaces with a Scene Sentence** — never default to `#0a-#0f` blue-black.

4. **Banned by default:** Inter/Roboto/Arial fonts; generic blue (`#3b82f6`) and AI purple (`#8b5cf6`/`#6366f1`); cream/beige backgrounds; blue-black dark; em-dashes in copy; marketing buzzwords; centered-hero-plus-three-cards; `border-radius > 16px` on cards; gradient text; `transition: all`; `100vh` (use `100dvh`).

5. **Copy reads human, not LLM.** No buzzwords, no aphoristic "Simple. Fast. Powerful.", no fake-precise numbers, no scroll cues, zero em-dashes.

6. **Accessibility is mandatory:** ≥4.5:1 body contrast, visible focus rings, alt text, sequential headings, `aria-label` on icon buttons, color never the sole signal, 44×44px touch targets, `prefers-reduced-motion`.

7. **Light/dark theme** with a toggle, CSS custom properties, system-preference default, `localStorage` persistence — both themes fully designed, not just inverted.

8. **Refinement pass + checklist before delivery.** The instinct to add more is usually wrong; fix spacing, contrast, and typography instead. Run the pre-delivery checklist in `design-process.md`.

---

## Step 3 — Reduce work with open-source component libraries (Track B)

When there's a build step, don't hand-roll dropdowns, dialogs, and date pickers — that's where hand-written code fails on a11y and keyboard handling. Pull them from a library instead.

| Library | Model | Reach for it when |

|---------|-------|-------------------|

| **shadcn/ui** | Copy-paste via CLI + registry + **MCP** (Radix/Base UI + Tailwind) | Largest ecosystem, you want to own/edit every component; lowest-effort for an agent via MCP/CLI |

| **HeroUI v3** (was NextUI) | **npm package**, auto-updating (React Aria + Tailwind v4) | Polished defaults with zero maintenance; just update the package |

| **coss ui** (was Origin UI) | Copy-paste (Base UI + Tailwind), Cal.com's system | Dense, production-grade Cal.com-style UI; OK with beta churn |

> **Never paste component code into work from memory.** These libraries ship fast and APIs drift. **Look up the current component + props at build time** — via the library's MCP server, its `llms.txt`, its CLI registry, or its docs page. The library's own source is the truth, every time. Exact lookup URLs, CLI/MCP setup, the copy-paste-vs-package tradeoff, and the build-step reality are in `references/component-libraries.md`.

Default when unspecified and a build is justified: **shadcn/ui** (MCP + CLI make it the lowest-effort), unless "zero maintenance" → HeroUI, or "Cal.com look" → coss ui.

### Advanced motion: GSAP (works on BOTH tracks)

Component libraries give you correct components; they don't give you cinematic motion. For scroll-driven storytelling, multi-step timelines, text-into-characters reveals, SVG morph/draw, or FLIP layout transitions, reach for **[GSAP](https://gsap.com/)** — now 100% free (incl. all former-paid plugins: ScrollTrigger, SplitText, MorphSVG, Flip…). Unlike the component libraries, GSAP is plain JS that loads via a CDN `<script>` tag with **no build step**, so it works in a single-file Track A preview *and* a Track B app.

Decision: plain CSS for hovers/toggles/simple reveals (the default — don't pull 50KB for a button); GSAP only when the motion is a *feature* (landing-page scroll story, hero text reveal, animated SVG). Full guidance — when-to-use table, CDN loading, core/timeline/ScrollTrigger API, plugin list, the React `useGSAP` hook, and the reduced-motion/cleanup rules — is in `references/animations.md` (GSAP section). Look up the current version and plugin APIs at gsap.com at build time; don't ship memorized snippets.

---

## Dashboards

For multi-panel monitoring views (portfolio, prices, system health), read `references/dashboards.md` after picking a track: it covers finding real data (Starchild proxied APIs + rate-limit math), real-time updates (polling/SSE/WebSocket), dashboard layout, loading/error/empty states, and performance. Charts setup is in `references/charts.md`. Never put fabricated numbers on a dashboard.

---

## Reference map

| File | Read when |

|------|-----------|

| `references/design-process.md` | The full quality gate — Design Read, Dials, Scene Sentence, all design rules, copy rules, anti-slop tests, theme support, pre-delivery checklist |

| `references/aesthetics.md` | Building a palette / choosing type — methodology + real-brand values + dark-surface tint guide |

| `references/components.md` | Hand-building nav, cards, tables, buttons, forms, hero, CTAs |

| `references/animations.md` | Motion — scroll reveals, hover, modals, entrance strategies, timing, **+ GSAP advanced-motion layer** (timelines, ScrollTrigger, SplitText, SVG, FLIP, useGSAP) |

| `references/charts.md` | Charts — Chart.js/ECharts setup, chart-type selection, mock data |

| `references/component-libraries.md` | shadcn/ui · HeroUI · coss ui — when to use which + how to look up components dynamically |

| `references/dashboards.md` | Data sourcing, real-time, dashboard layout, performance |