Frontend Design

Clade for Codex

This workflow runs directly in Codex. Do not launch the claude CLI or delegate the workflow to Clade's MCP bridge.

Codex compatibility rules:

• Plugin skills are namespaced. Invoke this workflow explicitly as $clade:frontend-design; a bare $name does not select the installed Clade plugin.
• Read the nearest AGENTS.md files for repository instructions. If a project has only CLAUDE.md, treat it as legacy project guidance and read it too.
• Store new Clade working state under .clade/ (or ~/.clade/ for personal state). Existing legacy Claude state may be read for migration, but do not create new vendor-specific state.
• A /skill-name reference means the corresponding Codex $clade:skill-name plugin skill, or the same workflow invoked naturally when explicit skill invocation is not available.
• Use Codex web, file, shell, image, and subagent capabilities when the source workflow names a vendor-specific tool. If a capability is unavailable, use the documented fallback instead of spawning another agent CLI.
• Paths such as <plugin-root>/... are relative to the installed Clade plugin containing this SKILL.md; resolve that root before invoking a helper.

Canonical Clade workflow

Interface Design Pipeline

Create, prototype, redesign, audit, or optimize production-grade interfaces across web, mobile, desktop, and native application surfaces. Preserve the historical frontend-design entry point, but do not treat every interface as a website.

Use evidence to decide what is best for this product. Awards reveal expressive possibilities; platform guidance defines learned behavior; task tests and production outcomes decide whether the result is actually better.

Operating contract

Before making visual choices:

1. Read references/ui-ux-benchmark.md completely.
2. Classify the platform from the request and repository. If unclear, run python3 <skill-root>/scripts/detect_interface_platform.py <project-root>. Treat its result as evidence, not authority; user intent and shipped targets win. Ask only when the unresolved platform would materially change the work.
3. Read the matching platform reference completely:
   • browser, responsive web, or PWA: references/platform-web.md
   • iOS, iPadOS, macOS, UIKit, SwiftUI, or AppKit: references/platform-apple.md
   • Windows, WinUI, WPF, or Windows App SDK: references/platform-windows.md
   • Android, Material, Views, or Jetpack Compose: references/platform-android.md
   • Electron, Tauri, Flutter, React Native, or another shared-code shell: references/platform-cross-platform.md, plus every actual target platform reference that affects the requested work
   • slides, decks, or other projected/presented surfaces: references/platform-presentation.md
4. Detect the design system before choosing colors, type, spacing, components, or motion.
5. Read references/design-direction-profiles.md for Standard and Full work, whenever the user asks for a theme, preset, style, or alternate version, and whenever the visual direction is materially undecided. A Micro change under an established system may reuse the existing direction and mark this N/A.
6. Read references/design-rules.md — the checkable floor: the spacing grid, the type-scale caps, the motion duration table, the state list, the review widths, and the copy ban. Every rule there is phrased so design-lint, a screenshot, or a grep can check it; "premium, modern, polished" is not a brief, and that file is what the brief decomposes into. A Micro change applies the sections the touched component reaches.
7. Read references/signature-motion.md when the ask names a hero animation, a scroll-driven or "Apple-style" product story, a 3D showcase, kinetic typography or a motion identity (眼前一亮 / 主视觉动效 / 滚动驱动动画), or whenever the profile sets motion to 4–5 or names a signature. It carries the vocabulary, the two archetypes with their timing budgets, the four implementation routes and when each fits, the semantic-motion rule, and the storyboard that must exist before any code.

For a mixed-platform product, share product logic, content, and brand tokens, then translate platform contracts separately. Do not average incompatible platform conventions into one lowest-common-denominator UI.

Scope lane

Run every phase below for every UI task, but scale the evidence and artifacts to the decision risk:

• Micro — a local, reversible component or style correction. Reuse existing product evidence; compare the platform rule and one relevant in-product or external pattern. Do not manufacture a research project.
• Standard — a component family, page, screen, or user flow. Use the official platform source, two direct-product flows where available, one mature design system, and one known failure/counterexample.
• Full — a new product, major redesign, unfamiliar interaction, or cross-platform system. Use the complete benchmark set: official platform, two direct competitors, an awarded reference, a mature design system, and a counterexample. Capture complete flows rather than hero screenshots.

State the lane and rationale. A skipped phase is not invisible: mark it N/A with a concrete reason.

Review-only requests

