> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/kapishdima/fonttrio/llms.txt
> Use this file to discover all available pages before exploring further.

# Installation

> Detailed installation instructions for Fonttrio font pairings in Next.js projects.

# Installation

This guide covers everything you need to know about installing and setting up Fonttrio in your project.

## Requirements

Before installing Fonttrio, ensure your project meets these requirements:

<CardGroup cols={3}>
  <Card title="Next.js 14+" icon="react">
    App Router required for `next/font` support
  </Card>

  <Card title="shadcn/ui" icon="component">
    CLI must be installed and configured
  </Card>

  <Card title="Tailwind CSS" icon="paintbrush">
    Required for utility classes
  </Card>
</CardGroup>

<Note>
  Fonttrio uses the shadcn/ui registry system, which requires the shadcn CLI to be installed in your project.
</Note>

## Prerequisites Setup

If you're starting a new project, follow these steps:

<Steps>
  <Step title="Create a Next.js project">
    Create a new Next.js 14+ project with the App Router:

    ```bash theme={null}
    npx create-next-app@latest my-app
    ```

    When prompted, select:

    * ✅ TypeScript
    * ✅ Tailwind CSS
    * ✅ App Router
  </Step>

  <Step title="Initialize shadcn/ui">
    Install and configure shadcn/ui in your project:

    ```bash theme={null}
    npx shadcn@latest init
    ```

    This will:

    * Install required dependencies
    * Create `components.json` configuration
    * Set up your `components/ui` directory
    * Configure your `tailwind.config` and `globals.css`
  </Step>

  <Step title="Verify setup">
    Ensure your project has these files:

    * `app/layout.tsx` - App Router layout
    * `app/globals.css` - Global styles
    * `components.json` - shadcn configuration
    * `tailwind.config.ts` - Tailwind configuration
  </Step>
</Steps>

## Installing a Font Pairing

