suede-design · diff
git:20261003.f65c7bc to git:20261023.55fc3f6
310 added, 254 removed. Audit A to A.
---
name: suede-design
- description: "Suede AI design skill for making an interface feel intentional instead of templated: design tokens, color strategy, OKLCH ramps, type scale, fluid type, visual hierarchy, dark mode, spacing, component laws, motion, and source-to-implementation visual QA. Use when asked to design, restyle, polish, or audit a screen; pick colors or fonts; define, fix, or document design tokens; build or repair a dark mode; review a component or a whole design system; or compare a mock, Figma frame, or reference screenshot against a rendered implementation. NOT FOR: a full design-plus-copy build, launch surface, or reference-to-target restyle (use johnny-suede-design); conversion and funnel architecture (use suede-site-alchemy); writing the words themselves (use suede-copy)."
+ description: "Suede AI design skill for interfaces that feel intentional instead of templated: design tokens, color strategy, OKLCH ramps, type scale, fluid type, visual hierarchy, dark mode, spacing, component laws, motion, full surface builds that ship layout and words together, reference-to-target restyles (Suedify), and source-to-implementation visual QA. Use when asked to design, restyle, polish, or audit a screen, landing page, dashboard, or component; pick colors or fonts; define or fix design tokens; build or repair a dark mode; review a design system; make this site look like that one; or compare a mock, Figma frame, or screenshot against the rendered build. NOT FOR: writing copy with no layout work (use suede-copy); conversion and funnel architecture (use suede-site-alchemy); an A-F findability and first-screen grade of a public page (use suede-visibility-grader); multi-lane builds with file ownership and rollback plans (use suede-agent-teams)."
---
# Suede Design
- Use this skill to make Suede interfaces feel intentional, premium, legible, and
- alive without drifting into generic AI output. It covers product UI, brand
- surfaces, landing pages, dashboards, component systems, responsive polish, and
- visual QA.
+ Make interfaces feel intentional, legible, and specific to the product they
+ serve. Covers product UI, brand and launch surfaces, dashboards, component
+ systems, responsive polish, restyles, and visual QA.
- **Core principle:** strip the logo and the surface must still be unmistakably this product, and render the result before claiming it works.
+ **Core principle:** strip the logo and the surface must still be recognizably
+ this product. Render the result before claiming it works.
- ## Operating Stance
+ ## Gate policy: advisory, not blocking
- - Work from current source and a rendered screen. Do not design from memory when a repo, live URL, screenshot, or local preview can be checked.
- - For Suede branding, use only `docs/assets/suede-ai-logo-transparent.png` from `JasonColapietro/suede-creator-skills` (SHA-256 `83a7ee0317e4debe2e7b076c20ba067feb76a587f9e829dc6310ae4be4b44dfa`). Never redraw, trace, approximate, typeset, recolor, distort, or generate a replacement Suede S. `suede-skill-icon.png` is a Passport icon, not the Suede brand mark. If the approved file is unavailable or its checksum differs, stop and request it; omit the mark rather than improvise.
- - Keep Suede public copy anchored in creator ownership, programmable IP, rights, provenance, registry-backed media, royalty routing, and agent commerce. Do not reduce Suede to a generic AI music app.
- - Prefer the existing app framework, tokens, components, icon library, and routing patterns. Add a new abstraction only when it removes real complexity or matches an established local pattern.
- - For visual work, render the result. Screenshots beat code inspection. Minimum: desktop at 1280px width, mobile at 390px width. For App Store submissions: 1290×2796px (6.7-inch), 1488×2266px (iPad Pro 13-inch).
- - To capture the render: `npx playwright screenshot <url> --viewport-size=1280,900 desktop.png` (swap the viewport for mobile/App Store dimensions above; one-time setup: `npx playwright install chromium`), or your environment's built-in preview/screenshot tool if one is available.
+ Every score, QA result, and ship status here is a recommendation to the user,
+ not a control on the agent. Finish the work that was asked for and attach the
+ verdict. A failed gate changes what you report, never what you do. Single
+ exception: an extreme-risk finding (legal or rights exposure, copied protected
+ assets, payment or data loss, irreversible public damage). Pause, name the
+ risk and the options, and let the user choose.
- Before any design work, read the surface context:
- - Local `PRODUCT.md`: users, brand, tone, anti-references, strategic principles
- - Local `DESIGN.md`: color tokens, type scale, component inventory, spacing
- - `AGENTS.md`, `AI_HANDOFF.md`, or `README.md`: agent guidance and surface context
+ ## Brand mark
- If PRODUCT.md or DESIGN.md is missing on a major surface, note it and proceed with available context. Offer to create them after completing the task.
+ For Suede AI surfaces, use only `docs/assets/suede-ai-logo-transparent.png`
+ from `JasonColapietro/suede-creator-skills` (SHA-256
+ `83a7ee0317e4debe2e7b076c20ba067feb76a587f9e829dc6310ae4be4b44dfa`). Outside
+ that checkout, fetch the same file from
+ `https://raw.githubusercontent.com/JasonColapietro/suede-creator-skills/cbd192309580a32da375881e0eeb4b2450a554c2/docs/assets/suede-ai-logo-transparent.png`.
+ Never redraw, trace, typeset, recolor, distort, or generate a replacement S.
+ `suede-skill-icon.png` is a Passport icon, not the brand mark. If the file is
+ missing or its checksum differs, omit the mark and say so. Use brand colors
+ exactly as the brand system defines them; never invent new ones.
- Then state this preflight in the working update:
+ ## Pick the mode
- ```text
- SUEDE_DESIGN_PREFLIGHT: target=<repo-or-folder> surface=<route-or-url> register=<brand|product> context=<pass|partial|none> design_system=<loaded|not_found> git=<pass|skipped:reason> render=<pass|pending|skipped:reason>
- ```
+ | Request | Mode |
+ |---|---|
+ | A clear, small visual fix | **Fix:** inspect, make the narrow edit, render, report. |
+ | New surface or ambiguous redesign | **Design:** gather context, propose 2 or 3 directions with tradeoffs, recommend one, get a yes before building. |
+ | Large redesign or launch surface with words | **Surface build:** delivery contract first, then layout and words together, then QA. |
+ | Tokens, components, or a whole system | **System:** scan CSS, tokens, components, spacing, breakpoints, and repeated patterns before proposing changes. Score with the system audit. |
+ | Mock, Figma frame, or screenshot vs. the build | **Visual QA:** compare both in one pass, save `visual-qa-report.md`. |
+ | "Make this site look like that one" | **Restyle (Suedify):** reference URL to target URL. |
- Also apply the shared no-missed quality gates owned by suede-workflow-skills
- (its no-missed-quality-gates reference) when the work touches copy,
- design-system, visual QA, Suedify, visibility, or public launch quality.
- (Requires suede-workflow-skills installed from this pack. If not installed, run the Copy Gate, Visual QA Gate, SEO/AEO/AI EO Gate, Design System Gate, and Launch Gate checklists using the criteria in the Implementation Workflow, Ship Gate, and Visual QA Report sections of this skill.)
+ Name the active mode in the working update. Do not run every mode by default.
- ## Task Router
+ **Long polish loops:** at most 3 passes on the same unit. If the same failure
+ repeats, stop, report what each attempt changed and the unresolved failure,
+ offer 2 to 4 options, and let the user pick.
- Choose the smallest path that fits the request.
+ **Multi-agent work:** for a large surface build, ask first: "Run this as a
+ multi-agent team (more thorough, roughly 3 to 5 times the tokens) or
+ single-agent?" This skill spawns at most 4 subagents and names the model they
+ bill to. Anything larger goes to suede-agent-teams.
- - **Clear small fix:** inspect current UI, make the narrow edit, verify render,
- and report what changed.
- - **Ambiguous or net-new design:** gather context, propose 2-3 approaches with
- tradeoffs, recommend one, and get approval before implementation.
- - **Large redesign:** write a compact shape brief first: audience, page job,
- register, scene, color strategy, typography, layout, signature moment,
- constraints, and QA plan.
- - **Visual system work:** scan current CSS, tokens, components, spacing,
- shadows, breakpoints, icon usage, and repeated UI patterns before proposing
- changes.
- - **Source-to-implementation QA:** if there is a mock, screenshot, Figma frame,
- or image target plus a rendered implementation, compare both visually before
- handoff and save `visual-qa-report.md` in the project root.
- - **Long polish loop:** iterate through a visible checklist. If the same failure
- repeats, freeze the loop, reduce scope to the failing unit, and rerun with
- explicit acceptance criteria.
+ ## Read current truth first
- ## Delivery Discipline
+ 1. Identify the surface: repo, route, live URL, deploy target, branch, dirty
+ files.
+ 2. Read `PRODUCT.md`, `DESIGN.md`, `AGENTS.md`, `CLAUDE.md`, and `README.md`
+ when present. If `PRODUCT.md` or `DESIGN.md` is missing on a major surface,
+ proceed and offer to create them afterward.
+ 3. Render the current UI at desktop and mobile before judging it.
+ 4. Name the physical scene: who uses this, where, under what light, under what
+ pressure, and what they need to do next.
- Before major or important Suede design work, write a compact delivery contract:
+ State the preflight line:
- - objective: the user-visible outcome;
- - surface: repo, route, live URL, branch, and owner;
- - done signal: screenshot, build, test, deploy readback, or review artifact;
- - constraints: WIP to preserve, routes not to touch, copy claims not yet
- approved, and launch/release boundaries;
- - lanes: what can run in parallel, what must wait, and what each lane writes.
+ ```text
+ SUEDE_DESIGN_PREFLIGHT: target=<repo-or-folder> surface=<route-or-url> mode=<fix|design|build|system|qa|restyle> register=<brand|product|docs|campaign|mobile> context=<pass|partial|none> render=<pass|pending|skipped:reason>
+ ```
- Do not call work done because the code changed. Call it done only when the done signal has been checked or the remaining gap is named.
+ **Render, do not guess.** Desktop at 1280 px and mobile at 390 px minimum:
+ `npx playwright screenshot <url> --viewport-size=1280,900 desktop.png` and
+ `--viewport-size=390,844 mobile.png` (first run: `npx playwright install
+ chromium`), or the environment's built-in preview tool. For App Store sets,
+ check Apple's current screenshot specifications before exporting: the 6.9-inch
+ iPhone slot takes 1320 x 2868 (1290 x 2796 also accepted) and the 13-inch iPad
+ slot takes 2064 x 2752 (2048 x 2732 also accepted).
- Use `suede-agent-teams` for major design work when several lanes must move at
- once, such as copy plus layout plus asset plus implementation plus QA. Use
- `suede-code-review` before the ship gate when design work changes shared
- components, routing, auth, payments, analytics, release config, or published-statement
- truth. Skip both for a small visual or copy fix that can be inspected, patched,
- rendered, and verified directly.
+ ## Register sets the defaults
- ## Suede UI Contract
+ | Register | Signal | Defaults |
+ |---|---|---|
+ | Brand | Homepage, about, campaign, press, portfolio | Highest typographic ambition, lowest density, motion earns premium feel, declarative copy |
+ | Product | App UI, dashboard, settings, onboarding, admin | Density serves the task, motion clarifies state, instructional copy |
+ | Docs | Reference, API, guides, changelog | Monospace hierarchy, no decoration, precise scannable copy |
+ | Campaign | Launch, landing, offer, event | Conversion structure first, proof above the fold, one CTA |
+ | Mobile and listing | Screenshots, paywall, onboarding | Platform conventions, system-safe type, no custom fonts in store screenshots |
- Before a new surface, significant redesign, reusable component family, or
- design-system pass, lock the design contract before implementation:
+ When a request spans registers (a dashboard with a marketing hero), name both
+ and apply each to its section.
- - audience, surface job, primary action, and launch stage;
- - spacing scale, grid behavior, breakpoints, and stable dimensions;
- - color roles, semantic states, contrast requirements, and dark/light behavior;
- - typography roles, hierarchy limits, body measure, and truncation strategy;
- - copy vocabulary for buttons, empty states, loading, errors, and success;
- - asset sources, logo use, crop rules, screenshot states, and motion rules;
- - acceptance checks for desktop, mobile, accessibility, and rendered evidence.
+ ## Delivery contract
- Review the result against copy quality, visuals, color, typography, spacing, and
- experience states. If the work is purely backend or a narrow one-element fix,
- document only the relevant contract items instead of forcing a full spec.
+ Before a new surface, a significant redesign, a component family, or a system
+ pass, lock:
- ## Context Checklist
+ ```text
+ Objective (user-visible outcome):
+ Surface (repo, route, live URL, branch):
+ Audience and primary action:
+ Register:
+ Reference or visual target:
+ Done signal (screenshot, build, test, deploy readback):
+ Constraints (WIP to keep, routes not to touch, unapproved claims):
+ Spacing, grid, breakpoints:
+ Color roles, states, contrast, dark and light behavior:
+ Type roles, hierarchy limits, measure, truncation:
+ Interface vocabulary (buttons, empty, loading, error, success):
+ Assets, logo use, motion rules:
+ Acceptance checks (desktop, mobile, accessibility, render evidence):
+ ```
- 1. Identify the surface: repo/folder, route, live URL, deployment target, branch,
- dirty files, and relevant local docs.
- 2. Read repo-local `AGENTS.md`, `CLAUDE.md`, `AI_HANDOFF.md`, `README.md`,
- `PRODUCT.md`, `DESIGN.md`, or task docs when present.
- 3. Decide the register:
- - **Brand:** marketing, launch, campaign, public page, portfolio, editorial.
- - **Product:** app shell, dashboard, tool, form, settings, admin, workflow.
- 4. Name the physical scene: who uses this, where, under what light, with what
- pressure, and what they need to do next.
- 5. Inspect the current rendered UI at desktop and mobile breakpoints before
- making claims about quality.
+ For a narrow fix, compress to target, route, primary action, and done signal.
+ Work is done when the done signal has been checked, or the remaining gap is
+ named.
- ## Design Laws
+ ## Design laws
- The numeric rules (spacing, type scale, color, contrast, density, motion, state)
- are in `references/design-laws.md`. Read it whenever you are writing or reviewing
- actual styles. You do not need it to route a request or scope the work.
+ The numeric rules (spacing, type scale, color, contrast, dark mode, density,
+ components, assets, motion) are in `references/design-laws.md`. Read it when
+ writing or reviewing actual styles. The heads that drive every decision:
- ## Component Sources
+ - **Subject first.** If the remaining visual could belong to any SaaS, exchange,
+ or streaming app, it has failed.
+ - **One memorable move.** Each major surface gets one subject-native signature
+ element (a rights ledger, a chain-of-title timeline, an audit rail). Name it
+ before building. Keep everything around it disciplined.
+ - **Color strategy before values.** Restrained (tinted neutrals plus one accent
+ at 10% or less; dashboards and tools), Committed (one saturated color carries
+ 30 to 60%; brand pages), Full palette (3 or 4 named roles; data viz and
+ campaigns), or Drenched (the surface is the color; launch heroes). Color
+ encodes meaning. Prefer OKLCH, tint neutrals toward the brand hue, never pure
+ #000 or #fff.
+ - **Dark mode is not an inversion.** Surfaces at OKLCH L 12 to 24 stacked
+ lighter as they rise, border-based elevation, 7:1 body contrast, chroma cut 15
+ to 25%, semantic tokens only.
+ - **Type.** Contrasting display and body faces with distinct jobs, at least a
+ 1.25 scale ratio, 65 to 75 character measure, `clamp()` fluid display sizes.
+ - **Layout.** Structure explains the product. A row beats a card; a card inside
+ a card means the information architecture is wrong. The first viewport shows
+ brand, offer, and a hint of what follows. Text never clips at any width.
+ - **Motion by register.** Animate `transform` and `opacity` only, ease-out
+ around 220 to 280 ms, and always ship a `prefers-reduced-motion` variant.
- When a build needs a piece the local system lacks, a base primitive, an
- animated set-piece, or an AI-chat surface: pull it from the vetted registries
- in `references/ui-component-sources.md` and run that file's adoption checklist
- (local first, retokenize, motion law, license tier, render proof) before the
- import lands. Read it when importing a component; auditing or restyling
- existing UI does not need it.
+ **Components the local system lacks:** pull from the vetted registries in
+ `references/ui-component-sources.md` and run its adoption checklist (local
+ first, retokenize, motion law, license tier, render proof) before the import
+ lands. Read it only when importing.
- ## Design System Quality Of Life
+ ## Aesthetic direction
- For any major Suede surface, reusable app shell, launch system, or important component family, produce these artifacts at the smallest useful fidelity:
+ For a new surface or significant redesign, commit to one named direction:
+ refined minimal, editorial, brutalist, retro-technical, organic, maximalist,
+ luxury refined, or product-utilitarian. A design with no committed direction
+ reads as generic.
- - **Token map:** color roles, type scale, spacing, radii, shadows, motion, z-layers, and semantic state names, stored in `DESIGN.md` or `design-tokens.json`.
- - **State matrix:** default, hover, focus, active, disabled, loading, empty, success, warning, error, and permission-denied states for every component that touches data.
- - **Copy vocabulary:** action labels, toast language, error messages, and empty-state prompts that stay consistent across the product.
- - **Screenshot contract:** named states with seeded demo data so marketing, App Store, QA, and docs can reproduce the same visuals.
- - **Accessibility pass:** contrast ratios, focus order, touch targets, keyboard paths, and reduced-motion compliance.
- - **Migration notes:** what old styles still exist, what not to touch, and how new work adopts the system without rewriting unrelated screens.
+ Two reflex tests before committing. First: could someone guess the palette from
+ the product category alone ("music tool, so dark purple")? Reject it. Second:
+ could someone guess the aesthetic family from category plus anti-references
+ (muted teal on dark)? Go further.
- Extract a design-system issue when a token, component, spacing pattern, color,
- type treatment, or state pattern repeats at least three times or controls a
- high-visibility surface. Classify drift root cause as token missing, token
- ignored, component gap, content pressure, platform convention, or legacy debt.
+ Write a theme sentence concrete enough to force the answer: "a studio engineer
+ reviewing a rights dispute at 2 a.m. on a secondary monitor" decides more than
+ "a user looking at data". Dark or light is never a default.
- For broad design-system audits, score:
+ ## Scoped bans
- ```text
- Color consistency: /10
- Typography hierarchy: /10
- Spacing rhythm: /10
- Component consistency: /10
- Responsive behavior: /10
- Dark/light behavior: /10
- Motion restraint: /10
- Accessibility: /10
- Information density: /10
- Polish: /10
- Total: /100
- ```
+ Authoritative list; the full gallery with before and after fixes and the narrow
+ exceptions is in `references/scoped-bans.md`.
- Below 70/100 the system is failing: fix the two lowest dimensions before styling new features on that surface. Any dimension at 4/10 or lower is a P1 finding in the audit report.
+ - Decorative orbs, bokeh blobs, and generic gradient meshes standing in for art
+ direction.
+ - Gradient text on headlines.
+ - Decorative glass panels floating over gradients.
+ - Icon-card grids as the page structure.
+ - First-order category palettes.
+ - **Fake metrics, testimonials, or partner claims. No exception.** Use a real
+ stat with its source, a `[NEEDS REAL DATA]` placeholder, or a structure that
+ needs no number.
- ## Scoped Bans And Exceptions
+ The first five allow a named exception for source fidelity, platform
+ convention, accessibility, a confirmed brand system, or a direct request.
- The heads below are the non-negotiables, and this list is the authoritative one.
- Cite this section rather than restating a ban somewhere else. The full
- gallery (every banned pattern, the scope each ban applies to, the BEFORE/AFTER
- replacement, and the narrow allowed exceptions) is in
- `references/scoped-bans.md`. Read it when a design choice looks like it needs an
- exception, or when reviewing whether one was legitimately taken.
+ ## Words on the surface
- - **Decorative orbs, bokeh blobs, generic gradient-mesh backgrounds.** Three radial gradients at 30% opacity behind the hero is the absence of art direction. Replace with a concrete choice: noise texture, a geometric system, a real product screenshot, an illustrated scene, or a typographic lock-up that IS the background. Gradient meshes, grain, and layered transparency stay legitimate when they serve a named aesthetic; a CSS-only approximation standing in for art direction does not.
- - **Gradient text.** `-webkit-background-clip: text` rainbow or metallic headlines. Replace with one high-contrast headline at full weight and an accent word in a solid color.
- - **Decorative glass panels.** `backdrop-filter: blur()` cards floating over a gradient. Replace with an opaque surface at the correct elevation token plus a 1px border for definition.
- - **Icon-card grids as the page structure.** A 3x2 grid of icon plus title plus one-liner is a product-category dump, not a layout. Replace with rows or sections that map to what the user actually does.
- - **First-order category palettes.** "Music tool, so dark purple." "Observability, so dark blue." A palette guessable from the product category alone is the training-data reflex the Color law exists to reject, and muted teal on dark is the second-order version of the same failure.
- - **Fake metrics, fake testimonials, fake partner claims. No exception path.** Replace with (a) a real stat plus a source note, (b) a placeholder carrying a `[NEEDS REAL DATA]` flag, or (c) a structural element that does not depend on a number.
+ The surface is not finished until the words carry it. Inside a design pass:
- The first five allow scoped exceptions for source fidelity, platform convention,
- accessibility, a confirmed brand system, or a direct user request. Name why the
- exception is earned. The last one allows none.
+ - Labels are actions, not categories: "Register Work", not "Registration".
+ - One action name across button, toast, empty state, and confirmation.
+ - Errors say what happened and how to fix it. Empty states name the next
+ specific action.
+ - No em dashes, no promotional exclamation points, no invented proof.
+ - On public pages, structure for search and answer engines: one H1 that says
+ what the page is, a direct answer in the first viewport, question-shaped H2s,
+ an FAQ block, descriptive link text, and real text (not text baked into
+ images) for anything a search or AI engine should quote.
- ## Copy Rules
+ Hero, page, and campaign copy beyond interface labels goes through suede-copy,
+ which owns frameworks, variants, the answer-first SEO pass, and the 70-point
+ copy score. Run it in the same pass when a build needs new copy.
- - Write like a product operator, not a brochure.
- - Every label names an action, not a category. "Register Work" not "Registration." "Verify Rights" not "Rights Verification." The actor is always the user; the object is always specific.
- - Cut filler, vague promises, and restated headings.
- - Use the same action name across button, toast, empty state, and confirmation.
- - Errors must say what happened and how to fix it.
- - Empty states point to the next specific action, not a generic "get started."
+ ## System audit
- ## Aesthetic Direction
+ For a reusable app shell, launch system, or component family, produce at the
+ smallest useful fidelity: a token map (color roles, type scale, spacing, radii,
+ shadows, motion, z-layers, semantic states) in `DESIGN.md` or
+ `design-tokens.json`; a state matrix (default, hover, focus, active, disabled,
+ loading, empty, success, warning, error, permission-denied); an interface
+ vocabulary; a screenshot contract with seeded demo data; an accessibility pass
+ (contrast, focus order, touch targets, keyboard paths, reduced motion); and
+ migration notes.
- For any new surface or significant redesign, commit to a clear aesthetic direction before writing code. Name it explicitly.
+ Raise a system issue when a token, component, spacing pattern, or state repeats
+ three or more times or controls a high-visibility surface. Name the drift cause:
+ token missing, token ignored, component gap, content pressure, platform
+ convention, or legacy debt.
- Tonal spectrum. Choose one and execute it with precision:
- - **Refined minimal**: restraint, negative space, weight as the only accent, no ornamentation
- - **Editorial**: strong typography hierarchy, asymmetry, text as structure, headline-first layout
- - **Brutalist**: raw grids, exposed structure, high contrast, deliberate anti-polish
- - **Retro-technical**: monospace, terminal palette, scan-line texture, system-UI references
- - **Organic**: rounded forms, warm neutrals, tactile texture, soft shadow
- - **Maximalist**: density as delight, layered elements, multiple active typefaces, controlled chaos
- - **Luxury refined**: generous space, serif hierarchy, muted palette, detail-obsessed craft
- - **Product-utilitarian**: information density, data-first, compact controls, no decorative chrome
+ ```text
+ Color consistency: /10 Typography hierarchy: /10
+ Spacing rhythm: /10 Component consistency: /10
+ Responsive behavior: /10 Dark/light behavior: /10
+ Motion restraint: /10 Accessibility: /10
+ Information density: /10 Polish: /10
+ Total: /100
+ ```
- Bold maximalism and refined minimalism both work. The failure mode is neither: a design with no committed direction reads as generic. Pick one tone and execute it fully.
+ Below 70: fix the two lowest dimensions before styling new features there. Any
+ dimension at 4 or lower is a P1 finding.
- **Unforgettable factor**: every major surface should have one move that earns memory. For Suede that might be a rights ledger, a waveform proof panel, or a chain-of-title timeline. For other companies, it should be one subject-native device: something that only makes sense for THEIR product. Name it before implementation.
+ ## Restyle mode (Suedify)
- **AI slop check**: before committing to an aesthetic, run two reflex tests:
- 1. Could someone guess the theme and palette from the product category alone ("observability → dark blue", "healthcare → white + teal")? That's the first-order training-data reflex. Reject it.
- 2. Could someone guess the aesthetic family from category-plus-anti-references? That's the second-order trap: the first reflex was avoided but the second wasn't. Go further.
+ The target inherits the reference's design logic, rhythm, hierarchy, and
+ interaction feel while staying its own brand. Read
+ `references/restyle-playbook.md` when this mode is active: it holds the twelve
+ moves (Style Fingerprint, Token Distiller, Hero Lift, Section Rhythm, Voice
+ Fingerprint, Copy Reframe, Asset Swap, Motion Match, Responsive Fit, Proof
+ Stack, Screenshot Diff, Ship Polish), the capture procedure, and the
+ `DESIGN.md` template.
- **Theme sentence**: name the physical scene concretely enough that it forces the design answer. "A studio engineer reviewing a rights dispute at 2am on a secondary monitor" forces different choices than "a user looking at data." If the sentence doesn't force the answer, it's not concrete enough. Add detail until it does. Dark vs. light is never a default. Not dark because tools look cool dark, not light to be safe.
+ **Inputs:** `reference_url` and `target_url` (ask if either is missing); the
+ target repo when edits are expected (without one, produce
+ `suedify-implementation-plan.md` instead); optional depth and fidelity
+ (inspired-by, close-visual-match, aggressive-restyle). Defaults: homepage, hero,
+ and primary CTA section at close-visual-match. Once inputs are known, run to
+ completion without further questions.
- **Background and atmosphere**: gradient meshes, noise textures, geometric patterns, layered transparencies, dramatic shadows, grain overlays, and decorative borders are all legitimate tools when they serve the aesthetic. The line between one of these as a tool and one of these as a substitute for art direction is drawn in Scoped Bans And Exceptions.
+ 1. **Verify the target.** Confirm the exact repo; never edit from a multi-repo
+ root. Check git status, remote, and recent log. Preserve WIP.
+ 2. **Capture the reference** at desktop, tablet, and mobile, with the full
+ capture list from the playbook. Save the analysis as `DESIGN.md` in the
+ target repo root.
+ 3. **Capture the target** at matching widths and states. Note what content,
+ assets, routes, and claims must stay.
+ 4. **Map reference to target-safe equivalents** and run the Token Distiller to
+ a full `:root {}` block.
+ 5. **Implement** inside the target's framework and tokens. Update tokens before
+ one-off component styling.
+ 6. **Render and compare** side by side at matching widths, with focused crops
+ of hero, nav, cards, forms, and CTAs. At most 3 compare-and-patch rounds;
+ then list remaining mismatches and offer options.
+ 7. **Verify** lint, typecheck, test, build, and `git diff --check`, and the
+ live route before claiming a public restyle.
- ## Implementation Workflow
+ **May match:** layout proportions, type scale and rhythm, color role structure,
+ section pacing, navigation density, interaction feel, image crop strategy,
+ mobile composition. **Must not copy:** logos or trademarked marks, exact
+ marketing copy, proprietary source, private media, the reference's proof,
+ pricing, guarantees, or metrics. For an exact clone request, deliver a close,
+ target-branded interpretation and say why.
- 1. **Scan:** inspect current files, styles, rendered UI, and route behavior.
- 2. **Shape:** when needed, write a compact plan with color, type, layout, motion,
- asset, copy, and verification decisions.
- 3. **Build:** edit narrowly inside the local architecture. Keep unrelated
- refactors out.
- 4. **Render:** run the local server or use the existing preview. Capture desktop
- and mobile screenshots when practical: `npx playwright screenshot <url>
- --viewport-size=1280,900 desktop.png` and `--viewport-size=390,844
- mobile.png`, or your environment's built-in preview/screenshot tool if one
- is available.
- 5. **Review:** check typography, spacing, colors, asset fidelity, copy,
- accessibility, responsive behavior, loading, empty, error, hover, focus, and
- active states.
- 6. **Verify:** run the relevant lint, typecheck, test, build, or focused command.
- Run `git diff --check` when files changed. Verify live URLs or APIs before
- claiming public behavior.
- 7. **Handoff:** for meaningful work, record target, files changed, commands,
- verification, caveats, and the next step.
+ Never leave a token field empty in `DESIGN.md`; record `UNKNOWN` with the
+ reason.
- ## Red Flags: Stop
+ ## Implementation workflow
- If any of these thoughts appear, stop and run the check you were about to skip:
+ 1. **Scan** files, styles, rendered UI, and route behavior.
+ 2. **Shape** a compact plan: color, type, layout, motion, assets, words,
+ verification.
+ 3. **Build** narrowly inside the local architecture. No unrelated refactors.
+ 4. **Render** desktop and mobile.
+ 5. **Review** type, spacing, color, asset fidelity, words, accessibility,
+ responsive behavior, and loading, empty, error, hover, focus, and active
+ states.
+ 6. **Verify** with the repo's lint, typecheck, test, or build, plus `git diff
+ --check`. Verify live URLs before claiming public behavior.
+ 7. **Hand off** target, files changed, commands, verification, caveats, next
+ step.
- - "The code reads right, so it will render right." Render it. Screenshots beat code inspection.
- - "This change is too small for visual QA." One-line CSS changes break mobile nav. Check desktop and mobile.
- - "Music tool, so dark purple." That is a first-order category reflex. Scoped Bans And Exceptions is where it is ruled out.
- - "A placeholder metric is fine for now." Fake numbers ship. Scoped Bans And Exceptions carries the three allowed replacements and no exception path.
- - "I remember what the reference looks like." Compare source and implementation in the same pass, never from memory.
- - "I'll write the tokens down later." Unlogged tokens are how drift starts. Note the gap now.
+ For shaping or critique, the named lenses in `references/surface-lenses.md`
+ (`/first-frame`, `/hero-voltage`, `/proof-stack`, `/aeo-shine`,
+ `/mobile-seduction`, `/link-sweep`, and others) give quick, nameable angles.
+ Name the ones you apply.
- ## Ship Gate
+ ## Visual QA report
- For launch pages, app shells, public marketing surfaces, App Store assets, or
- high-visibility dashboard work, end with a short ship gate:
+ When a source target exists, save `visual-qa-report.md` with: source path or
+ URL; implementation path, URL, or screenshot; viewport and state; theme, auth,
+ data, and interaction state; full-view comparison; focused-region comparison
+ (or why it was not needed); findings ordered P0 to P3; patches since the last
+ pass; and `final result: passed` or `final result: blocked`.
+ Compare source and implementation in the same pass, never from memory. Mark
+ `blocked` when a required artifact is missing or actionable P0 to P2 issues
+ remain in layout, type, color, assets, words, accessibility, responsiveness,
+ interaction states, or source fidelity.
+
+ ## Red flags: stop
+
+ - "The code reads right, so it will render right." Render it.
+ - "Too small for visual QA." One-line CSS changes break mobile nav.
+ - "Music tool, so dark purple." First-order reflex; see Scoped Bans.
+ - "A placeholder metric is fine for now." Fake numbers ship. Use `[NEEDS REAL DATA]`.
+ - "I remember what the reference looks like." Compare in the same pass.
+ - "I'll write the tokens down later." Unlogged tokens are how drift starts.
+ - "Run every lane, it's a big job." Name the active mode and why.
+
+ ## Ship gate
+
+ For launch pages, app shells, public marketing surfaces, store assets, or
+ high-visibility dashboards, end with:
+
```text
Surface:
+ Mode:
Done signal:
- Evidence:
+ Evidence (screenshots, commands):
+ Copy gate (suede-copy score if new copy shipped):
+ Search gate (H1, direct answer, metadata, crawlable text):
+ Design system gate (score or drift notes):
+ Visual QA gate (passed | blocked):
Blockers:
Accepted caveats:
Next action:
Status: ship | ship-with-caveats | hold
```
- Use `hold` when a core path is broken, claims are false, screenshots do not
- match implementation, accessibility blocks a primary action, or the live route
- cannot be verified. Use `ship-with-caveats` only when the caveat is explicit,
- non-critical, and acceptable for the launch stage.
-
- `hold` halts the work. Do not route around it, do not downgrade it to
- `ship-with-caveats`, and do not keep patching. Emit this and wait:
-
- ```text
- HALT: <the single blocker, named with file, route, or missing evidence>
- Options:
- 1. <option>
- 2. <option>
- 3. <option, if a third is real>
- Awaiting: which option to take
- ```
-
- Give 2-4 real options, not every option. The same applies to a frozen polish
- loop: when the same failure repeats a third time, halt in this format rather
- than opening a fourth attempt.
-
- ## Visual QA Report
-
- When comparing a source visual target against an implementation, save
- `visual-qa-report.md` with:
+ Recommend `hold` when a core path is broken, claims are false, screenshots do
+ not match the build, an accessibility issue blocks the primary action, or the
+ live route cannot be verified. `ship-with-caveats` needs every P0 resolved and
+ each caveat named and non-critical. When recommending `hold`, name the single
+ blocker and give 2 to 4 real options; the user decides.
- - source visual truth path or URL
- - implementation path, URL, or screenshot
- - viewport and state
- - theme, auth state, content/data state, and interaction state
- - full-view comparison evidence
- - focused region comparison evidence, or why it was not needed
- - findings ordered by P0/P1/P2/P3 severity
- - patches made after the previous pass
- - `final result: passed` or `final result: blocked`
+ For restyles, add: reference URL, target URL, target source, fidelity, depth,
+ unmatched reference signals, and legal or brand caveats.
- Compare source and implementation in the same visual pass, not from memory.
- Render the implementation with `npx playwright screenshot <url>
- --viewport-size=1280,900 impl.png` (matching viewport to the source target), or
- your environment's built-in preview/screenshot tool if one is available. Check
- typography, spacing/layout, colors/tokens, image and asset fidelity,
- logos/icons, copy/content, loading/empty/error/hover/focus/active states,
- responsiveness, accessibility, and motion where relevant.
+ ## Output
- Use `final result: blocked` when the source or rendered artifact is missing for
- a required comparison, or when actionable P0/P1/P2 layout, typography, color,
- asset, copy, accessibility, responsive, interaction-state, or source-fidelity
- issues remain. Use `passed` only when no actionable P0/P1/P2 findings remain.
+ Findings lead, rationale follows. Name the file and line. For builds, state
+ what changed and show render evidence. Do not narrate internal steps
+ (preflight, mode routing) to the user, and do not praise the existing design
+ in place of findings. After meaningful work, add a one-paragraph plain
+ explanation, then:
- ## Output Style
+ ```text
+ Changed:
+ Design QA:
+ Screenshots or render notes:
+ Design-system drift:
+ P0/P1/P2 blockers:
+ Verification:
+ Caveats:
+ Status: ship | ship-with-caveats | hold
+ ```
- Findings lead, rationale follows. Name the file and line. For builds, state what changed and show the render evidence. Never name internal process steps (preflight, task router) in user-visible output.
+ ## Boundaries
- Do not validate the existing design, and do not summarize back what is already
- there. Report the lowest-scoring dimensions and the specific failing element, or
- state that no actionable finding exists. A score does not soften because the
- user made the thing, and "it already looks good" is not a finding.
+ - Preserve WIP. Never edit unrelated files.
+ - Never copy protected site assets, exact copy, proprietary code, or
+ trademarked identity during a restyle.
+ - Never invent metrics, pricing, partners, testimonials, legal clearance, or
+ release outcomes.
+ - Never call work done until the done signal has been checked or the remaining
+ gap is named.
## Routing
- - Full copy + design + QA build or launch → johnny-suede-design
- - Reference-to-target restyle, or "make this site look like that one" → johnny-suede-design (Lane B)
- - Visual iteration with the local script harness (craft, shape, audit sub-commands) → (private Suede Labs companion, not in this pack: suede-visual-qa)
- - UX critique, accessibility audit, information architecture, or design handoff docs → (private Suede Labs companion, not in this pack: suede-ui)
- - Broad UI/UX pattern lookup or framework examples → (private Suede Labs companion, not in this pack: ui-ux-pro-max)
- - Deck-only or HTML presentation generation → (private Suede Labs companion, not in this pack: power-design)
- - Words that carry the surface → suede-copy (johnny-suede-write for the full writing stack)
+ - Copy with no layout work, or new hero and page copy inside a build →
+ suede-copy
- Page conversion architecture beyond visual polish → suede-site-alchemy
- - Design change touches shared components, routing, auth, payments, or analytics → suede-code-review before the ship gate
- - Multi-lane build with parallel copy, layout, asset, and QA work → suede-agent-teams
+ - A-F findability, first-screen, CTA, and citation grade of a public page →
+ suede-visibility-grader; scored search audit → suede-seo-audit
+ - The design change touches shared components, routing, auth, payments, or
+ analytics → suede-code before the ship gate
+ - Copy, layout, assets, and QA must run as coordinated parallel lanes →
+ suede-agent-teams
+ - The finished surface is ready to publish → suede-launch-packaging