When the ask is to review, audit, or 挑毛病 an existing surface rather than to build one, run phase 1 (baseline captures) and phase 6 (the review in references/design-review.md) and skip the rest with N/A. Deliver findings by P0–P3 severity, each with the rule it breaks and the fix; then apply the fixes unless the user asked for a report only. No adjectives — "modern, clean, professional" is not a finding.

Seven-phase pipeline

1. Lock the problem

Identify the target users, target platform(s), and three most important tasks. Classify the request as greenfield design, optimization, or implementation of an approved spec. Record technical constraints, input modes, accessibility needs, locales, performance budget, and the desired outcome.

Draft the one-line Design Read and a clade.design-direction/v1 profile from references/design-direction-profiles.md. Treat both as hypotheses until the benchmark confirms them. For redesigns, choose preserve, evolve, or reframe explicitly; never smuggle a reframe into a request for polish.

For greenfield and reframe work, also write the Style DNA — six lines, each concrete enough to grep or screenshot against:

Personality:       three adjectives — precise, trustworthy, calm (not cold)
Must not read as:  the AI SaaS template; purple gradients; glassmorphism;
                   floating orbs; every block in a rounded card
Signature marks:   3–5 repeated features — large condensed headlines; mono for
                   data and status; hairline borders on a visible grid; one
                   green for action and success; panels slide 8 px on open
Density:           marketing surfaces loose, working surfaces compact
Radius:            container 8 / button 6 / tag 999 — not every element a pill
Shadow:            only on what floats; cards separate by border, ground, space

"Premium, modern, techy" is not a DNA. "Techy" has to say which typeface, radius, border, colour, motion and density. Reference products are allowed only as split borrowings — A's density, B's type register, C's motion speed — never one product's page structure. Style comes from repeated choices, not from personality on all five axes (type, colour, geometry, imagery, motion) at once: pick one or two as the identity and keep the rest quiet.

For optimization, establish the baseline before editing: capture the current rendered surface and important flows, list observed failures, and tie each proposed change to task success, error recovery, comprehension, accessibility, or a product metric. Do not translate personal taste into an unqualified "improvement."

2. Build the benchmark

Use the evidence ladder and reference-set rules in references/ui-ux-benchmark.md. Inspect complete states and flows: loading, empty, error, permission, offline, undo, keyboard, touch, and destructive paths where relevant. Separate observations from hypotheses.

Produce a compact benchmark brief containing:

• the reusable pattern and why it fits this task;
• the platform behavior that must remain native;
• the product behavior worth inventing;
• the brand expression worth making distinctive;
• rejected patterns and why they fail here.

Confirm or revise the Design Read and profile after reviewing the evidence.

3. Define behavior before decoration

Specify information hierarchy, navigation, content, and the shortest coherent task path. For each interactive component, consider:

• rest, hover where available, keyboard focus, pressed, selected, disabled, and loading;
• success, empty, error, permission, offline, undo, and recovery states at the flow level;
• mouse/trackpad, keyboard, touch, stylus, assistive technology, and remote/game controller inputs only where the target platform supports them;
• localization expansion, dynamic type/font scaling, dark/high-contrast modes, and reduced motion.

Hover must never carry required information. Cursor changes must follow platform and component semantics, not fashion. Motion must perform at least one job: confirm feedback, explain spatial relationship, preserve continuity, guide attention, or express progress. If removing an animation does not make the change harder to understand, omit it.

4. Choose the visual checkpoint

Brand surfaces first: if this is a brand's own site or landing page, if sibling products must not look related, or if "make it distinctive" is part of the ask, load references/brand-differentiation.md and follow it before choosing anything visual. It carries the standing constraints — the visual-school pool, the four-dimension palette method, the banned default palettes and typefaces, the signature-interaction rules, and the anti-laziness checklist. Those constraints were being hand-typed into prompts for five months while this skill did not contain them; the one thing not to do is design from taste and then check the file afterwards.

Decide whether a preview reduces meaningful rework:

Three materially different directions before one is chosen — Full-lane greenfield or reframe only. Each direction is a Style DNA card with a different school, type strategy, geometry, density and motion character, plus why it fits this product and what could go wrong with it. Three recolours of one layout are not three directions. Pick one, or ask the owner to, then proceed. Under an established design system, or for Micro and Standard work, mark this N/A.

