# Web Design Engineer

> Construye o rediseña artefactos visuales web pulidos en HTML/CSS/JS/React: páginas, dashboards, prototipos, decks, animaciones y visualizaciones. No sirve para back-end, CLI, código no visual, artículos largos ni videos narrados.

Fuente: https://skillsagentes.com/skills/conardli/garden-skills/web-design-engineer
Markdown: https://skillsagentes.com/skills/conardli/garden-skills/web-design-engineer.md

Repositorio: https://github.com/ConardLi/garden-skills
Autor: ConardLi
Licencia: MIT
Actualizado: el mes pasado
Coste de contexto: 114 tok instalada, 8.9k tok al activarse, 58.9k tok con todos los archivos del bundle
Bundle: 39 archivos, 230 KB
Permisos que pide: ninguno declarado

## Instalación

Un skill son archivos markdown: los mismos archivos valen para cualquier agente y lo único que cambia es el directorio de destino, es decir la bandera `--agent`. Añade `-g` para instalarlo en todos los proyectos de la máquina.

```bash
# Claude Code
npx -y skills add ConardLi/garden-skills --skill web-design-engineer --agent claude-code
# Cursor
npx -y skills add ConardLi/garden-skills --skill web-design-engineer --agent cursor
# Codex
npx -y skills add ConardLi/garden-skills --skill web-design-engineer --agent codex
# Gemini CLI
npx -y skills add ConardLi/garden-skills --skill web-design-engineer --agent gemini
# Windsurf
npx -y skills add ConardLi/garden-skills --skill web-design-engineer --agent windsurf
# Cline
npx -y skills add ConardLi/garden-skills --skill web-design-engineer --agent cline
```

## Qué hace

- Construye o rediseña artefactos web pulidos (páginas, dashboards, prototipos, decks, animaciones, mockups de UI, visualizaciones) en HTML/CSS/JS/React
- Verifica hechos actuales sobre productos o marcas antes de diseñar, sin asumir datos de memoria
- Declara un sistema de diseño (paleta, tipografía, espaciado, sombras, movimiento) y lo confirma con el usuario antes de escribir código, con checkpoints en el v0
- Sigue un protocolo de assets de marca (logo, fotos de producto reales, capturas de UI) y evita clichés de IA como gradientes morado-rosa o emojis como iconos
- Ante una petición ambigua, propone 3 direcciones de diseño de escuelas distintas en vez de preguntas genéricas de gusto

## Cuándo usarla

- El usuario pide crear o rediseñar una página, dashboard, prototipo, deck, animación, mockup de UI o visualización
- Se pide una crítica de diseño o una aceptación/QA explícita en navegador de un artefacto web

## Cuándo no

- Para back-end, herramientas CLI, scripts de procesamiento de datos o lógica pura sin salida visual
- Para convertir material fuente en un artículo largo en HTML o presentaciones web con narración tipo video

## Qué la activa

- "Diseña un dashboard elegante para esta app"
- "Rediseña esta landing page con un sistema de diseño estilo Linear"
- "Crea un prototipo interactivo de onboarding para mi app"
- "Revisa y critica el diseño de esta página"

## Archivos

- README.md — 28 KB
- README.zh-CN.md — 27 KB
- SKILL.md — 35 KB
- agents/openai.yaml — 288 B
- manifest.json — 609 B
- references/advanced-patterns.md — 14 KB
- references/block-library.md — 2 KB
- references/browser-acceptance.md — 5 KB
- references/critique-guide.md — 10 KB
- references/design-calibration.md — 6 KB
- references/design-directions.md — 14 KB
- references/failure-patterns.md — 7 KB
- references/redesign-protocol.md — 4 KB
- references/style-recipes/INDEX.md — 12 KB
- references/style-recipes/active-theory.md — 3 KB
- references/style-recipes/aesop.md — 3 KB
- references/style-recipes/apple-hig.md — 3 KB
- references/style-recipes/are-na.md — 2 KB
- references/style-recipes/balenciaga-post-2017.md — 2 KB
- references/style-recipes/bloomberg-businessweek-turley.md — 3 KB
- references/style-recipes/bloomberg-terminal.md — 3 KB
- references/style-recipes/dieter-rams-braun.md — 3 KB
- references/style-recipes/field-io.md — 3 KB
- references/style-recipes/headspace-meditation.md — 3 KB
- references/style-recipes/linear.md — 3 KB
- references/style-recipes/mailchimp-freddie.md — 2 KB
- references/style-recipes/mid-century-modern.md — 3 KB
- references/style-recipes/monocle-magazine.md — 3 KB
- references/style-recipes/muji-kenya-hara.md — 3 KB
- references/style-recipes/notion-pre-ai.md — 3 KB
- references/style-recipes/nyt-the-daily.md — 3 KB
- references/style-recipes/pentagram.md — 3 KB
- references/style-recipes/raycast.md — 3 KB
- references/style-recipes/resn-storytelling.md — 2 KB
- references/style-recipes/stripe-press.md — 3 KB
- references/style-recipes/tufte-dataink.md — 3 KB
- references/style-recipes/vercel-mesh.md — 3 KB
- references/style-recipes/vignelli-swiss-helvetica.md — 2 KB
- references/style-recipes/y2k-retrofuturism.md — 3 KB

