Foundations is an opinionated collection of components, patterns, and guidelines for building consistent and accessible user interfaces. Inspired by projects like shadcn, the goal is to allow developers to copy components into their projects and customize them as needed, or simply take inspiration to build their own versions.
Clone the repository:
git clone https://github.com/significa/foundations.git cd foundationsEnable pnpm via Corepack:
This project uses pnpm (version pinned in
package.jsonviapackageManager). Node version is specified in.nvmrc.corepack enable pnpmInstall dependencies:
pnpm install
Set up environment variables (optional):
The project ships with no required environment variables. PostHog analytics is the only thing that uses them, and if
POSTHOG_KEY/POSTHOG_HOSTaren't set, the analytics init is skipped at runtime — local development works without a.envfile.To enable analytics, copy
.env.exampleto.envand fill in real values.Start the dev server:
pnpm dev
The site will be available at
http://localhost:4321.Search uses Pagefind, which indexes the production HTML.
pnpm devdoes not index — open the search dialog and you'll see a hint to runpnpm dev:pagefindinstead, which builds, indexes intopublic/pagefind/, and starts the dev server. Subsequentpnpm devruns reuse that index until you wipepublic/pagefind/.
Documentation pages are written in .mdx format. All content is driven by Astro Content Collections, defined in src/content.config.ts.
The src/foundations folder contains all the foundational content and follows a specific convention:
page.mdx: Used to create the documentation page.- Source files are added to the root of the folder.
- Any file ending in
.preview.tsxwill be made available as a preview (see "Code Previews" below).
Each page.mdx file should include the following metadata structure:
| Field | Type | Description | Required |
|---|---|---|---|
title | String | The title of the docs page. | Yes |
description | String | A brief description of the docs page. | Yes |
preview | String | The slug of a "Code Preview" to be used as a cover. | No |
files | Array | List of source files. | No |
dependencies | Array | List of dependencies, each with a name and href. | No |
folder | String | Used for sidebar organization. | No |
Each dependency in the dependencies array should have the following structure:
| Field | Type | Description | Required |
|---|---|---|---|
name | String | The name of the dependency. | Yes |
href | String | URL to the dependency. | Yes |
This metadata is crucial for ensuring that each documentation page is properly structured and provides all necessary information.
While developing, you can visit /preview/[slug] to open a [slug].preview.tsx file. This makes it easier to develop in isolation.
A preview file can optionally export a meta object to control how it is displayed.
| Option | Values | Default | Description |
|---|---|---|---|
layout | 'centered''fullscreen''padded' | 'centered' | Controls how the preview is framed inside its container |
mode | 'inline''iframe' | 'iframe' | Whether the preview renders inline or inside an iframe in docs pages |
| Command | Description |
|---|---|
pnpm dev | Start the Astro development server |
pnpm dev:pagefind | Build the site and start a dev server with Pagefind search working |
pnpm build | Build for production (includes Pagefind indexing via postbuild) |
pnpm preview | Preview the production build locally |
pnpm types:check | Run astro sync and TypeScript type checking |
pnpm format | Auto-format all files (Biome for TS/TSX/CSS, Prettier for .astro) |
pnpm lint | Run Biome linter with auto-fix (including unsafe fixes) |
pnpm check | Full CI check: Biome CI + Prettier check on .astro + type checking |
Note:
pnpm devdoes not index Pagefind, so the search dialog will show a "Could not load Pagefind instance" message. Runpnpm dev:pagefindonce to build the index — subsequentpnpm devruns will pick it up frompublic/pagefind/.
| Tool | Purpose |
|---|---|
| Astro | Core framework — static site generation, routing, MDX, content collections |
| React 19 | Interactive islands (component previews, search, menus, etc.) |
| Tailwind CSS v4 | Utility-first styling via the Vite plugin |
| MDX | Markdown + JSX for content pages (page.mdx files) |
| Pagefind | Static full-text search, indexed at build time |
| Phosphor Icons | Icon library |
| Shiki | Syntax highlighting (themes: kanagawa-lotus / github-dark) |
This project uses both Biome and Prettier — by design, not by accident.
Biome does not yet support .astro files. Prettier, with the prettier-plugin-astro plugin, fills that gap. Once Biome adds support for .astro files, we should remove Prettier and consolidate on Biome for all formatting and linting needs.
This project is licensed under the GPL-3.0 License.
Shadcn and Lucia Auth serve as excellent examples of robust foundational platforms that people can use to build upon. This project aspires to combine the strengths of both by offering ready-to-use components alongside detailed guides and recipes, simplifying the process of kickstarting any project.
For more details, refer to the codebase and explore the components and patterns provided.
Built by Significa.