Write Frontend

---
name: write-frontend
description: >
  Apply browser conventions to HTML, CSS, TypeScript, platform apps, uikit, Storybook, and browser
  libraries. Load for browser work; add framework, architecture, and test skills as needed.
---

# Frontend Conventions (common)

Load [develop-feature](../develop-feature/SKILL.md) for local drafting, developer discussion,
publication timing, test completion, and final cleanup. Run the affected app locally during a draft
as well as Storybook for rendered review; a component library can use its workbench. Explain the
flow, expected states, provisional behavior, and boundaries in language the developer can assess.

Apply this base layer to every browser-facing change. Read the target file, its nearest siblings,
the package manifest, TypeScript config, lint config, and public exports before editing. Preserve a
coherent local pattern unless it conflicts with a rule below or a current platform standard.

This skill owns generic implementation quality, not repository placement. In the A-Novel workspace,
use `write-platform` for terminal application shells and product policy, `write-design-system` for
uikit visual contracts, and nodelib for reusable non-visual client runtime or tooling configuration.
Load `write-svelte` for Svelte files, `write-frontend-tests` for tests or stories, and
`write-design-system` for tokens or reusable UI. Service REST clients under `pkg/js` also load
`write-js-package`.

Load `plan-ui-design` before deciding a new or materially changed flow, interaction pattern,
information hierarchy, component family, or visual language. This skill owns implementation quality;
`plan-ui-design` owns the human-facing contract that implementation must preserve.

**Rendered-UI hard gate:** Start Storybook with `BROWSER=none` and `--no-open`, inspect the exact
changed story in the integrated browser, keep the server live through review, and put its freshly
verified actual Markdown link in the completion report beside the PR and task or issue links. Send
screenshots of the changed screens in the conversation as well. Never put a local-only Storybook URL
in a GitHub PR body. A screenshot or placeholder never substitutes for the live link.

Use this authority order when guidance conflicts:

1. Repository contracts and supported-browser policy.
2. Normative web standards and WCAG.
3. Official framework or tool documentation for the installed version.
4. Maintained FOSS guidance from standards bodies and established organizations.
5. Local convention and personal preference.

Read [references/standards.md](references/standards.md) before choosing a browser API, accessibility
pattern, security boundary, design-token model, or unfamiliar framework feature. Verify versioned
APIs against current official documentation rather than relying on memory.

## Validation by stage

During drafting and issue review, run the app, inspect changed stories, and use focused checks.
Add only tests needed to validate the draft. After issue scope approval, complete relevant coverage
with `write-frontend-tests`, including affected Playwright journeys and screenshot comparisons.
Perform the final cleanup and rerun affected checks before marking ready.

Use repository scripts as declared for final validation; do not invent parallel commands:

```bash
pnpm format                         # write formatting when the repo provides it
pnpm lint                           # formatting check + types + ESLint
a-novel test --type=pnpm -y         # all pnpm tests discovered by the workspace CLI
a-novel build --type=pnpm -y        # production/package builds
```

Run the narrowest package or test target while iterating, then run all applicable gates before the
change is ready. Load `use-a-novel-cli` whenever running test or build commands. A production build
is mandatory for routing, SSR, package-export, bundler, or environment-boundary changes.

## Live UI review — mandatory handoff

Treat Storybook as a mandatory review surface for every change that affects rendered UI. Do not
declare UI work complete from source inspection, unit tests, screenshots, or a static build alone.

The handoff contract is non-negotiable:

1. Add or update the smallest story or docs page that renders the changed UI and its meaningful
   states. If the repository has no usable Storybook, establish it within the agreed scope or report
   the missing review surface as a blocker.
2. Start the repository's Storybook command with `BROWSER=none` and `--no-open`. The process must
   not launch an external browser tab and must stay live for the operator unless they ask to stop it.
3. Wait for readiness, discover the actual listening URL and port, and verify that the exact changed
   story or docs route responds from where the developer opens it. Behind WSL or another VM boundary,
   bind IPv4 with `--host 0.0.0.0`: an IPv6-only listener is not forwarded to the host's `127.0.0.1`.
4. Open that route in the integrated browser and inspect it. Prefer it over the Storybook root when
   handing off a specific component.
5. Keep localhost and other local-only Storybook links out of GitHub PR descriptions. They are
   session-scoped review surfaces, not durable PR metadata.
