Frontend Crafting

Frontend Crafting

Design and build interfaces that come from the subject, not from a template. This file is a router: it fixes the contract every workflow shares and points to the one reference file the current request actually needs. Design rules live in the references, never here.

Scope

Use this skill when the request is about how an interface looks, reads, or behaves:

• building a new page, screen, or component from a brief;
• reworking an existing surface, whether the change preserves the current design or replaces it;
• critiquing a UI and reporting what is wrong;
• refining a surface that is already broadly right.

Do not use it to drive a browser, capture screenshots, or debug a running local app; that is web-debug. This skill also does not pick a framework, a hosting target, or a data layer.

Core principles

1. The subject supplies the character. Typography, palette, rhythm, and imagery come from what the product actually is and who uses it. Generic character is the default failure mode, and no amount of styling covers it.
2. Structure carries information. Every panel, card, divider, and badge must encode something true about the content. Structure that exists to fill space is decoration wearing a layout.
3. Ambition is a function of the surface. A marketing page and an operations console want different amounts of risk. Mode detection decides this before any styling decision.
4. Correctness and accessibility are absolute; taste is not. Aesthetic rules are defaults with stated exceptions, never bans. Accessibility, semantics, and behavioral correctness do not bend.
5. Plan, critique, build, critique. Judge the intent before writing code and judge the result after. Both passes are cheap; a wrong concept rendered well is not.

Mode detection

The workflow and mode announcement - and the design read it leads to - belongs in the visible reply, never only in private reasoning: it is a commitment the requester checks the result against, and an unseen commitment binds nothing. Reasoning about the mode is not announcing it. If the two readings of the request genuinely diverge, ask exactly one question - never a questionnaire - and output Step 0 right after the answer. Step 0 owns the trigger and the format.

Step 0 - announce before touching files

Output exactly one line before the first file write or edit, whatever the tool, and before any finding, recommendation or verdict. Reading files, searching, exploring the codebase, and saying what you are about to look at are all fine before it: the line needs the surface read first.

Workflow: <create|redesign|review|polish> · Mode: <Persuade|Read|Operate|Experience> · Read: <one sentence>

No file may be written and no judgement reported before this line appears. The second trigger carries the review workflow, which writes nothing: without it "before the first write" would never fire there and silence would score as compliance.

For a repository-wide request, name the workflow plus every dominant mode actually present, however many that is - two is common but not a ceiling, for instance Mode: Operate + Read + Persuade when a repository genuinely mixes three. Per-surface modes belong in the surface table of the report, not in this line; references/review.md carries that contract, and it loads after Step 0 has already been output.

A single surface can also carry two modes at once, not as a repository mix but as one surface doing two jobs simultaneously - an operate console that is also the product's showcase moment, for instance. Name it Mode: <Mode1>+<Mode2> (spine: <Mode>), where the spine is the mode whose density and keyboard contract govern when the two disagree. The (spine: ...) suffix is what marks a composite surface; a list of modes without it always reads as a repository mix. references/direction.md carries the composite-surface contract in detail.

Workflow - what kind of change is being asked for:

Surface mode - what the surface is for. Read the surface, not the product: a marketing site can contain a documentation page, and a product can contain a pricing page.

Workflow routing

Read only the file the current work needs. Loading more than the request calls for costs context and produces rules that fight each other.

• Read references/direction.md for any request that needs design intent: brief inference, the one-line design read, the surface modes in detail, and the optional reasoning axes. Create and redesign always start here. Review and polish read it only when the intent is unclear or a single surface reads as composite.
• Read references/create.md when building a surface that does not exist yet.
• Read references/redesign.md when changing the design of a surface that already exists, in either direction: preserving the current design language or replacing it.
• Read references/review.md when the request is a critique, an audit, or a design review.
• Read references/polish.md when refining a surface that is already broadly right, including requests phrased as an intent such as bolder, quieter, better typeset, or more delightful.
• Read references/quality-gate.md before building a new surface or substantially modifying an existing one, and before writing any review findings. It is the technical floor: accessibility, semantics, focus, forms, motion, overflow, performance, states, and copy. A small local refinement does not need it; polish.md carries its own compact pre-flight.
• Read references/anti-patterns.md when a design decision feels familiar and you want to know whether that is convergence or a defect, and when a review needs the catalogue of default failures. It is the single source of truth for anti-default material.

Precedence rules

When two considerations collide, resolve in this order.

1. The brief wins. An explicit instruction from the user overrides any default in this skill, including its aesthetic preferences. Quiet constraints count as brief: accessibility-first mandates, public sector work, regulated industries, and products for children all outrank visual ambition without being stated as design instructions.
2. The incumbent stack wins. Before introducing a dependency, a token, or a pattern, check what the project already uses: framework, styling approach, design system, component library, design tokens, animation library, naming conventions, and copy conventions such as capitalization. Match them. A new dependency needs a reason the existing one cannot cover.
3. Preserve and redesign never mix silently. Refinement keeps the existing design language; redesign replaces it. Splitting the difference produces a surface that is neither. If the right answer is the other one, say so and get agreement before switching.
4. No universal aesthetic bans. Absolutes are reserved for correctness and accessibility. Every aesthetic rule here is a default that a brief can earn back, and each one states when it legitimately does not apply.

Framework neutrality

The core of this skill works for Vue and Nuxt, React and Next, Svelte and SvelteKit, and plain HTML, CSS, and JavaScript. Rules are written in terms of HTML, CSS, and DOM behavior. Where an example is specific to one framework or one styling approach it is labelled as such, for instance "Example (React)", and is illustration rather than requirement.

Bounded verification

Visual checking is bounded so it cannot become an open loop:

1. Build the surface completely first. Do not verify partial work.
2. Inspect desktop and mobile together in one batched pass.
3. Fix everything found in one batch.
4. Optionally confirm once that the batch landed. Then stop.

A review-only request never modifies code. Findings are reported, not applied, unless the user asks for the fix afterwards.

Definition of done

• The Step 0 line was output before any file was touched and before any finding was reported, and the work matches what it announced.
• Intent is traceable to the subject: someone could name why this looks the way it does.
• Every requirement in references/quality-gate.md that applies at MUST level holds, including keyboard operability and visible focus.
• Loading, empty, and error states exist wherever the surface can reach them.
• Desktop and mobile were both inspected, in one pass, and the findings were fixed.
• Nothing was silently replaced that the request only asked to refine.
• What was approximated, faked, or left for later is stated plainly rather than implied as done.