suede-design — independently scanned and version-tracked by SaferSkills.
SaferSkills independently audited suede-design (Agent Skill) and scored it 100/100 (green). The audit ran 55 deterministic rules across Security, Supply Chain, Maintenance, Transparency, and Community; it found 0 high-severity and 0 lower-severity findings. The full rule-by-rule trace and per-finding evidence are below. Free, methodology-open.
Findings & checks · 0 flagged
Every scanned point with the score it earned and what moved between them.
First recorded scan — no prior version to compare against.
The primary manifest — the file an agent reads to learn what this artifact does.
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.
Before any design work, read the surface context:
PRODUCT.md: users, brand, tone, anti-references, strategic principlesDESIGN.md: color tokens, type scale, component inventory, spacingAGENTS.md, AI_HANDOFF.md, or README.md: agent guidance and surface contextIf 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=<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> mutation=openFor 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;reference URL exists;
Also apply the shared no-missed gate at ../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 from the same repo. If not installed, run Copy Gate, Visual QA Gate, SEO/AEO/AI EO Gate, Design System Gate, and Launch Gate checklists using the criteria defined in the Workflow section of this skill.)
Choose the smallest path that fits the request.
and report what changed.
tradeoffs, recommend one, and get approval before implementation.
register, scene, color strategy, typography, layout, signature moment, constraints, and QA plan.
shadows, breakpoints, icon usage, and repeated UI patterns before proposing changes.
or image target plus a rendered implementation, compare both visually before handoff and save suede-visual-qa.md in the project root.
repeats, freeze the loop, reduce scope to the failing unit, and rerun with explicit acceptance criteria.
Before major or important Suede design work, write a compact delivery contract:
approved, and launch/release boundaries;
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.
Before a new surface, significant redesign, reusable component family, or design-system pass, lock the design contract before implementation:
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.
dirty files, and relevant local docs.
AGENTS.md, CLAUDE.md, AI_HANDOFF.md, README.md,PRODUCT.md, DESIGN.md, or task docs when present.
pressure, and what they need to do next.
making claims about quality.
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?"
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.
Before picking values, commit to a strategy on this axis:
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 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.
distinct jobs.
type steps.
hierarchy, not hero-scale text.
Typography anti-patterns to avoid without explicit justification:
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.
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.
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:
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.
counters, tiles, canvases, and toolbars should not resize when labels, hover states, loading text, or data changes.
clearly and leave a hint of the next section visible on mobile and desktop.
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: <input placeholder="Email address" /> with no visible label AFTER: <label>Email address</label><input placeholder="e.g. [email protected]" />
Modals: A modal is for a destructive action, a focused sub-task that needs temporary full attention, or a preview that shouldn't break navigation context. It is not the first answer to "the user needs more information." Use inline expansion, a side drawer, or a dedicated route instead when the content is browseable or the action is reversible. Every modal has one primary action and one escape (keyboard Escape + backdrop click). Never stack modals.
BEFORE: clicking "details" opens a modal with a scrollable list of 12 items AFTER: clicking "details" expands an inline panel or navigates to a detail route
Empty states: An empty state is a conversion opportunity, not a placeholder. It must contain: what would be here (one concrete example), why it's empty (the specific reason), and what to do next (a single, specific action). Never show just an illustration and "No results found." Name the specific thing that's missing.
BEFORE: [Icon] No tracks yet. with a disabled button AFTER: Register your first work to start building your rights ledger. [Register a Work →]
Data tables: Column headers are left-aligned except numeric columns, which are right-aligned. Rows are 40-48px tall for data-dense tables, 56-64px when each row needs a secondary line. Alternating row fills are a last resort for wide tables with more than 8 columns. Prefer generous column padding and strong header contrast instead. Sort indicators are visible on hover for all sortable columns, not just the active one. Pagination controls live below the table, right-aligned, with total count visible at all times.
Navigation: Primary navigation shows the user's current location at all times with a visible active state that is not just color. Use weight, underline, or background shape so it survives grayscale. Depth beyond three levels means the information architecture needs restructuring, not another nav level. Mobile nav collapses to a bottom tab bar (max 5 items) or a full-screen drawer. Never a hamburger that reveals a sidebar on a phone.
surface needs a visual asset. Do not replace visible brand assets, product imagery, or nonstandard icons with CSS shapes, emoji, placeholder divs, or improvised inline drawings.
or an operator-provided brand folder. Do not reference private local asset paths in public docs, screenshots, or generated output.
interactive or moving as intended, and responsive.
Every animation must justify its CPU cost. If removing it makes the UI clearer, remove it. If keeping it makes an action legible (a row sliding out when deleted, a panel expanding from its trigger, a success state settling into place), keep it.
Never animate width, height, top, left, or margin. Animate transform and opacity only.
Exit curve: ease-out-expo (cubic-bezier(0.16, 1, 0.3, 1)), duration 220-280ms. The UI should feel like it arrives, not drifts.
Entrance sequencing for lists, cards, and panels: translate3d(0, 12px, 0) → translate3d(0, 0, 0) + opacity 0→1, 240ms ease-out-expo, stagger 40ms per item, max 6 items staggered then clamp. Cap total reveal sequence at 480ms. Panels enter at 300ms; hero content at 180ms.
Scroll-triggered reveals fire once, not on every scroll direction change. Use IntersectionObserver with threshold: 0.15.
In React, use Motion (Framer Motion). Always include a prefers-reduced-motion variant that removes translate and cuts duration to 0ms.
For any major Suede surface, reusable app shell, launch system, or important component family, produce these artifacts at the smallest useful fidelity:
DESIGN.md or design-tokens.json.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.
For broad design-system audits, score:
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: /100These are not blanket bans. Keep or recreate a pattern when source fidelity, platform convention, accessibility, a confirmed brand system, or a direct user request makes it the right choice. When making an exception, name why it is earned.
Rewrite the element if any of these appear as a lazy default:
Gradient text. BEFORE: -webkit-background-clip: text rainbow or metallic effect on headlines AFTER: A single high-contrast headline at full weight with an accent word in a solid color, or a single-hue gradient at low chroma (essentially a slight lightness shift)
Decorative glass panels (blur + translucent background). BEFORE: backdrop-filter: blur(20px) card floating over a gradient background AFTER: An opaque surface at the correct elevation token, with a 1px border for definition
Colored side-stripe borders on cards, alerts, or list items. BEFORE: A card with a 4px left border in --color-warning indicating status AFTER: An icon + label in the semantic color inside the card; or a top-of-card banner strip that spans the full width and carries text
The hero-metric template (big number, tiny label, support stats, gradient accent). BEFORE: $2.4M in 80px weight-900 with "Revenue generated" in 12px below it AFTER: A metric placed inside a real workflow context. E.g., the royalty total shown inside the rights ledger column it belongs to, not isolated as a hero number.
Identical icon-card grids as main page structure. BEFORE: 3×2 grid of cards each with icon + title + one-line description AFTER: A task-driven layout where each row or section maps to a specific user action, not a product category
Modal as the first answer to every interaction. BEFORE: Every "view details" → opens modal AFTER: Inline expansion, side panel, or dedicated route; modal reserved for destructive confirmation or focused isolated actions
Decorative orbs, bokeh blobs, generic gradient backgrounds. BEFORE: Three radial gradients at 30% opacity behind the hero AFTER: A concrete art-direction choice: a noise texture, a geometric system, a real product screenshot, an illustrated scene, or a typographic lock-up that IS the background
Centered hero copy over a stock-feeling gradient with no real Suede artifact. BEFORE: "Own Your Music" centered on dark purple, no visual content below AFTER: A hero that contains a real product artifact (a partial rights registry UI, an animated waveform ledger, a claim receipt) with copy anchored to it.
Fake metrics, fake testimonials, fake partner claims. No exception. Remove and replace with either: (a) a real stat with a source note, (b) a placeholder with a [NEEDS REAL DATA] flag, or (c) a structural element that doesn't depend on a specific number.
Em dashes in UI or marketing copy. BEFORE: "Distribute your music. Own every right." AFTER: "Distribute your music. Own every right." Use a period, a colon, or a comma. If the clause needs an em dash, restructure the sentence.
For any new surface or significant redesign, commit to a clear aesthetic direction before writing code. Name it explicitly.
Tonal spectrum. Choose one and execute it with precision:
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.
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.
AI slop check: before committing to an aesthetic, run two reflex tests:
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.
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. Do not substitute generic gradient blobs, bokeh orbs, or CSS-only approximations for real art direction.
asset, copy, and verification decisions.
refactors out.
and mobile screenshots when practical.
accessibility, responsive behavior, loading, empty, error, hover, focus, and active states.
Run git diff --check when files changed. Verify live URLs or APIs before claiming public behavior.
verification, caveats, and the next step.
For launch pages, app shells, public marketing surfaces, App Store assets, or high-visibility dashboard work, end with a short ship gate:
Surface:
Done signal:
Evidence:
Blockers:
Accepted caveats:
Next action:
Status: ship | ship-with-caveats | holdUse 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.
When comparing a source visual target against an implementation, save suede-visual-qa.md with:
final result: passed or final result: blockedCompare source and implementation in the same visual pass, not from memory. 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.
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 the render evidence. Never name internal process steps (preflight, task router, mutation) in user-visible output.
~30 seconds. Free. No account. Every finding cites a rule and a line of evidence.