6. In each draft or final handoff of rendered UI, include direct app and Storybook routes as
   applicable, with steps to try, expected results, and limits. Include PR and issue links once they
   exist; creating them is not a prerequisite to local review. Provide at least one direct
   Storybook link. Use a clickable inline link such as
   `[Button — Storybook](http://127.0.0.1:6006/?path=/docs/button--docs)`, substituting the actual live
   URL and route. Repeat it in any later report that hands completed UI work back; an earlier report
   does not satisfy the current handoff.
7. Send screenshots of every new or changed screen and state in the conversation, with the host's
   file-sharing tool, at the reviewed viewports and in each supported locale. The developer may be
   unable to reach the local server, from another device or across a VM's network boundary, so the
   screenshots are their first look. Send them again when the screens change.
8. Re-resolve every linked route immediately before sending the completion report. If the server
   stopped or changed, restart it and verify the new link before reporting completion.

Screenshots accompany the live link; a screenshot, placeholder such as “visual preview,” stale URL,
or instruction to find an earlier link does not replace it.

## Dependencies

- Load `choose-dependency` before adding, replacing, or evaluating a package.
- Prefer the web platform, an existing workspace package, or an existing dependency in that order.
- Before implementing reusable code in a terminal app, route visual contracts to uikit and
  framework-agnostic runtime or shared build/lint/test/localization configuration to nodelib.
- Require an explicit reason for every runtime dependency: capability, maintenance owner, release
  health, browser cost, license, security posture, and why the current stack cannot provide it.
- Prefer standards-body or established-organization ownership. Do not adopt an unmaintained package
  or a narrow personal utility for code that is straightforward to own.
- Import the narrowest documented public entry point. Never deep-import private package files.
- Keep browser bundles free of Node-only modules and server-only transitive dependencies.

## TypeScript and modules

- Keep `strict` enabled. Do not introduce `any`, disable strict checks, or hide errors with broad
  casts. Use `unknown`, narrow it, and validate untrusted data at the boundary.
- Model impossible states out with discriminated unions. Represent absence deliberately; do not use
  empty strings, magic numbers, or non-null assertions as state management.
- Prefer inference inside a function and explicit types at exported, callback, network, storage, and
  component boundaries. Use `satisfies` when checking a value without widening it.
- Use `type` imports for type-only dependencies and ES modules exclusively.
- Keep domain data serializable unless the boundary explicitly supports richer values.
- Treat API, URL, storage, message, and DOM data as untrusted at runtime even when TypeScript types it.
- Catch `unknown`; preserve the original cause when translating errors. Never silently discard a
  rejected promise.
- Arrays and objects travel by reference, and `sort`, `reverse`, `splice` and `fill` mutate in place.
  On data the function does not own, use `toSorted`, `toReversed`, `toSpliced` and `with`, and copy
  with `structuredClone`, never a `JSON.parse(JSON.stringify(…))` round trip.
- Keep a declaration out of the statement it feeds. A long literal inside an `if`, `switch`, loop
  header or call argument becomes a named constant declared just before the statement. A
  configuration object passed to its factory, as in `defineConfig({…})`, keeps its idiomatic form.
- Pipes are idiomatic, but a callback longer than three lines passed to `map`, `filter`, `reduce`,
  `flatMap`, `forEach`, `find`, `some`, `every`, `sort`, `then`, `catch` or a similar method becomes
  a named function. Declare it outside the enclosing function and pass what it uses as parameters,
  which makes its captures explicit.

## Naming and files

- Name Svelte components in PascalCase and plain TypeScript/CSS modules in lowercase camelCase or a
  single lowercase word, matching the surrounding package.
- Mirror source names in tests and stories: `Button.svelte.test.ts`, `Button.stories.svelte`, and
  `retry.test.ts`. Follow SvelteKit route filenames exactly where its router owns the convention.
- Name exported types and components in PascalCase; functions, values, and props in camelCase; and
  true constants in SCREAMING_SNAKE_CASE only when the package already uses that distinction.
- Give booleans a state or capability name (`disabled`, `hasError`, `canRetry`) and event callbacks
  the behavior they represent (`onSubmit`, `onDismiss`). Avoid generic `data`, `item`, or `handler`
  when a domain name is available.

## Components and controllers

- UI components are pure presentation. Reactivity that changes rendered state belongs to an injected
  controller; components must not create hidden state owners or mutate controller state.
  Render semantic HTML and accessibility state, translate native events
  into semantic requests, and own only DOM mechanics such as element references, focus movement,
  measurements, and transient typeahead bookkeeping.
- Put meaningful rendered state and its transition rules in a pure controller with no DOM access,
  component rendering, route imports, storage, session, or network calls. A controller may use the
  framework reactive primitive in a `.svelte.ts` module.
