# Web apps

Default to a light server-rendered stack unless the product is clearly
frontend-heavy. If a page can remain a form and a template, keep it light.

## Default posture

- Use semantic HTML forms and links before client-side JavaScript.
- Use plain CSS with semantic variables for modest interfaces.
- Add a small frontend toolchain only when formatting, typechecking, bundling, or
  component complexity earns it.
- Use existing package managers and lockfiles. Ask before introducing a new one.

This is the default for admin panels, dashboards, release trackers, internal
tools, and server-rendered apps with modest interaction.

## CSS and accessibility

- Use semantic HTML and real form controls.
- Include viewport and colour-scheme metadata.
- Use CSS custom properties as semantic design tokens. OKLCH is preferred for
  colour palettes when browser support is acceptable.
- Support dark mode by overriding semantic tokens under `prefers-color-scheme`.
- Use spacing, radius, type, and measure scales instead of one-off values.
- Prefer simple responsive layouts with CSS grid/flex.
- Use accessible fonts when bundling fonts; include licence metadata when the
  project is REUSE-compliant.
- Do not use ARIA to compensate for avoidable non-semantic markup.

## Security

- Treat form/query values as untrusted.
- Use a sanitizer when rendering user-provided HTML or Markdown-derived HTML.
- Keep auth/session logic in a domain package; handlers should not duplicate
  password or token handling.

## Escalate only when needed

Escalate to a frontend-heavy stack only when the UI needs rich local state,
complex component composition, desktop integration, drag/drop, long-running event
streams, or substantial client-side interaction.

## Go path

For Go web apps or Wails frontends, read [golang/index.md](golang/index.md)
first and follow its web or Wails chain. The Go path covers `net/http`,
templates, `embed`, Wails/Svelte posture, and Go-specific security/library
choices.