Skip to content

Repository files navigation

Foundations

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.


Table of Contents


Getting Started

  1. Clone the repository:

    git clone https://github.com/significa/foundations.git
    cd foundations
  2. Install Node and pnpm:

    Node and pnpm are pinned in mise.toml (the exact pnpm version is in package.json via packageManager).

    mise install
  3. Install dependencies:

    pnpm install
  4. 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_HOST aren't set, the analytics init is skipped at runtime — local development works without a .env file.

    To enable analytics, copy .env.example to .env and fill in real values.

  5. Start the dev server:

    pnpm dev

    The site will be available at http://localhost:4321.

    Search uses Pagefind, which indexes the production HTML. pnpm dev does not index — open the search dialog and you'll see a hint to run pnpm dev:pagefind instead, which builds, indexes into public/pagefind/, and starts the dev server. Subsequent pnpm dev runs reuse that index until you wipe public/pagefind/.


Authoring

Documentation pages are written in .mdx format. All content is driven by Astro Content Collections, defined in src/content.config.ts.

Folder Structure

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.tsx will be made available as a preview (see "Code Previews" below).

Pages

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

Dependencies Structure

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.

Code Previews

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

Commands

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 with Biome
pnpm lint Run Biome linter with auto-fix (including unsafe fixes)
pnpm check Full CI check: Biome CI, type checking, page deps and knip

Note: pnpm dev does not index Pagefind, so the search dialog will show a "Could not load Pagefind instance" message. Run pnpm dev:pagefind once to build the index — subsequent pnpm dev runs will pick it up from public/pagefind/.


Stack

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)

Linting & Formatting

Biome is the only linter and formatter, .astro files included. Its Astro support (html.experimentalFullSupportEnabled in biome.json) is still marked experimental, so expect occasional formatting changes when Biome is bumped.

License

This project is licensed under the GPL-3.0 License.

Acknowledgments

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.

Used by

Contributors

Languages