Beyond UI

Beyond UI

The goal is a UI that a working designer would sign their name to. That never comes from an agent inventing a gradient hero from memory. It comes from studying what already wins, stealing the structure, and composing it from libraries that solved the hard parts first.

Two failure modes this skill exists to kill:

1. AI slop — centered hero, three feature cards, Inter everywhere, purple-blue gradient, emoji icons, transition-all duration-300 on everything, rounded-2xl bg-white/10 backdrop-blur.
2. Skipping the scout — writing CSS from scratch because it is faster than looking anything up. It is not faster. It is how the first failure mode happens.

Non-negotiables

0. Install the upstream skills before you work — no bypass. Beyond UI is a composition layer over the design skills named in references/SKILLS.md. Run node scripts/bootstrap-upstream-skills.mjs first (or the manual npx skills add … equivalents it prints). If something cannot be installed, read its raw SKILL.md from the source URL and record the miss in .beyond-ui/state.json → skills.missing. Never proceed as though a skill had been read, and never paraphrase one from memory instead of fetching it.
1. Scout before you design. No layout, palette, type scale or animation is chosen before references/SCOUT.md has been executed and its findings written down. The scout result is an artefact (.beyond-ui/scout.md), not a vibe.
2. Reuse beats invention, every time. If a component, effect or animation exists in references/LIBRARIES.md or references/COMPONENTS.md, use it. Hand-rolled is the fallback for the 5% that is genuinely bespoke, and it must match the quality of what it stands in for. The same applies to 3D: a scene that needs WebGL is built with Three.js / react-three-fiber (or Threlte/TresJS, or model-viewer for a plain GLB) — via references/THREEJS.md — never with a hand-rolled canvas, a CSS fake, or a video pretending to be interactive 3D.
3. shadcn/ui is the component base. Every button, input, dialog, dropdown, table, form control, toast, tab, sheet, tooltip and menu comes from shadcn/ui unless a documented reason forbids it (see references/SHADCN.md → "When not to use shadcn"). Raw <button>, <input>, <dialog> and hand-built dropdowns are a defect, not a style choice.
4. Motion is mandatory, but never decorative-only. Scroll reveals, state transitions, and micro-interactions are expected. Animation that does not communicate hierarchy, causality or state is noise. Every motion decision respects prefers-reduced-motion.
5. No unverified UI claims. "Looks great" is not evidence. A UI change is done when it was rendered and looked at — screenshot at 3 viewports minimum (see § Verify).
6. Do not ship generic copy. Placeholder lorem, "Empower your workflow", "Supercharge your team" and unnamed customer logos are defects. Write real, specific, product-true copy or use the project's own domain language.
7. Preserve the project's identity. If the project has a brand, palette, type stack or design system, that wins over your taste. Beyond UI upgrades craft, not identity, unless a redesign was explicitly requested.

The workflow

0a BOOTSTRAP install the upstream design skills; verify they are present (no bypass)
0b RECON     stack, brand, existing design system, motion budget, target audience
1 SCOUT      galleries + prompt sources + registries, filtered to this product's domain
2 DIRECTION  pick ONE direction, write the design contract (type, colour, spacing, motion, references)
3 COMPOSE    shadcn base -> animated registry components -> effects; only then custom code
4 BUILD      token-driven Tailwind, real copy, real states (loading/empty/error), responsive
5 CRITIQUE   run the anti-slop checklist against the rendered page, fix, re-render
6 VERIFY     screenshots at 3 viewports + reduced-motion pass + a11y pass + report

Steps 1 and 2 are the ones agents skip. They are the ones that decide whether the output looks designed. Budget them: scout is ~15–25% of the work, not a formality.

0a. Bootstrap — mandatory, before anything else

node scripts/bootstrap-upstream-skills.mjs          # add --global for user scope, --check to report only

This installs the upstream design skills this skill composes — impeccable, hallmark, ui-ux-pro-max, taste-skill, Anthropic frontend-design, Addy Osmani frontend-ui-engineering, the Vercel skills (web-design-guidelines, react-best-practices, composition-patterns, react-view-transitions, react-native-skills), bencium design, accesslint, the Refactoring-UI port and skill-creator — via the official npx skills CLI, cloning anything that is not CLI native (and keeping it as reference material when a repo ships no SKILL.md). references/SKILLS.md holds the full matrix, the manual commands, the conflict rulings, and the proof required that they were actually followed.

scripts/bootstrap-upstream-skills.sh is the bash equivalent for POSIX shells.

Rules: run it once per project (re-running is idempotent); if a source cannot be installed, fetch its raw SKILL.md URL and read it instead — a one-line npx skills use <repo>@<skill> | claude also works for a single skill without installing; record skills.installed / skills.missing in .beyond-ui/state.json. Proceeding without this step, or claiming compliance with a skill that was never fetched, is a hard fail.

0b. Recon (≤ 10 tool calls)

Scaffold the run: node scripts/scaffold-state.mjs creates .beyond-ui/state.json (from assets/state-template.json) and .beyond-ui/scout.md, without overwriting an existing run.

Then read the project before deciding anything: framework and version (Next/Vite/Astro/Svelte/RN), Tailwind version, existing components/ui (is shadcn already installed?), tokens/theme file, font loading, image pipeline, package.json animation deps, and the actual product domain. Check whether shadcn is present before running init — re-initialising a customised system is destructive.

Everything the scout returns is filtered by the recorded stack: a Tailwind v3 snippet in a v4 project is the most common copy-paste break, and a framer-motion registry in a motion project installs a second, conflicting animation library.

