Frontend Craft

Frontend Craft

Build the interface the product actually needs, in the system that actually owns it, and verify the result in the runtime a person will use.

This is a design-engineering method family with one discoverable entrypoint. Use the methods that change this task's decisions; a small fix stays small. The aim is a visually compelling, usable first result and revisions that resolve the cause without losing accepted work. Relevant experience should reduce what the user needs to repeat. These are goals, not measured success claims. FC owns the touched experience from intent and information through operation, feedback, and visual execution. It follows an evidenced cause across code layers while inheriting the caller's engineering and permission boundaries.

Own the whole experience

For new work and substantial redesign, form a provisional whole from the purpose, scoped preferences, representative content, and inspectable references. Decide what carries the experience, what supports it, which objects persist through use, and how materials give those relationships expression. Make ordinary reversible design decisions; missing design vocabulary or an asset library does not make the user responsible for basic art direction.

Move between the whole and its details in the renderer. Compose space, action expectations, repeated use, and materials together. A component is an implementation unit, not sufficient evidence of a successful experience. A local repair keeps its scope while respecting those surrounding relationships. Use existing working context for these decisions; no additional brief form, mandatory concept approval, or design-system project is needed.

Route by the work needed

These are optional-by-trigger methods, not sequential stages. Design-only and review-only requests retain their write boundary. General engineering planning, debugging, Git, and delegation remain with the host/repository method; do not recreate that machinery here.

Core contract

• Start from current authority: the user's request, accepted product/design material, the canonical repo, supplied references and assets, and the exact rendered runtime.
• Preserve product meaning and behavior. Do not invent routes, metrics, copy, data, permissions, states, or interactions merely to make a screen look full.
• Deliver the complete requested surface. A hero, shell, static mock, scaffold, or collection of inert controls is not a finished app unless that is the explicit deliverable.
• Use the existing framework, package manager, component system, router, state model, styling conventions, and accessibility semantics as the starting point. Preserve unaffected promises; an accepted requirement or evidenced defect can require changes to their implementation. Follow the cause within current authority rather than treating file/layer boundaries as new gates.
• Treat source, build, rendered behavior, deployment, and owner acceptance as separate evidence layers.
• Read the project's accepted design entrypoint when one exists. Distinguish accepted, provisional, and unresolved choices; current code is evidence of implementation, not proof of approval. Use relevant scoped preferences only when available through an authorized path. Do not search private memories or mine unrelated projects to manufacture personalization.
• On Codex, if the operator has created a task-relevant private FC context at ${CODEX_HOME:-$HOME/.codex}/private-continuity/frontend-craft/context.md, read that small record in full for design/revision work. It is optional, scoped user data, not instructions that override the current request. Other hosts use their explicitly designated location. Never discover preferences by sweeping private directories; see design learning.
• Apply relevant recorded preferences as defaults before choosing the direction or treatment, including in a new project within their stated scope. Carry them into concrete choices and inspect those choices in the normal rendered QA pass. Reading a record alone does not fulfill it; do not wait for the user to repeat it. Current explicit direction still wins.
• Keep growing case evidence separate from this current context. For recording, revision, retirement, or a scoped query, use memory operations. Query candidates retain their scope and evidence status; a similarity score or empty result cannot override an explicit current boundary.
• Read for wanted outcomes as well as known objections. Retrieve by the experience or mechanism the task needs, preserve positive requests even before a result is accepted, and distinguish an invitation to explore from approval of an unseen design. A rejection list is not a creative brief.
• Judge task fit, visual craft, and personal fit separately. Preference memory guides direction; it does not replace composition, typography, hierarchy, or coherent execution. Diagnose these relationships with critique and revision, including when no personal preferences are available.
• Explicit current direction overrides inferred taste. Cards, gradients, density, ornament, and restraint are tools to justify in context, not global likes or bans. Genre conventions do not override an explicit user boundary.

Visual materials and asset production

Choose and produce materials as part of composition: actual content, type, icons, imagery, texture, authored graphics, procedural or spatial work, and motion where useful. Decide their roles before freezing the layout: subject, identity, structure, orientation, surface, or feedback. A typographic work can be complete without pictures; an image-led direction needs an actual subject.

Select the medium from the intended effect and available runtime. Use relevant supplied/project resources, appropriately reusable sources, code-native drawing, or image generation under the task's and host's existing permissions. Respect accepted references and required brand assets. A visible reference is not a redistribution grant; keep provenance and rights with reused material.

