finesse-ui

# 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. --- ## 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. 5. **Assemble the skeleton — again, the right one for the register.** **brand** → pick one of the four **§5 brand skeletons** (landing · portfolio · lookbook · studio) by what the page has to *do*. **product** → the skeleton is the **shell morphology** in `product-ui.md` §1 (sidebar · floating panel · bento · triptych …), **not** §5. **h5** → the skeleton is the frame (§1) plus the chosen morphology (§4); §5's brand skeletons and `product-ui.md` §1's desktop shells are both wrong inside 390px. Motion-motivated only, in all three. 6. Run the **§6 Cheapness Blacklist** (`references/anti-cheap.md`), the **mobile floor** (`references/mobile-floor.md`), and **§8 Pre-Flight** (`references/preflight.md`) before shipping. **h5 builds run `h5-mobile.md` §9–§10 instead of the mobile floor** — the notch/frame/scroll/touch gates, which are a different set of failures from "a desktop page reaching a phone". Then **record the build** — append to `.finesse/log.json` and stamp the CSS (`divergence.md` §4.3). An unrecorded build is one the next run will collide with. The `references/*.md` files are the deep material. Load the one you need for the current phase — do not inline all of them. | Reference | When to load | |-----------|-------------| | `component-scope.md` | **Before the Brand Read, when the brief is one element, not a page** — a button, an input, a card, a modal. Routes to the component flow: keeps the register + craft floor + existing tokens, skips the skeleton / hero engine / rotation, and enforces the one gate that decides whether a component is well-made — **all eight states shipped**, plus a preview file that makes them visible instead of claimed | | `divergence.md` | **At §0, before the Design Read — the anti-sameness layer.** Load it when output keeps converging, when the user says "feels generic / like every other AI site", or before *any* soul decision: the five-axis composition method (compose a soul, don't select one from a list), the anti-default two-altitude check, the die roll that breaks the model's argmax, and the assert-then-confirm direction proposal. **§4 is the memory** — `.finesse/log.json` + the CSS stamp, with a defined read step (§0) and write step (§8); without it "don't repeat" is a rule with nothing behind it. **Read its §0 register boundary first** — divergence is a goal for brand and a *bounded* tactic for product (never diverge on dashboard navigation conventions) | | `design-dna.md` | Laying the **brand** substrate (grain, vignette, display type, color tokens, palette families). Product/dashboard inherits only its **universal craft floor** (§1: tinted neutrals, translucent borders, contrast floors) — the surfaces/cards/type/motion of a dashboard come from `product-ui.md` §0, not here | | `theming.md` | Brief asks for a light/dark toggle or multiple swappable named themes — the token-role and hardcoded-color pitfalls of a runtime palette switch (not the single-locked-palette default) | | `motion.md` | **Any brief that mentions motion — 动效 · 炫酷 · "make it move" · "有动画" — and every `brand` build.** The motion layer above the engines: the two axes nobody separates (**EFFECT** what's seen vs **ROUTE** how it's built), the **six routes** with their weight, their still form and their failure mode (CSS · native scroll-driven · View Transitions/WAAPI · GSAP · Canvas/WebGL · zero-dep CSS 3D space), a **ten-family effect catalogue** with ~80 variants and each family's *slop form*, the **effect → route lookup** that stops the model reaching for 60KB to do four lines of work, and the **beat sheet** that replaces "one hero engine + generic fade-ups" with four beats from four different families. Load it **before** `hero-engines.md`: that file answers *which engine*, this one answers *whether you need an engine at all* | | `hero-engines.md` | Building the hero engine (brand register); also covers a secondary motion vocabulary (split-char reveal, magnetic buttons, curtain wipe, scan-line, per-card fly-in) for non-hero moments elsewhere on the page — the **decision** layer (which engine). **Scope note: these are the two heaviest routes (R4 GSAP · R5 Canvas/WebGL) of the six in `motion.md`** — reach here only once that file's lookup has sent you to a heavy route | | `page-crafting.md` | **The brand implementation layer** — what `chart-crafting.md` is to `dataviz.md`. Load it when you stop choosing and start writing: the **motion gate** (`REDUCE`/`FINE` probes + terminal states — universal, product too), canvas **DPR** + cyclic palettes + amplitude envelopes, `mask-image` photo dissolve, the **photographic-hero scrim stack**, container-query panels, nav **scroll-spy** over alternating sections, zero-dependency **sticky horizontal pin**, **exploded-view** scrub, colorway **pin+snap**, `clip-path` wipes, hand-written **FLIP** lightbox, **generative** (guillotine-split) layouts, CSS-only **geometric collage**, full-page engine + section scrims, and the Fibonacci→KNN→traversal 3D recipe | | `h5-mobile.md` | **The page only ever lives on a phone** — H5 / 移动端页面 / 活动页 / 小程序页 / app UI 原型 / mobile PDP / 报告 H5. The **fourth register**, and a *container* one: it fixes the frame and wraps another register for content. Carries the viewport contract, the locked-`body`/scrolling-`#app` architecture that inverts every other register, the 560px desktop phone frame, safe-area math, the thumb-zone inversion (primary actions at the **bottom**), the touch rules that have no desktop equivalent (`passive`, `pointercancel`, tap-highlight, 44px), six phone morphologies, and the native furniture recipes — status bar, TabBar, bottom sheet, FAB, push and hand-written FLIP transitions. **Not the same file as `mobile-floor.md`**: that one keeps a *desktop* page from breaking on a phone; this one is for a page that has no desktop form at all | | `mobile-floor.md` | **Any build that will be seen on a phone** — i.e. nearly all of them. The six mechanical causes of a broken phone layout, with the fix for each: `overflow-x: clip` vs `hidden` (and why `hidden` kills your sticky nav), `minmax(0,1fr)` on image-bearing grid tracks, clickable text that never wraps at *any* width, `overflow-wrap: anywhere` on display headings, one sticky at `top:0`, and the **all-caps `line-height` floor** that overrides §3's `.86–.95` for uppercase display type. `preflight.md` asks whether it breaks; this file says why it breaks | | `3d-effects.md` | Adding a 3D moment — CSS tilt/flip/coverflow/depth-parallax or Three.js model/displacement | | `style-personas.md` | Picking a soul (brand register) | | `inspiration-catalog.md` | Persona picked but you want a wider menu of proven techniques for that soul, or the brief doesn't fit any of the 10 personas cleanly | | `plain-words.md` | **Any time you are writing text the *user* reads** — the §0.B Design Read, `audit` findings, the memory-lock notice. finesse's whole vocabulary (`register`, `SPECTACLE`, `grain`, `scrim`, `eyebrow`, `hairline`) is load-bearing internally and opaque externally, and it leaks out at exactly the moments the user is supposed to make a decision. One-clause observable glosses, plus the list of internal terms (five-axis coordinates, axis letters, reference filenames) that must **never** reach a user | | `anti-cheap.md` | Before any delivery — cheapness scan | | `product-ui.md` | Dashboard / admin / data app — pages you **read** (product register) | | `workflow-ui.md` | Pages you **operate** (product register): publish/create wizards, merchant & admin consoles, config, settings, review queues — the workflow shell, numbered section cards, radio-card choices, live-preview aside, pre-submit check, derived budget panels, draft/commit | | `ai-console.md` | **Something other than the user is doing the work, and the page's job is to make that trustworthy** — AI 工作台 / agent console / 智能体控制台 / copilot UI / 值守台. **A capability layer, not a page type**: decide 后台 vs 工作台 first (§1's resolver), pick the body, *then* stack this on — it fails by being *untrustworthy* rather than unreadable or unfinishable, and that failure can land on any of them. Carries the four questions it must answer continuously, the three tenses on one screen (queue · live run · history), the **run stream** that replaces the chart as the centrepiece, the **nine run states** that `product-ui.md` §5's eight component states don't cover (including `partial` and `stopped`), stop as a primary resident control, the in-stream approval card with linked evidence, cost/context as first-class, the artifact surface, the desktop three-column shell and **what changes on a phone** (§9). Also the palette rule this category dies on: the AI-violet default, and the `--auto` vs `--needs` semantic pair | | `product-palettes.md` | **Any product-register page** — the color layer `design-dna.md` §6 doesn't cover: 5 tinted neutral ramps, 16 accents with light/dark + text-on-accent contrast, 12 paste-ready sets, the known-SaaS palettes (Linear/Stripe/Supabase/Grafana…). Load it **before** picking a color, or you will reach for blue | | `examples/EXAMPLES.md` | The positive-reference corpus — 22 real shipped pages (9 brand + 8 dashboards + 1 AI console + 4 H5) with a per-file "what to study" table. **Open the closest one before building**, especially for dashboards and phone shells (lift patterns, not whole files) | | `dataviz.md` | Chart-heavy product UI beyond the starter table — full 25-type selection matrix, a11y grade + mandatory fallback, library picks (the **decision** layer) | | `chart-crafting.md` | **Any** hand-built dashboard chart in a single self-contained file (mandatory for bars — the barcode-chart trap) — the no-library **implementation** layer: the value→height rule, `div height:value/max%` bar recipe, SVG coordinate normalization, line/area draw-in, donut/gauge grow, stacked bars, sparklines, the three animations × reduced-motion pairing, slider-driven live update | | `commerce-ui.md` | Product detail page (PDP), listing/category page (PLP), cart, checkout — commerce register | | `asset-sourcing.md` | **At §0.B, as soon as the page has anywhere a picture would carry it** — a hero, a gallery, an H5 cover or scene, a PDP shot, even a dashboard's empty state or avatar row. Not a category checklist and not a delivery-time scan: the paths (generate · real stock · generative placeholder) and the **ask-first gate on all of them** only work if they fire before the layout is written. Carries the session-capability check that decides which path you can honestly offer, and the rule that naming images is an offer the user answers — never a licence to generate or download | | `preflight.md` | Final checklist before saying "done" | | `design-model.md` | Multi-page projects — token consistency | | `redesign-mode.md` | Upgrading an existing page — audit-first protocol | | `audit.md` | Read-only diagnostic — cheapness + spectacle + preflight scan | | `init.md` | New project — write `PRODUCT.md` (the persistent brief) | | `document.md` | Existing codebase — extract `design-model.yaml` from real code | --- ## Commands finesse runs as a full build by default, but supports **verb commands** for targeted iteration on an existing page — so you don't re-run the whole Brand Read for a single complaint. Each command loads one reference and does one job. | Command | Category | Does | Reference | |---------|----------|------|-----------| | `craft [brief]` | Build | The full flow: Brand Read → Dials → substrate → engine → assemble (the default) | all | | `init` | Setup | New project: write `PRODUCT.md` (register, soul, locked dials, anti-references) — the brief every later task reads | `init.md` | | `document` | Setup | Existing codebase: extract the built design system into `design-model.yaml`; report drift | `document.md` |