Jaw Dev Frontend

Dev-Frontend — Domain-Correct Frontend Engineering

Build production-grade frontend implementations from an established product/design direction. This skill owns HTML/CSS/component/runtime implementation, responsive behavior, accessibility wiring, visual verification, and frontend platform rules.

Role separation: For design judgment — typography/color/layout direction, UX decision gates, product personalities, or vague visual briefs — load dev-uiux-design first. This skill implements the chosen direction; dev-uiux-design makes the design decisions. Implementation anti-slop tell detection and enforcement stays here (concrete rendered tells in UI); design-level concept/taste judgment lives in dev-uiux-design.

Role boundary (canonical — identical in dev and dev-uiux-design): dev owns universal process, evidence, and safety rules. dev-uiux-design owns design intent, direction, and concept judgment. dev-frontend owns concrete frontend implementation and rendered tell enforcement. Anti-slop has three layers: dev = output/process hygiene (FAMILY-SLOP-01), dev-uiux-design = concept/taste judgment (is this direction generic or domain-wrong?), dev-frontend = rendered implementation tell detection and removal (FE-AI-TELL-01).

C0/C1 work (small local patches): See dev §0.0 Work Classifier + §0.1 Patch Fast-Path before reading references.

dev is canonical: dev §0.2 Rule Classes, §3 Verification Gate, and §5 Safety Rules apply to all work governed by this skill.

Modular References

Start with anti-slop.md, aesthetics.md, responsive-viewport.md, and visual-verification.md. Add domain/locale/stack references only when relevant. For C2 ordinary app screens (form/table/list/detail), crud-ui.md alone suffices; add the style references above for marketing/visual surfaces or C3+ work.

• UI/rendering bug RCA: load dev-debugging.
• Build pipeline, bundle config, or deployment: load dev-devops.
• Project setup or file placement conventions: load dev-scaffolding.
• Data-driven dashboards, reporting views, or data format expectations: load dev-data.

When frontend choices depend on current framework, design-system, browser API, library behavior, or package/source freshness, follow dev §External Evidence and Recall Routing and load the search skill for current/external lookups.

Verification grounding

STRICT: For render/executable artifacts (HTML, SVG, games, UI, charts), run the real renderer: headless browser, screenshot, canvas check, or equivalent. Observe the actual output yourself, fix what observation reveals, then re-run. Static parsing confirms well-formed files; it does not prove the artifact is visually or interactively correct. One clean observation is enough for unchanged state; do not re-render unchanged output just to repeat evidence.

0. Frontend Routing

Before designing or coding, classify the work:

Default rules:

• For apps/tools/dashboards, build the actual working surface first, not a marketing hero.
• For Korean-first work, read korea-2026.md and ux-writing-ko.md.
• For any soft 3D miniature, mascot, chibi, toy-like object, or character-like asset, read soft-3d-asset-gates.md.
• For product/brand/object/place/person pages, use concrete visual assets in the first viewport.
• For finance, government, B2B, admin, auth, security, and developer tools, keep visual warmth restrained and subordinate to clarity.
• Every user-facing decision point must justify its existence — defaults first, one primary action per screen, choices demoted to progressive disclosure (dev-uiux-design UX-LAZY-01 owns the gate).
• For text-heavy surfaces (landing, marketing, editorial, public service), apply typography wrapping defaults — see typography-wrapping.md. Dashboard table cells are excluded.

1. Component Identification

When the user describes UI in vague terms (e.g. "접히는 거", "팝업 같은 거"):

1. Recommend the best-fit component with reasoning: <Name> — <what it does, why it fits>
2. Confirm, then proceed

If the user already names a specific component, skip this step. Reference: component.gallery/components

For new React/Vue/Svelte/Next UI source files, prefer .tsx or typed component files when the repo supports TypeScript. Inherit dev TypeScript strict-compatibility rules. If frontend structure is unclear, read existing source-of-truth docs first, then document pages, components, routes, state stores, and build commands in the repo's existing docs before broad implementation.

