Design

Design: Build It With a Point of View

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

Update check (non-blocking). Before starting, run bash ../../scripts/check-update.sh once; if it prints a line, relay it to the user, then continue. It runs at most once a day, only reads a public version file, sends no data, and fails silently.

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 Screenshot Iteration Mode, 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 rules/durable-context.md for when to read durable context, the read-order budget, and the memory-type mapping.

For /design, visual constraints are decision, preference, and principle entries; reusable product and UI patterns are pattern and learning. Current screenshots, rendered output, code, design tokens, and user feedback 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.

Visual Quick-Fix Mode

Activate when the user asks for a narrow visual repair with a concrete symptom: overflow, clipped or wrapped text, misalignment, spacing imbalance, contrast/readability, localized text not fitting, or compact responsive breakage. This is for fixing an existing surface, not redesigning it.

Flow:

1. Read the current UI evidence: screenshot, rendered page, native view, or responsible component.
2. Name the exact visual defect in one sentence.
3. Make the smallest material, geometry, spacing, contrast, typography, or text-fit change that fixes that defect.
4. Verify the real running surface or generated artifact. Check long words, localized strings, compact states, and at least one narrow viewport when applicable.
5. If the fix touches three or more components, changes product behavior, or reveals a direction problem, stop and switch to Screenshot Iteration Mode or Lock the Direction First.

Spacing unification rule. If a magic spacing or sizing value has been adjusted three times and the layout still looks off, stop tuning. Replace the N independent padding / gap / margin / size values with one shared named token (Spacing.s4, --gap-content, gap-4). Outer container padding defaults to the same value as inner element gap. Asymmetry that survives tuning is structural, not numeric, so more rounds of magic numbers will not converge. Reduce the count of independent values first, then argue about the specific value.

Fixed-height action slot, uniform typography. Any container that swaps children based on state (status bar, action slot, toolbar row, menu item) must use one font size across every state. Vary fill, stroke, opacity, color, or icon, never font size. A 1pt height delta between secondary 13px and primary 14px becomes visible jitter at the state transition. CTA pill buttons in the same slot use the same size (typically 14px), distinguished by background and border, not by typography.

Completion screen layout. Operation-complete surfaces show the single result the user came for: the actual reclaimed size / processed count / changed state. Long explanations belong in a details overlay opened from a summary row, not in the primary completion line. Do not add a separate "Review" button next to the summary row when one tap on the row already opens details; do not show an empty "0 skipped" entry point. If there is no skipped or failed item, hide the details affordance entirely.

Safety-bound action design. For cleanup, deletion, uninstall, reset, or permission-changing surfaces, do not make the UI feel simpler by hiding recoverability. Bulk select, auto-select, one-tap delete, or "recommended" destructive defaults are only appropriate when each row is understandable to the target user and carries enough identity to verify safety (name, source, owner, path, preview, or recovery implication as relevant). If rows are opaque identifiers, inferred leftovers, or machine-only paths, prefer review-first UI, current-target scoping, disabled destructive affordances, or explanatory grouping over faster batch controls. A feature request for fewer clicks is not enough to remove the user's ability to verify what will change.

Quiet product boundary. Fewer clicks and richer controls are not automatically better. Remove misleading affordances before adding alternate controls, prefer quiet defaults for diagnostics and alerts, and fix unstable motion cadence before changing speed or adding a new motion preference. If the current UI implies an action, state, or promise it cannot support, remove that implication first.

Screenshot Iteration Mode

Activate when the user sends a screenshot or image alongside a complaint ("这里很丑", "这个不对", "fix this", "looks wrong"). The existing product is the direction. Skip the five-question direction lock.

Flow:

1. Read the screenshot. State the problem in one sentence: what specifically looks wrong (spacing, contrast, alignment, typeface, color, density, hierarchy). Preserve the user's negative label when it is diagnostic; do not translate "丑", "乱", "不清晰", or "怪" into vague "make it modern" language.
2. Wait for the user to confirm the diagnosis before touching code.
3. If the user provides a reference screenshot, older version, or "this one is good" example, compare current vs. reference and name the visual deltas before choosing a fix.
4. If the diagnosis is a known UX problem (split-view sync, infinite scroll, virtualised list, sticky header), spend one round surveying how 2-3 mature products in the same category solve it before writing code. Cite what each does. Skip only if the fix is purely cosmetic (color, spacing, copy).
5. Find the responsible code: grep for the component name or class, read the actual file. Do not rely on memory or assumptions about file location.
6. Apply the minimal fix. For existing products, try material/opacity, geometry, spacing, typography, or text-fit adjustments before redesigning the surface.
7. Verify the result in a browser, native app, screenshot tool, or rendered artifact at desktop width and 375px mobile width when applicable. Check long words, localized strings, button labels, and compact states for overflow. If the host cannot render, say that explicitly and hand off the exact view the user should check.
8. Ask the user to verify in the browser. Do not hand off without this step.

Calibration rules:

• The user's screenshot is the strongest design brief in the turn. Keep it visible in the reasoning until the fix is done.
• The real running product is the oracle. Product pages, app screenshots, release pages, and current UI state override generic style instincts.
• Do not flatten specific taste feedback into generic UI adjectives. "More premium" is not a diagnosis; "caption baseline drifts above the Chinese line" is.
• If the screenshot exposes a regression, broken render, timing issue, or generated asset defect rather than taste, route to /hunt and preserve the visual evidence.

Native screenshot handoff. For native apps, once you have proven the app builds, runs, and can reach the target view, do not spend repeated cycles fighting focus, window ordering, or coordinate-click automation just to capture final visual proof. Make one bounded automation attempt. If it is flaky, name the exact screen and ask the user for the screenshot to iterate against. This is a visual QA boundary, not a substitute for build/run verification.

Boundary: if the fix requires changing 3 or more components, or if it reveals a direction problem rather than a specific bug, pause and run the full direction lock before continuing.

Redesign priority order (when reworking an existing UI rather than building from scratch): font replacement → color cleanup → hover/active states → layout and whitespace → replace generic components → add loading/empty/error states → typographic polish. This order maximizes visual lift while minimizing the blast radius of each pass. Full rules in references/design-reference.md. Common traps and absolute CSS bans: references/design-traps.md.

Lock the Direction First

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:

1. Who 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.

2. What 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 "Brand preset flow" in references/design-reference.md. Ask first, run the preset, then decompose against the generated file.

3. What is the design signature? A typeface, color system, unexpected motion, asymmetric layout. Pick one and make it obvious.

4. What are the hard constraints? Framework, bundle size, contrast minimums, keyboard accessibility.

5. What 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. For token decisions (color, font, motion): load references/design-tokens.md. 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.

Hard Rules

references/design-reference.md is already loaded during direction lock. It owns the full rules: typography, OKLCH color, motion timings, layout defaults, CSS-pattern bans, accessibility baseline, and complexity matching. Apply them. Do not restate them here.

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.

Gotchas

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.