设计与 UI
frontend-standards
React renderer standards — ports & adapters (service hooks), design tokens, motion tokens, @ajh/ui primitives, i18n, feature isolation, React Query, a11y. Load for changes under apps/desktop/src/renderer/**.
saeedkolivand · 已有 AI 审核记录
安装与使用
运行命令前先阅读来源与依赖说明。复制命令不会自动安装或执行。
npx skills add saeedkolivand/ai-job-hunter-app --skill frontend-standards技能说明
name: frontend-standards description: React renderer standards — ports & adapters (service hooks), design tokens, motion tokens, @ajh/ui primitives, i18n, feature isolation, React Query, a11y. Load for changes under apps/desktop/src/renderer/**.
Frontend standards (mostly ESLint-enforced)
Authoritative: docs/DESIGN_SYSTEM.md, docs/PATTERNS.md.
Ports & adapters (HIGH if violated)
- No
window.api.*infeatures/,routes/,components/— use service hooks fromrenderer/services/(React Query). ESLint errors on direct access. - Data fetching — React Query via service hooks only; no
useState + useEffectfor remote data.
React Query & async mutations (HIGH on correctness)
- Invalidation must match —
invalidateQueries({ queryKey })is a prefix match; a key factory that appends a trailingundefined/optional segment (keys.x.y()→['x','y',undefined]) will not match the typed queries (['x','y','viewed']). Fix it with the correct key: the shorter prefix (['x','y']), or a deliberatepredicate— noteexact: truedoes not fix it (an exact match on the wrong shape['x','y',undefined]still misses['x','y','viewed']). After a mutation, confirm the key you invalidate hits the queries that render the affected UI (#486: shipped this twice → stale viewed/saved badges). - Mutations — never show success / apply optimistic state / emit tracking events before the mutation resolves. Two cases: (a) awaited —
await mutateAsync(), then run the success effects, intry/catch; (b) detached (void/fire-and-forget) — attach a.catchsurfacing a fixed@ajh/translationserror key (never rawerr.message) and put the success effects in.then, not on the line after the call. - Nullable at the IPC boundary — guard a contract-optional/
nullvalue (a field a command may return absent) before string/array ops (.toLowerCase()/[0]/.split()).
Design system
- Tokens —
text-brand/bg-brand/border-brand/ring-brand; CSS varsvar(--color-brand). No[#RRGGBB]in className. - Motion —
import { transition } from '@ajh/ui'(.fast/.normal/.relaxed/.slow/.spring/.modal/.overlay); no inline{ duration, ease }. - Primitives —
@ajh/ui(Button,Input,TextArea,SelectDropdown,ModalShell,GlassCard,EmptyState, …). No raw<button>/<select>/<textarea>(exception:<input type="range|file|checkbox|radio|hidden">). - Imports — import
@ajh/uidirectly, not@/components/ui/*(exceptUpdateBanner).
i18n (HIGH if user-facing text is unwrapped)
Import useTranslation / TFunction from @ajh/translations, never react-i18next directly (the renderer init shim is @/i18n). All user-facing strings localized.
Accessibility (WCAG 2.2 AA floor — non-negotiable; the design-audit recurring gaps)
- Visible focus — every interactive element has a
:focus-visiblering (≥2px,outline-offset, visible against its bg). NEVER strip native focus withall: unset/border: none/background: nonewithout replacing it; a focusable custom widget needs more than a stroke/color shift. - Reduced motion — gate every animation/transition behind
@media (prefers-reduced-motion: reduce); a blanket* { animation: none }must NOT also kill focus-visible transitions. Reveal-on-scroll under reduce: drop the translate (no positional jump), keep opacity. - Contrast — meet AA (4.5:1 normal, 3:1 for ≥24px/bold). Muted text on light/"paper" backgrounds is the usual failure (the audit found ≈3.3–3.8:1) — darken the muted token, don't ship it.
- Real controls — prefer an
@ajh/uiprimitive (Button/Switch/…) over a hand-rolled control; raw<button>is banned in the renderer (see Primitives). If a click handler must live on a<div>/<span>, it needsrole="button"+ ReacttabIndex={0}+ anonKeyDownEnter/Space handler. Icon-only controls needaria-label(not justtitle); toggle/filter/segmented controls needaria-pressed. - Dialogs/overlays — a custom modal needs
role="dialog"/"alertdialog"+aria-modal="true"+aria-labelledby/-describedby+ focus management/trap; transient banners getrole="status"+aria-live. - SVG — informative SVG:
role="img"+aria-labelon the root, no conflicting roles on children; decorative SVGaria-hidden="true". A focusable SVG node needs a real visible focus indicator. - aria reference guards —
aria-controls/aria-*id references use the same render guard as the element they point to (no reference to never-rendered DOM); Enter/Space activation gates on the same enable/disable predicate as the click.
Structure
features/*own one route — never import across feature dirs.- 3+ states → a state machine in
lib/machines/viauseMachine. - File placement per
CLAUDE.md§9.
External standards & best-practices (verified 2026-06-19)
React 19 + React Compiler 1.0 GA (2025-10-07). WCAG 2.2 AA is the only a11y target (3.0 is a 2026 Working Draft — not yet). Core Web Vitals triad unchanged: LCP / INP / CLS.
- React 19 — Actions/
useActionState/useOptimisticfor async transitions;use(resource)reads a Promise/Context (suspends);refis a plain prop (forwardRefdeprecated). https://react.dev/blog/2024/12/05/react-19 - You Might Not Need an Effect — NO effect for: deriving data for render (compute in body /
useMemo), resetting state on prop change (usekey), or event-driven side effects (put in the handler). Effect only to sync with an external system. Test: "because shown" → effect; "because user did X" → handler. https://react.dev/learn/you-might-not-need-an-effect - React Compiler 1.0 — build-time auto-memoization;
useMemo/useCallback/memobecome measured escape hatches, not defaults; requires Rules-of-React (run the ESLint plugin). https://react.dev/blog/2025/10/07/react-compiler-1 - WCAG 2.2 AA most-relevant SC for a keybo