Documentation

Build on a deterministic infrastructure runtime.

Architecture references, API contracts, and module development guides for teams building high-trust products on top of Altason.

Documents

Sections

Primary Audience

Systems builders

Developers

Template developer guide

How to create site templates that apply to landing + dashboard + modules.

Reference

Developer templates guide

Templates define the structure + presentation of a project’s public site.

Landing page: template-driven layout, with content provided by the builder (headline/subheadline/CTA today; sections builder later).
Post‑login pages (authenticated workspace/module pages): template-driven structure and tokens. Customization is intentionally limited to basic copy + colors + theme.

The goal is a modular “business OS” feel: templates must never look like bolted-on marketing themes.

Template modes:

Auth-enabled templates: landing + auth + authenticated workspace
Landing-only templates: public pages only (no auth/workspace)

Current internal templates are auth-enabled.

For full acceptance criteria and tiered requirements, see:

docs/template-contract.md

What a template is (contract)

A template is identified by a templateId and is resolved per project via:

project.settings.site.templateId
The project’s core module (e.g. courses, products)

Templates are implemented in @v2/site-templates and provide:

Token overrides: CSS variables that tune container width, card radius, spacing density.
Landing renderer: a server-rendered landing layout for the core module (and a generic fallback).
Authenticated-shell rules: shared structure for signed-in routes (header/nav/content).

Required page inventory (end-user side)

Auth-enabled templates must provide a coherent design language across both public and authenticated surfaces.

Public landing:
- home/hero sections
- module marketing sections
- footer
Auth shell pages:
- login
- signup
- forgot password
- reset password
Authenticated workspace shell:
- authenticated workspace shell
- module page shell
- module navigation in the header/mobile menu
- consistent spacing/typography with landing (no separate “admin dashboard” visual system)
- responsive nav rule: on mobile, use a single menu system (drawer/hamburger/details) and hide duplicate inline header controls

Landing-only templates provide only public surfaces and should omit authenticated workspace requirements.

Templates are for end-user surfaces only and must not affect the builder backoffice UI.

Required UI primitive inventory

Auth-enabled templates must support at least all Tier-1 primitives from docs/template-contract.md, including:

layout shells (publicHeader, publicFooter, authShell, workspaceHeader, workspaceNav, workspaceContent)
navigation primitives (moduleLinks)
core surfaces (card, panel)
form controls (ui.form.controls)
feedback states (ui.feedback.error)
data views (ui.data.list, ui.data.keyValue)

Theming rules (light/dark)

Template surfaces must be token-driven (var(--site-*)) for both light and dark themes.
Avoid hardcoded light-only or dark-only backgrounds in shared sections (bg-white, fixed hex dark blocks) unless explicitly guarded by template theme selectors.
Secondary surfaces (hero badges, stat chips, drawer panels, footer backgrounds) must remain readable and visually coherent in both themes.

If a template does not declare a capability, modules that require it are blocked from install/use on that template.

Submission rules

No module-specific styling inside templates.
- Templates may choose layout variants based on coreModuleId.
- Templates must not hard-code visuals for a specific module beyond core-module landing structure.
Use shared site primitives.
- Module pages should rely on .site-section, .site-container, .site-card, and the --site-* tokens.
- Templates should only change tokens/attributes so modules inherit changes automatically.
Allowed customization
- From project settings: primaryColor, logoUrl, defaultTheme, and limited copyOverrides.
- Landing content comes from project.settings.landing (and future section builder).
Public copy rule
- Template landing pages should describe the business outcome for end users, not internal module/kit terminology.
Not allowed
- Custom headers per module page
- Per-module bespoke color palettes
- Heavy shadow systems or “marketing template” gradients that break the OS tone

Token surface (CSS variables)

Templates can set CSS variables via the site shell:

--site-container-max (e.g. 1100px)
--site-card-radius (e.g. 14px)
--site-card-padding (e.g. 22px)

The public site CSS (v2/apps/web/src/app/site/site.css) uses these variables so module pages automatically inherit template styling.

How templates are wired

The public site resolves and applies templates in:

apps/web/src/app/site/layout.tsx
- sets data-site-template
- applies CSS variables (tokens)
- applies default theme via data-site-theme and data-site-theme-default
apps/web/src/app/site/page.tsx
- resolves the template and calls template.renderLanding(...)

Builder UI (what project owners control)

Project owners configure global site appearance in:

Project settings → Site Appearance
- Template (dropdown)
- Primary color
- Logo URL
- Default theme

Landing content remains in:

Project settings → Landing Page
- Headline, subheadline, CTA text, etc.
- Template-specific section toggles and copy fields (for example AI SaaS hero badge visibility and hero stats visibility)

Marketplace submission checklist

Every template submitted for marketplace review must pass all of the following gates.

Structural

capabilities field is present and explicitly lists every capability the template supports (no empty/missing fallback)
Provides a clear landing layout for at least one core module (courses, products, agency-operations, etc.)
Generic fallback landing exists and renders correctly when no core module is set
For auth-enabled templates: auth shell styling is complete for login/signup/forgot/reset pages
For auth-enabled templates: workspace shell supports module pages using shared header/module-nav patterns (no duplicate independent nav systems)
For auth-enabled templates: authenticated shell behavior is defined and consistent across signed-in routes
Works in both light and dark modes

Design

Uses only token overrides + shared site primitives (.site-section, .site-container, .site-card, --site-*)
No bespoke page-level CSS that bypasses token variables
No custom headers per module page
No heavy shadow systems or marketing-template gradients

Code quality

renderLanding only imports from @v2/ui and @v2/site-templates (no direct module or app imports)
TypeScript compiles cleanly: pnpm --filter @v2/site-templates exec tsc --noEmit
No runtime errors when coreCourses, coreProducts, or currentUser are null

Compatibility

Template switch is blocked by the platform when installed modules require capabilities the template does not declare
Module install and core-module change paths are blocked when required capabilities are missing
Passes template contract lint: pnpm lint:template-contract
Tested with strict capability mode enabled in non-prod (no silent fallback warnings):

SITE_TEMPLATE_CAPABILITIES_STRICT=true pnpm --filter @v2/web dev
# or during typecheck:
SITE_TEMPLATE_CAPABILITIES_STRICT=true pnpm --filter @v2/web exec tsc --noEmit