Component lab before business pages. Before the first real screen, build a /design-lab — a Storybook story, a dev route, or one standalone HTML page — that shows the type scale, the palette, buttons, inputs, select, card, table, modal, tooltip, tabs, toast, status tags, a chart, the empty and loading states, and one motion example, in every state references/design-rules.md §7 lists. Skip it and the first-page button, the dashboard button and the settings-page input drift apart; the lab is where the token scale is proven once.

Signature motion is storyboarded before it is coded. For a hero intro or a scroll-driven product story, fill the segment table in references/signature-motion.md §6 — range, product, camera, light, copy, page state per segment — choose the implementation route by the shot (frame sequence + canvas + ScrollTrigger by default; real-time 3D only when the user must control the product), and state the budgets: intro length and its four beats, idle cadence, pointer response, pinned chapter length, frame counts per device, the reduced-motion static state. The motion must show the product's capability with the copy removed; "add some cool animation" is not a brief and is answered with the storyboard, not with fade-ins.

Once a direction is chosen, prefer one recommended checkpoint. Produce a second variant only when a real tradeoff remains unresolved by evidence; do not generate decorative option sprawl.

When composition or motion is 4 or 5, require a rendered checkpoint before committing to the direction. When comparing versions, hold content, tasks, and platform behavior constant and state the exact profile delta.

If the user asked to see the direction before implementation, make the preview viewable, provide the local/live URL or rendered image, and stop at that checkpoint for confirmation. Otherwise use the checkpoint as an internal review step and continue. Never present an HTML mockup as proof of native behavior.

5. Implement in the real surface

Use the existing framework, components, and repository conventions. Do not replace a working stack merely to express an aesthetic. Match implementation complexity to the value of the interaction.

Apply this precedence order when rules conflict:

1. safety, accessibility, and user data integrity;
2. platform input, semantic, window, and navigation contracts;
3. the project's explicit design system and shipped component library;
4. the product's task model and content;
5. brand expression and visual novelty;
6. general aesthetic guidance.

This is not a choice between native and custom. Keep the platform skeleton, invent the product brain, and express the brand without breaking either.

One representative page first. Polish one representative screen to the Definition of Done in references/design-review.md, then extend that language to the rest. Never build ten pages in one pass: the rules drift a little per page and the drift compounds until the pages no longer read as one product. Tokens only — no colour, size, spacing, radius or shadow outside the scale without a written reason at the site; design-lint source names each one.

6. Verify the implementation

Use three evidence tiers:

1. Source/static — types, lint, hard-rule grep, semantics, token usage, and design-lint source <dir> for the spacing grid, type-scale caps, motion table, token discipline and copy.
2. Rendered/interactive — real viewports or native previews, screenshots, focus order, keyboard/touch/pointer behavior, state transitions, contrast, text scaling, reduced motion, overflow, and realistic data.
3. Outcome — representative users performing target tasks, then production success, completion time, errors, abandonment, support tickets, retention, conversion, and performance percentiles where applicable.

Run the repository's tests and the platform checks named in the selected reference. For HTML/web output, run design-lint html <artifact> and inspect the live result at every declared viewport. A clean static check does not prove a rendered rule. For decks, run design-lint deck and, once rendered, design-lint render.

Then run the review in references/design-review.md: capture the page at 390 / 768 / 1280 / 1440 (or the declared breakpoints), list findings by P0–P3 with no adjectives, fix them in code, re-capture, and repeat until no P0 or P1 remains. Run design-lint source before the loop and again after; its WARN lines are questions the review answers with a fix or a written reason, never noise. The first generated version is a structural draft — report the counts at the start and at the end of the loop, not "looks good now".

Do not claim user testing, assistive-technology coverage, device coverage, or production improvement unless it actually occurred. Report an unrun tier as a named follow-up gate, not as a pass.

7. Compare and record

For optimization, compare before and after against the same tasks and constraints. Record decisions, rejected experiments, remaining uncertainty, and the next measurable signal. For a substantial or long-lived design, append the decision to the project's design-system Decisions Log when one exists.

Design system integration

Use the first design-system source found:

test -f .design-system.md && echo "FOUND: .design-system.md"
test -f design-system/SKILL.md && echo "FOUND: design-system/SKILL.md"
test -f DESIGN.md && echo "FOUND: DESIGN.md"

When one exists:

• Read it fully before visual implementation.
• Use its defined color, typography, spacing, motion, and component tokens. Treat [placeholder] as undefined and exercise freedom only there.
• Import its shipped components and brand assets; never redraw a supplied logo or rebuild a component primitive without a documented reason.
• Enforce grep-able hard rules against every task-owned file. Use a rendered validator for rules about contrast, size, coverage, hierarchy, or motion.
• Verify every declared viewport and appearance mode.
• Record significant choices and rejected experiments in its Decisions Log.