- Let a stateful component accept at most one controller. Do not split its contract across bindable
  state props, change callbacks, and a controller; stateless components need no controller.
- Expose semantic controller methods (`open`, `close`, `select`, `setChecked`) rather than generic
  setters. The component reports intent; the controller may accept, transform, or reject it.
- Export the controller contract and a configurable default factory. Callers may supply another
  implementation that satisfies the same contract, including fixed-state Storybook controllers.
- Keep controllers mockable and composable through structural contracts: inject collaborators, compose
  child controllers, and derive views of shared state without creating a second state owner. A plain
  typed object with fixed state and no-op transitions must be a valid replacement.
- Build every rendered state from static values. With fixed props and a fixed-state controller, a
  story reaches each state of the matrix, edge cases included, with no timer, fetch, `play` function
  or user event. Only DOM mechanics the user drives stay outside, such as focus, the caret, typing in
  progress and scroll. A state a story cannot reach that way is hidden state: move it into the
  controller.
- Unit-test controller transitions without rendering. Test the component boundary for DOM semantics,
  accessibility behavior, and rejected transitions.

## HTML and interaction

- Use the native element with the required behavior: `button` for actions, `a` for navigation,
  labels and controls for forms, and landmarks/headings for document structure.
- Add ARIA only when native HTML cannot express the contract. A role is a promise to implement its
  keyboard interaction, focus behavior, state, and accessible name.
- Set `type="button"` on non-submit buttons. Keep form submission, validation, autofill, and error
  association available without pointer input.
- Preserve logical source order and normal tab order. Never use a positive `tabindex`.
- Expose a visible focus indicator. Do not remove outlines without an equal or stronger replacement.
- Treat persistent state as stronger than transient input. Selected, checked, expanded, invalid,
  loading, and disabled meaning must remain clear while a control is hovered, active, or focused.
- For reusable content-bearing components, prefer the framework's native composition primitive over
  a string-only label prop when text, markup, icons, or nested components are semantically safe.
- Support keyboard, pointer, touch, zoom, reflow, text spacing, and assistive technology. Do not make
  color, hover, drag, or animation the only way to understand or operate a control.
- Provide useful alternative text and accessible names. Decorative media stays silent.
- Set document and changed-passage language correctly. Use logical CSS properties so RTL does not
  require a second component implementation.
- Treat WCAG 2.2 AA as the minimum acceptance baseline, not a guarantee supplied by automation.

## CSS and responsive layout

- Build coherence into the code, not into a sequence of visual corrections. Equivalent UI roles
  and states must reuse the same shared components, variants, tokens, and constants across screens
  and breakpoints. When they drift, trace the owning styles and remove duplicated definitions or
  compensating overrides before adding new CSS. Fix reusable behavior in uikit; keep only genuine
  application composition and layout differences local. Do not recreate a shared element just to
  tailor its appearance, or invent an abstraction for unrelated roles that merely look similar.
- Responsive rules normally change geometry, not a control's visual identity: preserve shared
  foreground, surface, opacity, typography, and interaction-state rules unless the product contract
  explicitly requires a difference. Verify the shared implementation on each actual backdrop;
  matching token names alone do not prove matching rendered colors through transparency layers.
- Prefer normal flow, Grid, Flexbox, logical properties, and container/media queries over measured
  JavaScript layout. Use feature queries for optional enhancements.
- Start from the smallest supported viewport and let content determine breakpoints. Avoid device-name
  breakpoints and user-agent sniffing.
- Use design tokens for product colors, spacing, type, radii, borders, elevation, and motion. A raw
  value is acceptable only for a local algorithmic constant with no design meaning.
- Use relative units for type and layout. Keep line height unitless. Reserve pixels for genuinely
  device-bound details such as a one-device-pixel hairline when the token contract calls for it.
- Keep selectors shallow and component-scoped. Avoid `!important`; fix cascade ownership instead.
- Preserve content at 200% text zoom and 400% page zoom/reflow. Do not clip user content to force a
  mockup height.
- Respect `prefers-reduced-motion`, forced colors, increased contrast where supported, and user font
  settings. Motion must not be required to understand state.
- Animate compositor-friendly properties when possible and never add animation without a purpose.

## State, data, and browser boundaries

- Give each piece of state one owner. Derive values instead of synchronizing duplicate state.
- Put shareable navigation state in the URL. Keep ephemeral interaction state local to the smallest
  component that owns it.
- Represent loading, empty, error, stale, and success states explicitly. Preserve useful content
  during refresh when the product contract allows it.
