# Beyond UI

> Use when building, redesigning, styling or polishing any user interface - landing pages, marketing or SaaS pages, dashboards, admin panels, web apps, mobile screens, or a single component - where the result should look designed by a senior product designer rather than generated by AI. Use it whenever the user asks for UI work or mentions a landing page, hero, pricing page, dashboard, shadcn, Tailwind, animations or transitions, or "make it look good/professional/modern", even if the skill is not named and the task looks small. It installs the upstream design skills, scouts award-winning galleries, template prompts and animated component registries, then composes from shadcn/ui and those libraries instead of inventing layout, motion and styling from scratch. Trigger phrases include "beyond-ui", "no AI slop", "make it beautiful", "award-winning", "awwwards level", "design a landing page", "build the UI", "redesign this page", "it looks AI generated", "add animations", "polish the UI".

- Skill: `jeetaksh25/beyond-ui` (Agent Skill, multi-file: 24 files)
- Install (CLI): `npx skillmds@latest add jeetaksh25/beyond-ui`
- Raw SKILL.md: https://api.skillmd.com/api/skills/jeetaksh25/beyond-ui/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Marketing & Growth
- License: MIT
- Author: Jeetaksh25 (https://skillmd.com/u/jeetaksh25)
- Updated: 2026-09-22
- Page: https://skillmd.com/skills/jeetaksh25/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

```bash
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:

| Check | Pass condition |
|---|---|
| Render | Screenshots at 390 / 768 / 1440 (and the project's real breakpoints) — visually inspected |
| Reduced motion | With `prefers-reduced-motion: reduce`, nothing critical disappears and no layout breaks |
| Keyboard | Full interactive flow reachable and operable by keyboard, focus visible throughout |
| Console | No errors/warnings from the new code; no hydration mismatches |
| Perf smoke | No new long tasks on load; hero animation does not regress LCP; no CLS from late-loading fonts/images |
| 3D (when present) | Poster is the LCP element; scene paused off-screen; frozen under reduced motion; asset bytes and throttled FPS recorded (`references/THREEJS.md`) |
| Token discipline | No raw hex/`px` outside tokens; dark mode verified |
| Registry integrity | Every added registry component still updates/compiles; unused ones removed |

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

| Need | Reference |
|---|---|
| Source universe + scout protocol + `.beyond-ui/scout.md` schema | `references/SCOUT.md` |
| Component registries, exact install commands, Tailwind/peer compatibility | `references/COMPONENTS.md` |
| shadcn/ui setup, theming, tokens, extension, when not to use it | `references/SHADCN.md` |
| Motion: easings, durations, patterns, GSAP/Motion/Anime/Lenis choice | `references/MOTION.md` |
| Effects: WebGL, shaders, SVG, liquid glass, grain, text effects | `references/EFFECTS.md` |
| 3D scenes: WebGL/Three.js/R3F playbook, libraries, asset pipeline, performance | `references/THREEJS.md` |
| Type, colour, spacing, layout, hierarchy craft rules | `references/DESIGN.md` |
| Award-winning inspiration galleries (50+) | `references/INSPIRATION.md` |
| Template/prompt sources (50+) | `references/PROMPTS.md` |
| Library index — install facts, framework support, licence | `references/LIBRARIES.md` |
| Upstream design skills this skill composes and defers to | `references/SKILLS.md` |
| Anti-slop hard fails + quality gates, scored | `references/CRITIQUE.md` |
| Copy, content shape, microcopy, SEO/OG surface | `references/CONTENT.md` |
| Accessibility and performance rules constraining motion | `references/A11Y-PERF.md` |
| Per-stack recipes (Next, Vite, Astro, Svelte, Vue, React Native) | `references/STACKS.md` |
| Bootstrapping the upstream skills (mandatory phase 0) | `scripts/bootstrap-upstream-skills.mjs` (`.sh` for POSIX shells) |
| Scaffolding the run state + scout artefact | `scripts/scaffold-state.mjs` |
| The scout artefact to fill in | `assets/scout-template.md` |
| The run state to fill in (skills, stack, registries, gates, evidence) | `assets/state-template.json` |
| Machine-readable registry + npm facts (versions, commands, verified dates) | `assets/registry-sources.json` |
| Worked end-to-end walkthrough | `references/EXAMPLES.md` |

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