When no design system exists, define a small constrained token scale before composing. Do not create a permanent design system unless the user asks for one or the implementation clearly requires reusable governance.

If asked to author a design system, ship:

• SKILL.md no longer than 100 lines with grep-able hard rules, token summary, component pointers, and a review checklist;
• DESIGN.md with rationale, component/state specifications, principle-to- application statements, open tensions, and a Decisions Log;
• paste-ready tokens, components, and brand assets;
• a validator for every hard rule that targets rendered output.

Component and aesthetic rules

• Prefer the project's component library. Use shadcn, MUI, Ant Design, Radix, SwiftUI/UIKit/AppKit, WinUI, Compose/Material, Flutter, or other declared primitives rather than rebuilding their contracts from scratch.
• Define the shared control set once, before the first screen: button (every variant and size), text input and its field states, card/surface, and navigation. Each gets its spacing, radius, border, type and state values written into the design-system file, and every screen reuses that definition. A second button style, a card whose radius differs from the one two sections up, or a nav that changes between pages is an inconsistency defect, not a per-page decision. Where the chosen school makes a component shape non-default (references/brand-differentiation.md Step 6), state that shape once for the whole set rather than per screen.
• Prove hierarchy in grayscale through size, weight, order, and space before relying on color.
• Use constrained type, spacing, radius, elevation, color, and motion scales.
• Choose a clear aesthetic direction appropriate to the product. Distinction should come from coherent hierarchy, content, composition, data expression, and a few signature moments, not effects on every control.
• A platform/system font is often the correct native choice. On expressive web and brand surfaces, choose typography deliberately; never reject a system font merely because it is common.
• Avoid generic AI styling: context-free purple gradients, interchangeable card grids, arbitrary glass, excessive pills, decorative dashboards, fake native chrome, and motion without a job.
• Do not add custom cursors, scroll hijacking, parallax, blur, grain, or texture unless they support the concept and survive platform, contrast, performance, and reduced-motion checks.

Accessibility and legibility floors

These are floors, not aesthetic targets. A design system may raise but never lower them.

• On web, meet WCAG 2.2 AA: body text at least 4.5:1; large text and meaningful non-text UI at least 3:1 against the real backdrop.
• Keep focus visible. Never remove an outline without an equally visible replacement, and ensure focused content is not obscured.
• Meet the target platform's minimum hit size; for web, never go below the WCAG 24x24 CSS px minimum/spacing exception and aim near 44px for primary touch actions.
• Guard or neutralize animation under reduced-motion settings.
• On web, use real headings, links, buttons, labels, and image alternatives before ARIA. On native platforms, use real accessibility roles, names, values, actions, and focus order.
• Test text enlargement, localization expansion, high contrast, keyboard or switch access, and screen readers when relevant. Mark human/device-only checks truthfully.

Presentation surfaces

For slides and decks, also follow references/platform-presentation.md and invert browser assumptions:

• Give each slide one dominant thesis with roughly 60/30/10 visual hierarchy.
• Keep audience-facing body copy at least 18pt where possible, with about 13pt as a metadata-only floor; keep the main slide near 70 words or fewer.
• Use heavy full-bleed surfaces as focal beats, not ambient decoration.
• Review at presentation distance and validate the rendered artifact, not only the source.

Public-web SEO only

Apply SEO metadata only to public, crawlable web pages. Do not add it to native apps, internal tools, isolated components, or visual prototypes unless they are also public pages. For an applicable page include a unique title, description, canonical URL, Open Graph title/description/image/URL, and appropriate WebSite or Organization structured data. Use the framework's native metadata API.

Required handoff

Start the implementation handoff with:

## Design Decisions

- **Scope lane**: [Micro / Standard / Full — rationale]
- **Platform**: [detected target(s), inputs, and platform reference loaded]
- **Design system**: [source and tokens/components used, or none]
- **Design direction**: [Design Read; `clade.design-direction/v1` preset,
  variant, mode, family, composition/motion/density, source, and overrides; or
  `N/A` for a Micro change that reuses an established direction]
- **Style DNA** (greenfield / reframe): [personality; must-not-read-as;
  signature marks; density; radius; shadow]
