Setup

How to setup your project to use Foundations.

Prerequisites

A React 19 project.
Tailwind 4 installed and configured.

We are using React 19. If you still on 18, please check the React 19 migration guide.
A few common changes are:

ref is now a prop like the others, so we don’t need to use forwardRef.

<Context> as a provider: You can now render <Context> as a provider instead of <Context.Provider>.

use can be used instead of useContext.

MutableRefObject is now RefObject.

It’s possible to use these components in React 18, but you will have to adapt the code as needed.

Installation

Install the core dependencies:


          npm install cva@beta tailwind-merge

We are using CVA 1.0.0 (beta). Check what’s new in their docs.

CSS Setup

Pick the strategy that matches your project: respect the user’s OS preference automatically, or expose a manual theme switcher backed by a data-theme attribute on <html>.

@import "tailwindcss";

@theme {
  /* Typography */
  --text-2xs: 0.625rem;

  /* Colors */
  --color-background: light-dark(oklch(100% 0 0), oklch(12% 0 0));
  --color-background-secondary: light-dark(oklch(96% 0 0), oklch(22% 0 0));

  --color-foreground: light-dark(oklch(0% 0 0), oklch(95% 0 0));
  --color-foreground-secondary: light-dark(oklch(65% 0 0), oklch(53% 0 0));

  --color-accent: var(--color-foreground);
  /* Foreground at the end means it is used on top of the accent color */
  --color-accent-foreground: var(--color-background);

  --color-border: light-dark(oklch(94% 0 0), oklch(26% 0 0));

  --color-ring: light-dark(
    color-mix(in oklab, var(--color-accent) 30%, transparent),
    color-mix(in oklab, var(--color-accent) 30%, transparent)
  );

  --color-error: oklch(63.7% 0.237 25.331);
  --color-warning: oklch(79.5% 0.184 86.047);
  --color-success: oklch(69.6% 0.17 162.48);
  --color-info: oklch(62.3% 0.214 259.815);

  /* Border radius — --radius is the dial; --radius-bump compensates squircles in supporting browsers (see @supports below) */
  --radius: 0.125rem;
  --radius-bump: 1;
  --radius-xs: calc(var(--radius) * 1 * var(--radius-bump));
  --radius-sm: calc(var(--radius) * 2 * var(--radius-bump));
  --radius-md: calc(var(--radius) * 3 * var(--radius-bump));
  --radius-lg: calc(var(--radius) * 4 * var(--radius-bump));
  --radius-xl: calc(var(--radius) * 6 * var(--radius-bump));
  --radius-2xl: calc(var(--radius) * 8 * var(--radius-bump));
  --radius-3xl: calc(var(--radius) * 12 * var(--radius-bump));
  --radius-4xl: calc(var(--radius) * 16 * var(--radius-bump));

  /* Panel-item inset, derived from radius (collapses to flush items at --radius: 0) */
  --inset: calc(var(--radius) * 1.5 * var(--radius-bump));

  /* Focus ring */
  --ring-width: 4px;

  /* Corner shape (round | squircle) */
  --corner-shape: squircle;

  /* Shadows */
  --shadow-*: initial;
  --shadow-xs: 0 1px 2px oklch(0 0 0 / 0.03);
  --shadow-sm: 0 1px 2px oklch(0 0 0 / 0.02), 0 2px 4px oklch(0 0 0 / 0.02);
  --shadow-md: 0 2px 3px oklch(0 0 0 / 0.02), 0 3px 6px oklch(0 0 0 / 0.02);
  --shadow-lg: 0 2px 4px oklch(0 0 0 / 0.02), 0 4px 8px oklch(0 0 0 / 0.02), 0 8px 16px oklch(0 0 0 / 0.02);

  /* easings */
  --ease-emphasized-accelerate: cubic-bezier(0.3, 0, 0.8, 0.15);
  --ease-emphasized-decelerate: cubic-bezier(0.05, 0.7, 0.1, 1);
}

@media (prefers-color-scheme: dark) {
  body {
    color-scheme: dark;
  }
}

/* prettier-ignore */
@utility mix-with-* {
  --color-mix-with: --value(--color-*, [*]);
}

/* prettier-ignore */
@utility border-mix-* {
  border-color: color-mix(
    in oklab,
    --value(--color-*, [*]),
    var(--color-mix-with, var(--color-foreground)) calc(--modifier(integer) * 1%)
  );
}

/* prettier-ignore */
@utility bg-mix-* {
  background-color: color-mix(
    in oklab,
    --value(--color-*, [*]),
    var(--color-mix-with, var(--color-foreground)) calc(--modifier(integer) * 1%)
  );
}

/* Squircles where supported, with a carve-out for full circles and a radius bump to match perceived roundness */
* {
  corner-shape: var(--corner-shape);
}
.rounded-full {
  corner-shape: round;
}
@supports (corner-shape: squircle) {
  :root {
    --radius-bump: 1.6;
  }
}

body {
  font-family: var(--font-ui);

  background-color: var(--color-background);
  color: var(--color-foreground);

  -webkit-font-smoothing: antialiased;
  -moz-osx-font-smoothing: grayscale;
}

Utilities Setup

Create a lib/utils.ts file with our utility functions:

import { defineConfig } from 'cva';
import { twMerge } from 'tailwind-merge';

export const {
  cva,
  cx: cn,
  compose,
} = defineConfig({
  hooks: {
    onComplete: (className) => twMerge(className),
  },
});

Icons Setup

We use Phosphor Icons by default, but you can use any icon library of your choice:


          npm install @phosphor-icons/react

useTopLayer

Avatar