finesse-ui

name finesse-ui description Build never-cheap, high-craft web interfaces — brand surfaces (landing pages, brand sites, launches, portfolios, hero pages with real WebGL/Three.js/Canvas/GSAP engines), product UI (dashboards, admin panels, analytics, data tables, app shells), workflow UI (merchant/admin consoles, publish & create wizards, config and settings pages, review queues), AI workbenches (AI 工作台, agent consoles, 智能体控制台, copilot UI, run streams, approval/human-in-the-loop cards), commerce pages (product detail pages, listing/category pages, cart, checkout), and H5 / phone-only screens (app UI prototypes, 活动页, mobile PDP, data-report H5, mobile sites). Routes by register: brand → soul + spectacle engine; product → palette + component system + density (split further into pages you READ = dashboards, pages you OPERATE = consoles/wizards, and and a DELEGATION layer that stacks on either when an agent does the work); commerce → PDP/PLP skeletons + anti-dark-pattern rules; h5 → a fixed 390×844 frame, safe-area math, thumb-zone hierarchy, and native furniture (status bar, TabBar, bottom sheet, FAB, push & FLIP transitions) across six phone morphologies. Ships a product color library (tinted neutral ramps + 16 accents + 12 paste-ready sets) so dashboards stop defaulting to blue. Always reads the brief first and audits against an anti-slop cheapness blacklist. Ships an anti-sameness layer (divergence) that composes a soul from five orthogonal axes instead of picking from a persona list, so repeat runs stop converging on one look. Routes single-element briefs to a component flow (8 mandatory states + a preview file) instead of the page apparatus. Carries a cross-run build log so rotation is enforced rather than narrated, and a mobile floor covering the six ways a crafted page breaks on a phone. Supports verb commands (audit · bolder · quieter · soul · diverge · animate · densify · redesign) for targeted iteration. Ships a motion layer that separates WHAT moves from HOW it is built: six routes (CSS · native scroll-driven · View Transitions/WAAPI · GSAP · Canvas/WebGL · zero-dependency CSS 3D space) against a ten-family effect catalogue of ~80 variants (spatial camera moves, particle fields, fluid & material, scroll narrative, typographic, image transform, geometric construction, physics & inertia, state transition, atmosphere), each family carrying its slop form; an effect→route lookup so a page stops shipping 60KB to do four lines of work; and a four-beat sheet that replaces "one spectacular hero over generic fade-ups" — because 「炫酷」 and 「好看」 select nothing, and every model answers them with the same particle hero. Separates 后台 (revolves around a batch of business objects) from 工作台 (revolves around one thing he does over and over) — one fork that decides density, soul and shell, resolved by what the thing revolves around rather than by head-count or screen; a workbench then picks a body, desktop or phone morph A.1. Ships an AI-workbench layer that stacks on any of them for the pages agents actually run in — a run stream instead of a chart, nine run states, a resident stop control, in-stream approval cards with linked evidence, and cost as a first-class receipt. Triggers on "make this look premium", "landing page", "personal site", "portfolio", "个人主页", "落地页", "lookbook", "dashboard", "admin panel", "商家后台", "工作台", "专属工作台", "个人工作台", "每日工作台", "打卡页", "记录页", "daily desk", "back-office", "console", "publish flow", "发布流程", "wizard", "settings page", "analytics UI", "data table", "app UI", "product page", "PDP", "listing page", "checkout", "dashboard colors", "AI 工作台", "agent console", "智能体控制台", "AI 助手界面", "copilot UI", "运行记录", "工具调用", "人工审批", "值守台", "H5", "H5 页面", "移动端页面", "手机端页面", "活动页", "小程序页面", "公众号页面", "app 原型", "mobile app UI", "app screen", "in-app page", "移动端商详", "报告 H5", "give it a soul / a vibe", "anti-slop", "hero animation", "动效", "炫酷", "加点动画", "让它动起来", "太静了", "滚动动画", "页面转场", "沉浸式", "走进去", "scroll animation", "page transition", "make it move", "feels generic", "every page looks the same", "每次都差不多", "make me a button", "just this component", "按钮", "单个组… version 0.20.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. How to use this skill 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. 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. Set the §1 Three Dials (SOUL · SPECTACLE · DENSITY). Product register pins SPECTACLE low, DENSITY high. 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. 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. 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. 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