# DESIGN.md

## Overview

<!-- FILL: one or two sentences on what the product is and who uses it. -->

<!-- FILL: where and how it's used (on the go on a phone, at a desk, on a shared screen, in a noisy room) and what that means for the UI. -->

**Core character:** <!-- FILL: three or four adjectives for how it should feel, and what it is *not* (e.g. not corporate, not generic SaaS, not "AI demo"). -->

**Primary modes:**
- Operate (<!-- FILL: this product's task screens -->)
- Experience (<!-- FILL: this product's moments that carry the feeling, or "none" -->)

<!-- FILL: one line on the physical constraint that matters most (quick glances, one-handed use, long reading sessions, etc.). -->

## Design Pick (before any UI code)

Run this whenever the Overview above still has `<!-- FILL -->` markers or `## Tokens` is empty. No UI code until it's done.

1. **Fill the Overview.** If it has FILL markers, ask the user 3–5 short questions (what the product is, who uses it, where it's used, how it should feel, which devices), then replace every marker with their answers.
2. **Show directions.** Load the `artifact-design` skill and publish **one** Artifact with **3–4 tabs**, one design direction per tab. Each tab shows:
   - the direction's name and a one-line rationale,
   - okLCH palette swatches,
   - the type pairing,
   - the radius and spacing feel,
   - 2 realistic key screens of *this* product at phone width, with real copy (no lorem).

   Directions must differ in character, not just recolor one layout. Every tab passes the Anti-Slop Checklist.
3. **Wait for a pick.** Stop and ask the user to pick one, or to mix parts ("tab 2 palette + tab 3 type"). Revise the artifact if they ask.
4. **Record it.** Write the chosen direction's name and its tokens into `## Tokens`. Only then write UI code.

Fallback if the Artifact tool isn't available: write `design-options.html` locally, open it, and follow the same steps.

## Anti-Slop Checklist (always apply)

Every screen is checked against this before it ships. Condensed from the impeccable.style slop catalog to what applies here.

**Color**
- No purple/cyan "AI" palette. No gradient text.
- No radial halo or spotlight backgrounds. No neon-glow dark mode.
- No default cream/beige as a stand-in for "warm".
- No gray text on colored surfaces; tint text toward the surface instead.
- Text contrast at least 4.5:1 (3:1 for large text, 24px+ or 19px+ bold).

**Type**
- Not Inter, not Geist. No italic serif display faces.
- No small label or badge sitting above a heading.
- Body at least 16px with line-height around 1.5. No tiny text anywhere.
- No all-caps body copy. No crushed or extra-wide letter spacing on body.
- Clear size and weight hierarchy. No skipped heading levels.

**Surfaces**
- No glassmorphism or frosted blur panels.
- No side-tab accent borders (thick colored left edge on a card).
- Never a border and a wide soft shadow on the same element.
- No cards nested inside cards. No extreme corner radius.
- No decorative grids, stripes, or dot patterns behind content.

**Layout**
- No grids of identical icon + title + blurb cards.
- No hero-metric template (big number, small label, repeat).
- Spacing groups related items; gaps vary with meaning, not one uniform gap.
- Side gutters 16px minimum. Nothing overflows at 360px width.

**Motion**
- No pulsing dots, blinking cursors, marquees.
- No bounce or elastic easing on routine UI.
- Animate transforms and opacity only; nothing that shifts layout.
- Content is visible even if an animation never runs.
- Respect `prefers-reduced-motion`: drop movement, keep state changes.

**Copy**
- No em-dash habit. Use commas, periods, or parentheses.
- No "supercharge", "unleash", "seamless" style claims.
- No "Not X. Y." slogans. No label that repeats the heading it sits under.

**Imagery**
- No rough SVG mascots or placeholder-blob illustrations. Type and color carry the personality.

## Screen sizes

Phone first, tablet second, laptop supported. Nothing relies on hover; every touch target is 44px or larger.

| Size | Width | Layout |
|---|---|---|
| Phone | 360–599px | Single column. The one primary action sits at the bottom in thumb reach. |
| Tablet | 600–1023px, portrait and landscape | Wider cards and bigger type. Still one primary action. |
| Laptop | 1024px+ | Centered max-width column. No layouts stretched edge to edge. |

<!-- FILL: project-specific layout notes, e.g. which panels sit side by side in tablet landscape. Delete this line if there are none. -->

---

## Impeccable References

These are mandatory reading and the authoritative source for design quality and anti-slop rules:

- Main guidelines: https://impeccable.style/
- AI slop catalog: https://impeccable.style/slop/

Principles adopted from these:

- **One primary action per screen.** Everything else is visibly secondary.
- **Know the job of each screen.** Operate screens (<!-- FILL: this product's task screens -->) favor clarity and speed. Experience screens (<!-- FILL: this product's moments, or "none" -->) are allowed drama and tension.
- **Visible labels.** No icon-only controls, no placeholder-as-label inputs.
- **Touch targets 44px+.**
- **Press state:** scale 0.96 over 160ms.
- **Hover lift (pointer devices only):** translateY(-1px) over 150ms.
- **Tokens documented as okLCH** in the section below.

## Tokens

Filled by Design Pick. Empty until the user picks a direction.

Look: <!-- direction name and one line on its character -->

### Colors

| Token | okLCH | Use | Text on it |
|---|---|---|---|

### Type

### Radius