Suede Design

Suede Design

When to use this skill instead of related skills

• suede-design (this skill): design system tokens, color ramps, type scale, component-level polish, brand identity decisions
• 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, design handoff docs: (private Suede Labs companion, not in this pack: suede-ui)
• Broad UI/UX pattern lookup, framework examples, palette/font/chart searches, or non-Suede implementation heuristics: (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)
• johnny-suede-design: full-stack build combining design + copy + visual QA for a launch or redesign

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.

Core principle: strip the logo and the surface must still be unmistakably this product, and render the result before claiming it works.

Operating Stance

• 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.
• 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 --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.

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

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.

Then state this preflight in the working update:

SUEDE_DESIGN_PREFLIGHT: target= surface= register= context= design_system= git= render= mutation=open

For major design work, reusable systems, reference visual matching, App Store assets, or public launch surfaces, keep mutation=open only after these are known:

• PRODUCT.md or product context status;
• DESIGN.md or design-system context status;
• shape brief status for net-new or large redesigns;
• source visual target status when a mock, screenshot, Figma frame, or

reference URL exists;

• rendered implementation status;
• ship blocker status.

Also apply the shared no-missed gate at ~/.claude/skills/suede-workflow-skills/references/no-missed-quality-gates.md 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.)

Task Router

Choose the smallest path that fits the request.

• 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.

Delivery Discipline

Before major or important Suede design work, write a compact delivery contract:

• 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.

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.

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 public claim truth. Skip both for a small visual or copy fix that can be inspected, patched, rendered, and verified directly.

Suede UI Contract

Before a new surface, significant redesign, reusable component family, or design-system pass, lock the design contract before implementation:

• 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.

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.

Context Checklist

1. Identify the surface: repo/folder, route, live URL, deployment target, branch,

dirty files, and relevant local docs.

1. Read repo-local AGENTS.md, CLAUDE.md, AI_HANDOFF.md, README.md,

PRODUCT.md, DESIGN.md, or task docs when present.

1. Decide the register:

• Brand: marketing, launch, campaign, public page, portfolio, editorial.
• Product: app shell, dashboard, tool, form, settings, admin, workflow.

1. Name the physical scene: who uses this, where, under what light, with what

pressure, and what they need to do next.

1. Inspect the current rendered UI at desktop and mobile breakpoints before

making claims about quality.

Design Laws

Subject First

Strip the logo from any Suede surface. If the remaining visual could belong to a generic SaaS, a crypto exchange, or a music streaming app, the design has failed. Suede surfaces should feel like purpose-built studio infrastructure: precise, traceable, and operator-grade. Every surface should answer: "What does a creator do here, specifically?"

One Memorable Move

Give each major surface one signature element that earns attention: an interactive rights passport, a waveform ledger, a chain-of-title timeline, a studio console, a claim map, a provenance receipt, or another subject-native device. Keep the surrounding UI disciplined so the signature move carries.

Color

• Pick a strategy from the Color Strategy Axis below before picking any values.
• Color must earn its position by encoding meaning: ownership, rights status, action type, risk level, state change, tier, or provenance chain. Decorative color is waste.
• First-order reflex to reject: "music/creator tool → dark purple gradient." Second-order trap: avoided purple but landed on muted-teal-on-dark anyway. Go further until the palette is specific to this surface's physical scene.

Color Strategy Axis

Before picking values, commit to a strategy on this axis:

• Restrained: tinted neutrals + one accent ≤10% of surface area. Default for product dashboards, admin, tools, and focus-heavy workflows.
• Committed: one saturated color carries 30–60% of the surface. Default for brand pages and identity-driven screens. The "one accent ≤10%" rule does NOT apply here.
• Full palette: 3–4 named color roles, each used deliberately. Use for data visualization, campaign pages, and multi-feature products.
• Drenched: the surface IS the color. Use for campaign heroes, launch moments, and brand statements.

Pick a strategy before picking values. Avoid defaulting to Restrained for everything. Committed and Full palette designs require it to feel intentional.

For CSS color values, prefer OKLCH. Reduce chroma as lightness approaches 0 or 100 to avoid garish extremes. Tint every neutral toward the brand hue (chroma 0.005–0.01 is enough). Never use pure #000 or #fff.

Dark Mode

Dark mode is not an inversion. These are the specific rules:

Surfaces: Dark surfaces use lightness 10-18 OKLCH, not 0. Background layers stack from dark to slightly lighter: base (L=12) → elevated (L=16) → overlay (L=20) → modal (L=24). Never use pure black as a surface.

Shadows: Shadows disappear on dark surfaces. Replace elevation cues with border-based layering: 1px border at oklch(1 0 0 / 0.08) on elevated surfaces, oklch(1 0 0 / 0.12) on modals. Drop-shadows only appear in dark mode when the element is physically "lifted" (a draggable card, a tooltip, a floating toolbar).

Contrast minimums: body text on dark background: minimum 7:1 (WCAG AAA). Secondary text: 4.5:1. Disabled text: 3:1. Do not use near-black text on dark surfaces. Use light text with opacity adjustments (oklch(1 0 0 / 0.45) for secondary, oklch(1 0 0 / 0.25) for disabled).

