v2.5.0 — distinctive, not just coherent

Dogfooding real product builds surfaced the next failure mode: StyleSeed
reliably prevented ugly UI but could still leave it generic (default
indigo, tight desktop type, the Lucide-icon-in-a-pale-chip cliché, no
focal point, demo layout copied verbatim). This release forces the
identity layer.

Rules (CLAUDE.md / AGENTS.md / .cursorrules):
- Golden Rules 14-16: no default/unlocked accent or copied demo layout
  (coherent != distinctive); one focal point per screen; match the type
  scale to the surface (desktop body >=16px, not 14px)
- Quick Setup is now MANDATORY (was "recommended") with a Mood step
  (edges/feel/density/tone), smart domain defaults (no default indigo),
  a font step, and surface -> type-scale
- Quality Gate gains Distinctive / Focal / Type-fit checks
- VISUAL-CRAFT CC-9b: ban the AI icon-chip cliché (generic Lucide icon in
  an identical pale rounded-square repeated per feature); prefer dropping
  the chip or numbered/typographic markers
- Font Size by Surface table (mobile-tight vs desktop-larger) + font
  pairing recommendations; lock gains Surface / Mood / Font fields

Skills:
- /ss-score: new Distinctiveness category (10 pts), default-indigo and
  desktop-tight-type deductions; weights rebalanced to 100
- /ss-update: Step 6 Retrofit — re-do an old generic build to the new
  standard (write a lock, re-score, fix to >=80, report before/after)

Release: VERSION 2.5.0, CHANGELOG [2.5.0], version.json whatsNew.
README: quantified badge row + a simulated agent transcript showing the
plan -> lock -> gate flow, anti-drift lock elevated.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01UaNeAAjvq7tbMXPj72dcZB

Author: bitjaru

CHANGELOG.md

