Getting Started

v0.1.0

Install Perimeter Church's shadcn-compatible components directly into your project. You own the source — customize everything.

Prerequisites

Node.js

v18 or later

pnpm

Package manager

shadcn

Tailwind CSS v4 + TypeScript

1. Configure the Registry

Add the Perimeter registry to your project's components.json:

json

{
  "registries": {
    "perimeter": {
      "url": "https://style.perimeter.org/r"
    }
  }
}

2. Install Components

Add individual components with the shadcn CLI. Each component copies its source into your project with all dependencies:

bash

pnpm dlx shadcn@latest add @perimeter/button

Or install the full base set — all 55 components, tokens, and utilities in one command:

bash

pnpm dlx shadcn@latest add @perimeter/perimeter-base

Browse all available components in the component library.

3. Use in Your Code

Import installed components from your project's component directory. They work like any other React component:

tsx

import { Button } from "@/components/ui/button"
import { Card, CardHeader, CardTitle, CardContent } from "@/components/ui/card"

export function MyPage() {
  return (
    <Card>
      <CardHeader>
        <CardTitle>Welcome</CardTitle>
      </CardHeader>
      <CardContent>
        <p>Your content here.</p>
        <Button variant="default">Get Started</Button>
      </CardContent>
    </Card>
  )
}

Theming

The default palette is a warm stone theme in OKLCH color space. Project-specific themes override selected tokens while inheriting everything else.

Apply a Project Theme

Set the data-theme attribute on your root element:

tsx

<html data-theme="metrics">
  <body>
    {/* Components automatically use the metrics color palette */}
  </body>
</html>

defaultperimeter-apimetrics

Dark Mode

Toggle dark mode by adding the .dark class. This works independently of project themes:

tsx

<html class="dark">
  <body>
    {/* All components switch to dark variants */}
  </body>
</html>

{/* Combine with a project theme */}
<html class="dark" data-theme="perimeter-api">
  <body>
    {/* Dark mode + project-specific colors */}
  </body>
</html>

Create a Custom Theme

Add a JSON file to registry/themes/ with your overrides. Only specify the tokens you want to change — everything else inherits from the default palette: