# Design UI

> Design and build polished, non-generic UI for this TanStack Start + React + Tailwind v4 + shadcn/Radix app. Use whenever you create or restyle any interface surface — pages, landing pages, dashboards, forms, modals, nav, and game overlays (start screens, HUD, menus). Covers design tokens, layout, typography, color, spacing, motion, and the anti-"AI-slop" rules that keep output from looking generic. Triggers on "design", "UI", "make it look good", "polish", "landing page", "theme", "style", "redesign", "ugly", "clean up".

- Skill: `deedlefake/design-ui` (Agent Skill, multi-file: 6 files)
- Install (CLI): `npx skillmds@latest add deedlefake/design-ui`
- Raw SKILL.md: https://api.skillmd.com/api/skills/deedlefake/design-ui/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Design & Media
- Author: deedlefake (https://skillmd.com/u/deedlefake)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/deedlefake/design-ui

---


# Design & UI

Make interfaces that look intentional and premium, not template-generic. This is
the single biggest quality lever in the app builder. Apply it to **DOM / overlay
UI** — pages, chrome, HUD, menus, forms. (For a 3D game's gameplay canvas, see
the `building-games` skill; this skill governs the DOM UI layered over it.)

**Read `references/` for depth** (loaded on demand — don't inline it all):
- `references/refined-ui.md` — the full product-chrome/overlay design system.
- `references/typography.md` — type scale, pairing, rhythm.
- `references/surfaces.md` — elevation, borders, shadows, layering.
- `references/animations.md` — motion, easing, transitions.
- `references/performance.md` — keep UI smooth (60fps, no jank).

---

## 1. Design-system-first (do this before styling anything)

Define the system once, then compose from it. **Never** sprinkle ad-hoc values.

- **Tokens in CSS (Tailwind v4 is CSS-first).** Put the palette, radii, and fonts
  in `src/styles.css` under `@theme` as CSS variables; consume them as Tailwind
  utilities. One source of truth.
  ```css
  @import "tailwindcss";
  @theme {
    --color-bg: #0b0b0f;      --color-surface: #16161d;
    --color-fg: #e7e7ea;      --color-muted: #a0a0ab;
    --color-primary: #14b8a6; --color-border: #26262f;
    --radius: 0.75rem;        --font-sans: "Inter", system-ui, sans-serif;
  }
  ```
- **Use shadcn/ui components** (Radix primitives + `cva` variants + `tailwind-merge`)
  for buttons, dialogs, dropdowns, inputs, etc. They're accessible and consistent.
  Generate them into `src/components/ui`; style via tokens, not inline hex.
- **Tailwind v4 base fix — buttons need a pointer cursor.** v4's Preflight makes
  `<button>` use `cursor: default`, which feels broken. Add this once in
  `src/styles.css` so buttons/clickable roles show a pointer:
  ```css
  @layer base {
    button:not(:disabled),
    [role="button"]:not(:disabled) { cursor: pointer; }
  }
  ```
- **Ban ad-hoc styling:** no raw hex in JSX, no `text-white`/`bg-black` literals,
  no arbitrary values like `p-[16px]` or `text-[13px]`. If you need a value,
  it becomes a token or a scale step.

## 2. The quantified rubric (cheap rules that prevent "ugly")

- **≤ 3–5 colors total** (one primary + neutrals + at most one accent). No random
  extra hues. Don't default to purple unless asked.
- **≤ 2 font families** (often one). Pair a display/heading with a body, or use one.
- **Line-height 1.4–1.6** for body; tighter for large headings.
- **When you override a background color, override the foreground/text color too**
  (contrast must hold — check both light and dark).
- **Mobile-first**: design the ~390px layout first, then scale up. No horizontal
  overflow; tap targets ≥ 44px.
- **Consistent spacing scale** (4/8-based). Generous whitespace beats cramming.
- **One accent, used sparingly** for primary actions — not everywhere.

## 3. Anti-AI-slop (the tells that make output look generic — avoid)

- **No gradient-blob filler**, no giant hero gradients as a substitute for content.
- **No emoji as icons** — use a real icon set (`lucide-react`).
- **No hand-drawn SVG** illustrations/maps/charts — use real libraries (`recharts`
  for charts) or real generated images.
- **No placeholder images / lorem-gray boxes** in the final product — generate
  real images or use real content; set `crossOrigin="anonymous"` on canvas images.
- **Avoid the overused-font look** (default system-only, or Comic Sans-tier picks).
- **Every element earns its place.** Cut decorative noise. Establish a system,
  then vary with intent — not randomness.
- **Match the existing UI when editing** an app in place; don't introduce a second
  visual language.

## 4. Layout & hierarchy

- Clear visual hierarchy: one primary action per view; size/weight/color express
  importance. See `references/typography.md` and `references/surfaces.md`.
- Use real layout structure (grid/flex, container max-widths), not absolute-position
  hacks. Align to a consistent grid.
- Empty states, loading states, and error states are part of the design — don't
  ship blank/janky intermediate states.

## 5. Motion (subtle, purposeful)

- Short, eased transitions (150–250ms) on hover/press/enter; respect
  `prefers-reduced-motion`. Details in `references/animations.md`.
- Never animate layout in a way that causes jank; prefer transform/opacity.

## 6. Game overlays (when this pairs with `building-games`)

The gameplay canvas is owned by `building-games`. This skill styles the **DOM
overlay**: start/"click to play" screen, HUD, score, menus, pause, mobile
controls. Keep overlay readable over the canvas (backdrop, contrast), and keep it
out of the pointer-lock/gameplay input path.

---

## Finish checklist (before you call UI done)
- Tokens defined in `@theme`; no ad-hoc hex / arbitrary values in JSX.
- ≤ 5 colors, ≤ 2 fonts, consistent spacing scale.
- Contrast holds; foreground overridden wherever background is.
- Mobile (~390px) has no overflow; targets ≥ 44px.
- Real icons/images/charts — none of the anti-slop tells.
- Loading/empty/error states handled; motion subtle and reduced-motion-safe.
- Rendered and eyeballed in a browser (see AGENTS.md verification), not just curl.