- **Directions considered** (Full greenfield / reframe): [three, one line each,
  and why the chosen one]
- **Benchmark**: [reference set, reusable pattern, counterexample, rejected choice]
- **Brand differentiation** (brand surfaces only): [visual school and why; the
  four palette decisions; typeface and why, with its line heights and its weight
  set; signature interaction, **the technology chosen to build it and why that
  one over the alternatives**, and how it belongs to both school and subject;
  and the final test — beside a typical Linear or Vercel site, are these visibly
  two different companies?]
- **Core components**: [button per variant, text input, card, navigation —
  radius, border, padding, elevation, and hover/focus/pressed treatment, stated
  once. Every screen consumes these; a screen needing a new component adds it
  here first.]
- **Screens in scope**: [the enumerated screens or routes this spec governs, so
  "implemented consistently across all of them" is checkable rather than felt.]
- **Native vs custom**: [platform skeleton / product brain / brand expression]
- **Visual checkpoint**: [real surface / HTML study / native preview / direct implementation — why]
- **State and motion**: [states covered; each motion's job or no-motion decision]
- **Signature motion** (only when one exists): [archetype — scroll story or
  hero intro; route and why; the storyboard table or its location; intro /
  idle / pointer budgets; frame counts per device; reduced-motion state; the
  §7 acceptance items not yet met]
- **Verification**: [source, rendered/interactive, and outcome evidence; explicit unrun gates]
- **Review loop**: [widths captured; P0/P1 count at start → at end; P2/P3
  left and their owner; `design-lint source` FAIL/WARN counts before and after]
- **Measured worst contrast**: [ratio and tool/lane, or truthful reason it was not measurable]

Before reporting completion:

• confirm every pipeline phase is represented or marked N/A with a reason;
• run project tests, design-system checks, and selected platform verification;
• inspect the real rendered/native result rather than trusting source alone;
• confirm every screen named in Screens in scope was implemented against the design note, and name any screen deliberately left on the old system;
• confirm no implemented screen introduces a colour, font, radius, or motion duration that is absent from the design note — cross-screen consistency is the deliverable, not a side effect;
• walk the Definition of Done in references/design-review.md item by item for every screen in scope, and name the items that are not met rather than rounding them up;
• preserve task-owned work through the repository delivery workflow;
• use DONE_WITH_CONCERNS when human/device/production evidence needed for the user's stated outcome remains unavailable.

Use DONE, DONE_WITH_CONCERNS, BLOCKED, or NEEDS_CONTEXT truthfully. After three failures of the same approach, stop repeating it and report the blocking condition.

Additional skill reference

Interface Design Pipeline

Guides interface work from evidence and platform choice through preview, implementation, and verification. The historical frontend-design name stays for compatibility; the workflow covers web, mobile, desktop, and native apps.

Usage

/frontend-design        # Run the platform-aware interface pipeline
/frontend-design profile=soft-premium motion=1
/frontend-design review <path-or-url>   # P0–P3 review of an existing surface, fixes applied

"Design sense" is carried as checkable rules, not adjectives: the spacing grid, type-scale caps, motion duration table, state list and review widths in references/design-rules.md; the screenshot review loop, severity ladder and Definition of Done in references/design-review.md; and `design-lint source

Every invocation classifies the target platform and task size, reads the shared benchmark contract plus the relevant platform adapter, then runs all seven pipeline phases at proportional depth. It respects the project's design system, keeps platform contracts native, and makes product workflow and brand choices deliberately.

For a theme, style, or alternate version, select a named design-direction profile or infer a custom one, then tune composition, motion, and density. A profile is a reusable hypothesis; repository and platform evidence still win.

When visual direction is materially uncertain, it creates a viewable checkpoint before expensive implementation. HTML is preferred for browser UI and may be used as a clearly labelled visual study for native apps; native behavior must be validated in the real platform preview, simulator, or running app.

Delivery completion

If this workflow changes files or external state:

• Inspect the real final state before responding, including git status for a repository task.
• Never report DONE while task-owned changes are uncommitted. Use or continue $clade:delivery and create a repository-compliant checkpoint or preserve the work when committing is unavailable.
• When the user request or trusted repository policy makes publication, deployment, or live verification part of the task, do not silently downgrade the result to local-only work.
• If a required delivery transition lacks authority, credentials, a destination, or reachable external state, report BLOCKED or NEEDS_CONTEXT rather than appending a "not committed/pushed/deployed" caveat after DONE.