project-design

What this skill does

# Project Design Skill

Generate production-grade, visually distinctive web interfaces. Every page must look like it was designed by a professional — not generated by AI.

## When to Use

This skill applies whenever you generate HTML/CSS/JS for any visual web output — dashboards, landing pages, web apps, tools, portfolios, or any other page type.

## Reference Files

| File | Read When |
|------|-----------|
| [references/aesthetics.md](references/aesthetics.md) | Building a color palette, choosing typography, designing layout — the methodology for making design decisions |
| [references/components.md](references/components.md) | Building UI components — navigation, cards, tables, buttons, forms, hero sections, CTAs |
| [references/animations.md](references/animations.md) | Adding motion — scroll reveals, hover effects, modals, drawers, page load sequences |
| [references/charts.md](references/charts.md) | Creating charts — Chart.js/ECharts setup, chart type selection, mock data generation, dashboard layouts |

---

## Priority Override: User Settings Come First

If the user (or the brief) explicitly specifies any design preference, that preference **overrides** the corresponding Design Dial result. The priority order is:

1. **User-specified settings** (highest priority) — explicit requests like "use dark mode", "make it blue", "use Playfair Display font", "I want a minimalist style"
2. **Design Read inference** — signals inferred from the brief content and context
3. **Design Dials** (lowest priority) — time-based random selection, used only for dimensions the user didn't specify

**How this works in practice:**
- User says "build me a dark portfolio" → Surface is locked to dark, skip the Surface dial. Other dials (Accent, Typography, Family) still spin randomly.
- User says "use green and serif font" → Accent is locked to Green, Typography is locked to Serif. Surface and Family still spin randomly.
- User says nothing about design → all 4 dials spin randomly (the default behavior).
- User says "make it look like Apple's website" → this is a complete design direction. Skip all dials, infer the aesthetic from the reference.

**Never argue with the user's taste.** If they want purple gradient on a cream background, do it well. Document the user override in the Design Dials output line:

