JavaScript Web App Standard

The javascript-web-app profile covers browser applications built from owned HTML, CSS, and JavaScript. The default posture is no-build: source files are served directly by a host app or static file server until a package manager, bundler, or transpiler is clearly justified.

Profiles

javascript-web-app

Generic browser runtime profile for plain HTML, CSS, JavaScript, tests, docs, contracts, and hygiene ratchets.

python-js-app

Python package or FastAPI-style application that serves a browser runtime. It inherits the web rules and adds uv, Hatchling, Ruff, Pyright, and Python-to-browser API contract expectations.

No-Build Default

A build step is optional. Projects may use native browser JavaScript, explicit script load order, ES modules, or manifest-ordered IIFEs. If a Node toolchain is introduced, package.json and its lockfile must be committed and CI must run the declared lint/test/build scripts.

Import maps, direct ES modules, and modern CSS are preferred when they keep source inspectable in the browser. Build tools are allowed when they remove real complexity, such as package dependency resolution, reusable TypeScript libraries, generated assets, or browser automation infrastructure.

Source Boundaries

• Owned source lives under src/.
• Third-party, generated, minified, and vendored assets live under vendor/, lib/, _build/, or node_modules/.
• Module order and global namespace ownership must be documented.
• Python-served apps document static routes, JSON APIs, and WebSockets.

Documentation Layout

JavaScript profiles require a canonical JavaScript standard design doc. Repositories may keep the legacy root page docs/design/javascript-standard.html or use the foldered design-doc layout docs/design/standards/javascript.html. Projects with another deliberate layout may configure the canonical path:

[documentation.standard_docs]
javascript = "docs/design/standards/javascript.html"

JavaScript Rules

• Checked JavaScript is the baseline: use jsconfig.json or tsconfig.json with allowJs, checkJs, and noEmit, or put // @ts-check at the top of owned JavaScript modules.
• Use JSDoc for public function shapes, domain data, event payloads, and API responses. Prefer named typedefs for contracts that cross module or Python/browser boundaries.
• Use one module per concern.
• Avoid accidental globals; write through one documented namespace.
• Keep event wiring, state mutation, rendering, and transport separate.
• Gate new complexity, large files, nesting, and trailing whitespace.
• Move to TypeScript when reusable framework code, shared CAD state, or cross-application libraries need exported types, refactoring safety, or stronger module boundaries.

JavaScript Tests

• Algorithmic JavaScript, parsers, CAD state machines, geometry adapters, and data transforms require deterministic tests with known inputs and known outputs.
• Prefer the Node built-in node:test runner and node --test for dependency-free module tests. Rack can orchestrate those commands through a Python signoff stratum.
• DOM-heavy code should be split so pure decisions are unit-tested and only rendering, focus, pointer, keyboard, and browser integration remain in browser smoke tests.
• Prefer browser smoke tests for app startup, DOM wiring, and key flows.

CSS Rules

• Define design constants as CSS custom properties. Colors, spacing, z-index layers, radii, shadows, typography, and animation timings should use named tokens instead of repeated hard-coded values.
• Separate layout, component, state, and utility sections or files.
• Use cascade layers, custom properties, selectors, media queries, and container queries directly before adding Sass, PostCSS, or a CSS build step.
• Avoid inline styles except for runtime geometry or deliberate dynamic values.
• HTML owns semantic structure and stable IDs or data attributes. CSS owns layout and visual state. JavaScript toggles classes, attributes, and custom properties instead of writing raw style strings except for runtime geometry.
• Use stable dimensions for controls, toolbars, panels, canvases, and tables.
• Keep generated and minified CSS isolated from owned styles.
• Gate trailing whitespace, oversized files, and invalid brace balance.

Web Components

Web Components means the platform custom element, Shadow DOM, template, and slot APIs. The standard is to build owned wn-* primitives when a UI pattern is reused or needs lifecycle, accessibility, encapsulated DOM, or a stable event contract.

• Use native HTML first, including <dialog> and the Popover API where they fit. Wrap repeated patterns such as dialogs, toast regions, property rows, toolbar buttons, inspectors, and panel shells.
• Do not create custom elements for static layout, one-off business views, or pure algorithm/state modules.
• Prefer open shadow roots, slots for caller-owned content, CSS custom properties for theme tokens, and part names for deliberate styling hooks.
• Public events must be documented and should normally set bubbles: true and composed: true when consumers outside the component need to observe them.
• Third-party web components are dependencies, not a default UI strategy. Vendor them only with the same review, lock, license, and update policy used for other frontend dependencies.

WASM

• Browser-facing WASM must be tested through the same JavaScript wrapper, loading mode, and data marshalling path that the app uses.
• Use Node or headless-browser tests for JS-to-WASM smoke and contract checks. Pure WASI or core WASM runtimes such as Wasmer or Wasmtime are optional when they give a faster ABI/kernel test, but they do not replace browser-wrapper validation.
• WASM artifacts need a manifest or docs that identify target runtime, exported entry points, generation command, and release inclusion rule.

Agent-Time Visual Verification

Agents changing UI must open the app in a browser, inspect the rendered state, and use screenshots or DOM checks to verify that important controls, canvas content, panels, dialogs, and responsive states are not broken. CI should still test the underlying algorithms, contracts, and generated files without depending on human visual judgment.

Command Surface

Repositories must expose simple verbs even when the underlying shell differs. The required verbs are install, update, build, test, and signoff. Optional verbs include clean, dev, and run.

Existing repositories may keep PowerShell, shell, Make, package scripts, or Python wrappers. New cross-platform repositories should prefer a small Python or uv-backed orchestrator with thin platform wrappers when native shell behavior diverges.

Signoff

No-build projects should provide dependency-free scripts/js_hygiene.py and scripts/css_hygiene.py ratchets, plus Rack L99 tests that call them. Projects with Node tooling may satisfy the same role through committed package scripts and lockfiles.

Web signoff should include type checking, CSS token hygiene, JS/CSS hygiene, deterministic module tests for non-DOM logic, browser smoke where feasible, Python API contract tests for served apps, and release validation for generated standalone HTML bundles.