v1.0.3 to v1.2.0

- version: 1.0.3

- 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.

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

- 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.

- 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.

- ## 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:**

- 1. 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)

- 2. 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")

- ```

- 3. Reference the image with a **relative path** in HTML: `url('./hero.png')` — NOT `url('../images/...')`. Preview can only serve files within its own directory.

- 4. 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 |