self-evolve-framework 1.1.0 → 1.2.0

package/template/skills/design/SKILL.md

@@ -1,173 +0,0 @@
----
-name: design
-description: "Produces distinctive, production-grade UI for pages, components, visual interfaces, typography, and screenshot-driven polish. Use when users ask 设计/做页面/做组件/UI/前端/截图 or say a screen is ugly, unclear, inconsistent, or visually wrong. Not for backend logic or data pipelines."
-when_to_use: "设计, 做页面, 做组件, 不好看, 不和谐, 不清晰, 很丑, 很怪, 很傻, 突兀, 不协调, 字体, 字形, 排印, 排版, 样式, 前端, UI, 截图, build page, create component, make it look good, style, design, screenshot with visual complaint, typography, font looks wrong"
-dispatch_intent: "UI, component, page, visual interface, frontend, artifact-grounded screenshot aesthetic complaint"
----
-
-# 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](../../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.
-
-**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
-
-| 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. |
-| 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. |
-
-## 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.

package/template/skills/design/references/design-aesthetic-quality.md

@@ -1,67 +0,0 @@
-# Design Aesthetic Quality and Production Structure
-
-## App Shell Rules
-
-When building a sidebar + main workspace layout (Slack, Linear, Notion class):
-- Decorative backgrounds default to off
-- Surface hierarchy uses background-color steps and shadow only
-- All interactive elements get `active:scale-95`
-- Button radius is consistent within each component type (pick one: pill, square, or one fixed value, do not mix)
-- Commit to a named radius scale before the first component
-
-## Options Guide
-
-When asked for design options, give at least 3 variations spread across genuinely different dimensions:
-
-- **Dimensions to vary**: visual density, typographic personality, color temperature, layout structure, motion character, amount of decoration, level of abstraction
-- **Mix approaches**: one option follows existing conventions closely, one remixes the brand DNA, one is deliberately unexpected
-- **Progress from basic to bold**: the first option is safe and understandable; later options push further
-- Three options that differ only by accent color are not three variations. Vary layout, typeface, motion, surface treatment.
-
-## DESIGN.md Scaffold (Optional, Production UIs)
-
-For a multi-page or production UI, emit a short `DESIGN.md`-style summary before writing the first component. The nine sections:
-
-1. **Visual Theme and Atmosphere**: mood, density, design philosophy in 2-3 sentences
-2. **Color Palette and Roles**: semantic name + value + functional role for each color token
-3. **Typography Rules**: font family, size scale, weight scale, line-height, letter-spacing
-4. **Component Stylings**: buttons (all states), cards (if used), inputs, navigation
-5. **Layout Principles**: spacing scale, grid columns, whitespace philosophy
-6. **Depth and Elevation**: shadow system or background-color-step system; describe each level
-7. **Do's and Don'ts**: 5 to 10 guardrails specific to this project
-8. **Responsive Behavior**: breakpoints, how navigation collapses, touch target minimums
-9. **Agent Prompt Guide**: color reference (name: value pairs) + 3-5 example component prompts with all values inlined
-
-For a single component or quick prototype, skip this. The three-line thesis is sufficient.
-
-## Pre-Handoff Checklist: Strategic Omissions
-
-Items most frequently missing from AI-generated UIs:
-
-- [ ] **Custom 404 page**: a branded page with a clear path back
-- [ ] **Back navigation**: every page reachable by user action must have a path back
-- [ ] **Form client-side validation**: inline errors adjacent to each field
-- [ ] **Skip-to-content link**: visually hidden `<a href="#main-content">Skip to main content</a>` as first focusable element
-- [ ] **Cookie consent**: for EU or California jurisdictions
-- [ ] **Footer Privacy and Terms links**
-
-These are not polish items. They are the difference between a demo and a shippable product.
-
-## Reference Material Priority
-
-When source code and a screenshot are both available: read the code. Source files contain exact token values; screenshots require guessing.
-
-When only a URL is provided: fetching returns extracted text only, with no layout information. For visual references, ask for a screenshot rather than inferring from stripped HTML.
-
-## Adding to Existing UI
-
-When extending an existing interface, first understand its visual vocabulary. Match all of the following before writing the first line of new code:
-- Copywriting tone and reading level
-- Color palette and semantic color roles
-- Hover and click states: scale, color shift, underline, background fill
-- Animation style: duration, easing, whether interactions bounce or are ease-out
-- Shadow and card treatment
-- Layout density and whitespace rhythm
-- Border radius choices
-
-If swapping in different content would make the new component look out of place, the vocabulary was not matched closely enough.

