finesse-skill

---
name: finesse-ui
description: 'Build and refine high-craft web interfaces: brand sites, product dashboards and workflows, AI workbenches, commerce, H5/mobile screens, and individual components. Route by purpose, preserve project identity, and audit visual quality, accessibility and motion. Supports Apple-inspired / 苹果风 design through editorial, app and spatial modes with runnable card studies. Use for landing pages, portfolios, dashboards, admin panels, settings, agent consoles, product pages, checkout, mobile app UI, design-system extraction, redesign, typography, color, layout, animation, drag/swipe/sheet interactions and anti-generic iteration. Includes targeted audit, bolder, quieter, soul, diverge, animate, depth, densify, init and document workflows. Excludes backend-only tasks.'
version: 0.22.0
user-invocable: true
argument-hint: "[craft · audit · bolder|quieter|soul|diverge · animate|depth|densify · redesign · init|document] [target]"
license: MIT
metadata:
  short-description: Craft interfaces that never look cheap
---

# finesse — Technically Spectacular · Soul-Distinct · Never Cheap

> **finesse builds two kinds of interface and routes by register (§0):**
> - **brand** — design IS the product: landing pages, brand sites, launches, portfolios, hero pages. Optimize for **spectacle + soul + first impression** — a real visual engine, an opinionated personality.
> - **product** — design SERVES the product: dashboards, admin panels, analytics, data tables, app shells, settings. Optimize for **clarity + density + usability** — and still never cheap.
>
> The through-line is identical: **high craft, zero AI-slop.** What applies to **both** is the **universal craft floor** (tinted neutrals, no `#fff`/`#000`, translucent/hairline borders, tinted shadows, contrast floors), the cheapness blacklist (§6), and the pre-flight (§8). What **forks** is the *substrate above that floor* and the middle: **brand** lays the §3 brand substrate (`design-dna.md` — grain, vignette, display type) and reaches for a hero engine (§4); **product** lays its **own** substrate (`product-ui.md` §0 — surfaces, cards, KPI tiles, density) and reaches for a component system + data viz. A dashboard is a **different design language**, not a brand page with charts — it does **not** inherit grain / vignette / giant hero type / dark-default / a hero engine.
>
> **Two more registers sit alongside them, and they work differently from each other.** **commerce** (PDP/PLP/cart/checkout) is a *hybrid* — route it to brand or product by what the specific page is doing. **h5** (phone-only screens: app UI, 活动页, mobile PDP, report H5) is a **container**: it fixes the frame, the safe areas, the thumb hierarchy, and the OS furniture, then wraps one of the other three for the content grammar underneath. A mobile PDP is `h5` + `commerce`; an app dashboard screen is `h5` + `product`. h5 never replaces a content register — it wraps one.
>
> Every rule below is **contextual**. Nothing fires automatically. Read the brief, set the register, then pull only what fits. A skill that produces the same page for every brief has failed.

---

## Apple design language (optional)

For Apple style / 苹果风, read `references/apple-design.md` before choosing the substrate or persona. Keep the existing register, add `design-language=apple` and choose `apple-mode=editorial|app|spatial`. Its scoped overrides take precedence over conflicting aesthetic defaults below, including pure-black/white bans, mandatory grain/vignette, extreme leading and forced persona/engine rotation. Functional and accessibility gates still apply. Component requests retain component scope. Editorial recipes and seven runnable studies are indexed in `references/apple-patterns.md`.

## How to use this skill

0. **Check the scope before anything else.** If the brief is a **single element** — a button, an input, a card, a modal, a toast — go to `references/component-scope.md` and follow it instead; steps 1–6 below are page apparatus and are wrong for one component. Detection and the ambiguity question live in that file.
1. Run **§0 Brand Read** — read `.finesse/log.json` (the rotation memory, `divergence.md` §4), then infer **register** (brand vs product) + soul before touching code. Output the Design Read: the coordinate line, **a plain `You'll see:` line the user can actually veto**, the **`Images:` line naming every slot a picture would carry and where it would come from**, its two most likely objections, and the rotation as a sentence (§0.B). Before writing that `Images:` line, **check this session's actual tool list** — an image-gen tool, an MCP image tool, a network fetch, or none — because it decides what you can honestly offer (`asset-sourcing.md` §1), and **prove the one you're about to name actually runs here** before naming it (§1.1 — listed is not usable; a generator with no credential is not Path A). Offer it and **wait**; never generate or download off your own inference.
2. Set the **§1 Three Dials** (SOUL · SPECTACLE · DENSITY). Product register pins SPECTACLE low, DENSITY high.
3. **Lay the substrate — the right one for the register.** All share the **universal craft floor** (tinted neutrals, no `#fff`/`#000`, translucent/hairline borders, tinted shadows, contrast floors — `references/design-dna.md` §1). Above that floor the substrate forks:
   - **brand** → the **§3 brand substrate** (`references/design-dna.md`): grain, vignette, `clamp()` display type, dark-default, layered hero depth.
   - **product** → the **product substrate** (`references/product-ui.md` §0): premium surfaces/cards, KPI tiles, floating panels, fixed type scale, feedback-only motion. **Never** pour grain / vignette / giant hero type / dark-default / a hero engine into a dashboard — that's brand grammar, not product grammar.
   - **h5** → the **frame comes first** (`references/h5-mobile.md` §1): the viewport contract, the locked `body` + scrolling `#app`, the 560px desktop phone frame, then the safe-area math (§2). Only after the frame is standing do you lay the substrate of the register it wraps.
4. **Then the paths fork further:**
   - **brand** → pick a **§2 Soul** (`references/style-personas.md`) and build **one §4 Hero Engine** (`references/hero-engines.md`).
   - **product** → **pick a palette from `references/product-palettes.md` first** (the neutral ramp is 80% of the pixels; skipping this step is how every dashboard comes out blue). Then split by the page's job:
     - **pages you read** — dashboards, analytics, monitoring → `references/product-ui.md` (density, tables, charts, interaction states). **Before writing, open the closest dashboard in `examples/`** (index: `examples/EXAMPLES.md`) to see `product-ui.md` §0 applied in shipped code — lift patterns, not whole files.
     - **pages you operate** — publish/create wizards, merchant & admin consoles, config, settings, review queues → `references/workflow-ui.md` **on top of** `product-ui.md` (workflow shell, numbered sections, radio-card choices, live preview, pre-submit check, derived totals, draft/commit). There is **no form-workflow page in `examples/`** — build from the reference, and do **not** force-fit a dashboard example onto a form.
     - **pages you delegate on** — AI 工作台, agent consoles, copilot UI, anything where something *other than the user* does work over a duration → `references/ai-console.md` **on top of** `product-ui.md` (three tenses on one screen, the run stream, nine run states, a resident stop, the in-stream approval card, cost as a receipt). Open `examples/relay-agent-console.html`. A dashboard fails by being unreadable and a console by being unfinishable; **this one fails by being untrustworthy**, and none of the dashboard parts address that.
   - **h5** → pick one of the **six morphologies** (`h5-mobile.md` §4: app shell · paged deck · snap narrative · commerce stack · longform site · ambient screen), then load the **content register it wraps** and follow that bullet above. Build the native furniture from `h5-mobile.md` §5 rather than inventing it — a TabBar is a convention, not a design opportunity.