Projects / packages-portal-commons
Stoa: web components and styles that static sites share, rendered at build time.
Stoa is a small set of light-DOM web components and styles for static sites: a header, a page foot, a theme engine, search, filters, calendars, issue tables and a diagram viewer. Each unit has a pure renderer that writes complete markup at build time and an element that upgrades it in the browser, so every page reads without script. Sites vendor the whole package at a release, under a lock, rather than installing it.
Public platform repository · source
The problem
What this is for.
Sites built by the same people drift apart one component at a time: each grows its own header, its own theme switch, its own search, and a fix made in one never reaches the others. Copying code between them spreads the drift; a shared package from a registry makes every build depend on something it fetches. Stoa holds the shared parts in one place and lets each site take a reviewed release into its own repository, checked file by file.
Whose problem
Whether it is yours.
Reach for it if you build static sites, especially with Eleventy, and want them to share a frame, themes, search and dated content without a framework or a runtime dependency. It is not a design system for a single-page application, and it brings no brand: a site supplies its own identity.
Capabilities
What it actually does.
- A Theme Engine that resolves themes and System, Light, Dark or Solar mode, with a pre-paint script and keys named from a prefix.
- A responsive Header and a Page Foot that frame a page, with site-owned brand, navigation, sources and footer.
- A Command Bar searching a build-time index from the keyboard, a shortcut registry and a Filter Bar that keeps its query in the address.
- Calendar views with subscribable feeds, a Timeline and a Today board, all from one calendar set.
- A validated Issues List and an accessible Diagram Viewer, and a workbench that shows every unit live with editable inputs.
State
How finished it is.
In use by several static sites, released in tagged versions with a changelog and a consumer register. Most units are marked as candidates to stand alone later; until then they ship together in one package.
Using it
How to start.
Vendor packages/stoa into a site at a release with its own tool, then render the units at build time and define their elements in the browser. Try each one first in the workbench.
Read the guides.
Everything this site publishes about packages-portal-commons is in Stoa, a Docs section of 8 pages written to be read in order. It starts at Stoa.
Boundaries
What it deliberately does not do.
It ships no site identity: brand, palettes, navigation, content and source registers stay with each site. It is not published to a package registry, and nothing in a site's build fetches it. Public visibility does not grant a licence to use, copy or redistribute.
Authority
What this repository owns.
Canonical source of the shared Stoa units and of the tool sites use to vendor and verify them.
That boundary is deliberate. The ecosystem separates philosophy, engineering discipline, capability semantics, portable standards, and executable behaviour so that none of them can quietly absorb another. The full directory shows where this project sits relative to the rest.
Nearby
Other projects of the same kind.
ki-techne-harness— A runnable personal-controller execution fabric for the ecosystem.homebrew-tap— The Homebrew tap that packages the released Knowledge Islands command-line tools.ki-website— The public publication layer — this site.
See every public project, or go straight to the released command-line tools.