Installation Guide
Getting Started
Get up and running with @freehold/ui in your React project. This guide covers installation, configuration, and your first component.
Requirements
Required
- React 18.0+ or React 19.0+
- Tailwind CSS 3.4+
- TypeScript 5.0+ (recommended)
Recommended
- Next.js 14+ (App Router)
- Node.js 18+
1. Installation
Install the package using your preferred package manager:
npm
npm install @freehold/ui
pnpm
pnpm add @freehold/ui
yarn
yarn add @freehold/ui
2. Optional Dependencies
Some components require additional peer dependencies. Install only what you need:
ChartsBarChart, LineChart, PieChart
npm install recharts
Rich TextRichTextEditor
npm install @tiptap/react @tiptap/pm @tiptap/starter-kit @tiptap/extension-link @tiptap/extension-placeholder
3. Tailwind CSS Configuration
Add the Freehold theme to your tailwind.config.ts:
tailwind.config.ts
import type { Config } from 'tailwindcss'
const config: Config = {
content: [
'./src/**/*.{js,ts,jsx,tsx,mdx}',
// Include @freehold/ui components
'./node_modules/@freehold/ui/dist/**/*.{js,mjs}',
],
theme: {
extend: {
colors: {
background: {
primary: '#FAF9F6',
secondary: '#F5F3EF',
tertiary: '#EFECE6',
elevated: '#FFFFFF',
},
sand: {
50: '#F9F7F4',
100: '#F2EDE6',
200: '#E5DDD1',
300: '#D4C8B8',
400: '#C4B49E',
500: '#B8A48E',
600: '#A08A6E',
700: '#86715A',
800: '#6B5A48',
900: '#544737',
},
text: {
primary: '#2C2824',
secondary: '#5C574F',
tertiary: '#8A847A',
inverse: '#FAF9F6',
},
},
fontFamily: {
heading: ['"DM Serif Display"', 'Georgia', 'serif'],
body: ['"DM Sans"', 'system-ui', 'sans-serif'],
mono: ['"JetBrains Mono"', 'Consolas', 'monospace'],
},
borderRadius: {
DEFAULT: '0.5rem',
md: '0.625rem',
lg: '0.875rem',
},
boxShadow: {
'warm-sm': '0 1px 2px 0 rgba(184, 164, 142, 0.05), 0 1px 3px 0 rgba(44, 40, 36, 0.04)',
warm: '0 2px 4px 0 rgba(184, 164, 142, 0.08), 0 4px 8px 0 rgba(44, 40, 36, 0.04)',
'warm-md': '0 4px 6px -1px rgba(184, 164, 142, 0.1), 0 6px 12px -2px rgba(44, 40, 36, 0.05)',
'warm-lg': '0 8px 16px -4px rgba(184, 164, 142, 0.12), 0 12px 24px -6px rgba(44, 40, 36, 0.06)',
elevated: '0 4px 8px 0 rgba(184, 164, 142, 0.08), 0 8px 16px -4px rgba(44, 40, 36, 0.06)',
},
},
},
plugins: [],
}
export default config
4. Font Setup
Freehold uses three fonts. Add them to your project via Google Fonts or local files.
Option A: Google Fonts (Next.js)
app/layout.tsx
// app/layout.tsx
import { DM_Serif_Display, DM_Sans, JetBrains_Mono } from 'next/font/google'
const dmSerif = DM_Serif_Display({
subsets: ['latin'],
weight: '400',
variable: '--font-heading',
})
const dmSans = DM_Sans({
subsets: ['latin'],
variable: '--font-body',
})
const jetbrains = JetBrains_Mono({
subsets: ['latin'],
variable: '--font-mono',
})
export default function RootLayout({ children }) {
return (
<html className={`${dmSerif.variable} ${dmSans.variable} ${jetbrains.variable}`}>
<body className="font-body">{children}</body>
</html>
)
}
Option B: CDN Link
index.html
<link rel="preconnect" href="https://fonts.googleapis.com">
<link rel="preconnect" href="https://fonts.gstatic.com" crossorigin>
<link href="https://fonts.googleapis.com/css2?family=DM+Sans:wght@400;500;600;700&family=DM+Serif+Display&family=JetBrains+Mono:wght@400;500&display=swap" rel="stylesheet">
5. Import Styles
Import the component styles in your app entry point:
app/layout.tsx
// app/layout.tsx or _app.tsx
import '@freehold/ui/styles.css'
import './globals.css' // Your Tailwind styles
6. Quick Start
You're ready! Import and use components:
app/page.tsx
import { Button, Card, CardContent, Badge } from '@freehold/ui'
export default function MyPage() {
return (
<Card variant="elevated" padding="lg">
<CardContent>
<Badge variant="approved" className="mb-3">New</Badge>
<h2 className="font-heading text-xl text-text-primary mb-2">
Welcome to Freehold
</h2>
<p className="text-text-secondary mb-4">
Your components are ready to use.
</p>
<Button variant="primary">Get Started</Button>
</CardContent>
</Card>
)
}