Fundatio

Fundatio is Vastare's canonical frontend design foundation package. It provides design tokens, Sass maps, Sass functions, Sass mixins, CSS custom property contracts, raw native HTML baselines, Bootstrap adapter support, and framework-neutral TypeScript HTML/accessibility primitives.

Fundatio sits below Vastare UI kits, WordPress themes, SPAs, and future frontend applications. It gives downstream projects a consistent foundation without turning itself into an application framework or component library.

Current version

1.0.0-beta.1

Beta readiness

1.0.0-beta.1 is Fundatio's first integration-ready beta. The public integration surface is ready for serious downstream testing in WordPress themes, Vue SPAs, Intosseus, Pubosseus, Bootstrap-consuming surfaces, and future frontend applications.

Beta means the exports, assets, documentation, demo, and TypeScript helpers are ready for real integration testing. It does not mean the package is frozen forever.

Required beta surfaces are covered:

• compiled CSS consumption;
• selective SCSS consumption;
• compiled JavaScript consumption;
• typed TypeScript consumption;
• copied font assets under dist/fonts;
• copied image assets under dist/img;
• raw native element baselines;
• Bootstrap adapter and Bootstrap Core bridge;
• public demo verification;
• package export tests.

What Fundatio is

Fundatio owns low-level frontend infrastructure:

• design tokens;
• Sass maps, functions, and mixins;
• CSS custom property contracts;
• font and image asset distribution;
• reset/reboot foundation;
• raw semantic HTML element baselines;
• Bootstrap adapter and Bootstrap Core bridge;
• light/dark theme mode support through data-bs-theme;
• framework-neutral TypeScript HTML helpers;
• package documentation and demo verification.

What Fundatio is not

Fundatio is not:

• a UI kit;
• a Bootstrap clone;
• a Vue or React component package;
• a WordPress plugin or theme;
• an application framework;
• an auth/session package;
• a CRM, eCommerce, or dashboard package;
• a BFF/API client;
• a place for business or domain logic.

Application components belong in downstream packages such as pkgn-intosseus, pkgn-pubosseus, WordPress themes, or application frontends. Fundatio stays boring and foundational, which is how foundations avoid turning into junk drawers with exports.

Installation

npm install @vastare/pkgn-fundatio

Bootstrap is included as a dependency because Fundatio exposes a public scss/bootstrap-core entrypoint that imports Bootstrap SCSS directly. Consumers that compile Bootstrap components against Fundatio should keep Bootstrap installed in the consuming project too.

CSS usage

Use the compiled full foundation CSS directly:

<link rel="stylesheet" href="/node_modules/@vastare/pkgn-fundatio/dist/css/main.css" />

Or import a selective compiled CSS entrypoint from a bundler that supports package CSS imports:

import '@vastare/pkgn-fundatio/css/typography.css';
import '@vastare/pkgn-fundatio/css/forms.css';

SCSS full usage

@use '@vastare/pkgn-fundatio/scss/main';

SCSS selective usage

Fundatio is intentionally split into selective entrypoints:

@use '@vastare/pkgn-fundatio/scss/tokens';
@use '@vastare/pkgn-fundatio/scss/functions';
@use '@vastare/pkgn-fundatio/scss/typography';
@use '@vastare/pkgn-fundatio/scss/forms';

Available SCSS entrypoints:

@vastare/pkgn-fundatio/scss/main
@vastare/pkgn-fundatio/scss/tokens
@vastare/pkgn-fundatio/scss/maps
@vastare/pkgn-fundatio/scss/functions
@vastare/pkgn-fundatio/scss/mixins
@vastare/pkgn-fundatio/scss/fonts
@vastare/pkgn-fundatio/scss/reset
@vastare/pkgn-fundatio/scss/bootstrap
@vastare/pkgn-fundatio/scss/bootstrap-core
@vastare/pkgn-fundatio/scss/text
@vastare/pkgn-fundatio/scss/lists
@vastare/pkgn-fundatio/scss/forms
@vastare/pkgn-fundatio/scss/tables
@vastare/pkgn-fundatio/scss/media
@vastare/pkgn-fundatio/scss/body
@vastare/pkgn-fundatio/scss/paragraph
@vastare/pkgn-fundatio/scss/heading
@vastare/pkgn-fundatio/scss/typography

Compiled CSS entrypoints are emitted under dist/css for CSS-producing layers.

Compiled CSS entrypoints include:

@vastare/pkgn-fundatio/css/main.css
@vastare/pkgn-fundatio/css/tokens.css
@vastare/pkgn-fundatio/css/fonts.css
@vastare/pkgn-fundatio/css/reset.css
@vastare/pkgn-fundatio/css/body.css
@vastare/pkgn-fundatio/css/paragraph.css
@vastare/pkgn-fundatio/css/heading.css
@vastare/pkgn-fundatio/css/typography.css
@vastare/pkgn-fundatio/css/text.css
@vastare/pkgn-fundatio/css/lists.css
@vastare/pkgn-fundatio/css/forms.css
@vastare/pkgn-fundatio/css/tables.css
@vastare/pkgn-fundatio/css/media.css
@vastare/pkgn-fundatio/css/bootstrap.css
@vastare/pkgn-fundatio/css/bootstrap-core.css