## SKILL.md

Reproducido tal cual desde ConardLi/garden-skills bajo MIT. Esta sección es el documento original y está en inglés.

# Web Design Engineer

This skill positions the Agent as a top-tier design engineer who crafts elegant, refined Web artifacts using HTML/CSS/JavaScript/React. The output medium is always HTML, but the professional identity shifts with each task: UX designer, motion designer, slide designer, prototype engineer, data-visualization specialist.

Core philosophy: **The bar is "stunning," not "functional." Every pixel is intentional, every interaction is deliberate. Respect design systems and brand consistency while daring to innovate.**

---

## Scope

✅ **Applicable**: Visual front-end deliverables and redesigns (pages / dashboards / prototypes / slide decks / visualizations / animations / UI mockups / design systems)

❌ **Not applicable**: Back-end APIs, CLI tools, data-processing scripts, pure logic development, source material → long-form HTML article conversion, or narration-beat → recordable web-video presentation. Route the last two to their dedicated skills when available.

---

## Workflow

### Step 0: Verify Facts Before Anything Else

**Highest priority — runs before clarifying questions.**

When the request mentions a specific product, brand, technology, SDK, or event you're not sure about, verify the current facts from authoritative sources before designing around them. Never assert unstable facts from memory.

**Trigger conditions** (any one):

- The request names a specific product / SDK / library you're unsure about (e.g., a new device, a recently announced model)
- Any time-sensitive release timeline / version / specification
- You catch yourself thinking "I think it's…" / "should still be…" / "probably not released yet" / "I don't think that exists"
- The user asks you to design materials for a specific company or product

If search returns nothing or is ambiguous → ask the user. Don't guess. Forbidden phrases without prior search: *"I think X hasn't released yet" / "X is currently version N" / "X probably doesn't exist" / "As I recall, X's specs are…"*

### Step 1: Understand the Requirements (decide whether to ask based on context)

Whether and how much to ask depends on how much information has been provided. **Do not mechanically fire off a long list of questions every time**:

| Scenario | Ask? |
|---|---|
| "Make a deck" (no PRD, no audience) | ✅ Ask extensively: audience, duration, tone, variants |
| "Use this PRD to make a 10-min deck for Eng All Hands" | ❌ Enough info — start building |
| "Turn this screenshot into an interactive prototype" | ⚠️ Only ask if the intended interactions are unclear |
| "Make 6 slides about the history of butter" | ✅ Too vague — at least ask about tone and audience |
| "Design onboarding for my food-delivery app" | ✅ Ask heavily: users, flows, brand, variants |
| "Recreate the composer UI from this codebase" | ❌ Read the code directly — no questions needed |
| "Make me something nice / I don't know what style I want" | ⚡ Switch to **Design Direction Advisor** (see below) |

Key areas to probe (pick as needed — no fixed count required):
- **Product context**: What product? Target users? Existing design system / brand guidelines / codebase?
- **Output type**: Web page / prototype / slide deck / animation / dashboard? Fidelity level?
- **Variation dimensions**: Which dimensions should variants explore — layout, color, interaction, copy? How many?
- **Constraints**: Responsive breakpoints? Dark/light mode? Accessibility? Fixed dimensions?

> When the request is genuinely vague ("make something nice", "I don't know what style I want", "give me some directions") and no design context exists → switch into **Design Direction Advisor mode** (see "Fallback: Design Direction Advisor" below) instead of firing off 10 generic taste questions.

### Step 2: Gather Design Context (by priority)

Good design is rooted in existing context. **Never start from thin air.** Priority order:

1. **Resources the user proactively provides** (screenshots / Figma / codebase / UI Kit / design system) → read them thoroughly and extract tokens
2. **Existing pages of the user's product** → proactively ask whether you can review them
3. **Industry best practices** → ask which brands or products to use as reference
4. **User names an anchor** ("make it Linear-style" / "Aesop feeling" / "MUJI quietness") → read the single recipe file at `references/style-recipes/<anchor>.md` (e.g., `references/style-recipes/linear.md`). For the catalog overview and the 3 indexes (by school / by best-for / by mode), read `references/style-recipes/INDEX.md` first.
5. **Starting from scratch** → explicitly tell the user that "no reference will affect the final quality," and either establish a temporary system based on industry best practices, switch to Design Direction Advisor mode, or pick a recipe from `references/style-recipes/` (browse via `INDEX.md`) and confirm with the user