1. Scout

Execute references/SCOUT.md. It defines the source universe (50+ inspiration galleries, 50+ prompt/template sources, 45+ component and animation libraries) and the protocol for using it: pick the product's domain and aesthetic keyword set, pull 6–10 concrete references from the galleries, pull 3–5 structural prompts from the prompt sources, then map every visual element you intend to build to a library that already ships it.

Output .beyond-ui/scout.md with: references: (URL + what is stolen from it), library map: (element → library → exact install/registry command), rejected: (what you saw and why it does not fit). This file is the design's justification; a UI with an empty scout file is unfinished.

2. Direction — the design contract

Write two things, in this order.

The Design Read — one line, before any code: surface, audience, and the visual language you are reading the brief as. "Reading this as: B2B SaaS landing for technical buyers, with a Linear-style minimalist language and one kinetic moment in the hero." If the brief is ambiguous on something that changes the design, ask exactly one question rather than guessing wide.

Then the contract:

• Aesthetic name — one phrase ("Swiss editorial with a warm paper substrate", "dense terminal brutalism", "soft neumorphic fintech"). Not "modern and clean".
• Type — display + body + mono faces, with the exact loading strategy. Banned as the only choice: the default system stack, Inter-by-reflex, and any face the project already uses unless it is genuinely the right answer. references/DESIGN.md lists the vetted type sources.
• Colour — the actual values (OKLCH preferred), with the neutral ramp, one accent, one signal colour, and the surface/elevation strategy. No purple-on-dark-gradient default.
• Spacing & rhythm — the scale, the section rhythm, the max content width, the grid.
• Motion — the easing set, the durations, the entrance strategy, the scroll behaviour, and the reduced-motion fallback. Reference references/MOTION.md.
• References — the 3+ real sites this direction is derived from.
• Non-goals — what this design deliberately will not do.

This contract is binding for the rest of the build. Deviating mid-build is how a page ends up with five competing aesthetics.

3. Compose

Order is fixed, and it is the whole point of this skill:

1. shadcn/ui first — install the primitives the surface needs (npx shadcn@latest add …), then restyle via tokens/CSS variables, never by forking the component into a one-off.
2. Animated registries second — Magic UI, Aceternity, animate-ui, React Bits, Kokonut, Cult, Syntax, Hover.dev, Motion Primitives, Animata; see references/COMPONENTS.md for commands.
3. 3D / WebGL third, when the brief is 3D — read references/THREEJS.md first: it decides whether 3D is justified, picks the library (three.js → react-three-fiber + drei; Threlte/TresJS for Svelte/Vue; model-viewer for a plain GLB viewer), and gives the asset pipeline (gltfjsx --transform, Draco + KTX2), the scene patterns, and the performance/accessibility guards.
4. Effects fourth — Anime.js v4, GSAP (+ free plugins), Motion, Lenis, shaders, SVG animation, liquid glass; see references/LIBRARIES.md and references/EFFECTS.md.
5. Custom last — only what is genuinely bespoke, written to the same standard, reusing the project's tokens and the primitives' patterns (Radix behaviours: focus trap, aria wiring, escape).

4. Build

• Tailwind utilities bound to tokens; no magic hex in JSX. Dark mode is a token swap, not a second stylesheet.
• Real states: loading (skeletons matching the real geometry), empty (with a real next action), error, partial, offline, permission-denied. A page with only the happy path is unfinished.
• Responsive by construction: design the 390px layout, then the 768px, then the wide one. Reflow intentionally — do not let the desktop layout shrink.
• Accessibility is not a polish step: semantic landmarks, one h1, labelled controls, visible focus, contrast ≥ 4.5:1 in both themes, keyboard-complete flows.

5. Critique

Run references/CRITIQUE.md against the rendered page, not the source. It is a scored checklist with hard fails (the slop detectors) and quality gates (hierarchy, rhythm, restraint, detail). Fix every hard fail, then the lowest-scoring gate, then re-render before scoring again.

6. Verify

A UI change is complete when all of these were observed:

Record the artefact paths in .beyond-ui/state.json, then emit the pre-emit critique stamp and report in ≤ 8 lines: Design Read, direction chosen, files touched, libraries used, checks run with results, and anything deliberately deferred. An axis below 3 in the stamp means a revision pass is still owed — the work is not done.

Routing table — read the reference when you reach that step

Traps

• Scout theatre. Opening three galleries, "getting inspired", and writing the same generic hero. The scout file must name URLs and say what was taken from each.
• Skipping the bootstrap. Writing a landing page from memory while the upstream skills sit uninstalled. If skills.missing is non-empty, read the raw SKILL.md files before building.
• Registry roulette. Installing eight animated components that do not share an aesthetic. The direction contract decides which two or three registries are in play.
• Version drift. Copying a Tailwind v3 / framer-motion snippet into a v4 / motion project. Check the stack first; adapt or skip.
• Motion everywhere. Every element fading up on scroll is its own kind of slop. Motion earns its place by signalling hierarchy, cause, or state change.
• Glassmorphism as a personality. Blur + translucent borders + gradient blobs is one aesthetic, not a default — and it needs the @supports fallback plus a contrast check.
• Designing past the content. A beautiful shell around placeholder text ships as a placeholder.
• Ignoring the existing design system. A parallel set of tokens and components duplicates the project's and breaks it. Extend, do not fork.
• Accessibility as a final pass. Retrofitted a11y is always worse and always more expensive.
• Copying a reference wholesale. Steal grammar (section order, density rhythm, motion behaviour), never a full site's identity, copy, imagery or assets.