Universal Foundation CSS

Build your own design system with open, framework-independent foundations.

Universal Foundation CSS (UF-CSS) is an open-source design-system construction toolkit: optional mathematical tools, semantic modeling methods, hierarchy and grid references, token generators, framework adapters and component contracts. It does not prescribe a visual system. Each developer or product creates and owns its own design language.

Status: v1.0.0 source testing. The repository and root lockfile declare 1.0.0, ready for hands-on testing after merge. This is not an npm publication, Git tag, or certification of production readiness. Real-device and manual screen-reader checks remain pending. Optional grid references are not all executable CSS recipes.

See the design freedom and extension philosophy before adopting a preset. All existing scales, grids, categories and starter tokens are optional examples, not mandatory conventions.

Implementation status and next steps

See the step-by-step implementation plan for all phases, exact folders, dependencies, review gates, and which capabilities are already implemented versus planned.

Phases 00–08 are implemented for their declared experimental scopes. Phase 09 has 25 successful Playwright/axe Chromium checks across independent light/dark designs; physical-device, manual screen-reader, approved screenshot baselines and actual browser zoom remain open. Phase 10 adds an inspect-only project audit and safe CLI preview. Phase 11 adds release-artifact verification and a manual, guarded prerelease workflow. The source version has been updated to 1.0.0 for testing; npm publication and Git tagging remain separate, unperformed actions. See roadmap, release readiness guide and quality evidence.

Actual framework-consuming projects

Beyond isolated adapters, the feature branch now builds applications consuming the actual locally packed npm tarball. Framework-consumer guide explains exactly which imports, compilers and style overrides each project controls.

• Next.js + StyleX App Router uses a project-owned editorial theme and produces a production Webpack build.
• Expo / React Native uses a different independent project theme, safe-area context, font scaling and Metro's Android JavaScript export.
• Packed Tailwind v3/v4, Bootstrap, StyleX and native consumer verifies distribution exports in a separate installed environment.
• Normal HTML, Vue, Svelte, Angular and Astro can import the same generated CSS custom properties without a framework-specific runtime.

These are verified build integration tests, not physical-device, visual-regression or full WCAG audits. The package remains experimental and unpublished. No required brand, grid, hierarchy, font or styling library is imposed.

The problem it solves

Projects frequently develop competing UI rules: one app uses 16px gutters, another uses 24px, headings change font roles, and buttons behave differently across web and mobile. UF-CSS separates shared decisions and behavior from platform-specific rendering and product branding.

It is not a Tailwind replacement, a mandatory UI theme, or a claim that golden ratios and UX heuristics are universal laws.

Seven foundation domains

Directory	Responsibility
foundation-formular	Pure modular scale, fluid clamp, spacing, grid geometry and WCAG contrast calculations; documented UX principles
semantic	Content, navigation, surface, action, status and interaction roles
hierarchy	20 useful categories across communication, structure, visual techniques and interaction
tokens	Core, brand slots, semantic colors, typography, layout, motion and extended token roles
patterns	Ten optional framework-neutral task patterns, including forms, filters, article, dashboards and tables
components	Behavioral and accessible-state contracts, not prebranded components
grid	37 registered web, editorial, geometric, classical and spacing systems with honest implementation statuses

Get started (repository)

Node.js 22 or newer is recommended for developing the repository.

git clone https://github.com/kingbattash/Universal-Foundation-CSS.git
cd Universal-Foundation-CSS
npm install
npm run verify

The build emits JavaScript and declarations under dist/. No stable npm package is published yet.

TypeScript example

import {
  modularScale,
  spacingStep,
  fluidClamp,
  contrastRatio,
  getGrid,
  hierarchy,
} from "@kingbattash/universal-foundation-css";

// After publishing or linking the package:
const titleSize = modularScale(3);           // 31.25px
const sectionGap = spacingStep(8);           // 32px
const responsiveTitle = fluidClamp(32, 64); // CSS clamp(...)
const accessible = contrastRatio("#111111", "#ffffff") >= 4.5;
const layout = getGrid("twelve-column");     // css-recipe

Optional CSS adapter

For plain HTML / CSS, use the opt-in neutral stylesheet. It contains only namespaced --uf-* values and uf-* layout helpers; it does not reset global element styles.

<link rel="stylesheet" href="./path/to/foundation.css" />
<section class="uf-container">
  <div class="uf-grid">
    <article>First item</article>
    <article>Second item</article>
  </div>
</section>

Browse the vanilla HTML example. The layout helper stylesheet is maintained independently, but its variables are generated from the canonical token source in tokens/source.tokens.json.

Choosing a grid

UF-CSS offers choices, not 37 mandatory styles. A grid registry entry declares whether it is a CSS recipe, a mathematical helper, or a reference. For example:

• twelve-column: available as a simple responsive CSS recipe.
• rule-of-thirds: available through a geometry helper.
• golden-canon: reference only; not a browser CSS engine.
• four-point: spacing rhythm, not a literal column grid.

See the grid catalog before selecting a layout.

Interactive design-system builder

Run the opt-in setup wizard to choose or skip your own colors, typography, spacing, structural grids, composition guides, hierarchy, and framework adapters. It previews all planned files and requires explicit confirmation before creating a directory.

# From this repository (not yet published on npm)
node scripts/cli.mjs init