Styling architecture

Fundatio's styling pipeline is:

Tokens → Maps → Functions → Mixins → CSS Custom Properties → CSS

Design values must flow through that pipeline. Raw element CSS should consume CSS custom properties for design decisions. Literal values are reserved for mechanical reset behaviour such as margin: 0, box-sizing: border-box, display: block, and similar browser-normalisation values.

CSS custom properties are the runtime contract. They are native CSS variables, not PostCSS variables.

Raw element selector model

Fundatio styles raw HTML elements directly:

p {
}
h1,
h2,
h3,
h4,
h5,
h6 {
}
ul,
ol {
}
input,
select,
textarea,
button {
}
table,
th,
td {
}

Fundatio native CSS must not emit .fd-*, .fundatio-*, utility, layout, or component classes. Consumers may add their own classes in their own applications, but Fundatio does not require or generate styling classes for native baselines.

Buttons, form controls, tables, and media receive reset/base treatment only. Branded button variants, cards, navbars, dashboards, and application UI belong in downstream packages.

Theme mode usage

Fundatio uses the same runtime colour-mode contract as Bootstrap:

<html data-bs-theme="dark"></html>

TypeScript helpers are available:

import { setThemeMode } from '@vastare/pkgn-fundatio';

setThemeMode('dark');
setThemeMode('system');

Bootstrap adapter usage

scss/bootstrap is the bridge-only adapter. It exposes Bootstrap-compatible Sass variables, maps, functions, mixins, and a lightweight custom-property bridge derived from Fundatio.

@use '@vastare/pkgn-fundatio/scss/bootstrap' as bootstrap;

.example {
  color: bootstrap.$primary;
  font-family: bootstrap.$font-family-base;
}

Bootstrap remains an adapter target. Fundatio tokens remain the design source of truth.

Bootstrap Core usage

scss/bootstrap-core imports Bootstrap's core Sass stack and emits Bootstrap Core CSS with Fundatio-derived variables:

@use '@vastare/pkgn-fundatio/scss/bootstrap-core';

Bootstrap Core includes root, reboot, type, helpers, and the utilities API. It does not include Bootstrap components such as buttons, forms, cards, modals, navbars, dropdowns, alerts, or accordions.

Consumers can opt into Bootstrap components themselves:

@use '@vastare/pkgn-fundatio/scss/bootstrap-core';

@import 'bootstrap/scss/buttons';
@import 'bootstrap/scss/modal';

Bootstrap helper and utility classes may appear in bootstrap-core.css because that entrypoint explicitly opts into Bootstrap output. Fundatio's native CSS remains class-free.

TypeScript usage

Fundatio exposes framework-neutral helpers for creating raw native HTML with accessibility guardrails.

import { createElement } from '@vastare/pkgn-fundatio';

const heading = createElement('h1', {
  text: 'Account settings',
});

Accessible image example:

createElement('img', {
  src: '/logo.svg',
  alt: 'Vastare',
});

Decorative image example:

createElement('img', {
  src: '/divider.svg',
  decorative: true,
  alt: '',
});

Button example:

createElement('button', {
  text: 'Save changes',
});

The helpers do not invent meaningful accessibility text. Missing image alt intent, missing form labels, and icon-only controls without accessible names are developer errors.

Public demo

Fundatio includes a raw semantic HTML demo:

npm run build:demo

The demo is defined in:

public/index.html
src/demo/main.ts

It loads generated dist/css/main.css and generated public/assets/main.js. It must not use custom demo CSS, demo classes, Bootstrap classes, inline presentation styles, or ID-based styling. It exists to prove Fundatio as it ships.

See:

• docs/demo.md
• docs/demo/html-element-demo-coverage.md

Consumer examples

Small examples live in:

examples/css
examples/scss
examples/typescript
examples/bootstrap-core

They are intentionally small and do not become demo applications.

Development commands

npm install
npm run typecheck
npm run lint
npm run format:check
npm run test
npm run docs:build
npm run build
npm run check

Granular commands:

npm run lint:ts
npm run lint:scss
npm run lint:demo
npm run test:ts
npm run test:scss
npm run test:package
npm run test:demo
npm run build:css
npm run build:js
npm run build:types
npm run build:demo
npm run docs:ts
npm run docs:scss

Publishing and package preflight

Before publishing or tagging:

npm install
npm run check
npm pack --dry-run

The package must not publish node_modules, logs, local environment files, coverage output, cache files, or temporary build artefacts.

Documentation

• Demo: docs/demo.md
• HTML demo coverage: docs/demo/html-element-demo-coverage.md
• SCSS index: docs/scss
• TypeScript API docs: docs/ts
• Changelog: CHANGELOG.md
• Contributing: CONTRIBUTING.md
• Security: SECURITY.md

Browser support

Fundatio includes a Browserslist configuration for downstream tooling. It targets maintained modern browsers and maintained Node versions. Do not add ancient browser support casually; the foundation should be stable, not trapped in a museum exhibit.

License

ISC. See LICENSE.