> **Design Dials**: Surface=USER(Dark) · Accent=3(Orange, #e87040) · Type=USER(Serif) · Family=2(Editorial) → Playfair Display

---

## Step 0: Design Read (MANDATORY)

Before writing ANY code, silently analyze the brief and output a single-line Design Read:

> **Design Read**: [page type] · [audience] · [atmosphere word] · [aesthetic family] · [light/dark/tinted]

**How to infer each signal:**

| Signal | Source | Example |
|--------|--------|---------|
| Page type | Explicit in brief or inferred from content | SaaS dashboard, editorial blog, dev tool, portfolio |
| Audience | Who will use this? | Enterprise buyers, indie developers, Gen-Z consumers |
| Atmosphere | One word capturing the emotional register | Clinical, playful, austere, warm, raw, luxurious |
| Aesthetic family | The design tradition this belongs to | Swiss/International, Neo-brutalist, Editorial, Soft-tech, Industrial |
| Surface | Light, dark, or tinted background | Dark with blue tint, warm off-white, pure white |

The Design Read anchors every subsequent decision. If two choices conflict, the Design Read wins.

---

## Step 0.5: Scene Sentence (MANDATORY for dark/tinted surfaces)

If your Surface dial (Step 1) selects a dark or tinted direction (indices 5 or 6), you MUST write a Scene Sentence before choosing any colors. This anchors the dark palette to a physical environment instead of defaulting to generic blue-black.

> **Scene**: [who] is using this [where], under [what lighting], in [what mood]

**Examples:**
- "A portfolio manager reviewing positions on a matte-black standing desk, single desk lamp, focused and alert"
- "A music producer in a dimly lit studio with purple LED strips, creative and immersed"
- "A researcher in a university library at dusk, warm overhead lights, contemplative"
- "A bartender checking inventory on a tablet behind a walnut bar, amber pendant lights, unhurried"
- "An architect reviewing blueprints in a concrete loft, overcast daylight through floor-to-ceiling windows, precise"

**The Scene Sentence determines your dark surface tint:**
- Studio with purple LEDs → deep purple tint, not blue-black
- Library at dusk → warm charcoal, not blue-black
- Standing desk with desk lamp → neutral near-black with warm accent
- Walnut bar with amber lights → warm brown-black
- Concrete loft with daylight → cool gray, not blue-black

**BANNED default scene**: "a developer's monitor in a dark room" — this is the AI default scene that produces the same blue-black every time. Be specific and varied.

See [references/aesthetics.md](references/aesthetics.md) § Dark Surface Tint Guide for the full scene-to-tint mapping table.

---

## Step 1: Spin the Design Dials (MANDATORY)

You have no memory of previous generations and WILL converge on the same dark-blue-card layout every time if left unchecked. To prevent this, you MUST spin four independent dials before writing any code. These dials constrain your direction but leave you full creative freedom within that direction.

### How to Spin

Take the **current UTC time** and compute four indices:

```
dial_A = UTC_minute mod 8                → Surface
dial_B = (UTC_minute + 3) mod 7          → Accent Hue
dial_C = (UTC_hour) mod 6               → Typography
dial_D = (UTC_hour + UTC_minute) mod 12  → Aesthetic Family
```

### Dial A: Surface (mod 8)

| Index | Direction | Description |
|-------|-----------|-------------|
| 0 | **Warm Light** | Off-white with warm undertone (cream-adjacent but NOT generic cream — add personality). Light cards, dark text. |
| 1 | **Cool Light** | White or blue-tinted white. Crisp, clinical, airy. Think Arctic, not generic. |
| 2 | **Pure White** | Clean `#ffffff` or `#fafafa`. Maximum contrast, no tint. Let typography and accent do the work. |
| 3 | **Tinted Light** | Light background with a subtle color tint — pale sage, lavender wash, soft peach, ice blue. Not white, not cream. |
| 4 | **Light with Color Pop** | White/light base with one bold colored section or element (colored hero, colored sidebar, colored footer). Mostly light. |
| 5 | **Tinted Dark** | Dark background with a NON-BLUE tint — try deep green, wine, charcoal-brown, dark purple, or slate-olive. NOT the `#0a-#0f` blue-black that AI always picks. Use Scene Sentence to anchor the tint. |
| 6 | **Neutral Dark** | True dark — near-black with NO color tint. Pure `#111` or `#0f0f0f`. Monochrome surface, let accent do the talking. Use Scene Sentence. |
| 7 | **Mixed** | Light header/hero + dark content area, or alternating light/dark sections. Two-tone page. |

### Dial B: Accent Hue (mod 7)

| Index | Hue Family | Suggested Range (pick your own specific shade) |
|-------|-----------|------------------------------------------------|
| 0 | **Warm Red** | Vermillion, terracotta, rust, brick — NOT generic `#ef4444` |
| 1 | **Gold / Amber** | Marigold, honey, saffron, brass — warm and rich |
| 2 | **Green** | Sage, olive, emerald, lime, mint — pick one, NOT teal |
| 3 | **Orange / Coral** | Tangerine, peach, salmon, burnt orange |
| 4 | **Pink / Magenta** | Rose, fuchsia, hot pink, dusty pink — bold or muted |
| 5 | **Violet / Purple** | Lavender, grape, plum, electric purple — own it fully |
| 6 | **Cool Blue** | Cobalt, cerulean, sky, steel — but NOT the generic `#3b82f6` or `#6366f1` |

### Dial C: Typography (mod 6)

| Index | Mood | Example Fonts (pick ONE — these are suggestions, not the only options) |
|-------|------|----------------------------------------------------------------------|
| 0 | **Serif** | Libre Baskerville, Newsreader, Lora, Playfair Display, Cormorant Garamond, Source Serif 4 |
| 1 | **Geometric Sans** | Instrument Sans, Gei