web.md

 1# Web apps
 2
 3Default to a light server-rendered stack unless the product is clearly
 4frontend-heavy. If a page can remain a form and a template, keep it light.
 5
 6## Default posture
 7
 8- Use semantic HTML forms and links before client-side JavaScript.
 9- Use plain CSS with semantic variables for modest interfaces.
10- Add a small frontend toolchain only when formatting, typechecking, bundling, or
11  component complexity earns it.
12- Use existing package managers and lockfiles. Ask before introducing a new one.
13
14This is the default for admin panels, dashboards, release trackers, internal
15tools, and server-rendered apps with modest interaction.
16
17## CSS and accessibility
18
19- Use semantic HTML and real form controls.
20- Include viewport and colour-scheme metadata.
21- Use CSS custom properties as semantic design tokens. OKLCH is preferred for
22  colour palettes when browser support is acceptable.
23- Support dark mode by overriding semantic tokens under `prefers-color-scheme`.
24- Use spacing, radius, type, and measure scales instead of one-off values.
25- Prefer simple responsive layouts with CSS grid/flex.
26- Use accessible fonts when bundling fonts; include licence metadata when the
27  project is REUSE-compliant.
28- Do not use ARIA to compensate for avoidable non-semantic markup.
29
30## Security
31
32- Treat form/query values as untrusted.
33- Use a sanitizer when rendering user-provided HTML or Markdown-derived HTML.
34- Keep auth/session logic in a domain package; handlers should not duplicate
35  password or token handling.
36
37## Escalate only when needed
38
39Escalate to a frontend-heavy stack only when the UI needs rich local state,
40complex component composition, desktop integration, drag/drop, long-running event
41streams, or substantial client-side interaction.
42
43## Go path
44
45For Go web apps or Wails frontends, read [golang/index.md](golang/index.md)
46first and follow its web or Wails chain. The Go path covers `net/http`,
47templates, `embed`, Wails/Svelte posture, and Go-specific security/library
48choices.