--- name: ui description: 'Builds distinctive, production-grade UI: pages, components, visual polish against screenshots or first-impression complaints, typography, and DESIGN.md/design-token contracts including Tailwind export via the @google/design.md CLI. Use when users ask for UI work, design tokens, or complain a screen looks unclear, ugly, or inconsistent. Not for backend logic or runtime/behavior regressions (route to hunt); intentional design-reference comparisons stay here.' when_to_use: '设计, 做页面, 做组件, 很丑, 很怪, 突兀, 不清晰, 字体, 字形, 排印, 排版, 样式, 前端, UI, 截图, 拖拽, 手势, 动效, 滑动, build page, create component, make it look good, style, design, screenshot with visual complaint, typography, font looks wrong, drag, gesture, swipe, DESIGN.md, design tokens, 设计系统文件, 设计 token 校验, designmd, tailwind token 导出' --- # UI: Build It With a Point of View If it could have been generated by a default prompt, it is not good enough. ## Overview UI builds distinctive, production-grade interfaces. Every visual decision is grounded in screenshots, design tokens, and the user's aesthetic direction. ## Outcome Contract - Outcome: a usable interface or visual fix with a clear point of view and no incoherent layout, text, or responsive breakage. - Done when: the real rendered surface or generated artifact has been checked against the user's visual goal and the relevant viewport states. - Evidence: screenshots, rendered UI, source components, design tokens, accessibility constraints, and user-provided references. - Output: the implemented visual change or a precise visual review with the remaining verification gap named. - Authorization: visual changes only. No backend logic, no data model changes, no deployment without current-turn approval. **Document & print typography** (report, slide deck, resume, long-form or print-oriented page, paged PDF) routes to a dedicated document design system / 排版 DSL with fixed constraints and templates; let that system draft the detailed plan instead of hand-rolling an over-designed document layout here. Screen 排版 (app surfaces, components, web pages) stays in this skill. When the user names such a system themselves, follow its conventions for that deliverable. ## When to Use - Building pages, components, or visual interfaces with production-grade quality. - Polishing existing UI against a first-impression visual complaint ("ugly", "inconsistent", "突兀"), with or without a screenshot. - Typography, font selection, and design-system token contracts. - Creating or managing DESIGN.md files via the `@google/design.md` CLI. - Screenshot arbitration: a screenshot whose complaint is "looks wrong / 看着不对" with no working baseline stays here; a screenshot proving a runtime or behavior regression (previously correct rendering now broken) routes to `hunt`; an intentional design-reference comparison against an approved design baseline stays here and loads `references/visual-comparison.md`. Chinese gut-feel complaints ("很傻", "很怪", "突兀", "不协调", "不和谐") about a visual are aesthetic rejections, not debugging symptoms, and follow the same rule. Generated image assets stay in `references/mode-generated-asset.md` even when the complaint arrives with a screenshot; coded or rendered UI surfaces route to `references/mode-screenshot-iteration.md`, not to `hunt`. For UI copy cuts, load the UI copy rules in `references/design-reference.md` before proposing deletions, including in quick-fix and screenshot modes. - Route to `hunt` for application-logic debugging and runtime regressions; route to `chrome` for browser-based evidence capture; route to `check` for code quality review. ## Durable Context Preflight When the user names memory, a prior decision, or a memory path, apply the project's durable-context rules when the project defines them. `/ui` specialization: current screenshots and rendered output override memory. Reuse durable visual preferences and mature interaction patterns, but still name the current visual problem from the screenshot or source before changing code. ## Reference Library Load the matching reference when the UI work enters that territory: | When building | Load | | --------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------- | | Component architecture, state, responsive, design-system adherence | `references/frontend-engineering.md` | | Forms, async actions, nav, lists, tables, overlays; empty/loading/error/permission/offline states | `references/ui-state-completeness.md` | | Comparing two captures — visual regression vs baseline, or UI vs design reference | `references/visual-comparison.md` | | WCAG 2.1 AA accessibility checklist (keyboard, screen readers, contrast, forms) | `references/accessibility-checklist.md` | | Live a11y audit on a rendered page (Lighthouse, focus flow, tap targets, contrast) | `references/a11y-debugging.md` | | Verifying the result in a real browser (screenshots, accessibility tree, clean console) | `references/browser-devtools.md` | | Gesture-driven surfaces (drag, swipe, sheet, carousel, slider, momentum, velocity handoff) | `references/design-gesture-physics.md` | | Charts, dashboards, or data visualization | `references/design-data-viz.md` | | Native app motion, spring physics, or platform motion conventions | `references/design-native-motion.md` | | DESIGN.md token contract internals (format spec, full CLI reference; expand via `design-md-cli.md`) | `references/design-md-format-spec.md`, `references/design-md-cli-reference.md`, `references/design-md-cli.md` | ## Mode Picker - Pick the path that matches each deliverable, then read it in full. - A request may combine paths, such as a page plus its generated social card. All matching paths share one initial preflight clarification round across the request; event-triggered recovery after work begins may reopen only the affected fields. - When triggers overlap, route by the artifact being changed: generated image assets take precedence over screenshot evidence for that asset, while screenshot iteration handles coded or rendered UI surfaces. - Building a new surface is the default and starts at `references/mode-direction-lock.md`; it needs neither quick-fix nor screenshot-iteration mode file. | Ask | Path | | --------------------------------------------------------------- | ---------------------------------------------- | | Fix one bounded visual defect on an existing screen | load `references/mode-quick-fix.md` | | Improve a rendered surface against a supplied screenshot | load `references/mode-screenshot-iteration.md` | | Produce a generated image asset | load `references/mode-generated-asset.md` | | Work a DESIGN.md token contract via the `@google/design.md` CLI | load `references/design-md-cli.md` | | Build a new page, component, or visual system | load `references/mode-direction-lock.md` | ## When Asked For Options Give at least 3 variations across genuinely different dimensions (density, typography, color, layout, motion). See "Options guide" in `references/design-reference.md` for the full variation framework. Three options differing only by accent color are not three variations. Offer without being asked when the decision is taste, not correctness: icon, weight, accent, motion feel. Two labeled candidates beat one landed guess, because the reply is a single letter instead of a rewrite round. For a structural change, describe the end state in a sentence or two and get a nod before writing the code. ## Common Rationalizations - "Clean and modern is a safe default" — it communicates nothing. Pick a specific aesthetic direction with a name. - "The component looks correct in the code" — code-correct UI can look broken in the browser; open it before handoff. - "Three cards with the same padding is responsive" — if swapping content doesn't require layout changes, the layout is a template, not a design. - "Adding a shadow makes it look premium" — if removing all shadows makes the design fall apart, the hierarchy was carried by decoration, not structure. ## Red Flags - Writing component code before all five direction dimensions are resolved by evidence, assumption, or clarification - Accepting "feels like Linear" as a direction without extracting concrete properties from it - Handing off without opening the rendered surface at the product's supported viewport range - Proposing a wholesale platform restyle for a native app that already has a coherent direction - Shipping a first viewport that trips the default-prompt tells cataloged in `references/design-reference.md` (Common Traps, AI Slop Test) - Fixing a visual complaint by redesigning the whole surface instead of the smallest material change ## Verification 1. Re-read the visual thesis from direction lock; check for drift toward generic defaults. 2. Run the aesthetic review checklist (Output: Aesthetic Review section) before handoff. 3. Render the product's supported viewport range yourself; fix breakage before handing off. Hand the user the exact view to check only when the host cannot render. ## Hard Rules The always-on bans live in `references/design-reference.md` (Absolute Bans, Reflex Fonts). Direction lock loads that file for the full rewrites, typography, OKLCH color, motion timings, layout defaults, accessibility baseline, and complexity matching; screenshot and quick-fix paths apply its bans without paying for the full read. The bans are deliberate-override rules, not a lint pass: when the committed direction genuinely calls for breaking one, break it deliberately and name the tradeoff in the handoff. The accessibility baseline and CSS-pattern bans stay non-negotiable. The motion rules in `references/design-reference.md` (frequency decides whether something animates; press feedback on every pressable control) apply in every mode, including the ones that skip the full reference. ## Gotchas | What happened | Rule | | --------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Used Inter as the display font | It communicates nothing. Pick something with a personality. | | Chose glassmorphism, ignored the mobile constraint | `backdrop-filter` is expensive on low-power devices. Name the tradeoff. | | Light-mode app: white panel on white background, visually indistinguishable | Adjacent nested surfaces must differ visually. Either background step (sidebar vs main ≥4% lightness difference) or shadow minimum `0 1px 3px rgba(0,0,0,0.10)`. | | Fixed visual polish by redesigning the whole surface | Locate the concrete visual delta first, then make the smallest material, opacity, geometry, or typography change that addresses it. | | Regenerated an image a third time after two "ugly" verdicts | Two rejections on look means the subject is the disagreement, not the palette. Stop generating and re-align on what the image says. | | Added a setting or louder control to solve UI noise | Remove the misleading affordance or choose a quiet default first | | English looked fine, localized text overflowed | Test long words and localized strings before handoff, especially inside buttons, tabs, nav, and compact cards. | | Relied on `…` truncation to fit text in a fixed-width slot | Guarantee fit instead: compact the format, cap to whole segments, or hard-trim with no glyph. Metric and label footers must never tail-truncate into an ellipsis. | | One extra word pushed a line into a wrap; the last line held a single orphan word | Inspect the container and forced breaks first; tighten repetition without losing meaning, never shrink type for a widow. Sweep sibling blocks for the same layout cause, not every short last line. | | Five text styles inside one small card | One text style per role inside a card, hierarchy by order; more than three distinct text styles in a small block is the smell. | ## Output: Aesthetic Review After significant build phases and at handoff, re-read the visual thesis from direction lock. If what is on screen drifted toward a generic default, identify the specific element that broke first (typeface, color, card treatment, spacing) and fix it before continuing. Run these checks before the handoff summary: - Is the brand or product unmistakable in the first screen? - Is there one strong visual anchor (real imagery, not a decorative gradient)? - Can the page be understood by scanning headlines only? - Does each section have one job? - Are cards actually necessary, or just default styling? - Does motion improve hierarchy or atmosphere, or is it ornamental? - Would the design still feel premium if all decorative shadows were removed? Then run the AI Slop Test in `references/design-reference.md` against the first viewport, which carries the default-prompt tells catalog. For any surface with forms, async data, or navigation, also run the state-completeness pass in `references/ui-state-completeness.md` (async lock, inline errors, skeleton, one primary CTA, edge-state matrix). If any check fails, fix first. Render the product's supported viewport or window range yourself: web breakpoints on both sides, and native minimum width, minimum height, their combination, and normal size. Test samples do not require new layout branches. Only when the host cannot render, say so and hand the user the exact view to check. End with: - Aesthetic direction, named and justified in 2-3 sentences - Non-obvious choices explained: typeface, color decisions, layout logic - Instructions for replacing placeholder content with real content Handoff prose scope: follow the write skill's punctuation rules (no em-dash U+2014) for reply text; copied code and quoted file content are exempt. After handoff, stop.