package/template/skills/design/references/design-data-viz.md

@@ -1,34 +0,0 @@
-# Design Reference: Data Visualization
-
-Load this only when the surface is a dashboard, analytics view, chart-heavy interface, or any number-dense data display. Marketing pages, landing pages, and generic component work do not need it.
-
-## Dashboard defaults
-
-Dashboards are utility surfaces: orient the user, show status, enable action. No hero sections, no marketing copy. Every element must earn its place by answering a question the user has.
-
-- Primary layout: status summary at top, detail below; or sidebar filters + main chart area.
-- Whitespace: tighter than marketing pages; users scan, not read. Use generous column spacing, not generous row height.
-- Number density: many numbers on screen at once is not a problem. Crowding without alignment is. Use `font-variant-numeric: tabular-nums` for all numeric columns. Right-align numbers. Left-align labels.
-
-## Chart selection
-
-| Use case | Chart type |
-|---|---|
-| Comparing values across categories | Bar chart (horizontal if labels are long) |
-| Trend over time | Line chart; avoid bars for time series with many points |
-| Part-whole relationships | Treemap (6+ segments) or stacked bar; pie only for 2-4 segments |
-| Distribution | Histogram or box plot; never pie chart |
-| Correlation | Scatter plot; do not use line chart |
-
-Pie charts with more than 4 segments communicate nothing. Use a treemap or ranked list instead.
-
-## Number-dense interfaces
-
-- `font-variant-numeric: tabular-nums` on every number column so digits align vertically.
-- Right-align all numbers; left-align all text labels. Mixed alignment in the same column is always wrong.
-- Subtle row separators: `1px` line at `rgba(0,0,0,0.06)` (light) or `rgba(255,255,255,0.05)` (dark). Alternating row backgrounds only if the table is very wide (12+ columns).
-- Column spacing: at least `16px` between adjacent columns; more between logically distinct groups.
-
-## Using a product as a benchmark
-
-When the user references a product for visual benchmark ("make it feel like Grafana" / "similar to Linear analytics"): extract 3-5 concrete data-visualization-specific properties from that product, not general aesthetic properties. Useful properties: chart color palette (exact values), grid line weight and opacity, axis label size and color, tooltip border-radius and shadow, empty-state treatment. Do not extract "minimal" or "clean" as properties; those are not actionable.

package/template/skills/design/references/design-reference.md

