Skip to content

Architecture

github-actions[bot] edited this page Nov 21, 2026 · 1 revision

Architecture

Spotstrap is one npm package, @kodentuzo/spotstrap, with no runtime dependencies. It has three parts.

Themes

src/themes/<name>.css sets the token contract's values for one theme (ADR 0001): shadcn's color names (--background, --primary…, --sidebar-*), --radius and the fonts, in oklch, light and dark. Values are static, so every platform parses them.

  • src/tailwind.css maps the tokens to Tailwind v4's theme, for shadcn/ui, shadcn-vue and shadcn-svelte. src/dark-class.css switches dark mode on a .dark class instead of the system setting.
  • scripts/build.ts writes the prebuilt outputs to dist/: dist/themes/<name>.css (plain CSS, for pages without Tailwind), dist/tokens.json and dist/tokens/<name>.json (oklch and hex, for meta tags, favicons and native code).
  • scripts/contract.ts is the contract every theme must fill; scripts/color.ts does the color math.

Blocks

src/blocks/ is the framework-free core of the pages every app repeats (ADR 0011):

  • privacy.ts: privacyPolicy() and legalNotice() turn the instance's legal facts (spotkit's LegalFacts) into a document model: a title, sections, and blocks of paragraphs and lists.
  • your-data.ts: createYourData(), the state of downloading and deleting your data, over spotkit's client.
  • analytics-choice.ts: createAnalyticsChoice(), the switch and the opt-in prompt, over spotkit's analytics().
  • messages/en.ts: every sentence, typed, so another language must fill every key.

Nothing in the core touches the DOM when imported, and dates are formatted in UTC, so a page renders the same on the server and in the browser.

Views and the registry

registry/vue/ holds the Vue views. Each renders a block with shadcn-vue's components. scripts/registry.ts (run by pnpm build) turns them into shadcn registry items, with each view's source inline, in dist/registry/vue/ (ADR 0012). The package ships them as @kodentuzo/spotstrap/registry/*, and kodentuzo.com serves them at https://kodentuzo.com/spotstrap/r/vue/<name>.json, where shadcn-vue add reads them.

Checks

test/ runs with node --test:

  • every text pair in every theme reaches WCAG AA, light and dark (accessibility.test.ts);
  • every theme fills the contract, with static values (contract.test.ts, static.test.ts);
  • the outputs build, and Tailwind compiles them (build.test.ts, tailwind.test.ts);
  • the blocks' documents and state, for full and minimal facts (blocks.test.ts);
  • every view compiles, and the registry items are valid (registry.test.ts);
  • the package's exports resolve (package.test.ts).

Clone this wiki locally