Repository navigation
ADR 0006
github-actions[bot] edited this page Nov 21, 2026
·
1 revision
Status: superseded · Built: done · Date: 2026-11-19 · Superseded by: 0009, 0012
Built in site/, with the Pages workflow. Goes live with the first push to main, after the one-time setup in docs/releasing.md.
Spotstrap needs a public home: what it is, how to install it, and one page per component with a live example and its HTML, the way headlessui.com shows Headless UI. Spotcraft's site (spotcraft's ADR 0024) already does most of this for its own docs: Astro with no UI framework, static output, the repository's Markdown rendered at build time, deployed to GitHub Pages.
Two needs differ from spotcraft's site:
- The examples are interactive: Menu, Listbox, Combobox and Tabs need
spotstrap/js, and a preview needs to switch themes, light and dark, and a phone's width. Spotcraft's site has no JavaScript at all. - A phone preview must be a real 375px viewport: the dialog's sheet and other
@mediarules depend on the viewport, not on the width of a box in the page.
-
Astro, in
site/, a private pnpm workspace package that depends onspotstrapfrom this repository. The site is styled with spotstrap itself (Tailwind source, theneutraltheme,dark-class.css) and usesspotstrap/js; whatever is awkward for the site is fixed in the library. -
Static output,
build.format: 'file', no UI framework. Docs pages are the repository's Markdown (docs/,CHANGELOG.md), rendered at build time. Component pages are MDX in the site, sodocs/components.mdgoes. -
JavaScript is allowed, from files only: the CSP is
script-src 'self', and a build check fails on any inline<script>. -
Examples are HTML fragments (
site/src/examples/<component>/<name>.html). Each is built into a standalone page with spotstrap's prebuilt CSS, every theme andspotstrap/js, and shown in an<iframe>with its source below. A toolbar switches the theme, light or dark, and phone (375px) or full width. -
GitHub Pages, deployed by
.github/workflows/pages.ymlon pushes tomain, which holds the released version, so the site shows what's on npm. Custom domainspotstrap.dev, DNS on Cloudflare pointing at GitHub's Pages addresses, not proxied. - Code samples are HTML only.
- The docs and the code move together; a release updates both.
- Every example is tested at a phone's width by the same hit-area probe as the library.
- The site can't go live before the first release.
- Pages can't send headers, so the CSP is a meta tag (no
frame-ancestors).
Published from docs/. Edit the files there; changes here are overwritten.