Design principles¶
Product principles for evaluators and contributors. The full numbered list also lives in the repository foundations corpus (maintainer-facing).
- Progressive disclosure. Users encounter a concept only when it solves a problem they have reached.
- Server first. Prefer server rendering unless browser execution provides clear user value.
- Standards first. Prefer HTML, CSS, HTTP, HTMX, and Web Components over proprietary protocols.
- FastAPI native. Extend documented FastAPI mechanisms instead of bypassing them.
- Explicit boundaries. Props, inputs, actions, data changes, events, and integration results have explicit contracts.
- Components compose. Components own structure and may own styles, examples, tests, documentation, and browser behavior.
- Addressability is explicit. Rendering a component never silently exposes an endpoint.
- Infer mechanics, not business intent. Authorization, trust, persistence, and destructive meaning remain explicit.
- Secure by default. Dangerous behavior requires a visible, explicit opt-in.
- Explain the magic. Every automatic decision is inspectable and overrideable.
- Deterministic rendering. The same prepared component produces equivalent HTML and metadata.
- Async at I/O boundaries. Data loading may be asynchronous; tree construction and serialization remain deterministic.
- Browser state stays local. Rich widgets may own transient interaction state without inventing an application-wide client store.
- No mandatory Node.js. The official development and production paths work without npm or a JavaScript bundler.
- Keep the core small. Heavy or domain-specific integrations are lazy optional packages or extras.
- Accessibility is contractual. Components express accessible names, states, keyboard expectations, and fallbacks.
- Operational behavior is visible. Timing, caching, assets, security context, routes, and payload sizes are inspectable.
- Escape hatches earn stability. Native HTML, attributes, CSS, Web Components, and explicit responses remain available.
- Framework adapters preserve authority. FastAPI, Flask, and Django retain their routing, security, sessions, and lifecycle semantics.
- Optimize after measurement. Complexity must be justified by representative evidence.