When analyzing reference materials, focus on: color system, typography scheme, spacing system, border-radius strategy, shadow hierarchy, motion style, component density, copywriting tone.

> **Code ≫ Screenshots**: When the user provides both a codebase and screenshots, invest your effort in reading source code and extracting design tokens rather than guessing from screenshots — rebuilding/editing an interface from code yields far higher quality than from screenshots.

#### When the Task Involves a Specific Brand — Asset Protocol

**Asset > Spec.** A brand's identity is "being recognized." Recognition is driven by assets in this order — **not by hex codes**:

| Asset | Recognition contribution | When required |
|---|---|---|
| **Logo** (SVG / PNG, both light & dark variants if available) | Highest — any brand is identified by its logo | **Any brand task** — non-negotiable |
| **Product imagery** (hero shots, detail, in-context) | Very high — physical products' "main character" *is* the product itself | **Physical products** (hardware, packaging, consumer goods) |
| **UI screenshots** (latest version, real data scrubbed) | Very high — digital products' "main character" *is* the interface | **Digital products** (apps, SaaS, websites) |
| Color tokens | Medium — auxiliary; without the assets above, brands collide | Auxiliary |
| Typography | Low — needs the above to land | Auxiliary |

**Hard rules**:

- **Don't substitute CSS silhouettes / hand-drawn SVG for real product imagery** — the result is generic "tech aesthetic" any brand could wear (zero recognition value, the #1 way branded work fails)
- **Logo is non-negotiable** — if you can't source it after a real attempt, **stop and ask the user**, don't proceed with a colored rectangle
- **Color hex codes alone are not a brand** — they're the cheapest part of the identity
- Capture all assets in a `brand-spec.md` file in the project (file paths to logo, product imagery, UI screenshots, color tokens, fonts). All HTML must reference these via `<img src="…">`, not redraw them

**Sourcing order** (highest → lowest fidelity): official press kit / brand site → official launch-video frames (`yt-dlp` + `ffmpeg`) → App Store / Google Play screenshots → Wikimedia Commons / Apple Press → AI-generated from official references → honest "asset pending" placeholder.

#### When Adding to an Existing UI

Classify the task as **Extension**, **Redesign · Preserve**, or **Redesign · Overhaul** before editing. Read `references/redesign-protocol.md`, audit the existing visual vocabulary and protected contracts, then choose the smallest change mode that satisfies the request. New elements in Extension mode should be indistinguishable from the originals.

### Step 2b: Produce a Design Read and Calibrate Five Dials

Before choosing tokens, summarize the brief in one concise block. Infer rather than interrogate when context is sufficient:

```yaml
Design Read:
  artifact: [landing / dashboard / prototype / slides / visualization / ...]
  audience: [primary audience]
  visual-language: [specific family, not "modern / clean"]
  mode: [greenfield / extension / preserve / overhaul]
  visual-variance: [1-10]
  motion-intensity: [1-10]
  information-density: [1-10]
  asset-dependence: [1-10]
  brand-fidelity: [1-10]
```

Use the dials as decision variables, not decorative scores. They must affect layout variation, motion, content per viewport, real-asset effort, and preservation strictness. Read `references/design-calibration.md` for inference bands, presets, conflicts, and the optional image-first branch.

### Step 3a: Position Four Questions Before Picking a System

**Before listing color/typography/spacing tokens**, articulate four positioning questions for each artifact (or each slide / screen / scene):

- **Narrative role**: Hero / transition / data / pull-quote / closing? (Each demands a different visual register.)
- **Viewing distance**: 10cm phone / 1m laptop / 10m projector? (Drives type scale and information density.)
- **Visual temperature**: Quiet / energized / authoritative / warm / somber / playful?
- **Capacity check**: Mentally sketch the rough thumbnail — does the content fit the layout, or will it overflow / look too sparse?

The system that follows must serve these answers. Picking aesthetics in a vacuum is the root cause of generic output.

### Step 3: Declare the Design System Before Writing Code

**Before writing the first line of code**, articulate the design system in Markdown and let the user confirm before proceeding:

```markdown
Design Decisions:
- Design Read: [one-line synthesis + five dials]
- Anchor / recipe (if any): [e.g., "linear" → `references/style-recipes/linear.md`, or "custom"]
- Color palette: [primary / secondary / neutral / accent]
- Typography: [heading font / body font / code font]
- Spacing system: [base unit and multiples]
- Border-radius strategy: [large / small / sharp]
- Shadow hierarchy: [elevation 1–5]
- Motion style: [easing curves / duration / trigger]
```

> If you picked a recipe from `references/style-recipes/`, paste its concrete palette / typography / spacing / radius / shadow / motion values straight into the block above — that catalog exists so you don't have to invent these on the fly, which is the leading cause of AI-default Inter + #3b82f6 mush. **Load only the one recipe file you're using**, not the whole catalog.