Chroma: In dark mode, reduce saturated color chroma by 15-25%. oklch(0.65 0.22 260) in light → oklch(0.72 0.17 260) in dark. Fully saturated accent colors on dark backgrounds feel neon. Pull back.

Semantic tokens: define light and dark values for every semantic token at design time. --color-surface-base, --color-surface-elevated, --color-border-subtle, --color-text-primary, --color-text-secondary, --color-text-disabled. Never hardcode hex in component CSS.

Typography

• Pair typefaces deliberately. Display, body, and utility text should have

distinct jobs.

• Use scale and weight for hierarchy; keep at least a 1.25 ratio between major

type steps.

• Keep body copy around 65-75 characters per line.
• Keep letter spacing at 0 by default. Do not use negative letter spacing.
• Match type size to context. Dashboards, cards, and toolbars need compact

hierarchy, not hero-scale text.

Typography anti-patterns to avoid without explicit justification:

• Overused system fonts: Inter, Roboto, Arial, SF Pro as the display face
• Symmetric type pairing: display and body from the same family
• Uniform weight: same weight across headline, subhead, and body
• Letter-spacing on body copy
• Negative letter-spacing on small text (under 16px)

Pair typefaces deliberately: one font earns the display role (personality, brand signal), one earns the body role (readability, neutrality). They should contrast: a geometric display pairs with a humanist body; a serif display pairs with a sans body.

Fluid Type Scale

Use clamp() for all responsive type. The pattern is clamp(min, preferred, max) where preferred is a viewport-relative value.

Reference scale (adjust to match the surface's type role):

--text-xs:   clamp(0.75rem,  0.70rem + 0.25vw,  0.875rem);
--text-sm:   clamp(0.875rem, 0.82rem + 0.28vw,  1rem);
--text-base: clamp(1rem,     0.94rem + 0.30vw,  1.125rem);
--text-lg:   clamp(1.125rem, 1.0rem  + 0.62vw,  1.375rem);
--text-xl:   clamp(1.375rem, 1.1rem  + 1.40vw,  2rem);
--text-2xl:  clamp(1.75rem,  1.3rem  + 2.20vw,  3rem);
--text-3xl:  clamp(2.25rem,  1.6rem  + 3.25vw,  4.5rem);

Min is the floor at ~375px viewport. Max is the ceiling at ~1440px. The preferred vw value controls how aggressively the type grows.

Never use fixed px font sizes for display, heading, or subheading roles. Fixed sizes are acceptable only for UI chrome (badges, labels, captions) that must not resize with viewport changes.

Line height scales inversely with size: large display text (≥2xl) uses line-height 1.05–1.1. Body text uses 1.5–1.6. Subheadings use 1.2–1.35.

Layout

• Make structure explain the product. Use bands, rails, timelines, consoles,

grids, tabs, and split panes because the content needs them.

Spatial composition: intentional layouts use asymmetry, overlap, diagonal flow, and the tension between density and negative space. All of these are legitimate tools:

• Asymmetry: column grids that don't divide evenly, intentional visual weight on one side
• Overlap: elements that break their containing rows to create depth
• Diagonal flow: content that leads the eye along a non-horizontal axis
• Generous negative space OR controlled density, not an accidental middle ground

Never use a card where a row would do. Use cards only for items that must be independently scannable, draggable, or selected, not as a visual wrapper for sections, tabs, or form groups. One card inside another card means your information architecture is wrong. Fix the hierarchy, not the nesting.

• Stable UI elements need stable dimensions: boards, grids, icon buttons,

counters, tiles, canvases, and toolbars should not resize when labels, hover states, loading text, or data changes.

• Build a semantic z-index scale: dropdown → sticky → modal-backdrop → modal →

toast → tooltip. Never arbitrary values like 999 or 9999.

• On landing pages, the first viewport must show the brand, product, or offer

clearly and leave a hint of the next section visible on mobile and desktop.

• Text must not overlap, clip, or fight its container at any viewport.

Controls

• Use icon buttons for familiar commands when the icon exists in the local icon set. Add tooltips for icons that are not obvious.
• Use segmented controls for modes, toggles or checkboxes for binary settings, sliders or inputs for numeric values, tabs for views, menus for option sets, and text buttons for commands.
• Keep touch targets usable and focus states visible.
• A dropdown or popover rendered with position: absolute inside a parent with overflow: hidden or overflow: auto gets clipped. Use the native `/popover API, position: fixed`, or a portal to escape the stacking context.

Component Laws

Forms: Every form field shows its label above the input, never as placeholder text. Placeholder is hint text only. It disappears on focus and must not carry required information. Error messages appear below the field they belong to, not as a toast. Required fields are marked; optional fields are not (the default expectation is required). A submit button is always the primary action; it is disabled only when the form is provably incomplete, never as the default initial state.

BEFORE: ` with no visible label AFTER: Email address`

Modals: A modal

…

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: JasonColapietro
• Source: JasonColapietro/suede-creator-skills
• License: MIT
• Homepage: https://jasoncolapietro.github.io/suede-creator-skills/

Install and usage instructions live in the source repository linked above.