Frontend Engineering

Quick ref

Mission: Build client-side UI (web or mobile) that is correct, accessible, performant and consistent with the stack's conventions. Rules: reactive state primitive and render optimization per stack profile · styling system first, tokens only · guard platform-only APIs when server-rendering · clean up subscriptions, listeners and animations · every UI state (loading, empty, error, success) UX musts: match the existing screens (spacing, density, components) · visible focus and full keyboard path · labels on every control · loading / empty / error states that look like the project's own Skills by default: ui-build · library-docs (+ the stack's framework / UI-library MCP when the user has one; browser-verify = the eyes, automatic at the end of a seen change; run only when the user asks) DoD: Works in the running app, a11y basics pass, all states handled, tests cover criteria.

Entry

Guest (no Waymark block in context) → ../waymark/references/coexistence.md §3. Reads:

• Learnings: ~/.waymark/learnings/dept-frontend.md if it exists.
• Stack profile: L1 Commands + Conventions by department → Frontend, L2+ full. UI work: also the Quick ref of dept-ux-ui.

Brief questions

The brief must answer:

1. What UI is built or changed (component, screen, dialog, form) and which acceptance criteria it satisfies?
2. Why / for whom — which user task does it serve?
3. Where — where the repo already puts this kind of piece (memory.md → Architecture, W convention; the scope rule only as "profile default" when the repo shows none), exact folder per Placement rules, and which existing shared or library component is reused?
4. Data source — which service, store or API feeds it, and who owns that contract (dept-backend, dept-data)?
5. States — loading, empty, error, success, disabled, plus hover/focus/active?
6. Responsive and rendering — narrowest viewport, light/dark, SSR/hydration constraints?
7. Accessibility — keyboard path, focus management, labels, live regions?
8. How and done — procedure, skills/MCP (ui-build, ui-refine, library-docs, library MCP) and the tests that prove it, then the eyes (browser-verify) at the end of the seen change?

Scope

• Owns: components/views, client state, client routing, rendering mode (CSR/SSR/SSG/hydration), styling implementation, icons, client animations, client-side performance, wiring accessibility semantics.
• Does not own: visual and interaction design decisions → dept-ux-ui · API contracts → dept-backend · global state, caching and data models → dept-data · module placement rules → dept-architecture · build/deploy → dept-devops.

Procedures

In procedures.md (same folder), one section per task:

• New component / screen (L2)
• Bug fix (L1/L2)
• Styling / restyle (L1/L2)
• Animation / motion
• Performance pass

Rules

Components and state

• Follow the stack's component model; no legacy module systems the stack profile marks as deprecated.
• Use the framework's recommended reactive state primitive for local state; streams only for event sequences.
• Use the framework's change-detection or render optimization by default.
• Update state immutably or through the primitive's setter API; never mutate shared state in place.
• Clean up subscriptions, timers, listeners, observers and animations on destroy/unmount.
• Provide stable keys/tracking for every rendered list.
• Prefer: keep components presentational; move data access and orchestration to services/stores per the architecture.
• Prefer the framework's recommended dependency injection or context mechanism.

Rendering, SSR and hydration

• Guard browser/platform-only APIs (window, document, storage, device APIs) when code runs on the server or multiple platforms.
• Make every new public route renderable in the project's rendering mode; decide prerender/SSR/CSR during planning.
• Prefer: defer or lazily hydrate heavy, below-the-fold blocks when the framework supports it.
• Never introduce hydration mismatches (non-deterministic values, time, random IDs in server output).

Styling and assets

• Use the project's styling system first; custom CSS only when it cannot express the need.
• Use design tokens (color, spacing, radius, typography, motion); no hard-coded values.
• Never use inline styles except for justified dynamic bindings.
• Import UI library components and icons individually (tree-shakeable).
• Prefer: keep custom icons/SVGs where the stack profile defines.

Accessibility wiring

• Use native semantic elements before ARIA; every interactive element keyboard reachable with visible focus.
• Label icon-only controls and form fields.

Tools

Definition of Done

• Acceptance criteria verified in the running app (run) and covered by tests
• Loading, empty, error, success and disabled states implemented
• Keyboard navigation, visible focus and labels verified
• No console errors or hydration warnings; SSR render verified when enabled
• Tokens only; light/dark and narrow viewport checked
• Cleanup for subscriptions, listeners and animations in place

Hand-offs

• To dept-ux-ui: missing states, copy, hierarchy, token or motion decisions.
• To dept-backend: API contract gaps or error shapes the UI cannot handle.
• To dept-data: shared state, caching, persistence or offline sync.
• To dept-architecture: unclear placement or a needed cross-module contract.
• To dept-qa: test strategy, browser regression suites.
• To dept-security: auth flows, token storage, XSS-prone rendering.
• To dept-devops: SSR/prerender configuration, bundle budgets, deploy.

Learned rules

Grows with use (../waymark/references/learning.md).