Lit Web Application Standard

TypeScript is the greenfield browser default. Lit is the preferred, but not mandatory, authoring library when reusable stateful custom elements, lifecycle, templating, or stable component contracts are warranted. Ordinary controls begin with semantic HTML.

Component Policy

• Use semantic HTML controls before wrapping or replacing them.
• Use Lit for repeated stateful behavior, lifecycle, and component contracts.
• Document Shadow DOM or light DOM per component family.
• Keep domain and workflow logic outside rendering classes.
• Expose typed properties, events, and accessibility states.

Application Shell

The shell owns global navigation, headers, panels, overlays, notifications, backgrounds, focus restoration, and responsive regions. Features select a named profile rather than manipulating those regions. Canonical profiles are workspace, focused, background-only, and bare.

Theme Structure

1. Primitive tokens hold raw palette, scale, font, radius, shadow, layer, and motion values.
2. Semantic tokens name surfaces, text, accents, borders, focus, status, and interaction roles.
3. Component rules consume semantic appearance roles and governed primitive scales for structural rhythm or dimensions.
4. Layout rules compose shell regions without redefining component appearance.
5. Theme variants replace primitives and semantic mappings without editing features.

Design-Literal Policy

Strict greenfield checks inspect a curated set of design-bearing properties, including foreground and background color, border color and radius, font family and size, shadow, spacing, control dimensions, z-index, and motion duration. Values outside theme roots use semantic custom properties.

Token definitions, zero, percentages, unitless values, runtime geometry, data visualization, currentColor, transparent, inheritance, and documented exceptions or migration ratchets remain valid.

Ratchet mode is migration-only and requires an existing review document that names its scope, review ownership or cadence, and removal trigger. Inline exceptions require a non-empty rationale adjacent to the affected declaration.

The strict canonical profile checks governed .css files and the standard Lit css tagged-template form in TypeScript and TSX. Aliased or dynamically constructed styling requires a project lint extension or reviewed exception because lexical checks cannot prove it.

Canonical Theme

The reference uses the approved Wavenumber dark industrial design language: dark layered surfaces, gold accent, compact density, square controls, zero-radius styling, strong panel boundaries, and optional rotating imagery. It also includes a visibly different alternate theme to prove replaceability.

Background Service

Background rotation is shell-owned. It preloads the next image, retains a solid-color fallback, crossfades only when motion is allowed, cleans up timers and image work, maintains readable contrast, and can be disabled by shell profile or user preference.

Assets And Typography

Approved Wavenumber backgrounds are versioned template snapshots with source, ownership/redistribution authorization, checksums, release inclusion, and update policy. Product logos and the full branding tree are not part of the public template. Stock-licensed assets require explicit raw public-template redistribution rights or must be excluded.

JetBrains Mono is the public reference font under SIL Open Font License 1.1 with a system-monospace fallback. Berkeley Mono is not redistributed; private products may select it through the typography token.

Native controls declare the active light or dark color scheme and use semantic surface and text roles where platform styling permits. Dropdown option popups must remain readable in the default dark theme and in theme variants.

Accessibility And Responsive Behavior

Components and the gallery demonstrate keyboard use, visible focus, contrast, disabled states, validation, loading, warnings, errors, notifications, narrow layouts, and reduced motion. Visual consistency does not override semantic control behavior or user preferences.

Executable Evidence

docs/templates/web/lit-activity/ is the canonical runnable shell and design-language evidence. It includes named shell profiles, centralized theme layers, a component gallery, an alternate theme, JetBrains Mono licensing, background provenance, responsive behavior, and reduced-motion handling. Run it and validate it using the commands in Build Documentation.