1.5 Objective Gates vs Style Samples

Two different kinds of rules live in this skill (see dev §0.2):

• Objective UX gates (STRICT/DEFAULT) — accessibility baseline (§7, §11), state coverage (loading/empty/error/permission), keyboard operability, visible focus, contrast. Missing these are review findings.
• Style direction (STYLE_SAMPLE) — design direction intake (§2), aesthetics, density profiles, product personalities, preset tokens, and the concrete values in §4-§5 (palettes, font choices, pixel max-widths). These illustrate acceptable choices; they are NOT requirements, must not override an existing design system (Design System Detection stays MANDATORY), and must never be enforced as universal taste (UX-STYLE-01).

2. Design Direction Intake

When the user cannot articulate a clear design direction, load dev-uiux-design first — it owns intent discovery and direction selection. This section validates and implements the chosen direction; it does not choose independently.

Before coding, validate the design direction from dev-uiux-design (or a concrete brief):

• Purpose: What problem does this interface solve? Who uses it?
• Surface: Is this a working tool, dashboard, public service, AI workflow, game, landing page, or editorial surface?
• Tone: Confirm the direction. For product tools this often means quiet, dense, trustworthy, and fast rather than loud.
• Constraints: Framework, performance budget, accessibility requirements.
• Signature: What ONE visual signature will make this unforgettable? (the signature moment; supporting scroll reveals may exist alongside it per motion.md FE-MOTION-BUCKET-01)

When user intent is vague ("깔끔하게", "모던하게", "just make it look good"), read the dev-uiux-design skill and run the User Intent Discovery Protocol before making routing decisions. If the user cannot answer these questions, use the dev-uiux-design skill's structured preference elicitation flow. Offer product references ("Notion 느낌? Linear 느낌?") and visual comparisons.

Concept pass before code (pointer — canonical: dev-uiux-design §2.5 UX-CONCEPT-GEN-01): for C2+ expressive or brand-visible surfaces, load dev-uiux-design §2.5 before implementation. It owns direction discovery, concept branching (open direction: 5 distinct isms → lock one → refine; concrete direction: 3-5 contextual variants), synthesis, and direction lock. Resume here after DESIGN.md is locked.

Intentionality over intensity. Bold maximalism, refined minimalism, dense utility, and friendly consumer UI can all work when they match the domain.

3. Baseline Configuration

Adjust these dials based on what's being built. Present to user if unclear.

After Design Read, set dials per dev-uiux-design §2 Dial Setting.

Product density profile (D1-D8 in references/core/product-density.md) sets component class; VISUAL_DENSITY (1-10) sets spacing within that class. These are orthogonal axes.

Adapt dynamically based on user requests. Dashboard → density up. Portfolio → variance up. Data tool → motion down. Korean app/tool surfaces usually need higher density and clearer hierarchy, not oversized hero text.

4. Implementation

Read references/core/aesthetics.md for full guidelines. Summary:

• Typography: Use domain-appropriate typography. For Korean-first UIs, prioritize CJK-safe stacks before Latin display fonts. Apply text-wrap: balance on all headings AND short descriptors (hero subtitle, card description, caption — anything 1-3 lines). Use text-wrap: pretty only on body paragraphs (4+ lines). pretty has no effect on short text and will leave Korean orphans like "합니다." or "화." on a line alone. See typography-wrapping.md for full rules.

• Color: Max 1 accent. Use neutral bases (Zinc/Slate) with singular high-contrast accent — avoid purple-on-white. One-note means the ENTIRE page is dominated by variations of a single hue family. One accent color with neutral bases is correct, not one-note.

• Layout: Match the product surface. Avoid centered-card/hero patterns in repeated-use tools.

• Motion: See references/core/motion.md. One signature moment + a few supporting reveals > 10 scattered effects; landing-bucket floor/ceiling per FE-MOTION-BUCKET-01.

