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.mdindex 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 whaMost 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.mdindex 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.mdindex 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 hierarchyReach 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.mdnew file mode 100644index 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.mdindex 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.mdindex 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 affThe 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.