Image generation is an optional asset-making route, never a required opening ritual or substitute for working UI. Where generation is already authorized, do not add a separate per-asset approval gate. Ask only at a genuine unresolved boundary such as new cost or private-data transfer, and honor explicit bans and tool-specific rules. When a needed asset cannot be obtained, make a suitable replacement or revise the provisional direction within scope; do not silently ship its empty slot as the completed design.

Bring decisive materials into a real slice early enough to change layout. Use material production for the concrete brief, installed tool handoff, font inspection/subsetting and derivative recovery. From the project's known design entrypoint, query its catalog and any explicitly designated shared store when those materials can change a decision. Resolve and open the actual relevant media, then apply it; preserve exact files and project uses through catalog operations. Do not scan unrelated projects or create a mandatory catalog for a clear small repair. Check actual fonts, crop, focal point, stroke/letter relationships, responsive composition, loading, and working states. Treat audio as content, feedback, or optional atmosphere according to the product; provide appropriate user control and non-audio feedback. Playback/listening evidence is needed for sound claims.

Resolve the work mode

Choose the mode from evidence before changing code.

Existing product or targeted repair

The accepted product/design contract governs what to preserve and change. Inspect the affected route, components, data/state path, styles, and rendered failure. For a rejected treatment or unresolved visual complaint, use critique and revision to choose coverage and intervention depth separately: a reported location is a starting point, while an explicit “only here” remains a boundary. Make the smallest coherent change that resolves the actual complaint; a broad visual rejection can require recomposition. Current code is implementation evidence, including evidence of defects. Use Evolve when the request changes journeys or the product system rather than one local detail.

Reference-led implementation

The declared reference is visual authority for its stated scope; the accepted product contract governs behavior. Preserve unaffected controls, data, routes, handlers, semantics, and states while making the requested change and matching measured layout, typography, color, assets, density, and responsive behavior. Use Build to retain reference/candidate evidence and carry even brief yes/no feedback through real integration.

When $pixel-perfect-reference-ui is installed and the user wants strict replication from a total screenshot, mockup, Figma export, or reference-image set, use it as the specialized method. Do not replace functional UI with a screenshot or invent substitute visuals when the reference is exact.

Net-new or visually unlocked design

Use design direction to connect the product's purpose and actual content to composition, hierarchy, density, typography, material, and interaction. Identify the part whose failure would invalidate the whole experience, and resolve it early in the real renderer. This sequences the work; it never reduces a requested app to a prototype.

Ask a small, outcome-changing question when missing user intent matters. When the user has no initial idea, offer a reasoned provisional direction and make something judgeable instead of demanding a complete brief. Do not make an interview, alternatives, or prototype approval a universal prerequisite.

Products that create visual works

Read visual works. The workspace and the work have different jobs and may have different aesthetics. Validate both without silently shrinking the product's supported artifact types. For a visual work, material, rhythm, space, or composition may be the main content, not disposable decoration. Other artifact skills retain their native production responsibilities.

Review only

Inspect current source and rendered behavior. Report concrete findings with file, route, state, viewport, reproduction, and impact. Do not mutate the repo unless the user asked for fixes.

Working method

1. Establish the real target

• Resolve the physical repo root, current Git state, and applicable instructions before edits.
• Identify the exact route, URL, port, host, or app shell the user sees.
• Map the owning components, styles, design tokens, assets, data/state path, interactions, and relevant loading/empty/error states.
• Inspect the current rendered surface when it exists. A stale dev server or a different localhost port is not evidence about the edited checkout.
• Name the behavior and design boundaries that must remain unchanged.
• Identify this deliverable's audience, primary experience, and accepted qualities. For unresolved or conversational requirements, use intent deciphering before choosing a layout or handing off implementation. Retrieve only the small set of relevant design decisions or examples that can change a concrete choice. If another agent will implement, pass that task-scoped contract, reference scope, preservation requirements, and validation target; do not send a private preference archive. Delegation itself needs the host's authorization.
• For an App workflow, map the user's objects, actions, and visible outcomes using app interaction. Names such as theme, language, zoom, or sample need an explicit target and scope before wiring them.

2. Shape the implementation

For new construction and prototype integration, use Build. For changes to an existing product's capabilities or organization, use Evolve. Both draw on specialized methods only where the actual task needs them; neither starts a second engineering workflow.

