Engineering Philosophy

“A system must be rigid enough to prevent collapse, yet invisible enough to allow life.” — Standard Technical Directives, 2026

The Standard Framework @stnd is engineered as an industrial-grade spec. It borrows its rigor from the structural manuals of the 1970s — such as the NASA or EPA Graphic Standards. It does not suggest; it dictates. It establishes absolute boundaries within which chaos and creativity can safely operate. These are the non-negotiables that keep a one-person framework coherent across years and across agents — every rule here is enforceable by reading the code; several are enforced by scripts.

The Duality: The Grid and The Garden

The architecture is built upon a deliberate duality:

1. The Standard (stnd.build): The mechanical grid. Unforgiving, mathematically absolute (anchored in the golden ratio φ), and completely modular. It is the sterile laboratory environment where layout, performance, and security rules are enforced without exception.
2. The Garden (stnd.gd): The organic outcome. A chaotic, living ecosystem where human thought, notes, and communities intertwine.

The Garden can only flourish because the Standard provides an indestructible trellis. If the framework leaks, the garden dies. Therefore, the framework’s architecture is defensive by design.

The Laws

1. No backward compatibility — pre-release; deprecated code is deleted, never shimmed. (The golden rule.)
2. DRY — reuse before you write.
3. Logic-less templates — .astro files hold zero business logic. They render; models and helpers think.
4. Vertical slices over horizontal layers — one feature, one folder, one manifest (index.module.js). A module encapsulates its own UI, its own logic (virtual:stnd/hooks), and its own integrations. Delete the folder, the feature disappears cleanly — no cross-domain side effects, no blast radius beyond the slice.
5. No assumption bleed — a shared code path must not bake in an assumption true for only one app. Per-app intent is declared in that app’s config; shared code stays source-agnostic. Bad: @stnd/press checking if the origin is standard.garden to rewrite a URL. Good: passing an app config object to configure rewrite behavior. Litmus test: would this code do the wrong thing if a different app imported it unchanged? If yes, fail loud on ambiguity rather than guess.
6. Fail loud — every fatal error links a stnd.build/manual/<slug> page, written when the error is written, not after the third support question.
7. English in the repo — all files, code, and published docs.

The Layers

APP      (consumer: apps/stnd.gd, apps/stnd.build, apps/reveal…)
   ↑ imports
FEATURE  (capabilities: press, loader, launcher, account…)
   ↑ imports
CORE     (infrastructure: core, modules, server, store)
   ↑ imports
SHARED   (pure: utils, dom, log, styles, fonts, themes)

Code in a given layer may only import from the layers below it — no circular or sideways climbing. Features never import a sibling feature’s logic (the one exception is visual primitives like @stnd/icon and @stnd/ui, meant to be composed). Boundaries are checked mechanically (pnpm boundaries, dependency-cruiser).

Concrete Invariants

Beyond the laws, three implementation choices are load-bearing — not stylistic preferences, but guarantees the rest of the system depends on:

Edge-Native and Stateless

The backend targets Cloudflare’s Edge exclusively (Workers, D1, R2, KV Cache). Connections to the database (Kysely-D1 via Better-Auth) are dynamically bound per-request; Node.js singletons are forbidden, preventing state-leakage between parallel requests across edge nodes. The guarantee: extreme global scalability with near-zero latency.

CSS-First, Zero-JS by Default

UI elements (buttons, badges, inputs) are pure CSS classes mapped by @stnd/styles — not every element wrapped in a JS framework. Components (Svelte/Astro) are reserved for complex state management (dialogs, command palettes) using Svelte 5 runes for surgical DOM updates without VDOM overhead. The guarantee: minimal payload, instant time-to-interactive.

Provide / Inject State Management

Prop-drilling across the Astro Server/Client boundary is an anti-pattern. @stnd/store implements a reactive nanostores registry: modules provide services (provide('user', userStore)) at boot, isolated Svelte islands inject them (inject('user')). The guarantee: Astro Islands stay perfectly agnostic of each other.

The Golden Rule of Naming

A “Universal vs. Unique” philosophy balances developer experience with brand identity:

1. Technical utilities get industry-standard names. If a package performs a standard technical function, name it the way the industry already does (@stnd/styles, not design; @stnd/ui, not components). This makes the DX invisible and predictable for newcomers.
2. Unique concepts get a proper name. If a package creates a new experience or product category (Module, Garden), give it a poetic, branded name.

The Lightroom Rule (Documentation)

Information is ordered by frequency of need, not by internal architecture. Lightroom’s develop panel opens with exposure and white balance and ends with camera calibration; documentation does the same:

• Every README opens with an ELI5 — the problem, the install, the smallest example — before any reference material.
• Reference detail follows, then Notes / Observations, then Todo.
• This manual obeys the same rule: philosophy first, then the Standard’s own norms, then framework reference, then lookup material last.

Cognitive load is a budget; spend it on what the reader came for.

Conclusion for the Auditor

The Standard Framework is not a prototype; it is an industrial tool. It enforces zero technical debt by aggressively purging backward-compatibility shims. It trades developer flexibility for absolute system predictability.

By understanding these constraints, one understands why the system can confidently support 10,000 active instances on a negligible resource footprint. We build the rigid box so that the mind can wander freely inside it.