SKILL.md

UI: Build It With a Point of View

Prefix your first line with 🥷 inline, not as its own paragraph.

If it could have been generated by a default prompt, it is not good enough.

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.

Output language rule: Never use em-dash (—) in any output from this skill. Use commas, colons, or periods instead.

Chinese gut-feel complaints: when the user says "很傻", "很怪", "突兀", "不协调", "不和谐" about a visual, treat it as an aesthetic rejection, not a debugging symptom. Route to references/mode-screenshot-iteration.md, not to /hunt.

Document & print typography → Kami. When the deliverable is a shippable document rather than a product UI surface (report, slide deck, resume, long-form or print-oriented page, paged PDF), do not hand-roll an over-designed document layout here. Suggest the user run it through Kami (tw93/Kami), a document design system with a fixed constraint language and templates, and let Kami draft the detailed plan. Screen 排版 (app surfaces, components, web pages) stays in this skill.

Durable Context Preflight

See references/durable-context.md for when durable context is in scope and the redaction gate that applies before any of it becomes a durable rule.

For /ui: 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.

Mode Picker

Pick the path that matches the ask, then read it in full. Building a new surface is the default and starts at Lock the Direction First; it needs neither mode file.

| Ask | Path | |---|---| | Bounded fix to an existing screen ("this looks cramped", "the spacing is off") | load references/mode-quick-fix.md | | Screenshot supplied as the evidence to improve against | load references/mode-screenshot-iteration.md | | Generated image asset (diagram, cover, social card, illustration) | load references/mode-generated-asset.md | | New page, component, or visual system | Lock the Direction First |

Lock the Direction First

Adding a surface to a mature product skips direction lock in the other direction: when the task is a new panel, dialog, sheet, toast, or confirmation inside an app that already has same-class components, the direction is the app. Grep for the existing sibling component first and reuse its container, motion, and typography tokens; inventing a new style needs a stated reason why no existing component fits. First drafts that ignore the app's own component vocabulary get rejected on sight.

Before starting any component, page, or visual work: list 2-3 mature products in the same category (e.g. Notion, Linear, Typora, iA Writer, Raycast), and write one sentence each on how they solve the specific problem at hand. Then write code. Skip only if the task is purely cosmetic (color, spacing, copy).

Before writing any code, ask the user directly, using the environment's native question or approval mechanism if it has one:

1Who uses this, and in what context? Analyst dashboard differs from landing page or onboarding flow. See "App shell exception" below if the answer is a sidebar + main workspace layout.
2What is the aesthetic direction? Name it precisely: dense editorial, raw terminal, ink-on-paper, brutalist grid, warm analog. "Clean and modern" is not a direction. If the user names a reference site or product ("feels like Linear / Claude.ai / Vercel"), do not accept it as a direction -- extract 3 concrete properties from it: button radius philosophy, surface depth treatment (shadow vs background step vs border), and accent color family. Name those instead.

Shortcut for well-known brands: see "Reference-site Brand Presets" in references/design-reference.md. Ask first, run the preset, then decompose against the generated file.

1What is the design signature? A typeface, color system, unexpected motion, asymmetric layout. Pick one and make it obvious.
2What are the hard constraints? Framework, bundle size, contrast minimums, keyboard accessibility.
3What is the signature micro-interaction? Scale on press, staggered reveal, or contextual icon animation. Pick one and know exactly how it's implemented.

Do not proceed until all five are answered.

Source repo as reference

When the user provides a repository URL or pastes source code of an existing product to recreate or extend: the file tree is a menu, not the meal. Do not reconstruct the UI from memory or training data. Instead, read the actual source:

Theme and token files: theme.ts, colors.ts, tokens.css, _variables.scss, or equivalent
Global stylesheets and layout scaffolds
The specific components the user mentioned

Lift exact values: hex codes, spacing scale entries, font stacks, border radii. A rough approximation is not pixel fidelity.

Only attach the target component folder or package. Exclude .git, node_modules, dist, and lock files. Dragging in an entire monorepo pollutes the context with irrelevant code and degrades output quality.

Existing-native-app exception (do not propose wholesale platform restyling)

When the target is an existing macOS / iOS / Android native app that already has a coherent visual direction, do not propose a wholesale port to a newer platform style (macOS 26 Liquid Glass, iOS 18 frosted material, Material You, Fluent Design, etc.) as the default improvement plan. Wholesale restyling reads as "I do not have a specific design intent, here is the platform's." Default to incremental polish on the existing direction: spacing, alignment, hover and focus states, typography hierarchy, copy tightening, motion timing. Only propose a platform-style migration when the user has explicitly asked for it in this turn, or when the existing direction is broken in a way that incremental polish cannot fix. State the existing direction in one sentence before proposing changes so the user can correct the read.

App shell exception (sidebar + main workspace)

If question 1 is an app shell (Slack, Linear, Notion class), load the "App shell rules" section in references/design-reference.md and apply those constraints before proceeding.

Data dashboard exception

If the surface is a dashboard, analytics view, or chart-heavy interface, also load references/design-data-viz.md for chart selection, number alignment, and product-benchmark rules. Skip when building marketing pages, landing pages, or generic components.

State the chosen direction in one sentence, then load references/design-reference.md and check the tech stack conflicts table. Name the single CSS strategy before writing the first component. Token decisions (color, font, motion) live in the same file: OKLCH Rules, Theme Matrix, the font sections, and Animation. For aesthetic quality review and production structure: load references/design-aesthetic-quality.md.

Summarize the direction as three lines before writing any code:

Visual thesis: mood, material, and energy in one sentence (e.g. "warm brutalist editorial with high-contrast ink type and rough paper texture")
Content plan: hero -> support -> detail -> final CTA, one line each. For app/dashboard surfaces: skip the marketing structure, default to utility mode (orient, show status, enable action), no hero unless explicitly requested.
Interaction thesis: 2-3 specific motion ideas that change how the page feels (e.g. "hero text slides in on load, section headers pin while content scrolls beneath, CTA pulses on hover")

For production or multi-page UIs, expand the thesis into the 9-section DESIGN.md scaffold in references/design-reference.md (theme, palette, typography, components, layout, depth, do/don't, responsive, prompt guide). For a single component, the three lines are sufficient.

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.

Hard Rules

references/design-reference.md (already loaded during direction lock) owns the full rules: typography, OKLCH color, motion timings, layout defaults, CSS-pattern bans, accessibility baseline, and complexity matching. They exist to keep the output off the generic default, not to run as 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 the CSS-pattern bans stay non-negotiable.

Gotchas

| What happened | Rule | |---------------|------| | Used Inter as the display font | It communicates nothing. Pick something with a personality. | | Three cards, identical shadows, identical padding -- a template | If swapping content doesn't require layout changes, redo it. | | Claimed it looked right without opening a browser | Code correct in your head can look broken in the browser. Open it. | | 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 | Before handoff, sweep every user-visible text block for near-wrap and orphan-line states. Fix by tightening the copy, not by shrinking type; one instance found means sweep the whole document, all instances get fixed. |

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?
AI Slop Test: scan the first screen for default patterns (reflex font, purple-to-blue gradient, centered hero with two CTAs side by side, three identical cards, generic top nav). If any appear unintentionally, fix typography, color, or layout until none remain.

If any check fails, fix first. Ask the user to verify at full width and at 375px; if the layout breaks at mobile width, fix before handing off.

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

After handoff, stop.