@@ -3,6 +3,44 @@
 All notable changes to StyleSeed. Agents can check the latest version at
 [version.json](https://styleseed-demo.vercel.app/version.json) and run `/ss-update`.
 
+## [2.5.0] — 2026-07-01
+
+**Theme: distinctive, not just coherent.** Dogfooding real product builds surfaced the next
+failure mode: StyleSeed reliably stopped UI from being *ugly* (rainbow, emoji, pure black) but
+could still leave it *generic* — the default indigo, the tight mobile type scale on a desktop
+screen, the "Lucide-icon-in-a-pale-chip" cliché repeated for every feature, an all-even grid with
+no focal point, and the demo layout copied verbatim. Coherent-but-generic still reads "an AI made
+this." This release forces the *identity* layer that made the reference demo look designed.
+
+### Added
+- **Mood step in Quick Setup** — the agent now pins the aesthetic in plain words (**edges** →
+  radius, **feel** → shadow/ornament, **density** → spacing/type, **tone** → motion/saturation),
+  proposing a skin-based default the user tweaks ("sharper corners"). Locked in `STYLESEED.md`.
+- **Smart domain defaults** — setup infers a domain-fit skin/color (Korean + fintech/regulation →
+  Toss `#3182F6`, etc.) instead of asking cold. **The unlocked default indigo (`#5E6AD2`/`#4F46E5`)
+  is now forbidden as a final choice.**
+- **Type scale by surface** — a desktop/web B2B scale (body ≥16px, section titles ≥20px, larger
+  hero) distinct from the tight mobile-app scale, plus a font-pairing recommendation table. Setup
+  and the lock now record **surface** and **font**.
+- **Retrofit path** (`/ss-update` Step 6) — re-do a screen built with an older, weaker StyleSeed to
+  the new standard: write a lock if missing, re-score, fix to ≥80, report the before/after score.
+- **`Distinctiveness` scoring category** in `/ss-score` (10 pts) and a matching Quality-Gate check.
+
+### Changed
+- **Quick Setup is now MANDATORY** (was "recommended") — if there's no `STYLESEED.md` and you're
+  about to build UI, running setup is the first step, before any code.
+- **Quality Gate gained Distinctive / Focal / Type-fit checks** — it now fails a default-indigo
+  accent, a copied demo layout, an all-even no-focal grid, and 14px body on a desktop screen.
+
+### Rules (gaps closed from real failures)
+- **Golden Rules 14–16** — never ship the default/unlocked accent or a copied demo layout
+  (coherent ≠ distinctive); one focal point per screen (an all-even card grid is the
+  machine-composed tell); match the type scale to the surface.
+- **No icon-chip cliché** (VISUAL-CRAFT **CC-9b**) — a generic Lucide line-icon in an identical
+  pale-tinted rounded-square, repeated for every feature, is a top "AI built this" tell; drop the
+  chip, vary the treatment, or use numbered/typographic markers.
+- Enforced across `CLAUDE.md`, `AGENTS.md`, `.cursorrules`, `/ss-score`, and `/ss-update`.
+
 ## [2.4.0] — 2026-06-23
 
 **Theme: consistent application.** Real usage showed the one-paste prompt could still
@@ -52,5 +90,6 @@ release raises the floor of the default path.
 - Agent-agnostic delivery: CLAUDE.md + AGENTS.md + .cursorrules.
 - 8 `/guides` + 7 `/screens` programmatic-SEO pages, `/how-it-thinks`, `/faq`.
 
+[2.5.0]: https://github.com/bitjaru/styleseed/releases/tag/v2.5.0
 [2.4.0]: https://github.com/bitjaru/styleseed/releases/tag/v2.4.0
 [2.3.0]: https://github.com/bitjaru/styleseed/releases/tag/v2.3.0

README.md

@@ -34,6 +34,11 @@
 
 <br />
 
+![74 design rules](https://badgen.net/badge/rules/74/8B5CF6)
+![15 skills](https://badgen.net/badge/skills/15/6C5CE7)
+![7 brand skins](https://badgen.net/badge/skins/7/6C5CE7)
+![48 components](https://badgen.net/badge/components/48/6C5CE7)
+
 [![GitHub stars](https://badgen.net/github/stars/bitjaru/styleseed)](https://github.com/bitjaru/styleseed/stargazers)
 [![License](https://badgen.net/github/license/bitjaru/styleseed)](https://github.com/bitjaru/styleseed/blob/main/LICENSE)
 [![Top 6 Frontend by acceleration — oosmetrics](https://badgen.net/badge/oosmetrics/Top%206%20Frontend%20by%20acceleration/green)](https://oosmetrics.com/repo/bitjaru/styleseed)
@@ -67,6 +72,19 @@ Read https://styleseed-demo.vercel.app/llms-full.txt and apply StyleSeed's desig
 
 That's it — the agent plans the design with you, locks a key color, then applies the rules to whatever you build next. (Planning first is what keeps the result from looking random — see [Troubleshooting](#troubleshooting--i-applied-styleseed-but-the-ui-still-looks-bad).) Works with **Claude Code (`CLAUDE.md`), Codex / Amp / Gemini CLI (`AGENTS.md`), and Cursor (`.cursorrules`)** — StyleSeed ships all three, so any agent picks the rules up automatically.
 
+**What your agent actually does with StyleSeed loaded:**
+
+```text
+you    ▸  build me a billing settings page
+agent  ▸  (plan mode) key color? I'd use one indigo accent — #5E6AD2 (SaaS). Motion: Snap. ok?  ▸ y
+agent  ▸  ✓ wrote STYLESEED.md — skin, accent, radius, motion locked, re-read every prompt
+agent  ▸  building… running the quality gate before I show you anything
+gate   ▸  ✗ two accent colors   ✗ "normal" rows colored   ✗ no empty state   → fixing
+agent  ▸  ✓ 88/100 — one accent, grey normal states, real empty/error states. here's the page.
+```
+
+**The `STYLESEED.md` lock is the anti-drift mechanic.** Your skin, key color, radius, and motion get written once and the rules make every agent re-read and obey them on *every* prompt — so the design stops being different each session. The [Quality Gate](#troubleshooting--i-applied-styleseed-but-the-ui-still-looks-bad) then self-reviews and fixes the UI (rainbow lists, two accents, missing states) *before* you ever see it.
+
 > **The rules are the product — and they need zero install or permissions.** They're
 > plain markdown (`CLAUDE.md` / `AGENTS.md` / `DESIGN-LANGUAGE.md`), so the prompt above —
 > or just copying those files in — is 90% of StyleSeed with nothing to approve.

demo-pricing/public/version.json

@@ -1,10 +1,10 @@
 {
-  "version": "2.4.0",
-  "released": "2026-06-23",
+  "version": "2.5.0",
+  "released": "2026-07-01",
   "rules": 74,
   "skills": 15,
   "skins": 7,
-  "whatsNew": "Consistent application: plan-mode Quick Setup (lock a key color before building), a design-lock file agents obey every prompt, and a Quality Gate that self-reviews + fixes UI to a quality floor before showing you (catches rainbow lists, emoji icons, two accents, missing states). Rule gaps fixed via dogfooding.",
+  "whatsNew": "Distinctive, not just coherent. Real builds showed StyleSeed could stop UI being *ugly* but still leave it *generic* (default indigo, tight desktop type, the AI icon-chip cliché, no focal point). This release makes the good path the default: Quick Setup is now mandatory with a Mood step (edges/feel/density/tone) + smart domain defaults (no more default indigo), a type scale that fits the surface (desktop body ≥16px), a ban on the icon-chip cliché, a one-focal-point rule, and a Quality Gate + /ss-score that now fail generic/template output. Plus a retrofit path (/ss-update Step 6) to re-do old generic builds to the new standard.",
   "update": "Run /ss-update, or: npx skills add bitjaru/styleseed",
   "changelog": "https://github.com/bitjaru/styleseed/releases",
   "repo": "https://github.com/bitjaru/styleseed"

engine/.claude/skills/ss-score/SKILL.md

@@ -24,45 +24,55 @@ map to the design language. Total = 100.
 
 | Category | Weight | Reads from |
 |---|---|---|
-| **Color discipline** | 18 | DESIGN-LANGUAGE §1, §18, §72 + VISUAL-CRAFT §C4 |
-| **Hierarchy & typography** | 18 | §2, §3, §4, §16 + Font Size table + VISUAL-CRAFT §C2 |
-| **Layout & rhythm** | 14 | §13, §14, §15, §61 + VISUAL-CRAFT §C1 |
-| **Cards & elevation** | 12 | §7, §8, §12, §1 + VISUAL-CRAFT §C3 |
+| **Color discipline** | 16 | DESIGN-LANGUAGE §1, §18, §72 + VISUAL-CRAFT §C4 |
+| **Hierarchy & typography** | 16 | §2, §3, §4, §16 + Font Size table + VISUAL-CRAFT §C2 |
+| **Layout & rhythm** | 12 | §13, §14, §15, §61 + VISUAL-CRAFT §C1 |
+| **Cards & elevation** | 10 | §7, §8, §12, §1 + VISUAL-CRAFT §C3 |
 | **States & a11y** | 18 | §11, §70, §71, §72 + VISUAL-CRAFT §C3 |
-| **Motion & interaction** | 8 | §24, §59 + `engine/motion` |
+| **Motion & interaction** | 6 | §24, §59 + `engine/motion` |
 | **Coherence** | 12 | VISUAL-CRAFT §C0 (one choice per axis) |
+| **Distinctiveness** | 10 | Golden Rules 14–16 + VISUAL-CRAFT §CC-9b (not generic/default/template) |
 
 ## How to score each category
 
 For each category, start at full marks and **subtract** for violations you find by
 reading the code. Be specific and evidence-based — cite the line.
 
-**Color discipline (20)** — deduct for: any `#000`/`text-black` (−4 each, cap −8);
+**Color discipline (16)** — deduct for: any `#000`/`text-black` (−4 each, cap −8);
 more than one accent hue used decoratively (−5); **emoji used as UI icons** (multi-color,
 breaks single accent) (−5); **a normal/OK/"보통" state shown in a status color** instead of
 neutral grey (−4); **status color on most/every row** (no severity hierarchy) (−4);
 **decorative hues** (gold stars, rainbow category dots) instead of accent/grey (−3);
 hardcoded hex where a semantic token exists (−2 each, cap −6); status conveyed by color
-alone (−4).
+alone (−4); **the unlocked default indigo (`#5E6AD2`/`#4F46E5`) used as the accent** instead of
+a chosen domain-fit color (−4).
 
-**Hierarchy & typography (20)** — deduct for: number/unit not ~2:1 (−4); font
+**Distinctiveness (10)** — a coherent screen can still read "AI-generated." Deduct for: the
+**icon-chip cliché** — a generic Lucide line-icon in an identical pale-tinted rounded-square,
+repeated for every feature/step (−4, §CC-9b); the **StyleSeed demo layout copied verbatim**
+(hero+chat / 3-step / feature-grid / pricing) with no product-specific identity (−4); **no focal
+point** — an all-even grid of same-weight, centered, evenly-spaced cards (−3); the hero shows a
+stock/placeholder visual instead of *this* product (−3). Cap −10.
+
+**Hierarchy & typography (16)** — deduct for: number/unit not ~2:1 (−4); font
 sizes off the Font Size table / `text-[var(--…)]` for size (−5); everything the
-same weight, no clear primary (−5); cramped or wrong line-height on body (−3).
+same weight, no clear primary (−5); cramped or wrong line-height on body (−3);
+**body < 16px on a desktop/web B2B surface** (tight mobile scale on a wide screen) (−4).
 
-**Layout & rhythm (15)** — deduct for: content on bare background, not in cards
+**Layout & rhythm (12)** — deduct for: content on bare background, not in cards
 (−6); `px-4`/`px-8`/`mx-4` instead of `px-6`/`mx-6` (−3); same section type
 repeated in a row (−4); no `space-y-6` rhythm (−3).
 
-**Cards & elevation (15)** — deduct for: 1px borders doing separation work that
+**Cards & elevation (10)** — deduct for: 1px borders doing separation work that
 tone+shadow should (−4); shadows over ~8% opacity / visibly heavy (−4); no
 card/background tone separation (−5).
 
-**States & a11y (20)** — deduct for: missing empty/loading/error state on a data
+**States & a11y (18)** — deduct for: missing empty/loading/error state on a data
 surface (−5 each, cap −10); contrast below 4.5:1 body / 3:1 large (−6); touch
 target < 44px (−4); no visible focus / `outline:none` (−5); icon-only control
 without `aria-label` (−3).
 
-**Motion & interaction (8)** — deduct for: random/ad-hoc fades instead of a named
+**Motion & interaction (6)** — deduct for: random/ad-hoc fades instead of a named
 seed/keyword (−3); motion that delays content or blocks an action (−4); no
 `prefers-reduced-motion` handling on custom motion (−3); scroll-linked/parallax
 (forbidden, §59) (−5).

engine/.claude/skills/ss-update/SKILL.md

@@ -12,7 +12,8 @@ allowed-tools: Read, Write, Edit, Grep, Glob, Bash
 - For first-time setup → use `/ss-setup`
 - For just one new component or skin — copy that file manually
 - For projects that have heavily diverged from upstream — manual diff review first
-- For updating user code/components — this updates engine files only, not your custom UI
+- Updating the engine is separate from re-designing your UI. Steps 1–5 update engine files only;
+  if you want an old generic build re-done to the new standard, that's **Step 6 (Retrofit)**.
 
 Automatically detect and update StyleSeed files in the current project.
 
@@ -143,6 +144,29 @@ Not touched:
 Next: run /ss-lint on your pages to check for rule violations.
 ```
 
+### Step 6: Retrofit existing UI (optional but recommended) — "re-do a generic old build"
+
+Updating the rules doesn't re-design screens you already built with an older StyleSeed. If the
+user says their existing UI still looks generic/"AI-made" (default indigo, icon-chip cliché,
+tight desktop type, no focal point, no design lock), offer to **retrofit it to the new standard**.
+This is the migration path for anyone who built before the distinctiveness rules existed:
+
+1. **Write a design lock if missing.** Check for `STYLESEED.md` at the project root. If absent,
+   run **Quick Setup** (CLAUDE.md) *now* with the user — pin **mood** (edges/feel/density/tone),
+   a **domain-fit key color** (NOT the default indigo), a **chosen font**, and the **surface**
+   (mobile vs desktop type scale). Write the lock. Existing generic builds almost always never
+   had a lock — this is the biggest fix.
+2. **Re-score the key screens.** Run **`/ss-score`** on the main pages. The new rubric flags
+   exactly the old-build tells: default-indigo accent, the icon-chip cliché (§CC-9b), body <16px
+   on desktop, no focal point, demo layout copied verbatim, missing states.
+3. **Apply the fixes.** Run **`/ss-review`** (or `/ss-review --fix`) screen by screen to retint to
+   the locked key color, replace the uniform icon chips, bump the desktop type scale, and create a
+   focal point. Re-score to **≥ 80**. Do the highest-traffic screen first.
+4. **Report the before/after score** so the upgrade is visible (e.g. "landing 63 → 88").
+
+Frame it honestly: the rules got stronger, so a screen that passed the old bar may score lower
+now — that's the point; fixing it is what makes it stop looking AI-made.
+
 ## Important
 
 - NEVER overwrite theme.css

engine/.cursorrules

@@ -59,6 +59,10 @@ Follow the StyleSeed design language strictly. Full reference: https://github.co
 - No emoji as UI icons (🚗🧺⭐ for lists/nav/status/categories) — they inject many uncontrolled colors and break the single accent. Use one line-icon set (Lucide) in currentColor.
 - No status color on a normal/OK/"보통" state (use neutral grey) and no colored badge on every row — color marks only the minority that needs attention; same value → same color.
 - No decorative hues (gold stars, rainbow category dots) — favorites/markers use the accent or grey.
+- No AI cliché icon treatment: a generic Lucide line-icon inside an identical pale-tinted rounded-square chip, repeated for every feature/step, is a top "AI made this" tell. Vary the treatment, use a set with more character, or drop the chip.
+- No default/unlocked accent (generic indigo #5E6AD2/#4F46E5) as a final choice, and don't copy the StyleSeed demo layout verbatim — lock a domain-fit key color + font first. Coherent ≠ distinctive.
+- No all-even grid of same-weight, centered, evenly-spaced cards — give each screen ONE focal point that dominates.
+- No 14px body on a desktop/web B2B screen — match the type scale to the surface (desktop body ≥16px, section titles ≥20px).
 - No pure black (#000) anywhere.
 - No content outside cards.
 - No section dividers between cards (space-y-6 is the separator).