Skip to content
FoundryFoundry — home
Search

Introduction

Installation

Stable

What Foundry needs, what it deliberately avoids, and how the token file connects to Tailwind.

Updated in v1.0.0

There is no package to install

Foundry is a template demonstration. `npm install foundry` will not get you this library — the code is copied, not installed. That is a deliberate trade: you own the source and can change it, and in exchange you do not get automatic upstream fixes.

Requirements

The component layer needs React 19 and a Tailwind v4 build. Everything else on this list is either optional or build-time only.

  • Package
    react
    Version
    19.x
    Why
    Required. Server Components and the modern ref API.
  • Package
    react-dom
    Version
    19.x
    Why
    Required. Overlays use createPortal.
  • Package
    next
    Version
    16.x
    Why
    Only for the starters and this documentation site. The primitives are plain React.
  • Package
    lucide-react
    Version
    1.x
    Why
    Icons. Swappable — every icon is imported by name at the point of use.
  • Package
    tailwindcss
    Version
    4.x
    Why
    Build-time only. Nothing ships to the browser.

The token file

Copy src/app/globals.css and import it once, at the root of your application. It contains three things:

  1. The token declarations, organised by scheme, palette and density
  2. A @theme inline block that exposes every token to Tailwind, so bg-surface, text-ink-muted and h-control all work
  3. A small base layer: focus treatment, reduced motion, prose typography

The theme script

Scheme, palette and density are read from localStorage by a blocking script in <head>, so they are applied before first paint. Without it you will see a flash of the wrong theme on every load. The script is in src/lib/theme.ts and is deliberately written as a string, because it has to run before any bundle exists.

What Foundry does not install

  • No state management library — component state is local, page state is in the URL
  • No styling runtime — Tailwind compiles away entirely
  • No animation library — transitions are CSS, and stop under reduced motion
  • No charting library — the one chart in the catalogue is inline SVG plus a data table
  • No component library underneath — the primitives are the bottom of the stack

Adapting a starter

The starters are route tables plus a renderer, not ten codebases. To adapt one, copy the route definition you want from src/lib/starters/index.ts, the shell from src/components/starter-kit/, and the blocks the routes name. Everything else is already in the component and section catalogues.