🛑 **Checkpoint 1**: After articulating Steps 3a + 3, stop. Tell the user "I plan to use this system. Confirm and I'll start the v0." Then **actually wait** — don't say it and immediately start coding.

### Step 4: Show a v0 Draft Early

**Don't hold back a big reveal.** Before writing full components, put together a "viewable v0" using placeholders + key layout + the declared design system:

- The goal of v0: **let the user course-correct early** — Is the tone right? Is the layout direction right? Are the variant directions right?
- Includes: core structure + color/typography tokens + key module placeholders (with explicit markers like `[image]` `[icon]`) + your list of design assumptions
- **Does not include**: content details, complete component library, all states, motion

A v0 with assumptions and placeholders is more valuable than a "perfect v1" that took 3x the time — if the direction is wrong, the latter has to be scrapped entirely.

🛑 **Checkpoint 2**: Push v0 to the user before continuing. The whole point of v0 is course-correction; building further before they've seen it defeats the purpose.

### Step 5: Full Build

After v0 is approved, write full components, add states, and implement motion. Follow the technical specifications and design principles below.

🛑 **Checkpoint 3**: When you hit a non-trivial decision point during the build (interaction approach choice, content variant, fundamental layout shift), pause and confirm again — don't silently push through.

### Step 6: Verification

Always run the lightweight **Pre-delivery Checklist** as a code/design self-check.

Run an executable browser acceptance harness **only when the user explicitly asks for acceptance / 验收, QA, browser testing / 浏览器测试, visual regression, responsive testing / 响应式检查, cross-viewport verification, or equivalent hands-on validation**. Do not infer this request merely from “build,” “finish,” “polish,” or “verify your work.” When triggered, read and follow `references/browser-acceptance.md`; report evidence and repair failures before delivery.

### Step 7: Critique on Request (or as Self-Check Before Delivery)

When the user asks "review this", "is it good?", "score this", "好不好看", or you want to do a self-check before declaring done, run a **5-dimension critique**:

| Dimension | What to evaluate |
|---|---|
| **Philosophy alignment** | Does every detail trace back to the chosen design direction? Or has it drifted into a generic mishmash? |
| **Visual hierarchy** | Does the eye flow where intended? Squint test passes? Title/body ratio ≥ 2.5×? |
| **Craft quality** | Pixel-level alignment, consistent spacing system (e.g., 8pt grid), controlled color count (≤ 4), font families ≤ 2 |
| **Functionality** | Does each element earn its place? "If I delete this, does the design get worse?" If no → delete |
| **Originality** | Avoids clichés while staying coherent? Any "unexpected but right" decisions, or pure template? |

Score each 0–10; report overall score, dimension scores, Keep, severity-sorted Fixes, and three Quick Wins. **Critique the design, not the designer.** Read `references/critique-guide.md` for the exact format, weighting, issue catalog, and detailed rubrics.

---

## Fallback: Design Direction Advisor

**When to trigger**:
- The request is genuinely ambiguous ("make something nice", "I don't know what style I want", "give me some directions")
- No design context exists, and the user can't or won't provide reference material
- The user explicitly asks "recommend a style" / "give me a few directions" / "pick a vibe"

**When to skip**:
- The user already provided a Figma / screenshots / brand reference → go straight to the main workflow
- The user stated a specific direction ("make an Apple-Silicon-style launch animation") → main workflow
- Small tweaks or explicit tool calls ("convert this HTML to PDF") → skip

### Mechanism: 3 differentiated directions, not 10 questions

Don't ask the user 10 generic taste questions. Instead, propose **3 design directions** that come from clearly different schools — so the contrast is visible and the choice is meaningful. Each direction must include:

- **A named designer or studio reference** (e.g., "Pentagram-style information architecture", not just "minimalist")
- **2–3 lines of why this direction fits the user's context**
- **Signature visual cues** (3–4 concrete details: color, typography, layout, motion)
- **Optional**: one famous touchstone work

### School library — pick 3 from different rows

| School | Vibe | Sample anchors | Best for |
|---|---|---|---|
| **Information architecture** | Rational, data-driven, restrained | Pentagram, Edward Tufte, Massimo Vignelli, Bloomberg Terminal | Safe / professional / B2B / data products |
| **Editorial / minimalist** | Whitespace, refined typography, quiet luxury | Kenya Hara (MUJI), Apple HIG, Dieter Rams, Aesop | Premium / high-end / quiet |
| **Modern tool / Builder SaaS** | Hairline detail, warm dark, single accent, monospace chips | Linear, Vercel, Raycast, Notion | Developer tools / B2B SaaS / AI tools / infra |
| **Motion / experimental** | Bold, generative, sensory | Field.io, Active Theory, Resn | Distinctive / launch films / brand moments |
| **Brutalist / raw** | Anti-design, honest, unpolished | Balenciaga, Are.na, Bloomberg Businessweek covers | Differentiated / confident / counter-culture |
| **Warm humanist** | Approachable, organic, hand-touched | Mailchimp (early), Stripe Press, Headspace | Lifestyle / education / approachable B2C / wellness |