• Assets: Use screenshots, product images, diagrams, charts, illustrations, generated bitmaps, or soft 3D only when they add product meaning. Never ship a placeholder. Prefer real/generated image or video assets over CSS gradient washes. Read any design reference or captured screenshot back into context before matching it. Third-party captures follow reference-capture.md (analysis-only, provenance manifest).

  1. Probe: ima2 status → ima2 serve if down → recheck.
  2. Generate: ima2 gen with explicit long prompts; --ref for style anchors.
  3. Inspect: read every candidate image back into context.
  4. Synthesize: element ledger per FE-ASSET-SELECT-01.
  5. Iterate: ima2 edit for targeted fixes.
  6. Verify: browser screenshot of rendered result.

  Fallback: $imagegen only when ima2 is truly unavailable.

  ima2 supports multi-candidate generation (-n N, multimode, and independent CLI parallel; FE-ASSET-PARALLEL-01), prompt builder, session style sheets, and provider routing (GPT/Grok/Gemini; FE-ASSET-PROVIDER-01). Monitor parallel jobs with ima2 ps --json and cancel unwanted jobs with ima2 cancel <id>. For motion assets, use ima2 video under FE-MOTION-VIDEO-01. Prompts must specify subject, composition, palette, lighting, style, and aspect per asset-requirements.md.

  Concept mockups guide implementation and are not shipped; production assets require candidate inspection and selection; cutout assets additionally follow FE-ASSET-BG-01.

• Visual verification: after UI changes, exercise the flow per jaw-dev-testing §4.6 (TEST-CU-QA-01) — open the dev server in the Manager embedded browser, POST …/<targetId>/screenshot, then READ the returned PNG — instead of claiming visual correctness from code alone.

Cutout Asset Generation (FE-ASSET-BG-01 surface — STRICT)

Every cutout asset MUST follow references/core/asset-production.md § Asset Background Strategy; load the routed asset references before generation.

5. Anti-Slop Enforcement

Rule classes (dev §0.2): items below are DEFAULT — deviate with a stated reason; concrete values and palettes are STYLE_SAMPLE (§1.5); the emoji-as-UI-icon ban is the only STRICT item.

Read references/core/anti-slop.md for full rules. Key standards:

Award evidence does not repeal these rules. Use the context-gated calibrations in ../jaw-dev-uiux-design/references/compositional-patterns.md: an exception is valid only when the device expresses specific product, artifact, or narrative content and the surface remains accessible without the effect.

Hero discipline (FE-HERO-01)

• First viewport must fit: hero content leaves a hint of the next section on mobile and desktop.
• Keep hero copy to ~4 text elements max: headline, subhead, primary CTA, one proof/context line.
• Do not put trust strips, pricing teasers, feature bullets, or mini dashboards inside the hero.
• Logo walls belong below the hero, not as hero filler.
• Plan font scale with image/product scale so neither crushes the other.

Before delivery, run the second-order reflex test (FE-REFLEX-TEST-01, anti-slop.md) against both the obvious category default and its fashionable opposite. Audit composite convergence tells under FE-CONVERGENCE-01 (anti-slop.md): hairline border+shadow, icon-tile-above-heading, italic-serif-hero, hero-metric template, and other multi-element compositions.