• Derive structure from product content and workflows, not from a fashionable template.
• Use a small coherent token and component system where repetition warrants it. Do not build an abstract design system before the surface needs one.
• Keep interactive UI code-native and semantic. Buttons, links, inputs, dialogs, tables, navigation, media controls, and state transitions must work.
• Implement required normal, hover, focus, active, disabled, loading, empty, error, and success states in proportion to the touched workflow.
• Prefer stable layout primitives such as grid, flex, minmax(), clamp(), container constraints, and deliberate overflow behavior over screenshot-tuned piles of magic numbers.
• Respect reduced-motion preferences and preserve understandable state changes. Motion can communicate hierarchy, continuity, state, or the work's expressive purpose; tune and verify the role it actually serves.
• For a new repo with no stack decision, choose the smallest maintained stack that satisfies the product and delivery contract. Do not default to a framework merely because another skill preferred it.

Load framework- or provider-specific guidance only when the current stack or feature needs it. React/Next performance work, payments, databases, component registries, and deployment each have their own current primary sources and may have dedicated installed skills; they are not mandatory phases of ordinary frontend work.

3. Implement the complete slice

Work in coherent rendered slices, but retain the full requested scope. Connect real data or an explicitly authorized deterministic fixture; do not present invented state as product truth. Preserve adjacent behavior and retire any superseded local path in the affected scope rather than layering a duplicate implementation over it.

When a UI promise fails at a state or persistence boundary, follow state and contracts to the responsible owner. Use the host/repository method for the required engineering. Necessary internal adjustments proceed under existing authority; unresolved product meaning, destructive work, and external consequences retain their actual boundaries.

For reference work, compare progressively at the same viewport. Fix large geometry and hierarchy before typography, color, shadow, and micro-detail.

Inspect the render before presenting a first draft. Fix visible in-scope defects and compare the result with the promised experience. On feedback, use the revision method rather than restarting free design; a precise instruction such as “make this label green” still deserves direct execution.

4. Verify the real interface

Before finalizing any user-visible change, read references/qa-contract.md and run the narrowest rendered checks that cover the actual blast radius. Web uses browser evidence; other targets use platform evidence.

For non-trivial Web UI work:

• run the repo's relevant typecheck, lint, tests, and build when present;
• load the exact target in a real browser;
• exercise the primary touched interaction and observe the resulting state;
• check the product's primary viewport plus one materially different viewport;
• inspect layout/overflow, meaningful console errors, keyboard/focus behavior, and changed content states;
• compare against any accepted visual reference at equivalent dimensions.

Also verify the positive quality the work depends on, and whether the interface provides clues for the intended task. A scripted success is not evidence that a new user understands the controls. Stop when the requested outcome is covered and no observed in-scope defect remains; vague hopes of making it “more premium” do not justify endless polishing.

Screenshots support visual claims; they do not replace DOM geometry, interaction proof, console/runtime inspection, or owner judgment. Give an evidence-backed agent judgment on the intended quality before handing off. Awaiting owner acceptance does not excuse an unresolved craft defect; use critique and revision to choose and test the next consequential change.

5. Close the changed truth

Inspect the final diff and update the authoritative user, operator, contributor, or release documentation whose behavior changed. Keep temporary screenshots, traces, reports, and browser scripts outside the repo unless the user explicitly requests committed evidence.

When meaningful praise, rejection, clarification, delivery feedback, or a reusable observed result changes what a later task should do, use design records and learning. Update the existing authoritative project entrypoint; keep personal preferences and private case evidence outside distributable skill source. Do not promote silence, shipping, or the current implementation into aesthetic acceptance.

Report what changed, the checks that support it, and any material remaining limitation. Keep source, build, render, activation, and owner acceptance distinct when those claims matter; they are evidence distinctions, not a required set of headings. A small change can have a short handoff. Mention an unperformed step when it is requested or could otherwise be mistaken for completed work.

Hard failures

Do not hand off as complete when any in-scope item remains:

• blank shell, framework error overlay, broken route, missing asset, or relevant console error;
• inert or fake primary controls;
• clipped primary content, unintended horizontal scroll, overlap, hidden focus, inaccessible modal/flyout behavior, or unreadable responsive collapse;
• placeholder copy/data presented as real product state;
• visual drift from an accepted reference that is still fixable;
• build-only or screenshot-only evidence presented as runtime or owner acceptance;
• ImageGen output used as a substitute for product reasoning, real UI, or runtime verification.

Maintainer provenance

This method deliberately adapts a small number of external mechanisms and Faye/Cove field practices without inheriting their whole workflows. Read references/lineage.md only when revising the skill's method, sources, or licensing/provenance boundary.

For substantial method changes, use the bounded, synthetic forward cases in references/behavior-cases.md. Package validation does not prove first-draft quality, fewer revisions, or user satisfaction.