Document the web-platform-first frontend architecture

[hnordt]

Summary

• add design record 0003 for Hyperkernel's web-platform-first frontend architecture
• make native HTML, CSS, ECMAScript, Node.js, and browser APIs the default implementation surface
• keep Tailwind CSS in the considered-solutions analysis rather than as a separate decision section
• document why headless UI libraries are excluded from the core interface
• define Svelte and SvelteKit as deliberate frontend exceptions
• accept Zod for the schema-validation capability missing from Node.js and browser APIs
• concentrate initial Zod use on the server while documenting client bundle concerns and the possible use of Zod Mini through zod/mini
• record the reasoning for not choosing React, Vue, htmx, framework-free Custom Elements, a custom application toolchain, or hand-written schema validation
• define security boundaries, tradeoffs, and evidence required for Evaluation and Stable status

Why

Hyperkernel already uses native CSS and intentionally avoids headless UI libraries, but the repository did not preserve the complete long-term reasoning behind those decisions or explain why Svelte, SvelteKit, and Zod remain justified exceptions.

This record makes the dependency boundary explicit. Staying close to platform standards reduces source-level lock-in, keeps core interaction behavior inspectable, and reduces the direct and transitive code trusted during development, build, and runtime. It also documents the real costs: Hyperkernel must own accessibility, focus, keyboard, and cross-browser behavior for its interface primitives.

Zod is accepted because it provides a strong, composable runtime validation and TypeScript inference API that neither Node.js nor the web platform provides. Most initial use remains server-side. Client bundle size is a known concern but not currently a primary optimization goal; browser code may use Zod Mini when its functional API and smaller tree-shaken output provide the better tradeoff.

Impact

This PR changes documentation only. It does not change runtime code or dependencies. The record is marked Development because the architecture is selected and partially implemented, while representative primitives and their accessibility, browser, validation, and bundle contracts are still being developed and evaluated.

Validation

• refreshed the design-record index after 0002 was merged and used the next available number, 0003
• verified the branch started from the latest main
• verified the diff contains only the new record and its index entry
• reviewed the Markdown structure, internal links, status metadata, and status history against records 0001 and 0002
• checked the Web Components and Svelte reactivity framing against current MDN and Svelte documentation
• checked the Zod and Zod Mini names, imports, APIs, and bundle tradeoffs against the current official Zod documentation
• repository test and formatting commands were not run because this is a connector-authored documentation-only change

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: d3689cba64

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[chatgpt-codex-connector]

Classify the record as Experience

The canonical guidance requires every meaningful change to be classified as Kernel, Extension, or Experience, but this metadata introduces Frontend as a fourth scope. That prevents the record from identifying its canonical review boundary; because it governs the application UI, classify it as Experience instead.

AGENTS.md reference: AGENTS.md:L15-L19

Useful? React with 👍 / 👎.