• Treat unexamined default typography as a slop signal. Choose a domain-appropriate stack; Korean-first UI should use CJK-safe fonts and system fallbacks deliberately.
• Gradient budget (FE-GRADIENT-01): gradient soup is the 2026 #1 anti-slop signal; max 1 ambient gradient per viewport and no gradients on 3+ sibling cards — see anti-slop.md § Gradient Budget
• One-note theme ban (FE-ONENOTE-01): full-page single-hue dark washes (terminal green, cyber cyan, CRT amber) are the current dark-mode tell — see anti-slop.md § One-Note Theme Ban
• No self-describing meta copy (FE-METACOPY-01): UI text must explain the product/user job, never narrate the mockup, layout, responsive behavior, or agent process — see anti-slop.md § Self-Describing Meta Copy
• Use neutral or intentional color palettes — purple gradients on white are now the old tell; gradient overuse and one-note single-hue themes are the current tell
• Use asymmetric or purposeful layouts — centered-everything reads as template
• Vary card sizes, spans, and groupings — equal 3-card grids read as generic
• Bento composition (FE-BENTO-01): bento grids must read as one interlocking slab with aligned row edges, a dominant cell, content-weighted spans, and no orphan tail — see layout-discipline.md § Bento Composition
• Avoid oversized bold hero text inside tools, dashboards, admin, finance flows, and public services
• Hero composition (FE-HERO-SPLIT-01): never build a split hero (left bold headline + right boxed screenshot/mockup card) unless the user explicitly requests one — the product visual is the stage (full-width, background, or interactive demo), never a right-column card; paid-conversion LPs are the one context to propose it — see layout-discipline.md § Hero Composition Grammar
• Avoid asset-free UI: abstract blobs/gradients do not replace real visual evidence
• Avoid generic soft 3D icon packs; soft 3D must be semantic, brand-consistent, and restrained
• NEVER use emoji as UI visual elements (feature icons, card icons, section markers, buttons) — emoji in production UI is the #1 AI slop signal. Use SVG icons (Lucide/Phosphor/Heroicons). See anti-slop.md § Emoji Slop
• Warm beige/cream backgrounds with brass/clay accents are banned as defaults for premium-consumer briefs — see anti-slop.md § Premium-Consumer Palette Ban
• Layout monotony (same family repeated, 3+ zigzag sections, overused eyebrows) — see references/core/layout-discipline.md
• Color, shape, and theme must be locked per-page and audited before shipping — see references/core/consistency-locks.md
• Use off-black (#0a0a0a, #111) — pure #000000 lacks depth
• Responsive enforcement (DEFAULT): every multi-column section must declare its mobile/tablet collapse behavior — "it'll work at mobile" is not a plan. See responsive-viewport.md
• Page containment required: max-w-[1400px] mx-auto or equivalent wrapper. Content stretching to viewport edges on wide monitors is a layout bug
• Mobile is a different product: section composition, CTA placement, and interaction model change on mobile — it is NOT just "desktop stacked vertically." See mobile-ux.md
• Use realistic, specific names and brands in placeholder content
• Write original copy — avoid "Elevate", "Seamless", "Next-Gen" and similar clichés
• Treat uncontrolled heading line breaks (orphaned single word, no text-wrap, no max-width in ch) as a slop signal — see typography-wrapping.md
• Treat short descriptors (hero subtitle, card description, caption) using text-wrap: pretty instead of balance as a slop signal — pretty does nothing on 1-3 line text, especially Korean
• Treat Korean orphan fragments ("합니다.", "화.", "입니다." alone on a line) as a slop signal — always verify Korean text breaks at target viewports
• Treat generic stroke icons as brand logo substitutes as a slop signal — use actual brand SVGs from Simple Icons, SVGL, or press kits. See brand-asset-sourcing.md

Icon Implementation (FE-ICON-01, DEFAULT)

• Library route: pick one library from the Design Read and confirm the exact package and its license before installing. @phosphor-icons/react is a reasonable default; iconoir-react, @untitledui/icons, @hugeicons/react, and lucide-react are for when the read actually selects that family.
• Custom route: generate the approved artwork with whatever image generation you have, trace it to vector (vtracer), optimize the SVG (svgo), then convert to a component (svgr) if the framework needs one. Preserve an editable source asset, and inspect both the SVG and the rendered component before shipping — an SVG that looks right in isolation can still render wrong at icon sizes.
• Layer consistency: one library per icon layer. Do not mix one family's navigation icons with another's content icons. A separate custom or premium domain layer is allowed only when it is deliberately art-directed as a layer.
• Weight semantics: regular is the default state, fill indicates selected or active, and duotone is reserved for empty states or illustrative emphasis. Keep size, optical weight, color behavior, and accessible labels consistent across the layer.

Cutout Asset Generation (FE-ASSET-BG-01, STRICT)

Every cutout asset MUST follow references/core/asset-requirements.md § Asset Background Strategy. Read that section before generating one; a cutout produced without its background strategy is the asset most likely to ship with a visible matte edge or a background that fights the surface it lands on.

• When NO design brief exists, do not invent a generic default: apply the domain-gated no-brief kit owned by dev-uiux-design §1 UX-DEFAULT-ISM-01 and state the assumption

Do not ship these tells (FE-AI-TELL-01)

Enforce the complete AI-default tell catalogs in references/core/anti-slop.md and references/core/layout-discipline.md.

6. Performance Guardrails

Animate only transform and opacity; isolate perpetual animation, remove temporary will-change, reserve z-index for systemic layers. Keep grain/noise filters off scrolling containers. Centralize polling/subscriptions; clean up SSE/WebSocket on unmount. Never open unbounded per-component connections; prefer one multiplexed connection. For detailed budgets and browser connection limits, read references/core/performance-budget.md.

7. Accessibility Baseline

• Semantic HTML (<button>, <nav>, <main>)
• Keyboard navigation for all interactive elements
• WCAG AA minimum (4.5:1 normal text, 3:1 large text)
• Visible focus indicators (focus-visible:ring-2)
• prefers-reduced-motion support
• Skip link or equivalent bypass for repeated navigation
• Focus must not be hidden by sticky headers, sticky bottom bars, sheets, or overlays
• Icon-only buttons need accessible names (aria-label, visible text, or labelled-by)
• Charts, status messages, loading progress, and AI streaming states need screen-reader labels or live regions where appropriate
• Do not encode meaning by color alone

A11y polish (FE-A11Y-POLISH-01, DEFAULT)

The checks below are the ones a functional a11y pass passes and a careful reviewer still fails:

• CTA text fits on one line at target breakpoints; if it wraps, shorten the label or change the layout.
• Inputs need visible boundaries against their background in default, focus, error, and disabled states.
• Duplicate CTA intent on the same screen should merge, or differ clearly by outcome.
• Button contrast is checked during visual review, not left to palette intent.

The last one is the pattern: each of these is satisfiable in the token layer and still wrong on the rendered page, which is why they are a review item rather than a lint.

• Modals, menus, comboboxes, bottom sheets, and command palettes must have a complete keyboard path
• Stress-test Korean long labels and screen-reader names; clipped Hangul is a failure
• Pointer targets follow WCAG 2.2 AA target-size rules; 44×44px is a conservative product baseline, not the only legal minimum

A11y polish (FE-A11Y-POLISH-01)

• CTA text fits on one line at target breakpoints; if it wraps, shorten the label or change the layout.
• Inputs need visible boundaries against their background in default, focus, error, and disabled states.
• Duplicate CTA intent on the same screen should merge or clearly differ by outcome.
• Button contrast is checked during visual review, not left to palette intent.

8. React, Forms, and Accessibility

For React hooks, state ownership, performance, and Compiler, read references/stacks/react.md. Custom hooks: only for reusable behavior with explicit inputs, small outputs, honest dependencies, justified effects, correct cleanup. Do not hide server/router/form ownership inside generic hooks. For forms: follow repo stack and schema-validation conventions; expose field errors accessibly with role="alert". For widget keyboard paths, focus trapping, ARIA state, and screen-reader testing, enforce references/core/a11y-patterns.md. The objective accessibility baseline in §7 remains mandatory.

12. Frontend Platform Rules

Prefer project conventions; detect installed framework/version before changing configuration. Read references/stacks/react.md for React 19.2+ features, Compiler, Suspense, Effects, state. Read references/stacks/nextjs.md for Next.js 16 App Router, caching, Server Actions, RSC. Prefer native CSS (container queries, :has(), nesting, subgrid, View Transitions, dvh/svh/lvh) before JS observers. Do not introduce Webpack-era config unless the existing app is Webpack-bound. Never cache user/session data without an explicit user-scoped key.

React and Next.js Version Gates

• React 19.2 features such as <Activity> and useEffectEvent require version detection; use React Compiler only when the repo enables it and measurement justifies the change.
• In Next.js 16, Turbopack is the default and Cache Components replace the old PPR flag. Validate and authorize Server Actions, and never cache session data without a user-scoped key.
• Vite, SPA-only React, React Native Web, and client-only embeds do not support Next.js Server Component assumptions; preserve their client architecture.

Modern CSS and Build Tools

• Prefer container queries, :has(), subgrid, View Transitions with fallback, text-wrap, viewport units, logical properties, and shallow nesting before JS layout observers.
• Detect Vite 7 versus Vite 8 before editing config. Vite 8 uses Rolldown/Oxc by default and requires Node 20.19+ or 22.12+; do not add Rollup/esbuild-era bridges blindly.
• Record browser Baseline status and fallback needs for modern features used by the target audience.
• Prefer dev servers that expose browser/runtime diagnostics to the agent: Vite 8 console forwarding and Next.js 16 DevTools integration are useful before static speculation.

Design System Detection (MANDATORY)

Before inventing tokens or components, inspect package.json, existing token/theme files, and the brief for Material, Carbon, Fluent, GOV.UK, USWDS, shadcn/ui, or another governing system. Use and theme the installed official system instead of recreating it. For shadcn/ui, inspect local source plus components.json, aliases, tokens, and registry conventions; remove demo-only variants and never hallucinate components.

Classify state using the table below before adding a store, Effect, or cache.

State Classification

Before adding state, classify it:

Rules: Do not store derived state just to sync with Effect. Do not put server state in Zustand. Do not put URL-shareable state only in component state. Keep optimistic state reversible.

Before creating tokens, run Design System Detection (MANDATORY): check package.json for installed systems, existing tokens/themes, and the brief. Aesthetic honesty (FE-AESTHETIC-HONESTY-01): aesthetic directions are not official design systems. For shadcn/ui, inspect local components and follow components.json, aliases, tokens, and registry. AI-native interfaces must represent real states; never fake streaming, citations, or tool calls.

13. Error Boundaries

React Error Boundary pattern:

• Wrap each major section (not the entire app) in an Error Boundary
• Error boundary renders: friendly message + retry button + report link
• Log error to monitoring service (Sentry, etc.) in componentDidCatch
• Never show stack traces to end users

Error state hierarchy:

1. Field-level: inline validation message
2. Form-level: summary at top of form
3. Section-level: Error Boundary with retry
4. Page-level: error.tsx / error page
5. App-level: root Error Boundary → offline/crash page

15. Backend Contract & Security Alignment

Frontend does not operate in isolation. When consuming backend APIs or implementing security-sensitive UI:

15.1 Contract Ownership

When a frontend change touches API consumption:

1. Check if the response shape assumption still holds
2. If changed, update or add a contract test first (see dev-testing §3.5)
3. Align frontend mocks/fixtures with backend golden examples

15.2 Security Responsibilities

15.3 Testing Integration

• Playwright smoke tests validate rendered flows AFTER backend API + contract tests pass
• Frontend unit tests mock API responses using the same envelope shape defined in dev-backend §5
• When backend error codes change, frontend error-mapping tests must be updated

§16 Pre-Flight Checklist

Before shipping a production frontend surface, run through the full pre-flight checklist at references/core/preflight-full.md. It covers design/composition, responsive/mobile, states/behavior, Korean-first rules, SEO/theme/i18n, and performance/verification gates. Use it as the C-phase audit companion for frontend work at C2+.