# Read-only plan suitable for an AI agent or CI
node scripts/cli.mjs init --config examples/builder/editorial.config.json --out ./my-system --dry-run

See the interactive wizard guide. The CLI is included in the experimental packed package as uf-css init; the corresponding npm package has not been published yet.

Create a completely custom design system

You can now generate adapters from your own token names and values, with no inherited color palette, font, spacing scale, grid or hierarchy. The generator accepts independently authored DTCG-style files and optional explicit Tailwind/Bootstrap mappings.

node scripts/generate-custom-system.mjs \
  --tokens examples/custom-systems/editorial/tokens.json \
  --mapping examples/custom-systems/editorial/mapping.json \
  --prefix press \
  --out ./generated/press

Two very different examples are included at examples/custom-systems/{editorial,operations}/. Both are compiled by the actual Tailwind v3/v4 and StyleX toolchains in CI, with Bootstrap output and native TypeScript checked. Read the complete custom system guide.

Cross-framework adapters

All adapters derive from tokens/source.tokens.json, which uses a supported subset of the DTCG 2025.10 typed-token format. Do not edit generated files directly.

Stack	Output	Status
Vanilla HTML/CSS	src/css/foundation.css and tokens.generated.css	Opt-in layout + semantic variables
Tailwind CSS v4	adapters/tailwind-v4/theme.generated.css	Generated @theme inline mapping; CLI smoke test passes
Tailwind CSS v3	adapters/tailwind-v3/preset.generated.cjs	Generated theme preset; CLI smoke test passes
Bootstrap 5.3	adapters/bootstrap/bootstrap.generated.css	Body/semantic variable and button mapping; component-specific coverage incomplete
StyleX	adapters/stylex/tokens.generated.stylex.ts	Generated defineVars/dark theme; Babel compilation verified; consuming app must configure StyleX
React Native/Expo	adapters/react-native/tokens.generated.ts	Generated typed native values; Expo Metro Android JS export passes; device tests pending

See adapter installation instructions for exact import order, examples, and limitations.

npm run generate:tokens  # Regenerate all adapters from canonical source
npm run check:tokens     # Verify no generated file was edited or missed

Project-specific themes

Your product can keep its own identity while using the universal rules. UF-CSS now includes a brand-neutral theme generator with semantic light/dark colors, basic contrast checks, and adapters for CSS, Bootstrap, StyleX and React Native.

node scripts/generate-project-theme.mjs \
  --config examples/project-theme/theme.json \
  --out ../my-project/styles/uf-css

Use --check to validate outputs and --force only for intentional regeneration. See the theme guide for configuration, import order, accessibility checks and limitations.

AI agent skill

A portable, open Agent Skills workflow helps coding agents audit, generate and migrate design foundations while preserving the project's brand. The canonical instructions live at .agents/skills/universal-foundation-css/SKILL.md.

Install into another project explicitly:

node scripts/install-skill.mjs --target all --project ../your-project

This copies the skill to supported Codex, Claude and Copilot project locations without overwriting an existing skill. Skills are not automatically installed in ChatGPT or every AI product. See AI agent setup.

Inspect an existing project without changing it

node scripts/cli.mjs audit --project ../your-project --format text
node scripts/cli.mjs audit --project ../your-project --format json

The Phase 10 auditor uses bounded, read-only project inspection to report stack/version evidence, CSS token duplication and potential interaction/import issues. It never runs your app, installs packages or changes any files. Its adapter suggestions are optional and require your review. For safe agent adoption and limitations, see the audit guide and AI agents. Unknown versions are never assumed supported.

Prerelease preparation (no publication)

npm ci
npm run verify
npm run verify:release             # build + npm pack --dry-run file manifest checks
node scripts/verify-packed-package.mjs  # independent offline tarball consumer

The Phase 11 release process includes a manual-only prerelease GitHub workflow. The repository package version is 1.0.0 for source testing; the prerelease-only workflow will not publish it, and no npm registry release has been authorized.

Development quality

npm run check:tokens # Canonical generated-output drift check
npm run check  # TypeScript type checking
npm run build  # Compiled .js and .d.ts files
npm test       # Formula, registry and contract tests
npm run verify # Type-check and tests

CI verifies token parity, the TypeScript suite, compiled Tailwind v3/v4, Bootstrap CSS, and StyleX Babel fixtures, plus an Expo SDK 57 Android JavaScript export. A sixth quality workflow now runs Playwright Chromium + axe-core on 25 browser scenarios, captures 12 responsive light/dark screenshots, and checks keyboard interactions and limited WCAG A/AA rules. Use npm ci --prefix integration/browser and npm test --prefix integration/browser after browser setup. Pixel-diff baselines, manual screen readers, true browser zoom and physical Android/iOS device validation are pending; see testing evidence and checklist.

Architecture and roadmap

• Architecture and dependency boundaries
• Grid reference catalog
• Development roadmap
• AI agent compatibility and installation
• Contributing, Security, Code of Conduct

Project identity is separate

An organization-specific design system (such as an AMGYNA design system) may consume UF-CSS and define its own brand, token values, components, fonts, densities and selected grid layouts. UF-CSS must never import or depend on that organization-specific package.

License

Apache License, Version 2.0. See LICENSE. Commercial and personal use are permitted under its terms. Contributions are welcome.

Maintained by kingbattash. Early development; no stable release or support guarantee.