Framework Guide & Invariants
The complete operational handbook for building with Standard — the four layers, vanilla-first styling, the eight laws, and unified hooks.
This guide is the single conceptual handbook for building applications and packages with the Standard framework (@stnd/*). It explains how the system is layered, how to style interfaces using the “Vanilla First” philosophy, how modules communicate through decoupled hooks, and how the eight inviolable laws are enforced across both human developers and autonomous AI coding agents.
1. The Four Layers of Standard
The Standard framework is constructed as four strictly decoupled tiers. Each tier depends only on the tiers beneath it, guaranteeing that presentation components, domain engines, and edge runtime adapters can evolve without circular dependencies.
flowchart TD
L3["Layer 3: Vertical-Slice Modules & App Engine (modules/*, index.module.js, hooks)"]
L2["Layer 2: Swiss Grid & Utilities (_standard-04-grid.scss, _standard-50-utilities.scss)"]
L1["Layer 1: Semantic Primitives & Baseline Reset (_standard-01-reset.scss, native tags)"]
L0["Layer 0: Design Tokens & Foundations (tokens.yaml, OKLCH scales, baseline rhythm)"]
L3 --> L2
L2 --> L1
L1 --> L0
Layer 0: Tokens & Baseline Foundations (tokens.yaml, @stnd/styles)
All design decisions originate from calibrated OKLCH mathematical ramps. Layer 0 establishes CSS custom properties for color roles (--color-foreground, --color-surface, --color-accent, --color-muted), the hybrid baseline rhythm scale (--space-base, --space-dN, --space-N), and Swiss typography tokens (--font-sans, --font-mono, --text-title, --text-body, --text-meta). No raw hex codes (#fff) or pixel lengths exist here.
Layer 1: Semantic Primitives & Reset
Native HTML elements (<button>, <input>, <select>, <dialog>, <table>, <blockquote>, headings <h1>-<h6>) are pre-styled directly by @stnd/styles. There are no custom CSS classes required to make a button or an input field look finished, accessible, and high-contrast. When you render <button>Click me</button>, it is already styled as the primary call-to-action with appropriate focus rings and responsive hit-targets.
Layer 2: Swiss Grid & Layout Utilities
A calibrated, minimal utility library based on Josef Müller-Brockmann’s Swiss typography grid. It provides a 12-column proportional grid (.grid-12, .col-span-6), flexbox alignment helpers (.flex, .items-center, .justify-between), hybrid spacing (.gap-2, .p-base, .mt-2), and reading width constraints (.max-w-prose, .max-w-page).
Layer 3: Vertical-Slice Modules & App Engine (@stnd/core, modules/*)
Feature code is isolated into domain vertical slices under modules/<feature>/. Each slice declares its public contract through an index.module.js manifest and hooks into shared rendering pipelines and action slots without importing sibling modules directly.
2. Vanilla First: Styling Philosophy & Invariants
Standard follows an uncompromising Vanilla First rule: rely on semantic HTML elements and framework defaults before writing a single line of custom CSS.
flowchart LR
A["1. Semantic HTML Element"] --> B["2. Framework Utilities"] --> C["3. Custom Style (Last Resort)"]
A -.->|Native styles from @stnd/styles| OK1["Finished UI"]
B -.->|Layout: .flex, .grid-12, .gap-2| OK2["Finished Layout"]
C -.->|Only domain-specific animations or canvas| Local["<style> Block"]
The Three Rules of Vanilla First
- Never re-declare what the framework already provides: Re-styling
border-radius,font-family, or base padding on native<button>,<input>,<select>, orarticle.cardis an architectural anti-pattern and is flagged by@stnd/mcp. - Minimal or empty
<style>blocks: Component<style>blocks should be minimal or completely empty. Layout arrangements (spacing, flex direction, grid columns) must be achieved through standard utility classes rather than ad-hoc CSS rules. - Zero literal colors & zero arbitrary typography: No hexadecimal strings (
#3b82f6),rgb(), orhsl()in component CSS. Derive shades usingcolor-mix(in oklch, var(--color-x) 10%, transparent). Never writefont-size: 14pxorfont-family: Arial; always use Swiss scale variables (--font-sans,--font-mono,--text-meta,--text-title).
Component Vocabulary
The framework enforces a shared, strict component grammar:
- Buttons: A
<button>is the primary action by default. There is NO.primaryor.btn-primaryclass. Secondary buttons are styled with class.accent(.secondaryis retired across the entire ecosystem). Other valid variants are.outline,.ghost,.link,.destructive, and.icon. Buttons must live inside anarticle.card<footer>or a.btn-group, never loose in a body text container. - Cards: An
article.cardfollows a triadic structure: an optional<header>(title and icon outside heading, sized 1cap x 1cap), a plain<div>for the body text, and an optional<footer class="flex-right">for actions. - No Emojis in the Interface: Do not use emoji characters (
✨,🔒,🌱,⚠️) in UI templates or button labels. Standard interfaces communicate through typography and vector icons via@stnd/icon(<Icon icon="ph:lock-key" />).
3. The Eight Inviolable Laws
The following laws are non-negotiable across every repository, application, and framework package:
| # | Law | Invariant & Enforcement |
|---|---|---|
| 1 | No backward compatibility | Pre-release software. No shims, no legacy aliases, no deprecation warnings. When an API or token name updates, update all consumers cleanly. |
| 2 | DRY (Don’t Repeat Yourself) | Reuse existing packages and utilities before authoring new abstractions. Inspect @stnd/* before writing custom helpers. |
| 3 | .astro holds no logic |
Frontmatter in .astro files is strictly reserved for template rendering and prop passthrough. Database queries, Stripe mutations, and business calculations live in domain models (modules/core/models/) or actions (actions.ts). |
| 4 | Vertical-slice modules | Features reside in modules/*. A feature module may only import from the foundation spine (modules/core/) or @stnd/* packages. Sibling feature modules must never import each other directly. |
| 5 | src/ minimal |
Application code lives in modules/. The src/ directory is kept completely minimal, acting only as the Astro runtime entrypoint. |
| 6 | Agent Lock | Never touch lines marked // @agents lock true without explicit instruction from the project founder. |
| 7 | Fatal errors documented | Every fatal build or runtime error must link to a diagnostic explanation page on stnd.build/manual/diagnostic/. |
| 8 | Build & Secrets | Always verify changes with pnpm build. Secrets must never be committed to wrangler.toml (use .dev.vars locally and wrangler secret put in production). |
4. The Unified Hooks System
To prevent modules from creating tightly coupled dependencies on one another, Standard provides a Unified Hooks Architecture (virtual:stnd/hooks). Modules register their contributions in their index.module.js manifest, and layouts or server routes consume them dynamically.
Hook Classification & Types
flowchart TD
H["Module Manifest: hooks: { ... }"]
H -->|Path to .astro / .svelte / .md| UI["UI Zone Contribution"]
H -->|Path to .js / .ts handler| Logic["Logic Hook"]
H -->|launcher:* or :action name| Act["Action Extension"]
UI --> R1["Rendered in layout via <Hook zone='...' />"]
Logic --> R2["Called in server via runHook() or runPipeline()"]
Act --> R3["Loaded in client via extensions[zone]"]
- UI Zones: Rendered inside layout templates with
<Hook zone="stnd:base" />. Multiple modules can register components to the same zone; they are rendered sequentially in load order. - Logic Hooks (
runHook): Fans a call out to every registered handler and gathers an array of returned values. Used for lifecycle notifications or parallel task gathering (astro:build:done,post:created). - Logic Pipelines (
runPipeline): Threads a single data descriptor through a pipeline of handlers sequentially. Each handler receives(descriptor, context)and must explicitly return the modified or untouched descriptor. - Action Extensions (
launcher:action,selection:action): Handlers exposed as callable actions for the client launcher or keyboard command palette.
The server: true Rule:
Any logic hook or pipeline handler that executes on the server (e.g. database lookups, authentication checks, edge operations) must explicitly specify { action: "./server/handler.ts", server: true }. Conversely, action extensions (launcher:* or :action) run in client bundles and must never declare server: true.
5. Machine Verification with @stnd/mcp
To guarantee that code authored by human engineers or autonomous AI agents remains 100% compliant with these rules, the framework ships with @stnd/mcp (packages/mcp/).
The MCP server connects directly to modern AI coding environments (Cursor, Windsurf, Claude Code, Google Antigravity) via the Model Context Protocol, exposing real-time queries for design tokens, HTML utility classes, and automated architectural audits (stnd_audit_app, stnd_audit_module, stnd_lint_markup, stnd_lint_markdown).