design

# Design: 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 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](../../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. St