Skip to content

Anti-AI-slop design skill for Claude Code, Cursor, and Codex.

CSS

Smart placeholders + mobile-responsiveness gates (skill v1.x)

Youssefdcd45e21d73e
diff --git a/skill/SKILL.md b/skill/SKILL.md
index 55a0e36..8c706e4 100644
--- a/skill/SKILL.md
+++ b/skill/SKILL.md
@@ -46,7 +46,7 @@ These four disciplines are **not** verb-specific. They apply to default Design,
4. **Re-drawn chrome forbidden.** Hallmark must not hand-build fake browser bars (URL pill + traffic-light dots), fake phone frames, fake code-block windows (mock title bar + dots wrapping a `<pre>`), or fake IDE chrome — the user's environment already supplies real chrome. Use real screenshots wrapped in a `<figure>` (with at most a hairline border), or omit the chrome and let the content stand on its own. See [`references/anti-patterns.md` § Re-drawn UI chrome](references/anti-patterns.md) and slop-test gate **57**.
-5. **Clickable text never wraps.** Buttons, primary nav links, footer links, breadcrumbs, and CTAs must read on a single line at every viewport between 320 px and 1920 px. The fix is, in order: shorten the label (most CTA labels are 30–40 % too long), `white-space: nowrap` and let the parent reflow, hide low-priority items at narrow widths, or collapse the nav into a sheet. See [`references/responsive.md` § Clickable text — never wraps](references/responsive.md) and slop-test gate **59**.
+5. **Mobile responsiveness — every emit verified at 320 / 375 / 414 / 768 px.** Hallmark's output must render flawlessly at all four widths. The non-negotiables: no horizontal scroll (gate 36), no two-line clickable text — buttons, primary nav links, footer links, breadcrumbs, CTAs (gate 59); image-bearing grid tracks use `minmax(0, 1fr)`, never bare `1fr` (gate 61); root has `overflow-x: clip` on both `html` and `body` — never `hidden` (gate 62); display headers wrap inside long words via `overflow-wrap: anywhere; min-width: 0` (gate 63); section heads collapse to one column on mobile across every theme variant (gate 64); radio-tab patterns don't scroll-jump (gate 65). See [`references/responsive.md` § Mobile — non-negotiable](references/responsive.md). This is a hard floor, not a wish list.
---
@@ -361,6 +361,8 @@ The non-negotiables live in [`references/`](references/). **Be precise about wha
Most pages don't need it. The strongest hero is often a typographic one. **Reach for [`hero-enrichment.md`](references/hero-enrichment.md) only when the brief points there** — a SaaS / dev-tool brief wants a demo video or mockup; a bakery / café / atelier brief wants a hand-built illustration; a manifesto wants nothing.
+**First — does the brief need imagery at all?** Run the image-need table at [`hero-enrichment.md` § Image-need detection](references/hero-enrichment.md). Default is typography-only. If the brief signals "needs photographic content" (e-commerce, team, food, travel) AND the user hasn't supplied real assets, use the placeholder strategy in [`assets.md` § Placeholder strategy](references/assets.md). If the brief allows non-photographic imagery (SaaS landing, manifesto, agency splash, editorial-led), prefer the [`imagery-kit.md`](references/imagery-kit.md) over photo placeholders. **Never ship invented stock photos as if they were the final design.**
+
Eyeball the brief or ask one short question. State the decision in one sentence (e.g., *"Enrichment: E1 Clipped-Edge Demo Video, Tier-A CSS-art mockup."* or *"Enrichment: none — typography only."*). The decision goes into the macrostructure stamp at Step 6.
**The enrichment hierarchy is non-negotiable.** Reach for the highest tier you can ship: typography only → Tier A pure CSS art → Tier B hand-built SVG → Tier C generated still (Nanobanana / Recraft) → Tier D library + customisation → **Tier E Lottie is last resort**, only for complex character motion that hand-build can't reach. Reaching for Lottie when CSS would have built it is the new tell.
diff --git a/skill/references/assets.md b/skill/references/assets.md
index de5e9b6..8b09c44 100644
--- a/skill/references/assets.md
+++ b/skill/references/assets.md
@@ -2,7 +2,34 @@
This file is loaded when an enrichment archetype actually needs an external asset (load-on-demand). It catalogues the *3–5 canonical sources per category*, the licence terms, the import patterns, the rules for using them, and the sources to avoid.
-**The reflex.** Before reaching here, ask: can this be built? See [`custom-craft.md`](custom-craft.md). The assets in this file are for the moments when hand-building isn't economical or when the brief explicitly calls for stock material. Treat this file as the back-pocket catalogue, not the first move.
+**The reflex.** Before reaching here, ask two questions in order: (1) Does the brief actually need imagery at all? See [`hero-enrichment.md` § Image-need detection](hero-enrichment.md). (2) If yes, can it be hand-built? See [`custom-craft.md`](custom-craft.md). The assets in this file are for the moments when both answers send you here.
+
+---
+
+## Placeholder strategy
+
+When imagery is needed *and* the user hasn't supplied real assets, pick from this canon — in order. Skipping tiers is the slop move.
+
+| # | Source | When |
+| --- | --- | --- |
+| 1 | **Hallmark imagery kit** ([`imagery-kit.md`](imagery-kit.md)) | Brief allows non-photographic imagery: SaaS landings, manifestos, agency / studio splash, type-led portfolio, editorial-led marketing. **Always preferred** when the kit's register fits. |
+| 2 | **Hand-built SVG composition** (Tier B from custom-craft.md) | Editorial-typographic brief where "imagery" can be a stamp / wordmark / colour-blocked composition. Use when the kit doesn't carry the register. |
+| 3 | **Picsum** — `https://picsum.photos/seed/<seed>/<w>/<h>` | Generic photo slot, keyword anchoring not critical. Use a deterministic seed (brand-name + slot-name) so the same render produces the same image. |
+| 4 | **Unsplash Source** — `https://source.unsplash.com/<w>x<h>/?<keywords>` | Keyword-anchored photo slot — food, travel, portrait, real product. Pass 1–2 specific keywords, never zero. |
+| 5 | **Local `public/placeholder-<type>.{jpg,svg}`** | Self-contained projects with no third-party deps. Single neutral grey-block SVG checked into the repo. |
+
+**Swappability — non-negotiable:**
+
+- Every placeholder image carries an HTML comment immediately above it: `<!-- TODO: Replace with real <thing>, target size: <WxH> -->`.
+- All placeholder URLs reference a single constant — a `--placeholder-base` CSS variable or `PLACEHOLDER_BASE` config constant. User edits one place to swap the entire site.
+- Alt text describes the **intended** subject ("Hand-thrown ceramic mug, top-down on linen") not the placeholder ("Picsum image"). When the user swaps in the real photo, alt is already correct.
+
+**Anti-patterns:**
+
+- Never inline base64 placeholder images (bloats CSS).
+- Never call random Unsplash without keywords (returns un-curated stock-photo-ish results).
+- Never use kittens / lorempixel / "tiger.jpg" / cute-default services. The placeholder must read as an obvious slot, not as content.
+- Never ship a kit image where the brief actually calls for a real product photo (e.g. abstract bottle for an actual coffee-shop hero). The kit is for atmosphere; photos are for subject.
---
diff --git a/skill/references/hero-enrichment.md b/skill/references/hero-enrichment.md
index a178e7e..24d8cc3 100644
--- a/skill/references/hero-enrichment.md
+++ b/skill/references/hero-enrichment.md
@@ -8,6 +8,34 @@ This file is loaded after the macrostructure pick (Step 3 in the design flow), w
---
+## Image-need detection — does this brief need imagery at all?
+
+Before picking an enrichment tier, decide whether the brief actually wants imagery. The default is **typography-only**. Match the brief against this table; act on the *first* row that fires:
+
+| Brief signal (any of these words / intents) | Image strategy |
+| --- | --- |
+| e-commerce, shop, store, product catalogue, brand, fashion, lookbook | Real product photos required — placeholder until user provides |
+| photography, portfolio, gallery, artist | Imagery *is* the page — placeholder until user provides |
+| food, restaurant, menu, dish, coffee, wine, recipe | Hero photo + product crops — placeholder until user provides |
+| team, staff, "about us", portraits, hiring, careers | Portrait crops — placeholder until user provides |
+| travel, hotel, destination, real estate, listing, property | Cover photo + tile photos — placeholder until user provides |
+| news, blog, magazine, journal, publication | Feature image per post — placeholder until user provides |
+| SaaS landing, manifesto, agency, studio, atmospheric, slow-and-editorial | **Kit-led.** Use Hallmark imagery kit (washes, transparent abstracts, ornaments) — see [`assets.md` § Placeholder strategy](assets.md) and [`imagery-kit.md`](imagery-kit.md). |
+| API, docs, changelog, CLI, library, dev-tool, SDK, package | **No imagery.** Typography-only. Code blocks if needed. |
+| editorial, essay, letter, foundry, type-specimen, broadside | **No imagery.** Display typography is the design. |
+| (all other / vague / unspecified) | **Default: typography-only.** When in doubt, no images. |
+
+Rules:
+
+- When the user has attached an image asset (or `.hallmark/preflight.json` cached one), use it. Never overwrite with a placeholder.
+- When the brief is genuinely ambiguous between a "needs photos" row and a "no imagery" row, ask one short question: *"Will you have product photos, or should I leave swappable placeholders?"*
+- A placeholder must look like a placeholder, not like a confident decision. The skill refuses to invent stock photos as if they were the final design.
+- Imagery rows above don't override genre overlays. Modern-minimal genre still suppresses decorative kit imagery (gate in `imagery-kit.md` anti-patterns).
+
+The hierarchy below picks the tier *after* this gate decides imagery is needed at all. Skipping this gate is what produces "blob illustration on every page" outputs — exactly the AI-default Hallmark refuses.
+
+---
+
## The enrichment hierarchy
Reach for the highest tier the brief lets you ship in the time you have. Skipping tiers is the new tell.
diff --git a/skill/references/imagery-kit.md b/skill/references/imagery-kit.md
new file mode 100644
index 0000000..3a853c4
--- /dev/null
+++ b/skill/references/imagery-kit.md
@@ -0,0 +1,170 @@
+# Imagery kit — curated abstract assets, hosted, ready
+
+A small set of pre-generated abstract / decorative imagery that any Hallmark output can pull from when a brief allows non-photographic imagery. The kit lives at:
+
+```
+https://hallmark-murex.vercel.app/imagery/<category>/<file>
+```
+
+The skill doesn't ship the binaries — it ships the manifest. References are absolute URLs. If the asset is missing (404), the skill falls back to source canon #2 in [`assets.md` § Placeholder strategy](assets.md) (hand-built SVG) without erroring.
+
+**Why this exists.** The v0.9.0 watercolor sprinkle was generated per-emit and was inconsistent. The kit recovers that aesthetic but as discrete, swappable, deliberately-composed assets. Compose with them like a senior frontend engineer: layered transparent PNG behind text, biased off-centre, intentionally large, mix-blend-mode where it earns its place. Not "abstract gradient on top of headline" — that's the AI default.
+
+---
+
+## Categories
+
+| Category | What | Format | Example uses |
+| --- | --- | --- | --- |
+| **watercolor** | Full-bleed soft-edge painterly fields. Warm + cool variants per palette family. | WebP | Section background accent; hero-half flood; behind-quote wash. |
+| **transparent** | Organic blob / brushstroke / stylized mark on transparent background. | PNG | Layered hero composition (large, off-centre, behind text). The masterclass move. |
+| **ornament** | Small hand-drawn stamps, plates, roman numerals, decorative flourishes. | SVG | Beside a quote; in the section-label gutter; closing a letter. |
+| **texture** | Subtle paper, weave, riso-dot, cross-hatch fields. Tile-able. | WebP | Body grain via `mix-blend-mode: multiply`; section-divider banding. |
+| **silhouette** | Abstract bottle / box / device / book / mug / card shapes. | PNG | Empty product slots before user uploads photos; comparison rows. |
+| **pattern** | Repeating motifs that read as fabric / paper / printed material. | WebP | Section-band texture; full-bleed fills behind decorative text. |
+
+**Naming:** `<category>-<palette-family>-<variant>.<ext>` — e.g. `watercolor-warm-01.webp`, `transparent-brush-cool-03.png`, `ornament-stamp-01.svg`, `texture-grain-paper-02.webp`. Palette families: `warm` · `cool` · `neutral` · `chromatic`.
+
+---
+
+## Manifest (placeholder until generation pass ships)
+
+When images land in `site/public/imagery/<category>/`, list them here as a key/value catalogue:
+
+```
+watercolor-warm-01.webp 1600×900 warm orange · cream paper hero half-flood, atmospheric
+watercolor-cool-01.webp 1600×900 cool blue · greyscale quote-behind wash
+transparent-brush-warm-01 1200×1200 burnt orange brushstroke layered hero, off-centre
+transparent-blob-cool-01 1200×1200 cobalt organic shape layered hero, behind headline
+ornament-stamp-01.svg inline ink-only stamp w/ numeral label-gutter, letter close
+texture-grain-paper-01 512×512 cream paper grain (tileable) body grain, blend-multiply
+silhouette-bottle-01.png 600×900 abstract bottle, transparent empty product slot
+silhouette-card-01.png 900×600 abstract product card comparison row
+pattern-cross-warm-01 400×400 cross-hatch warm (tileable) section-band texture
+```
+
+The skill picks an asset by matching the active theme's palette family + the brief's tone, then references it by absolute URL. Picking logic lives in Step 4 of [SKILL.md](../SKILL.md) — eyeball the manifest, choose the closest match, fall back if the file 404s.
+
+---
+
+## Usage patterns — how a senior engineer would compose these
+
+### Layered hero composition (the masterclass move)
+
+A transparent abstract object behind hero text. The image is bigger than you think it should be — that's what makes it feel intentional, not decorative.
+
+```css
+.hero { position: relative; isolation: isolate; }
+
+.hero__art {
+ position: absolute;
+ top: 50%;
+ right: -10%;
+ transform: translateY(-50%);
+ width: clamp(60%, 80vh, 1400px);
+ height: auto;
+ z-index: 0;
+ pointer-events: none;
+ /* Optional warmth: */
+ mix-blend-mode: multiply;
+ opacity: 0.85;
+}
+
+.hero__art--bias-left { right: auto; left: -10%; }
+
+.hero > * { position: relative; z-index: 1; }
+```
+
+Bias to one side (left or right, never centred). The text sits at `z-index: 1`, the art at `z-index: 0`. Test mobile: art may need to scale down or shift to avoid the headline at 320 px.
+
+### Section background wash
+
+A watercolor file as a full-bleed section accent. One section per page, never global.
+
+```css
+.section--wash { position: relative; isolation: isolate; }
+.section--wash::before {
+ content: "";
+ position: absolute;
+ inset: 0;
+ background: url("https://hallmark-murex.vercel.app/imagery/watercolor/watercolor-warm-01.webp") center / cover no-repeat;
+ opacity: 0.6;
+ z-index: -1;
+ pointer-events: none;
+}
+```
+
+### Decoration
+
+Inline ornament beside a quote or in the section-label gutter. Small. No border, no shadow, no animation.
+
+```html
+<p class="section-label">
+ <span class="num">02</span>
+ <img class="section-label__ornament" src="…/imagery/ornament/ornament-stamp-01.svg" alt="" aria-hidden="true" />
+ <span>Examples</span>
+</p>
+```
+
+```css
+.section-label__ornament { width: 1.5em; height: auto; vertical-align: middle; }
+```
+
+### Texture overlay
+
+Grain over a solid colour. Always opacity-capped at `0.15`.
+
+```css
+.texture-grain {
+ background-image: url("…/imagery/texture/texture-grain-paper-01.webp"), var(--paper-fill);
+ background-size: 256px 256px, cover;
+ background-blend-mode: multiply;
+ opacity: 1; /* the grain texture is at 0.15 in the source asset */
+}
+```
+
+### Empty state
+
+Generic silhouette in unfilled data slots, greyscale-tinted, with a "Replace with real photo" hint visible to the developer (HTML comment).
+
+```html
+<!-- TODO: Replace with real product photo, target size: 600×900 -->
+<picture class="product-card__photo product-card__photo--empty">
+ <img src="…/imagery/silhouette/silhouette-bottle-01.png" alt="Hand-poured ceramic vessel, studio lighting" />
+</picture>
+```
+
+---
+
+## Anti-patterns
+
+- **Don't use kit imagery as the literal subject.** An abstract bottle is *not* a stand-in for an actual coffee-shop hero — those need photographic placeholders (Picsum / Unsplash). The kit is for atmosphere / composition / decoration, not subject replacement.
+- **Don't layer 3+ kit pieces on one page.** Restraint. One transparent object in the hero + one wash in a later section is the cap.
+- **Don't apply the same watercolor wash to multiple sections.** It's a section accent, not a global treatment.
+- **Don't use kit imagery in modern-minimal genre** (Stripe / Linear / ElevenLabs school). That genre's whole point is the absence of decorative imagery.
+- **Don't centre the layered hero art.** Centred behind text is the AI-default move. Bias to one side, off-axis.
+- **Don't use mix-blend-mode without testing on the active paper.** `multiply` over a dark canvas inverts; `screen` over light paper washes out. Eyeball the result per theme.
+
+---
+
+## Generation pipeline (out-of-band, one-time)
+
+The kit is generated once per palette family, post-processed, and committed to the marketing site's public folder:
+
+```
+site/public/imagery/
+ ├── watercolor/ ~6 files × 4 palette families = 24 WebPs
+ ├── transparent/ ~6 files × 4 palette families = 24 PNGs
+ ├── ornament/ ~8 SVGs (palette-agnostic, use currentColor)
+ ├── texture/ ~6 tile-able WebPs
+ ├── silhouette/ ~6 PNGs (palette-agnostic, transparent)
+ └── pattern/ ~6 tile-able WebPs
+```
+
+**Tooling.** Nanobanana 2 / Recraft V4 with reference images. Prompt seed-list per category lives at the top of each file's directory in a `prompts.md` (one-line prompts, results pinned by seed for reproducibility).
+
+**Post-processing.** Trim, transparent-background where applicable, colour-balance against Hallmark's OKLCH palette tokens, save as WebP for size + PNG where alpha matters. Ornaments as inline SVG so they inherit `currentColor`.
+
+**Total target weight.** ≤ 5 MB across all categories. Each individual file ≤ 200 KB. Lossy WebP at q=80 unless the image needs lossless (ornaments → SVG; transparents → PNG with `pngquant`).
+
+**Re-generation.** Treat the kit as a refreshable batch, not a one-off. When the palette catalogue changes (new theme, new accent hue), re-generate the relevant palette family. Manifest above is the spec; assets are the deliverable.
diff --git a/skill/references/responsive.md b/skill/references/responsive.md
index cd7aeca..937a1d1 100644
--- a/skill/references/responsive.md
+++ b/skill/references/responsive.md
@@ -2,6 +2,20 @@
Mobile-first. Content-driven breakpoints. No desktop-only interactions.
+## Mobile — non-negotiable
+
+Every Hallmark output must render flawlessly at **320 px, 375 px, 414 px, and 768 px** CSS-pixel widths. Eyeball each viewport before marking the output complete:
+
+- No horizontal scroll (slop-test gate 36)
+- No clickable text wrapping to two lines (gate 59)
+- No image-bearing grid pushing the layout past viewport — use `minmax(0, 1fr)`, never bare `1fr`, on tracks containing images (gate 61)
+- Root carries `overflow-x: clip` on both `html` and `body` — never `hidden` (gate 62)
+- Display headers wrap inside long words via `overflow-wrap: anywhere; min-width: 0` (gate 63)
+- Section heads collapse to one column on mobile across every theme variant — per-theme overrides need a matching mobile rule (gate 64)
+- No scroll-jump on radio-tab clicks — radios in normal flow OR JS guard with `focus({ preventScroll: true })` (gate 65)
+
+This is a hard floor, not a wish list. A page that fails any of these on any of those four widths is not done. The slop-test gates listed run automatically — keep this checklist near the screen while building.
+
## Principles
- Base styles are for the smallest viewport. `min-width` media queries add as you go up. Never `max-width` as the primary direction.
diff --git a/skill/references/slop-test.md b/skill/references/slop-test.md
index de2d1a3..954c1a4 100644
--- a/skill/references/slop-test.md
+++ b/skill/references/slop-test.md
@@ -176,6 +176,22 @@ Universal. Buttons, links, and nav items must remain readable as single-line aff
The CSS stamp at Step 6 should record results: `· honest: pass (56) · chrome: pass (57) · tokens: pass (58) · responsive: pass (59) · icons: pass (60)`. Any failure must be fixed before shipping.
+## Mobile-responsiveness — the non-negotiables
+
+Universal. Every emitted page must render flawlessly at 320 px, 375 px, 414 px, and 768 px CSS-pixel widths. Gates 36 (no horizontal scroll) and 59 (no two-line clickable text) already cover the headline cases; 61–65 below codify the patterns the marketing-site responsiveness pass uncovered. Eyeball each viewport before marking the output complete.
+
+61. **Image-bearing grid track without `minmax(0, 1fr)`.** Does any `grid-template-columns` (or `grid-template-rows`) containing a `1fr` track render an `<img>` / `<picture>` / image-bearing element inside one of those tracks? If yes, the track must be `minmax(0, 1fr)` instead. Plain `1fr` resolves to `minmax(auto, 1fr)`, where `auto` minimum is the largest content's intrinsic width — for a 1024 + px native image, that's 1024 + px minimum, which pushes the layout past viewport on phones. The fix is one character per track: `1fr` → `minmax(0, 1fr)`.
+
+62. **Root missing `overflow-x: clip`.** Does the artifact lack `overflow-x: clip` on both `html` and `body`? If yes, fail. `clip` (not `hidden`) prevents horizontal scroll without creating a scroll context, so `position: sticky` descendants keep working. Hard requirement on every emitted page. Add to the base reset: `html, body { overflow-x: clip; }`.
+
+63. **Display headers without long-word wrap.** Does any element rendering display-size text (`h1`, `.hero__display`, `.section__title`, `.skill-row__title`, hero-equivalent classes) lack `overflow-wrap: anywhere; min-width: 0`? If yes, fail. Long hyphenated words ("AI-generated", uppercase compound brand names) overflow viewport because the only break opportunity is at the hyphen — `overflow-wrap: anywhere` lets the engine break inside the word as a last resort.
+
+64. **Per-theme section-head override without mobile collapse.** When a theme or variant overrides `.section__head { grid-template-columns: ... }` to anything other than `1fr`, does it also include the mobile-collapse rule, OR does a global `[data-theme] .section__head { grid-template-columns: 1fr }` exist at `@media (max-width: 48rem)` with matching specificity? If neither, fail. Theme-specific 2-column heads keep their template on mobile, the title wraps onto the section label, and the page reads broken (most visible on Sport: italic Anton title overlapping "02 / EXAMPLES").
+
+65. **CSS-only radio tab pattern that scroll-jumps.** When implementing tab toggles via `<input type="radio">` siblings + `:checked` selectors, does the artifact either (a) keep the radios in normal document flow with zero size + opacity 0 (no `position: absolute; top: 0`), OR (b) ship a JS handler that intercepts label clicks, calls `e.preventDefault()`, manually sets `radio.checked = true`, dispatches `change`, and focuses with `{ preventScroll: true }`? If the radios are at `position: absolute; top: 0` with no JS guard, fail. Default-position radios cause the page to jump to the section's top on every tab click — visible on every viewport but most disruptive on mobile.
+
+The CSS stamp at Step 6 records mobile pass alongside contrast: `· mobile: pass (36, 59, 61–65)`.
+
---
If any answer is **yes**, fix it. Do not ship slop.