goberomsu/craft-skills/principle-frontend

principle-frontend

Frontend structure is correct only relative to the incumbent framework, rendering model, product boundaries, and styling system. Establish those facts first, then keep framework mechanics in the shell, product behavior in cohesive slices, and shared code behind narrow supported APIs.

Principle references

• experience-first chooses the user's result over implementation convenience.

Governing principles

1. Preserve the incumbent framework, router, package manager, styling system, and state tools unless migration is separately approved.
2. Let the framework shell own runtime mechanics; let routes, features, and domains own product behavior.
3. Evaluate dependency legality before public API access; a barrel never legalizes an invalid import.
4. Promote reuse only after real consumers share semantics and a reason to change.
5. Measure a production baseline and candidate with the same method; never claim an unobserved optimization.

Runtime fact verification

Before relying on mutable framework, CLI, CSS-tool, or bundler behavior, inspect package.json, the authoritative lockfile, framework config, entrypoints, router mode, and installed styling/state tools. Follow the evidence contract in Requirements. A matching-version repository contract or reproducible local result overrides generic guidance. Leave unresolved capabilities unknown and preserve incumbent behavior.

Phase 0 — classify before changing

1. Classify the repository:

1. Classify the work:

1. Read only the references touched by the request. A rendering-architecture change reads architectures.md; a CSS-only correction does not load every reference.

Shell, slice, and promotion rules

These are logical owners, not mandatory folder names. Map them onto a coherent incumbent route-colocated, module-based, type-based, feature-based, or FSD structure. Introducing features/, entities/, or shared/ into a different incumbent convention is a separately approved migration, not a feature-edit default.

Keep code route- or feature-private first. Promote it only when multiple real consumers share semantics and a reason to change, then expose the smallest environment-safe public API and remove obsolete deep paths in the same change. Exact import and promotion rules live in references/folders.md.

Design judgment handoff

Call design only when work changes what users perceive, understand, decide, or can accomplish, or changes reusable visual/interaction language, tokens, primitives, cross-state/cross-viewport presentation, or accessibility experience. Apply experience-first when product, UX, or feature-scope tradeoffs arise. design owns DESIGN.md and the design judgment; principle-frontend implements approved design decisions. Keep rendering architecture, established-system implementation, faithful use of existing primitives, small fixes, CSS regressions, state placement, components, folders, and API boundaries within principle-frontend.

Requirements

• Node.js for project-local tooling. Probe with node --version; use the Node range supported by the detected framework version.
• Inspect dependencies and package manager without mutating them:

``bash node -e "const p=require('./package.json'); console.log(JSON.stringify({packageManager:p.packageManager,dependencies:p.dependencies,devDependencies:p.devDependencies},null,2))" for f in package-lock.json npm-shrinkwrap.json pnpm-lock.yaml yarn.lock bun.lock bun.lockb; do test -f "$f" && printf '%s\n' "$f"; done ``

• Use one authoritative lockfile. If multiple lockfiles exist, resolve ownership before an install or version claim.
• For every mutable React, Next.js, Vite, CSS-tool, router, or state capability, record: detected version/probe, official source, support boundary, and the release/update condition that requires re-review. Use a versioned official page, release tag, commit permalink, matching local types, or reproducible behavior for version-sensitive claims. Treat main, canary, and latest-branch pages as discovery sources, not proof of installed behavior.
• Official discovery sources: React, Next.js, Vite, Vue, Svelte, and Astro.
• Add a dependency only after the platform, framework, and incumbent stack cannot meet a concrete requirement. Record maintenance, bundle/runtime, SSR/RSC, security/license, and lockfile consequences. Do not add a router, global store, CSS framework, component kit, or analyzer by default.

API boundary

Centralize the API base, path/version prefix, proxy, and BFF boundary once per app. React/Vite apps use VITE_* environment values plus one API client; components call slice APIs, not hardcoded hosts. Next apps preserve the incumbent server-fetch, Route Handler, Server Action, or rewrite boundary. Public HTTP contracts belong to api; service architecture belongs to principle-backend.

Anti-patterns

• Framework shell contains checkout/catalog/user business logic → move behavior to its route or slice and keep the shell as composition.
• Root components/, hooks/, types/, or utils/ becomes the primary product architecture → colocate by capability or retain a separately documented small-app convention (`folders.md`).
• Upward, forbidden peer-slice, or deep internal import → fix dependency direction first, then import a narrow public API (`folders.md`).
• First similar implementation moves to shared → keep it local until semantics, consumers, ownership, and regression coverage justify promotion (`folders.md`).
• Primitive knows routing, fetching, authorization, or analytics; component API grows boolean matrices → restore a semantic reusable contract (`components.md`).
• Derived data, URL state, or server data is mirrored through effects/global stores → return it to its single owner (`state.md`).
• Global selectors, duplicated tokens, competing styling systems, or !important escalation spread across features → restore scoped ownership and the incumbent cascade (`css.md`).
• Version-blind install/upgrade advice → inspect the manifest, lockfile, and matching-version evidence first.
• Memoization, chunking, critical CSS, preload, or client-boundary changes lack a production baseline → measure before and after or make no optimization claim.

Verification

• [ ] Incumbent framework, router, package manager, lockfile, styling/state tools, and relevant versions were recorded.
• [ ] The framework shell contains runtime mechanics, not product behavior; route and slice ownership is explicit.
• [ ] Dependency legality, public APIs, server/client graph safety, and obsolete-path removal were checked.
• [ ] Component semantics, keyboard/focus behavior, variants, and controlled/uncontrolled ownership were tested where applicable.
• [ ] State refresh, back/forward navigation, mutation invalidation, serialization, and hydration were checked where applicable.
• [ ] CSS computed states, responsive/forced-colors/reduced-motion behavior, visual stability, and route delivery were checked where applicable.
• [ ] Production measurements use the same collection method for baseline and candidate and record source, delta, project threshold, and interpretation. Mark unavailable consumer telemetry N/A; never fabricate it.
• [ ] Visual work captures relevant states and viewports after the final edit; diff numbers direct review attention but do not decide correctness alone.
• [ ] design was called only for material visual/UX judgment; implementation stayed in principle-frontend, and DESIGN.md ownership stayed in design.