<Steps>
  <Step title="Browse available pairings">
    Visit [fonttrio.xyz](https://www.fonttrio.xyz) to browse all 49 curated pairings. Each pairing page includes:

    * Live preview with actual fonts
    * Typography scale visualization
    * Interactive type tester
    * Context previews (blog, landing, docs)
    * One-click copy install command
  </Step>

  <Step title="Copy the install command">
    Each pairing has a unique registry URL. The install command follows this pattern:

    ```bash theme={null}
    npx shadcn@latest add https://www.fonttrio.xyz/r/{pairing-name}.json
    ```

    For example, to install the Editorial pairing:

    <CodeGroup>
      ```bash npm theme={null}
      npx shadcn@latest add https://www.fonttrio.xyz/r/editorial.json
      ```

      ```bash pnpm   theme={null}
      pnpm dlx shadcn@latest add https://www.fonttrio.xyz/r/editorial.json
      ```

      ```bash yarn theme={null}
      yarn dlx shadcn@latest add https://www.fonttrio.xyz/r/editorial.json
      ```

      ```bash bun theme={null}
      bunx shadcn@latest add https://www.fonttrio.xyz/r/editorial.json
      ```
    </CodeGroup>
  </Step>

  <Step title="What gets installed">
    The shadcn CLI will:

    1. **Download font configurations** from the Fonttrio registry
    2. **Install three fonts** (heading, body, mono) via `next/font/google`
    3. **Add CSS variables** to your `app/globals.css`:
       ```css theme={null}
       :root {
         --font-heading: var(--font-playfair-display);
         --font-body: var(--font-source-serif-4);
         --font-mono: var(--font-jetbrains-mono);
       }
       ```
    4. **Apply typography scale** with optimized sizing:
       ```css theme={null}
       h1 {
         font-family: var(--font-heading);
         font-size: 2.25rem;
         line-height: 1.2;
         letter-spacing: -0.025em;
         font-weight: 700;
       }
       ```
    5. **Configure font loading** in your root layout
  </Step>

  <Step title="Verify installation">
    Check your `app/globals.css` file. You should see:

    * Font variable declarations in `:root`
    * Typography scale styles for h1-h6
    * Body and code font assignments

    Example output for the Editorial pairing:

    ```css theme={null}
    /* Font variables */
    :root {
      --font-heading: var(--font-playfair-display);
      --font-body: var(--font-source-serif-4);
      --font-mono: var(--font-jetbrains-mono);
    }

    /* Typography scale */
    h1 {
      font-family: var(--font-heading);
      font-size: 2.25rem;
      line-height: 1.2;
      letter-spacing: -0.025em;
      font-weight: 700;
    }

    h2 {
      font-family: var(--font-heading);
      font-size: 1.875rem;
      line-height: 1.25;
      letter-spacing: -0.02em;
      font-weight: 600;
    }

    /* ... more styles ... */

    body, p {
      font-family: var(--font-body);
      line-height: 1.65;
    }

    code, pre {
      font-family: var(--font-mono);
    }
    ```
  </Step>
</Steps>

## Registry Structure

Each pairing is distributed as a JSON registry item:

```json theme={null}
{
  "name": "pairing-editorial",
  "type": "registry:style",
  "extends": "none",
  "title": "Editorial — Playfair Display + Source Serif 4 + JetBrains Mono",
  "description": "Classic editorial pairing. High-contrast serif headings with readable serif body text.",
  "categories": ["serif", "editorial", "elegant"],
  "registryDependencies": [
    "https://www.fonttrio.xyz/r/playfair-display.json",
    "https://www.fonttrio.xyz/r/source-serif-4.json",
    "https://www.fonttrio.xyz/r/jetbrains-mono.json"
  ],
  "cssVars": {
    "theme": {
      "--font-heading": "var(--font-playfair-display)",
      "--font-body": "var(--font-source-serif-4)",
      "--font-mono": "var(--font-jetbrains-mono)"
    }
  },
  "css": {
    "h1": {
      "font-family": "var(--font-heading)",
      "font-size": "2.25rem",
      "line-height": "1.2",
      "letter-spacing": "-0.025em",
      "font-weight": "700"
    }
    // ... more styles
  },
  "meta": {
    "mood": ["elegant", "traditional", "authoritative"],
    "useCase": ["blog", "editorial", "magazine", "documentation"]
  }
}
```

## Using Fonts in Your App

After installation, fonts are available throughout your project:

### Automatic HTML Element Styling

The typography scale automatically styles HTML elements:

```tsx theme={null}
export default function Page() {
  return (
    <div>
      <h1>This uses --font-heading</h1>
      <h2>This also uses --font-heading</h2>
      <p>This uses --font-body</p>
      <code>This uses --font-mono</code>
    </div>
  )
}
```

### Using CSS Variables Directly

For custom components, use the CSS variables with Tailwind:

```tsx theme={null}
export default function CustomCard() {
  return (
    <div className="font-[family-name:var(--font-body)]">
      <h3 className="font-[family-name:var(--font-heading)] text-2xl">
        Card Title
      </h3>
      <p className="text-muted-foreground">
        Card description text
      </p>
    </div>
  )
}
```

### In Tailwind Config

You can also extend your Tailwind config to create utility classes:

```ts theme={null}
// tailwind.config.ts
export default {
  theme: {
    extend: {
      fontFamily: {
        heading: 'var(--font-heading)',
        body: 'var(--font-body)',
        mono: 'var(--font-mono)',
      },
    },
  },
}
```

Then use them as Tailwind classes:

```tsx theme={null}
<h1 className="font-heading">Heading</h1>
<p className="font-body">Body text</p>
<code className="font-mono">Code</code>
```

## Installing Multiple Pairings

You can install multiple pairings in the same project:

```bash theme={null}
npx shadcn@latest add https://www.fonttrio.xyz/r/editorial.json
npx shadcn@latest add https://www.fonttrio.xyz/r/minimal.json
npx shadcn@latest add https://www.fonttrio.xyz/r/corporate.json
```

All fonts will be loaded, and you can switch between pairings by updating the CSS variables:

```css theme={null}
/* Use Editorial */
:root {
  --font-heading: var(--font-playfair-display);
  --font-body: var(--font-source-serif-4);
  --font-mono: var(--font-jetbrains-mono);
}

/* Or use Minimal */
:root {
  --font-heading: var(--font-inter);
  --font-body: var(--font-inter);
  --font-mono: var(--font-jetbrains-mono);
}
```

## Customizing Typography Scale

You can customize the typography scale by editing `globals.css`:

```css theme={null}
h1 {
  font-family: var(--font-heading);
  font-size: 3rem; /* Increased from 2.25rem */
  line-height: 1.1; /* Tightened from 1.2 */
  letter-spacing: -0.03em; /* More negative spacing */
  font-weight: 800; /* Bolder */
}
```

## Troubleshooting

<AccordionGroup>
  <Accordion title="Fonts not loading">
    **Symptom:** Fonts don't appear after installation.

    **Solutions:**

    1. Clear your browser cache and hard refresh (Cmd/Ctrl + Shift + R)
    2. Restart your Next.js dev server
    3. Check that CSS variables are present in `globals.css`
    4. Verify `next/font` is working:
       ```bash theme={null}
       npm list next
       ```
    5. Check browser console for font loading errors
  </Accordion>

  <Accordion title="CSS variables not found">
    **Symptom:** Console shows "CSS variable not found" errors.

    **Solutions:**

    1. Verify the pairing was installed:
       ```bash theme={null}
       cat app/globals.css | grep "font-heading"
       ```
    2. Ensure `globals.css` is imported in your root layout:
       ```tsx theme={null}
       // app/layout.tsx
       import './globals.css'
       ```
    3. Check CSS variable syntax - should use `var(--font-heading)` not `--font-heading`
  </Accordion>

  <Accordion title="Typography scale not applying">
    **Symptom:** HTML elements don't have the expected styling.

    **Solutions:**

    1. Check CSS specificity - your custom styles may be overriding Fonttrio
    2. Ensure no other CSS is resetting h1-h6 styles
    3. Verify the typography scale CSS is present after the variables in `globals.css`
    4. Try using `!important` temporarily to diagnose specificity issues
  </Accordion>

  <Accordion title="shadcn CLI errors">
    **Symptom:** `shadcn add` command fails.

    **Solutions:**

    1. Verify shadcn is initialized:
       ```bash theme={null}
       cat components.json
       ```
    2. Update to latest shadcn version:
       ```bash theme={null}
       npm install -g shadcn@latest
       ```
    3. Check internet connection - registry must be reachable
    4. Try with full URL including `.json` extension
  </Accordion>

  <Accordion title="Font weights look wrong">
    **Symptom:** Fonts appear too bold or too light.

    **Solutions:**

    1. Check which font weights are loaded in the registry JSON
    2. Google Fonts may not include all weights for every font
    3. Customize weight in your CSS:
       ```css theme={null}
       h1 {
         font-weight: 600; /* Adjust as needed */
       }
       ```
    4. Some fonts have optical size variants - check if that's enabled
  </Accordion>

  <Accordion title="Performance issues">
    **Symptom:** Slow page loads or layout shift.

    **Solutions:**

    1. Fonttrio uses `next/font` which includes automatic optimization
    2. Fonts are loaded from Google Fonts CDN with optimal caching
    3. Reduce number of font weights if performance is critical
    4. Use `font-display: swap` (default in next/font)
    5. Consider font subsetting for non-Latin characters
  </Accordion>
</AccordionGroup>

## Best Practices

<CardGroup cols={2}>
  <Card title="Font Loading" icon="bolt">
    * Let `next/font` handle optimization
    * Don't manually load Google Fonts
    * Keep font weights minimal (2-3 max)
    * Use variable fonts when available
  </Card>

  <Card title="CSS Variables" icon="code">
    * Use the provided variables consistently
    * Don't hardcode font family names
    * Extend in Tailwind config for convenience
    * Document any customizations
  </Card>

  <Card title="Typography Scale" icon="text-size">
    * Maintain consistent scale ratios
    * Test at different viewport sizes
    * Use relative units (rem) for accessibility
    * Keep line heights readable (1.5-1.65 for body)
  </Card>

  <Card title="Customization" icon="wrench">
    * Start with defaults, then customize
    * Test changes across all components
    * Document your scale in design system
    * Consider dark mode contrast
  </Card>
</CardGroup>

## Next Steps

<CardGroup cols={3}>
  <Card title="Quickstart" icon="rocket" href="/quickstart">
    Get started in under 2 minutes
  </Card>

  <Card title="Browse Pairings" icon="grid" href="https://www.fonttrio.xyz">
    Explore all 49 curated pairings
  </Card>

  <Card title="Examples" icon="code">
    See real-world usage examples
  </Card>
</CardGroup>

<Warning>
  **License Note:** All fonts distributed through Fonttrio are from Google Fonts and are open source. Check individual font licenses for commercial use terms.
</Warning>