@@ -1,295 +0,0 @@
-# Design Reference
-
-## Tech Stack Conflicts
-
-These combinations produce silent failures or incoherent output. Never combine them:
-
-| Never combine | Why |
-|---|---|
-| Tailwind + CSS Modules on the same element | Specificity conflicts, unpredictable cascade |
-| Framer Motion + CSS transitions on the same element | Double-animating the same property causes jank |
-| styled-components or emotion + Tailwind | Two competing class systems fighting for the same DOM node |
-| Heroicons + Lucide + Font Awesome in one project | Visual inconsistency, size mismatches, bundle bloat |
-| Multiple Google Font families as display fonts | Competing personalities cancel each other out |
-| Glassmorphism backdrop-filter + solid `border: 1px solid` | Solid borders shatter the layered depth illusion |
-| Dark background + `#ffffff` text at full opacity | Too harsh; use `rgba(255,255,255,0.85)` or `#f0f0f0` |
-| Tailwind v4 `@theme` + dynamically constructed class names | `@theme` tokens generate utility classes JIT; if class names are built from variables or not present in scanned source, the class is purged and styles silently disappear. Fix: use static class names in source files, add to `safelist`, or define custom colors in `:root` + `extend.colors` in `tailwind.config.js` instead of `@theme` |
-
-Before writing the first component, name the single CSS strategy for the project: Tailwind only, CSS Modules only, or CSS-in-JS only. Do not drift from it.
-
-## Common Traps
-
-Before submitting, check whether any of the following slipped in without intention:
-
-- A purple or blue gradient over white as the hero background
-- A three-part hero: large headline, one-line subtext, two CTA buttons side by side
-- A grid of cards with identical rounded corners, identical drop shadows, identical padding
-- A top navigation bar with logo left, links center, primary action far right
-- Sections that alternate between white and `#f9f9f9`
-- A centered icon or illustration sitting above a heading above a paragraph
-- A four-column footer with equal-weight columns
-
-Any of these can appear if they serve the design intentionally. They cannot appear by default.
-
-Final test: if you swapped in completely different content and the layout still made sense without changes, you built a template, not a design. Redo it.
-
-## Content Authenticity
-
-Placeholder copy that looks real but is not real breaks the illusion the moment a user reads it. Apply these rules before handoff.
-
-**Sample data:**
-- No generic names: not John Doe, Jane Smith, Alex Johnson, or any first-name-last-name combination that reads as filler. Use culturally varied names with real specificity (e.g., Priya Mehta, Lars Eriksson, Nia Okafor).
-- No generic company names: not Acme Corp, Nexus, SmartFlow, TechCorp, Initech. Pick names with a domain (e.g., Meridian Logistics, Hokkaido Ceramics, Vantage Bioworks).
-- No Lorem Ipsum. Write short real copy that matches the layout's reading level.
-- No round numbers in data samples. `99.99%` uptime, `50%` conversion, `$100.00` MRR look synthetic. Use organic values instead: `99.94%`, `47.2%`, `$99.00`.
-- Multiple avatar instances must not share the same image. Multiple blog post or event cards must not share the same date.
-
-**UI copy:**
-- Sentence case on all headings. Title Case On Every Heading is the most common AI tell in body copy.
-- Remove exclamation marks from success states ("Saved!" → "Saved", "Done!" → "Done"). Reserve `!` for genuine urgency.
-- Never open an error message with "Oops!". It reads as condescending.
-- No passive voice in error messages ("Something went wrong" → "We couldn't load your data. Try refreshing.").
-- Banned AI marketing words in hero copy, CTAs, and feature descriptions: Elevate, Seamless, Unleash, Delve, Tapestry, Game-changer, Next-Gen, "In the world of...". These words communicate nothing about the product. Name the specific value instead.
-
-## Placeholders Over Imitations
-
-When an icon, image, or component is unavailable: use a placeholder. In hi-fi design a labeled placeholder is always better than a low-quality attempt at the real thing. Examples: a grey rectangle for a hero image, a monogram wordmark for a missing logo, a dashed border for a component not yet designed.
-
-Never draw illustrative imagery using inline SVG. SVG is for icons and geometric shapes. For photography, illustrations, or product shots, use a placeholder and ask the user to supply real assets.
-
-## Production Quality Baseline
-
-Check before handoff. These are not aesthetic choices, they are non-negotiable.
-
-> Treat the sections below as craft details, not defaults. Only apply them when they serve the locked visual direction. If removing a detail changes nothing about how the interface feels, leave it out.
-
-### Accessibility
-- Icon-only buttons need `aria-label`
-- Actions use `<button>`, navigation uses `<a>` (not `<div onClick>`)
-- Images need `alt` (or `alt=""` if decorative)
-- Visible focus states: `focus-visible:ring-*` or equivalent; never `outline: none` without replacement
-
-### Animation
-- Honor `prefers-reduced-motion`: disable or reduce animations when set
-- Animate `transform`/`opacity` only (compositor-friendly, no layout thrash)
-- Never `transition: all`; list properties explicitly
-- Interruptible animations: prefer CSS transitions for interactive state changes (hover, toggle, open/close) because they retarget mid-animation; reserve keyframe animations for staged sequences that run once (e.g., staggered page enters)
-- Staggered enter: split content into semantic chunks with ~100ms delay; titles into words at ~80ms; typical enter uses `opacity: 0 → 1`, `translateY(12px) → 0`, and `blur(4px) → 0`
-- Subtle exit: use a small fixed `translateY(-12px)` instead of full height; keep duration ~150ms `ease-in`, shorter and softer than enter
-- Contextual icon swaps: animate with `scale: 0.25 → 1`, `opacity: 0 → 1`, and `blur: 4px → 0px`. With a spring library: `{ type: "spring", duration: 0.3, bounce: 0 }`. Without: keep both icons in DOM (one absolute) and cross-fade with CSS using `cubic-bezier(0.2, 0, 0, 1)`
-- Scale on press: buttons use `scale(0.96)` on active/press via CSS transitions so the press can be interrupted; add a `static` prop to disable when motion would be distracting
-- Page-load guard: use `initial={false}` on animated presence wrappers for toggles, tabs, and icon swaps to prevent enter animations on first render; do not use it for intentional page-load entrance sequences
-
-### Performance
-- Transition specificity: never `transition: all`; list exact properties (e.g., `transition-property: scale, opacity`). Tailwind's `transition-transform` covers `transform, translate, scale, rotate`; use `transition-[scale,opacity,filter]` for mixed properties
-- GPU compositing: only use `will-change` for `transform`, `opacity`, or `filter`. Never `will-change: all`. Add only when you notice first-frame stutter; do not apply preemptively to every element
-- Images: explicit `width` and `height` (prevents layout shift)
-- Below-fold images: `loading="lazy"`
-- Critical fonts: `font-display: swap`
-
-### Touch and Mobile
-- `touch-action: manipulation` (prevents double-tap zoom delay)
-- Full-bleed layouts: `env(safe-area-inset-*)` for notch devices
-- Modals and drawers: `overscroll-behavior: contain`
-- Hover guard: wrap interactive hover states with `@media(hover:hover)` so they only apply on pointer devices, not touch screens. Tailwind: `[@media(hover:hover)]:hover:bg-...`. Without this, a tapped element on mobile gets a permanent hover state until the next tap elsewhere.
-
-### Typography Details
-- Text wrapping: `text-wrap: balance` on headings and short text blocks (≤6 lines in Chromium, ≤10 in Firefox); `text-wrap: pretty` on body paragraphs and longer text; leave default on code blocks and pre-formatted text
-- Font smoothing: apply `-webkit-font-smoothing: antialiased; -moz-osx-font-smoothing: grayscale` once on the root layout (macOS only)
-- Tabular numbers: use `font-variant-numeric: tabular-nums` for counters, timers, prices, number columns, or any dynamically updating numbers
-- Letter-spacing scales with font size: display type needs negative tracking to look engineered rather than stretched. Two tiers: roughly -0.022em for display sizes (32px and above), -0.012em for mid-range (20–28px), normal at 16px and below. Apply to any display-weight typeface, not just geometric sans. Positive letter-spacing on large headlines is always wrong.
-
-### Surfaces
-- Concentric border radius: calculate `outerRadius = innerRadius + padding` so nested rounded corners feel intentional, not mechanical; if padding exceeds `24px`, treat layers as separate surfaces and choose each radius independently
-- Optical alignment: nudge icons by eye, not just by math, so buttons feel centered; buttons with text and an icon use slightly less padding on the icon side (e.g., `pl-4 pr-3.5`); play triangles and asymmetric icons should shift `1px`-`2px` toward the heavier side, or fix the SVG directly
-- Shadows over borders: use layered `box-shadow` for depth on cards, buttons, and elevated elements so the surface feels lifted, not fenced in; reserve actual `border` for dividers, table cells, and layout separation (applies primarily to light mode; on dark surfaces see the dark-mode surface hierarchy rule below)
-- Image outlines: add a subtle inset outline so images hold their own depth without altering layout dimensions: `outline: 1px solid rgba(0,0,0,0.1); outline-offset: -1px` (light) or `outline: 1px solid rgba(255,255,255,0.1); outline-offset: -1px` (dark)
-- Minimum hit area: keep every interactive target at least 40×40px so even small controls feel generous and precise; extend with a centered pseudo-element when the visible element is smaller, and never let hit areas of two interactive elements overlap
-- Multi-card alignment: in a card group, bottom-align all CTA buttons so height variations between cards don't create a ragged action row. In pricing or comparison cards, align feature list items to a shared Y origin across all columns. In side-by-side panels (testimonials, plans, feature breakdowns), title, description, price, and action button must share baselines across the row. Section top and bottom padding need not be symmetric: optical balance often requires bottom padding 20-25% larger than top. Constrain body paragraph width to approximately 65 characters (ch) to maintain comfortable reading line length.
-- Light-mode app surface hierarchy: adjacent nested surfaces must be visually distinguishable. Minimum: background-color step of at least 4% lightness between sidebar and main area, and between main area and cards; or a shadow of at least `0 1px 3px rgba(0,0,0,0.10)` on elevated cards. A white card on a near-white background with `box-shadow: 0 1px 2px rgba(0,0,0,0.05)` is invisible -- that is not depth, it is noise.
-- Dark-mode surface hierarchy: the page canvas is a near-black solid (e.g. `#08090a`). Elevation is communicated by adding semi-transparent white overlays on top of that canvas: cards at `rgba(255,255,255,0.02)`, elevated surfaces at `0.04`, prominent panels at `0.05`. Borders follow the same logic: `rgba(255,255,255,0.05)` for subtle, `0.08` for standard. Traditional drop shadows (dark on dark) are nearly invisible; luminance stepping through background opacity is the primary depth cue on dark surfaces.
-- Border radius system: define a named radius scale during direction lock instead of picking values ad-hoc. A minimal scale is 3–4 tiers (e.g. `{4px, 8px, 12px, pill}`); a richer system might run 6–8 tiers. The point is committing to a named set before the first component so that all surfaces speak the same spatial language -- not covering every possible radius value.
-
-### Adding to Existing UI
-
-When extending an existing interface, first spend time understanding its visual vocabulary. Match all of the following before writing the first line of new code:
-- Copywriting tone and reading level (technical? casual? punchy?)
-- Color palette and semantic color roles (which tokens mean "danger", "success", "muted")
-- Hover and click states: scale, color shift, underline, background fill
-- Animation style: duration, easing, whether interactions bounce or are strictly ease-out
-- Shadow and card treatment: which surfaces are elevated, which are flush
-- Layout density and whitespace rhythm
-- Border radius choices and whether buttons are pill, square, or a specific fixed value
-
-If swapping in different content would make the new component look out of place, the vocabulary was not matched closely enough.
-
-### Responsive & Screen Verification
-- Verify the rendered surface, not a type check or CSS-balance read. Several regressions (early wraps, orphaned separator dots, table overflow) are invisible in source and only show in the render. Screenshot at phone (375px, plus 320px for buttons) and desktop (1280px), in every shipped locale.
-- Line widows: eliminate 1-2 word last lines by trimming the copy so the block rebalances, not by adding a `max-width` cap (a cap narrower than its container wraps early and leaves empty space on the right, which reads as a premature break). Detect objectively: flag any text block whose last line is under ~13% of its widest line; eyeballing misses them, and nested `<code>` hides them from greps.
-- Mobile CTA resting state: natural width, left-aligned to the surrounding text edge, height unchanged. Centering reads as floating; full-width `flex: 1` reads heavy; dropping button height to relieve a "too full" feel treats a width problem as a height one.
-- Spacing is a system, not a per-gap value. Run section spacing as one responsive ladder; when a page reads too airy or too tight, scale the whole set by a single factor across all breakpoints rather than tuning one gap. Asymmetry that survives tuning is structural.
-- Long-form and documentation surfaces stay light: a borderless prev/next text pager (not bordered cards), a sidebar active state as a thin rail rather than a filled block, and build-time zero-runtime-JS code highlighting (bake static spans, plain code stays the source) over a shipped highlighter.
-
-## Data Visualization Surfaces
-
-For dashboards, analytics views, chart-heavy interfaces, or number-dense displays, load `references/design-data-viz.md`. It owns dashboard defaults, chart selection, number alignment, and product-benchmark extraction.
-
-## Reflex Fonts to Reject
-
-LLMs default to these because they dominate training data. Using them signals "no decision was made." Pick from foundries with a clear voice instead. The ban is on reflex use as a display face; informed product-UI use (e.g. Inter for a dense data table) is allowed when justified. This list is not exhaustive -- any font used reflexively without a stated reason qualifies.
-
-Reject: Inter, DM Sans, DM Serif Display, DM Serif Text, Outfit, Plus Jakarta Sans, Instrument Sans, Instrument Serif, Space Grotesk, Space Mono, IBM Plex Sans, IBM Plex Serif, IBM Plex Mono, Syne, Fraunces, Newsreader, Lora, Crimson Pro, Crimson Text, Playfair Display, Cormorant, Cormorant Garamond.
-
-## Font Selection Procedure
-
-1. Write three words that describe the brand (e.g. "precise, minimal, fast").
-2. Name the three fonts you would reach for reflexively.
-3. Reject all three.
-4. Pick a typeface from a named foundry (Klim, Commercial Type, Colophon, Grilli Type, OH no Type, Village, etc.) or an open-source option with a clear personality that matches the brand words. Be able to explain why that specific typeface in one sentence.
-
-## CJK & Multilingual Type
-
-When the interface mixes Chinese, Japanese, or Korean with Latin, Latin-only type rules silently break the CJK text. Apply these before handoff:
-
-- **Latin face first, system CJK face after** in the stack, so each script renders with correct glyphs: `font-family: -apple-system, "SF Pro Text", "PingFang SC", "Noto Sans SC", sans-serif;`. Latin runs use the Latin face; Han characters fall through to the CJK face.
-- **Give CJK body text more line-height than Latin**: roughly 1.7–1.8 for reading. Dense Hanzi needs more vertical room than the 1.4–1.5 that suits Latin body copy.
-- **Tag runs with `lang="zh"` / `lang="ja"` / `lang="en"`** so the browser picks the right font and line-breaking. Mixed-language paragraphs break badly without it.
-- **Serif reading modes need an explicit CJK serif fallback.** Most Latin "reading serif" webfonts carry no CJK glyphs, so a serif toggle silently drops Chinese back to a sans and looks broken. Pair them: `"Newsreader", "Songti SC", "Noto Serif SC", serif`.
-- **Do not apply negative letter-spacing to CJK runs.** The display-type tracking rule above is Latin-only; tightening tracking on Hanzi cramps the glyphs and reads as a rendering bug. Scope tracking to `lang="en"` runs.
-
-## Color System: OKLCH Rules
-
-- Use OKLCH instead of HSL. OKLCH is perceptually uniform: equal numeric changes produce equal perceived changes across the spectrum.
-- Reduce chroma as lightness approaches the extremes. At 85% lightness a chroma around 0.08 is enough; pushing to 0.15 looks garish. At 15% lightness, tighten chroma similarly.
-- Tint neutrals toward the brand hue with a chroma of 0.005 to 0.01. Even this faint amount is perceptible and creates subconscious cohesion.
-- 60-30-10 is about visual weight, not pixel count. 60% neutral/surface, 30% secondary text and borders, 10% accent.
-- Never use gray text on a colored background. Use a shade of the background hue at reduced lightness instead.
-
-## Theme Matrix
-
-Choose light or dark deliberately based on audience and context. Neither is a default.
-
-| Context | Direction | Reason |
-|---|---|---|
-| Trading or analytics dashboard, night-shift use | Dark | High data density; reduced glare during long sessions |
-| Children's reading or learning app | Light | Welcoming, low fatigue for eyes still developing contrast sensitivity |
-| Enterprise SRE or observability tool | Dark | Operator context; dark surfaces read at a glance in low-light NOC rooms |
-| Weekend planning, recipes, journaling | Light | Ambient daytime use; light feels casual and approachable |
-| Music player or media browser | Dark | Content-forward; dark surfaces recede and let media pop |
-| Hospital or clinical patient portal | Light | Trust and legibility are paramount; clinical associations favor light |
-| Vintage or artisanal brand site | Cream/warm light | Dark would clash with the analog material references |
-
-If the answer is not obvious from the context, default to light. If the user's context implies both modes, ship light first and layer dark-mode tokens on top.
-
-## Absolute Bans (CSS-Pattern Level)
-
-These patterns appear in the majority of AI-generated interfaces. Each one has a specific rewrite. Not exhaustive -- any CSS pattern applied as a mindless default rather than an intentional choice belongs in the same category.
-
-| Pattern | Why | Rewrite |
-|---|---|---|
-| `border-left` or `border-right` wider than 1px as a section accent | The single most overused "design touch" in admin and dashboard UIs; it looks like a mistake at anything beyond a hairline divider | Change element structure: use a colored dot, a short horizontal rule, a background swatch, or a typographic weight shift instead |
-| `background-clip: text` gradient text | Decorative rather than meaningful; one of the top AI design tells; illegible when printed or in high-contrast mode | Use a solid brand color, a tinted neutral, or typographic weight for emphasis |
-| `backdrop-filter: blur` glassmorphism as the default card surface | Expensive on low-power devices; overused; the layered-depth illusion breaks with a solid border | Use elevated surfaces via background color steps and `box-shadow` instead |
-| Purple-to-blue gradients or cyan-on-dark accent systems | The canonical "AI design" color palette; communicates nothing about the brand | Pick a palette from the brand words via the OKLCH rules above |
-| Generic rounded-rect card with `box-shadow` as the default container | Template thinking; applies the same container to every content type regardless of hierarchy | Default to cardless sections; only add card treatment when the content type requires it |
-| Modals as a lazy escape for overflow UI | Interrupts flow and breaks browser back navigation; used when an inline expansion, drawer, or separate page would be better | Inline expand, detail panel, or dedicated route; modals only when the action truly requires focus-lock |
-| `transition: all` or animating width/height/padding/margin | Forces the browser into layout recalculation on every frame | List exact properties (`transition-property: transform, opacity`); use `grid-template-rows: 0fr to 1fr` for height reveals |
-
-## Motion Specifics
-
-Complements the motion timing in the main SKILL.md constraints.
-
-- No bounce or elastic easing. Real objects decelerate smoothly. Use exponential ease-out (`ease-out-quart`, `ease-out-quint`, or `cubic-bezier(0.16,1,0.3,1)`) for natural, high-quality deceleration.
-- Animate `transform` and `opacity` only. Every other property triggers layout or paint.
-- For height reveals, use `grid-template-rows: 0fr` to `1fr` transitions instead of animating `height` directly. It avoids the `height: auto` animation trap.
-- Icon swaps: use a 120ms cross-fade with `opacity` and a subtle `scale(0.9)` to `scale(1)`. No rotation unless rotation is semantically meaningful (e.g. a chevron indicating direction change).
-- Do not use `transition: all` even as a quick prototype shortcut. It animates layout, color, and font-size simultaneously, causing visible jank.
-
-## Reference-site Brand Presets (awesome-design-md)
-
-`VoltAgent/awesome-design-md` maintains 66+ curated DESIGN.md files extracted from real-world brand sites. Running `npx getdesign@latest add <brand>` drops the file into the project root, giving the agent concrete token values to decompose rather than reasoning from memory.
-
-**Usage rule:** never auto-run the command. Offer it as an option during direction lock, run it only with explicit user approval, and treat the result as seed decomposition material, not a finished direction.
-
-**Brands in the catalog** (recognize these when a user names a reference):
-
-| Category | Brands |
-|---|---|
-| AI & LLM | Claude, Cohere, ElevenLabs, Mistral, Ollama, Replicate, RunwayML, Together AI, xAI |
-| Dev Tools & IDEs | Cursor, Expo, Lovable, Raycast, Superhuman, Vercel, Warp |
-| Backend / DB / DevOps | ClickHouse, Composio, HashiCorp, MongoDB, PostHog, Sanity, Sentry, Supabase |
-| Productivity & SaaS | Cal.com, Intercom, Linear, Mintlify, Notion, Resend, Zapier |
-| Design & Creative | Airtable, Clay, Figma, Framer, Miro, Webflow |
-| Fintech & Crypto | Binance, Coinbase, Kraken, Revolut, Stripe, Wise |
-| E-commerce & Retail | Airbnb, Meta, Nike, Shopify |
-| Media & Consumer | Apple, IBM, NVIDIA, Pinterest, PlayStation, SpaceX, Spotify, Uber |
-| Automotive | BMW, Bugatti, Ferrari, Lamborghini, Tesla |
-
-**Conflict resolution:** this skill's rules always win. If the preset recommends a font on the Reflex Fonts blocklist (e.g. Inter as a display face), discard it and apply the Font Selection Procedure. If it proposes a pattern in the Absolute Bans table (e.g. purple-to-blue gradient), discard it. State the override in the handoff summary.
-
-Source: [github.com/VoltAgent/awesome-design-md](https://github.com/VoltAgent/awesome-design-md)
-
-## Reference Material Priority
-
-When source code and a screenshot are both available for a reference UI: read the code. Source files contain exact token values; screenshots require guessing. Reconstruct from what is written, not what is visible.
-
-When only a URL is provided: fetching it returns extracted text only, with no layout information. For visual references ("make it look like X"), ask for a screenshot rather than inferring visual design from stripped HTML.
-
-## DESIGN.md Scaffold (Optional, Production UIs)
-
-For a multi-page or production UI, emit a short `DESIGN.md`-style summary before writing the first component. This forces enumeration of decisions that would otherwise be left implicit and lets the user correct direction early. The nine sections:
-
-1. **Visual Theme and Atmosphere** - mood, density, design philosophy in 2-3 sentences
-2. **Color Palette and Roles** - semantic name + value + functional role for each color token
-3. **Typography Rules** - font family, size scale, weight scale, line-height, letter-spacing; a table if more than 4 levels
-4. **Component Stylings** - buttons (all states), cards (if used), inputs, navigation; describe each with states (default, hover, active, disabled)
-5. **Layout Principles** - spacing scale, grid columns, whitespace philosophy
-6. **Depth and Elevation** - shadow system or background-color-step system; describe each level
-7. **Do's and Don'ts** - 5 to 10 guardrails specific to this project, not generic rules
-8. **Responsive Behavior** - breakpoints, how navigation collapses, touch target minimums
-9. **Agent Prompt Guide** - a quick color reference (name: value pairs) + 3 to 5 example component prompts ready to paste into a follow-up request. Prompts must be specific enough to execute without further lookup: every value, every radius, every letter-spacing, every weight inlined. Example standard (values are illustrative, use the project's own tokens): "Create a hero on `{bg-canvas}`, headline at 48px weight 600, line-height 1.00, letter-spacing -0.022em, color `{text-primary}`, CTA at `{accent}` with `{btn-radius}` radius"; that level of specificity, not "hero with primary color and CTA button"
-
-For a single component or quick prototype, skip this. The three-line thesis in SKILL.md is sufficient.
-
-## Pre-Handoff Checklist: Strategic Omissions
-
-These are the items most frequently missing from AI-generated UIs because they require intentional product thinking, not visual judgment. Run through them before every handoff.
-
-- [ ] **Custom 404 page**: a generic framework 404 is a broken experience. Build a branded page with a clear path back (home link, search, or most-used nav items).
-- [ ] **Back navigation**: every page reachable by user action must have a clear, functional path back. Dead-end pages (detail views, confirmation screens, modal-only flows) are UX failures.
-- [ ] **Form client-side validation**: email fields validate format before submit; required fields show inline errors; error messages appear adjacent to the field, not only at form top.
-- [ ] **Skip-to-content link**: a visually hidden `<a href="#main-content">Skip to main content</a>` as the first focusable element in the document. Required for keyboard accessibility.
-- [ ] **Cookie consent**: if the product operates in the EU or California, cookie consent UI is not optional. Scope the implementation to the jurisdiction.
-- [ ] **Footer Privacy and Terms links**: every product page needs these. Their absence signals "demo", not "product".
-
-These are not visual polish items. They are the difference between a demo and a shippable product.
-
-## AI Slop Test
-
-Would a stranger glancing at the first viewport say "an AI made this" immediately? If yes, the committed direction was not committed enough. The usual culprits: reflex font, default purple accent, centered hero with generic card grid beneath. Fix the typography, the color system, or the layout until the answer flips.
-
-## Brand Preset Flow
-
-For well-known brands (Linear, Stripe, Claude, Vercel, Apple, Tesla, Notion, Figma, Airbnb, Spotify, and ~56 others catalogued in `awesome-design-md`): ask the user whether to pull the curated preset via `npx getdesign@latest add <brand>`. If they approve, run it, read the generated `DESIGN.md` at project root, then do the 3-property decomposition against that file rather than from memory. The preset is a starting point, not a direction: the user still names the aesthetic precisely, and the reflex-font blocklist and absolute bans still win on any conflict.
-
-## App Shell Rules
-
-When building a sidebar + main workspace layout (Slack, Linear, Notion class):
-- Decorative backgrounds default to off
-- Surface hierarchy uses background-color steps and shadow only
-- All interactive elements get `active:scale-95`
-- Button radius is consistent within each component type (pick one: pill, square, or one fixed value, do not mix)
-- Commit to a named radius scale before the first component (see Border radius system above)
-
-## Options Guide
-
-When asked for design options, give at least 3 variations spread across genuinely different dimensions:
-
-- **Dimensions to vary**: visual density, typographic personality, color temperature, layout structure, motion character, amount of decoration, level of abstraction
-- **Mix approaches**: one option that follows existing conventions closely, one that remixes the brand DNA in a new way, one that is deliberately unexpected
-- **Progress from basic to bold**: the first option is safe and understandable; later options push further
-- Three options that differ only by accent color are not three variations. Vary the layout, the typeface, the motion, the surface treatment.
-
----
-
-*Rules in Reflex Fonts, Font Selection, OKLCH, Theme Matrix, Absolute Bans, Motion Specifics, and AI Slop Test adapted from [pbakaus/impeccable](https://github.com/pbakaus/impeccable) (Apache 2.0). DESIGN.md Scaffold adapted from [getdesign.md](https://getdesign.md) (MIT); concept credited to Google Stitch. Brand preset catalog from [VoltAgent/awesome-design-md](https://github.com/VoltAgent/awesome-design-md) (MIT). Content Authenticity, Multi-Card Alignment, and Strategic Omissions inspired by [Leonxlnx/taste-skill](https://github.com/Leonxlnx/taste-skill).*