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 / static files only          → 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.

Design Read first. One line: page type · audience · atmosphere · aesthetic family · light/dark/tinted. Every later choice serves it.
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.
Anchor dark surfaces with a Scene Sentence — never default to
```
#0a-#0f
```
blue-black.
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
```
).
Copy reads human, not LLM. No buzzwords, no aphoristic "Simple. Fast. Powerful.", no fake-precise numbers, no scroll cues, zero em-dashes.
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
```
.
Light/dark theme with a toggle, CSS custom properties, system-preference default,
```
localStorage
```
persistence — both themes fully designed, not just inverted.
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 — 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.

AI-generated visual assets (optional quality boost)

When the user wants a premium, polished look — or when the project would benefit from custom imagery (hero backgrounds, logos, decorative illustrations, themed graphics) — load the image-create skill and use it to generate visuals with AI.

When to use:

Landing pages, portfolios, or dashboards where a custom hero image would elevate the design
Projects where the user explicitly wants "better looking" / "more polished" / "premium" output
Any time a stock photo or generic gradient feels insufficient

How to use:

Load the
```
image-create
```
skill (read its SKILL.md) and follow its instructions to generate an image with a prompt that matches the project's Design Read (atmosphere, aesthetic family, color palette)
The generated image is saved to
```
output/images/
```
. You MUST copy it into the project's preview/serve directory before referencing it in HTML:
```
bash("cp output/images/GENERATED_FILE.png output/projects/{slug}/src/hero.png")
```
Reference the image with a relative path in HTML:
```
url('./hero.png')
```
— NOT
```
url('../images/...')
```
. Preview can only serve files within its own directory.
If image generation fails, fall back to CSS gradients or abstract SVG patterns — never leave a broken
```
<img>
```
or
```
background-image
```
reference.

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

ui-design

NPX Install

Tags

SKILL.md Content