- Cancel or supersede obsolete asynchronous work. Guard against out-of-order responses.
- Keep rendering pure. Synchronize with external systems in framework lifecycle primitives, not in
  getters, templates, or module import side effects.
- Keep server-only code, environment variables, credentials, and privileged API calls out of browser
  bundles. Assume every shipped byte and source map is public.
- Use progressive enhancement for navigation and forms when the framework supports it. A network or
  JavaScript failure should degrade intentionally rather than strand the user.

## Localization language register

- Use the formal address form for static text when a language distinguishes registers (`vous` in French, `usted` in Spanish).
- Use the language’s conventional action-label form for buttons, links, and other controls. A control whose action is about the reader (signing up, signing in or out, their account and its details) speaks in the reader’s voice: `M’inscrire`, `Changer mon mot de passe`. A control that works the interface keeps the plain form, even on the reader’s data: `Afficher le mot de passe`. Other text names the reader’s things as theirs and says who acts, never an impersonal `Impossible de…`.
- Put no space before a colon in French (`Fin prévue:`), against standard French typography: a
  product ruling, enforced by uikit's catalog test. It applies to every catalog, page title and test
  expectation.
- Apply the same distinction to accessible names and Storybook states.
- Never list the options a reader can see, change or pick, as in "your username and picture": name
  the whole, as "this information". A new option then needs no copy change, and nothing goes stale.

## Security and privacy

- Never place secrets or long-lived credentials in client code, browser storage, logs, analytics, or
  error messages. Follow the repository authentication model.
- Do not render untrusted HTML. Use text interpolation; if rich HTML is a real product requirement,
  choose and configure a maintained sanitizer through `choose-dependency` and test bypass cases.
- Use safe URL construction and validate protocols before navigation. Do not concatenate executable
  markup, CSS, script, or query fragments from untrusted input.
- Collect and persist only required data. Do not add analytics, remote fonts, third-party scripts,
  beacons, or cross-origin calls without explicit product and security approval.
- Preserve CSP compatibility: avoid inline script generation, `eval`, and undocumented third-party
  origins.

## Performance and compatibility

- Set an explicit browser baseline in project configuration. Use feature detection and progressive
  enhancement; add a polyfill only after measuring need and bundle cost.
- Prefer semantic markup and CSS over JavaScript. Lazy-load non-critical routes and heavy features,
  not primary content or interaction affordances.
- Reserve media dimensions, serve responsive assets, and avoid layout thrashing. Batch DOM reads and
  writes only after measurement proves imperative layout is necessary.
- Measure before optimizing. Track user-facing latency and Core Web Vitals for applications; do not
  trade correctness or accessibility for an unmeasured micro-optimization.
- Handle offline, timeout, retry, and partial-response behavior at the owning boundary. Never retry a
  non-idempotent operation invisibly.
- Apply the shared traps in
  [prefer-small-solutions](../prefer-small-solutions/SKILL.md#keep-simple-code-fast). JavaScript
  adds these, in the browser and on the server:
  - Deep recursion throws `RangeError` and keeps every enclosing closure alive. Walk trees shaped by
    data with an explicit stack.
  - An async function that awaits a call to itself, such as a polling `return poll()`, chains one
    pending promise per turn and keeps them all. Loop with `while` and `await` instead.
  - Give every `addEventListener`, `setInterval`, observer, and subscription a teardown at the same
    ownership level. Prefer passing an `AbortSignal` as `{ signal }` so one abort removes them all.
  - Create `Intl` formatters, `RegExp` objects, and collators once per locale or module, never per
    call, item, or render.
  - Keep server module state immutable or bounded. Every SSR request shares it, so a per-user entry
    is a leak and a privacy defect.
  - On the server, read or cancel every `fetch` response body, error statuses included:
    `await response.body?.cancel()` before an early `return` or `throw`. Node's undici returns the
    connection to its pool only once the body settles.

## Completion checklist

- Semantic and keyboard behavior works without a mouse.
- Focus, zoom/reflow, reduced motion, forced colors, long content, localization, and RTL were
  considered in proportion to the change.
- Persistent states remain stable under transient interactions, and reusable content APIs compose
  naturally without sacrificing native semantics.
- Trust boundaries validate runtime data and do not expose secrets.
- Loading, empty, error, and success paths are intentional.
- `write-frontend-tests` covers changed behavior.
- Storybook is running, the changed UI was inspected there, and a freshly verified direct local link
  is in the completion report beside the PR and task or issue links, never in the PR body.
- Format, lint, pnpm tests, and production build pass.