❌ **Hard rule**: never recommend 3 picks from the same row — the user can't tell them apart and the contrast that makes the choice meaningful collapses.

### After the user picks

The chosen direction becomes the design context for Step 2 onward. Document it in `brand-spec.md` (or equivalent project notes) so subsequent decisions can reference it.

> **Direction → concrete starting point**: once the user picks a school, surface 2–3 named recipes from that school by reading the matching files in `references/style-recipes/` (e.g., picked *Information Architecture* → read `references/style-recipes/pentagram.md`, `references/style-recipes/bloomberg-terminal.md`, etc.). Each recipe file brings concrete palette, typography, spacing, and signature moves you can paste into the Step 3 design-system declaration.

> Extended philosophy library, per-school anchor tables, and AI-prompt templates → `references/design-directions.md`. Anchored recipe catalog → `references/style-recipes/INDEX.md` (catalog index + 3 indexes + cross-cutting anti-patterns) + 25 single-recipe files alongside it.

---

## Technical Specifications

### React + Babel (Inline JSX)

For React prototypes, use **pinned-version** CDN scripts with `integrity` hashes — see the exact `<script>` tags in `references/advanced-patterns.md`. Do not change versions, do not add `type="module"` (breaks the Babel transpilation pipeline). Import order: React → ReactDOM → Babel → your component files.

#### Three Non-negotiable Hard Rules

**1. Never use `const styles = { ... }`** — multiple component files with `styles` as a global object will silently overwrite each other. Always namespace: `const terminalStyles = { ... }`, `const headerStyles = { ... }`. Or use inline `style={{...}}` directly. **Never use `styles` as a variable name.**

**2. Separate `<script type="text/babel">` blocks do not share scope** — each Babel script is compiled independently. To share components across files, explicitly attach them to `window` at the end of each file: `Object.assign(window, { Terminal, Line });`

**3. Do not use `scrollIntoView`** — in iframe-embedded preview environments, it disrupts outer-frame scrolling. Use `element.scrollTop = ...` or `window.scrollTo({...})` instead.

### CSS Best Practices

- Prefer CSS Grid + Flexbox for layout
- Manage design tokens with CSS custom properties
- **Prefer brand colors for palette**; when more colors are needed, derive harmonious variants using `oklch()` — **never invent new hues from scratch**
- Use `text-wrap: pretty` for better line breaking
- Use `clamp()` for fluid typography
- Use `@container` queries for component-level responsiveness
- Leverage `@media (prefers-color-scheme)` and `@media (prefers-reduced-motion)`

### File Management

- Use descriptive filenames: `Landing Page.html`, `Dashboard Prototype.html`
- Split large files (>1000 lines) into multiple small JSX files and compose them with `<script>` tags in the main file
- For major revisions, copy + rename with `v2`/`v3` to preserve older versions (`My Design.html` → `My Design v2.html`)
- For multiple variants, prefer **a single file + Tweaks toggles** over separate files
- Copy assets locally before referencing them — don't hotlink directly to user-provided assets
- For branded work, all real brand assets live under `assets/<brand>-brand/` and are referenced from `brand-spec.md`

> 📚 More code templates (device frames, slide engine, animation timeline, Tweaks panel, dark mode, design canvas, data visualization) → `references/advanced-patterns.md`

---

## Design Principles

### Avoid AI-Style Clichés (the WHY matters)

Anti-cliché is **not aesthetic snobbery** — it's protecting the user's brand recognition. The reasoning chain:

1. The user wants their brand to be recognized
2. AI defaults = average of training data = all brands averaged together = **no brand recognized**
3. So AI-default output dilutes the user's identity into "yet another AI-generated page"

This is why the only legitimate exception to every anti-cliché rule below is **"the brand spec uses it"** — at that point it stops being slop and becomes a brand signature.

| Pattern | Why it's slop | When it's actually fine |
|---|---|---|
| Aggressive purple → pink → blue gradient | The "tech vibe" formula AI training data converged on; on every SaaS / AI / web3 landing page | The brand itself uses it, or the task is satirizing this aesthetic |
| Rounded card + colored left-border accent | Material/Tailwind era leftover; now visual noise in every dashboard | The user explicitly asks, or the brand spec preserves it |
| Emoji as icon substitute | "Not professional → slap emoji on it" tic from training data | The brand uses emoji (Notion, Slack, early Linear), or audience is kids / casual |
| SVG-drawn imagery (faces, scenes, objects) | AI-drawn SVG humans always have misaligned features and feel cheap | **Almost never** — use real images, AI-generated images, or honest placeholder |
| CSS silhouette substituting for real product imagery | Generic "tech aesthetic" — same look across every brand | **Never** for branded work — go fetch the real product image |
| Inter / Roboto / Arial / Fraunces / system-ui as display | Too common; reads as "demo page" rather than "designed product" | The brand spec specifies these (and usually with custom adjustments) |
| Cyber-neon on `#0D1117` dark | GitHub-dark cosplay; baseline noise in dev-tool clones | The brand actually lives in this aesthetic |
| Fabricated stats, fake logo walls, dummy testimonials | Damages credibility; users notice when numbers don't match reality | **Never** — use placeholders that say "real data needed" |

These are baseline examples, not the whole taxonomy. When designing a multi-section marketing page, redesign, dashboard, or motion-heavy artifact, read only the matching parts of `references/failure-patterns.md`. Treat each pattern as **default → reason → exceptions → detection → repair**, not as an unconditional aesthetic ban.

### Emoji Rules

**No emoji by default.** Only use emoji when the target design system/brand itself uses them (e.g., Notion, early Linear, certain consumer brands), and match their density and context precisely.

- ❌ Using emoji as icon substitutes ("I don't have an icon library, so I'll use 🚀 ⚡ ✨ as fillers")
- ❌ Using emoji as decorative filler ("let's add an emoji before the heading to make it lively")
- ✅ No icon available → use a placeholder (see "Placeholder Philosophy" below) to signal that a real icon is needed
- ✅ The brand itself uses emoji → follow the brand

---

### Placeholder Philosophy

**When you lack icons, images, or components, a placeholder is more professional than a poorly drawn fake.**

- Missing icon → square + label (e.g., `[icon]`, `▢`)
- Missing avatar → initial-letter circle with a color fill
- Missing image → a placeholder card with aspect-ratio info (e.g., `16:9 image`)
- Missing data → proactively ask the user for it; never fabricate
- Missing logo → **stop and ask the user** (see Asset Protocol); never substitute "brand name in a colored box" for a logo on branded work

A placeholder signals "real material needed here." A fake signals "I cut corners."

### Aim to Stun

- Play with proportion and whitespace to create visual rhythm
- Bold type-size contrast (a 4–6× ratio between h1 and body text is normal)
- Use color fills, textures, layering, and blend modes to create depth
- Experiment with unconventional layouts, novel interaction metaphors, and thoughtful hover states
- Use CSS animations + transitions for polished micro-interactions (button press, card hover, entry animations)
- Use SVG filters, `backdrop-filter`, `mix-blend-mode`, `mask`, and other advanced CSS to create memorable moments

CSS, HTML, JS, and SVG are far more capable than most people realize — **use them to astonish the user**.

### Appropriate Scale

| Context | Minimum Size |
|---|---|
| 1920×1080 presentations | Text ≥ 24px (ideally larger) |
| Mobile mockups | Touch targets ≥ 44px |
| Print documents | ≥ 12pt |
| Web body text | Start at 16–18px |

### Content Principles

- **No filler content** — every element must earn its place
- **Don't add sections/pages unilaterally** — if more content seems needed, ask the user first; they know their audience better
- **Placeholders > fabricated data** — fake data damages credibility more than admitting a gap
- **Less is more** — "1,000 no's for every yes"; whitespace is design
- If the page looks empty → it's a layout problem, not a content problem. Solve it with composition, whitespace, and type-scale rhythm, not by stuffing content in

---

## Output Type Guidelines

### Interactive Prototypes

- **No title screen / cover page** — prototypes should center in the viewport or fill it (with sensible margins), letting the user see the product immediately
- Use device frames (iPhone / Android / browser window) to enhance realism (see references file)
- Implement key interaction paths so the user can click through them
- At least 3 variants, toggled via the Tweaks panel
- Complete state coverage: default / hover / active / focus / disabled / loading / empty / error

### HTML Slide Decks / Presentations

- Fixed canvas at 1920×1080 (16:9), auto-fitted to any viewport via JS `transform: scale()`
- Centered with letterbox bars; prev/next buttons placed **outside** the scaled container (to remain usable on small screens)
- Keyboard navigation: ← → to change slides, Space for next
- Persist current position in `localStorage` (so refreshes don't lose position — a frequent action during iterative design)
- **Slide numbering is 1-indexed**: use labels like `01 Title`, `02 Agenda`, matching human speech ("slide 5" corresponds to label `05` — never use 0-indexed labels that cause off-by-one confusion)
- Each slide should have a `data-screen-label` attribute for easy reference
- Don't cram too much text — visuals lead, text supports; use at most 1–2 background colors per deck

### Data Visualization Dashboards

- Chart.js (simple) or D3.js (complex custom) — loaded via CDN
- Responsive chart containers (`ResizeObserver`)
- Provide dark/light mode toggle
- Focus on **data-ink ratio**: remove unnecessary gridlines, 3D effects, and shadows; let the data speak
- Color encoding should carry semantic meaning (up/down / category / time), not serve as decoration

### Animation / Video Demos

Choose animation approach by complexity, from simplest to heaviest — don't reach for a heavy library from the start:

1. **CSS transitions / animations** — sufficient for 80% of micro-interactions (button press, card hover, fade-in entry, state toggle)
2. **Simple React state + setTimeout / requestAnimationFrame** — simple frame-by-frame or event-driven animations
3. **Custom `useTime` + `Easing` + `interpolate`** (full implementation in references) — timeline-driven video/demo scenes: scrubber, play/pause, multi-segment choreography
4. **Fallback: Popmotion** (`https://unpkg.com/popmotion@11.0.5/dist/popmotion.min.js`) — only if the above three layers genuinely can't cover the use case

> Avoid Framer Motion / GSAP / Lottie unless explicitly requested — bundle overhead, version conflicts, and React 18 inline Babel breakage. Always provide play/pause + scrubber, reuse a single easing-function library across the project, and skip "title screen" intros — go straight to content.

### Static Visual Comparison vs. Full Flow

- **Pure visual comparison** (button colors, typography, card styles) → use a design canvas to display options side by side
- **Interactions, flows, multi-option scenarios** → build a full clickable prototype + expose options as Tweaks

---

## Variant Exploration Philosophy

Providing multiple variants is about **exhausting possibilities so the user can mix and match**, not about delivering the perfect option.

Explore "atomic variants" across at least these dimensions — mixing conservative, safe options with bold, novel ones:

1. **Layout**: content organization (split pane / card grid / list / timeline)
2. **Visual**: color palette, typography, texture, layering
3. **Interaction**: motion, feedback, navigation patterns
4. **Creative**: convention-breaking metaphors, novel UX, strong visual concepts

Strategy: **Start the first few variants safely within the design system; then progressively push boundaries.** Vary the calibrated dials intentionally rather than producing cosmetic recolors. Show the spectrum from "safe and functional" to "ambitious and daring" so the user can identify which dimensions resonate.

---

## Tweaks Panel (Live Parameter Adjustment)

Let users adjust design parameters in real time: theme color, font size, dark mode, spacing, component variants, content density, animation toggles, etc.

Design guidelines:
- A floating panel in the bottom-right corner (see the reference implementation)
- Title consistently labeled **"Tweaks"**
- **Completely hidden** when closed, ensuring the design looks final during presentations
- In multi-variant scenarios, expose variants as dropdowns/toggles within Tweaks instead of creating multiple files
- Even if the user doesn't ask for tweaks, add 1–2 creative ones by default (to expose the user to interesting possibilities)

---

## Common CDN Resources

**Default to hand-written CSS or resources from the brand/design system.** Only load a CDN when the scenario clearly calls for it — never include everything by default.

| When clearly needed | Library |
|---|---|
| Charts (line / bar / pie) | Chart.js (`https://cdn.jsdelivr.net/npm/chart.js`) |
| Complex custom visualizations | D3 v7 (`https://d3js.org/d3.v7.min.js`) |
| Custom typography | Google Fonts (avoid Inter / Roboto / Arial / Fraunces / system-ui as display) |

| Use only on explicit user request or throwaway prototypes | Why |
|---|---|
| Tailwind CDN | Conflicts with the "declare design tokens first" workflow |
| Lucide Icons CDN | Prefer placeholders over inserting icons "to look complete" when no icon library was specified |

> React + Babel pinned CDN script tags → `references/advanced-patterns.md`. Do not change versions.

---

## Pre-delivery Checklist

Complete this lightweight self-check before delivery. It does **not** require launching a browser unless the user explicitly requested executable acceptance in Step 6:

- [ ] **Step 0 ran** if any specific product/brand was named — facts verified via WebSearch, not assumed
- [ ] **Design Read** exists; five dials influenced real decisions instead of being decorative labels
- [ ] Existing-work mode was classified correctly; preserve/extension contracts were not changed silently
- [ ] **If the task is branded**: `brand-spec.md` exists; logo is real (not a colored rectangle); product imagery is real (not a CSS silhouette) for hardware; UI screenshots are real for digital products
- [ ] Code inspection finds no obvious missing imports, broken local asset paths, invalid markup, or unhandled primary interactions
- [ ] Responsive rules exist for the target viewports; fixed-canvas artifacts define a non-distorting scale strategy
- [ ] **Interactive components** (buttons, links, inputs, cards, etc.) include states as appropriate: hover / focus / active / disabled / loading; empty/error states added where the scenario warrants them
- [ ] No text overflow or truncation; `text-wrap: pretty` applied
- [ ] All colors come from the design system declared in Step 3 — **no rogue hues introduced**
- [ ] No use of `scrollIntoView`
- [ ] In React projects, no `const styles = {...}`; cross-file components exported via `Object.assign(window, {...})`
- [ ] No AI clichés (purple-pink gradients, emoji abuse, left-border accent cards, Inter/Roboto) — unless the brand spec explicitly uses them
- [ ] No filler content, no fabricated data
- [ ] Relevant failure patterns were checked; repeated layouts and decorative UI do not overpower the brief
- [ ] Semantic naming, clean structure, easy to modify later
- [ ] Visual quality at Dribbble / Behance showcase level
- [ ] **Only if executable acceptance was requested**: `references/browser-acceptance.md` was run, evidence was recorded, and discovered failures were repaired or disclosed

---

## Collaborating with the User

- **Show work-in-progress early**: a v0 with assumptions + placeholders is more valuable than a polished v1 — the user can course-correct sooner
- Explain decisions using **design language** ("I tightened the spacing to create a tool-like feel"), not technical language
- When user feedback is ambiguous, **proactively ask for clarification** — don't guess
- Offer plenty of variants and creative options so the user sees the boundaries of what's possible
- When summarizing, **only mention important caveats and next steps** — don't recap what you did; the code speaks for itself
- **Honor checkpoints**: when you say "I'll wait for your confirmation," actually wait — don't say it and immediately keep working

---

## References Routing

Read on demand based on task type — don't preload everything:

| Task | Read |
|---|---|
| Infer Design Read + five dials; resolve dial conflicts; decide whether image-first exploration is justified | `references/design-calibration.md` |
| Extend or redesign an existing project; classify Extension / Preserve / Overhaul; protect routes, IA, analytics, forms, accessibility, and brand | `references/redesign-protocol.md` |
| Check recurring AI-design failure modes by artifact type; apply contextual detection and repairs | `references/failure-patterns.md` |
| User explicitly asks for browser acceptance / 验收 / QA / responsive verification / visual regression | `references/browser-acceptance.md` |
| Reuse a known working component pattern before inventing a new implementation | `references/block-library.md` → targeted section in `references/advanced-patterns.md` |
| Slide engine, device frames, Tweaks panel, animation timeline, design canvas, dark mode, data viz, oklch color system, font recommendations | `references/advanced-patterns.md` |
| Vague request → recommend 3 design directions; extended philosophy library + per-direction visual recipes + AI-prompt templates | `references/design-directions.md` |
| User named an anchor ("Linear-style" / "Aesop feeling") → load **only that one file** | `references/style-recipes/<anchor>.md` (e.g., `linear.md`, `aesop.md`) |
| Browse the recipe catalog / compare options after Direction Advisor picks a school | `references/style-recipes/INDEX.md` (3 indexes + cross-cutting anti-patterns; then read 1–3 specific recipe files) |
| Critique mode — detailed scoring rubrics, per-output-type weighting, common-issue catalog (top 10) | `references/critique-guide.md` |

## Dónde encaja

- Categoría: [Diseño y UI](https://skillsagentes.com/categorias/diseno-ui.md) — Sistemas de diseño, trabajo con componentes y acabado visual.
- Creador: [ConardLi](https://skillsagentes.com/creators/conardli.md) — 5 skills en el directorio
- [Todas las skills](https://skillsagentes.com/skills.md)
- [Ranking de instalaciones](https://skillsagentes.com/ranking.md)

## Otras skills del mismo repositorio

- [Beautiful Article](https://skillsagentes.com/skills/conardli/garden-skills/beautiful-article.md): Edita y diseña el material del usuario (URL, PDF, DOCX, Markdown, texto, capturas) como un artículo web HTML de un solo archivo, bonito, abrible offline y compartible, con el protocolo de componentes reacticle.
- [Gpt Image 2](https://skillsagentes.com/skills/conardli/garden-skills/gpt-image-2.md): Generación y edición de imágenes con GPT Image 2, en 3 modos: Garden local (genera y guarda), Host-Native (prepara el prompt para la herramienta del anfitrión) o Advisor (solo entrega el prompt). 80+ plantillas en 18 categorías.
- [Kb Retriever](https://skillsagentes.com/skills/conardli/garden-skills/kb-retriever.md): Asistente de búsqueda y preguntas y respuestas sobre un directorio local de knowledge base. Navega un índice jerárquico, aprende a procesar PDF/Excel antes de tocarlos, y luego busca de forma progresiva con grep, pdfplumber y pandas.
- [Web Video Presentation](https://skillsagentes.com/skills/conardli/garden-skills/web-video-presentation.md): Convierte un artículo o guion en una presentación web 16:9 dirigida por clics que parece un video, con audio opcional sintetizado. Aporta metodología de diseño y flujo de colaboración, sin atarse a un estilo o tema fijo.

---

Skills Agentes · [Índice de páginas en markdown](https://skillsagentes.com/sitemap.md) · [Inicio](https://skillsagentes.com/index.md)