Skip to main content
Fonttrio is an open-source project, and we welcome contributions from the community. Whether you want to suggest a new font pairing, report a bug, or improve the codebase, your help is appreciated.

​
Ways to Contribute

Suggest Pairings

Have a font combination that works beautifully together? Share it with the community.

Report Issues

Found a bug or have a feature request? Open an issue on GitHub.

Improve Docs

Help make the documentation clearer and more helpful.

Code Contributions

Contribute to the codebase with bug fixes or new features.

​
Suggesting New Font Pairings

We’re always looking for high-quality font combinations to add to Fonttrio. Here’s how to suggest a new pairing:
1

Check Existing Pairings

Browse the current collection to ensure your pairing isn’t already included. We currently have 49 curated pairings.
2

Test Your Combination

Make sure your font pairing:
  • Works well together (heading + body + mono)
  • Is available on Google Fonts
  • Has good readability at various sizes
  • Works in both light and dark modes
3

Open an Issue

Create a new issue on GitHub with:
  • Heading font name and link to Google Fonts
  • Body font name and link to Google Fonts
  • Monospace font name and link to Google Fonts
  • Category (Editorial, Clean, Bold, Corporate, Creative)
  • Use case (blog, landing page, documentation, etc.)
  • Why this combination works well
4

Wait for Review

The maintainers will review your suggestion and provide feedback. If approved, it will be added to the collection.
All fonts must be available on Google Fonts to ensure they work with the next/font integration.

​
Reporting Issues

Found a bug or have a suggestion? Here’s how to report it:

​
Before Opening an Issue

  • Search existing issues to avoid duplicates
  • Check if the issue persists in the latest version
  • Gather relevant information (browser, OS, Next.js version)

​
Opening an Issue

  1. Go to GitHub Issues
  2. Click “New Issue”
  3. Provide a clear, descriptive title
  4. Include:
    • Steps to reproduce
    • Expected behavior
    • Actual behavior
    • Screenshots (if applicable)
    • Environment details

​
Code Contributions

Want to contribute code? Here’s how to get started:

​
Development Setup

1

Fork and Clone

git clone https://github.com/YOUR_USERNAME/fonttrio.git
cd fonttrio
2

Install Dependencies

Fonttrio uses Bun as the package manager:
bun install
3

Run Development Server

bun run dev
Open http://localhost:3000 in your browser.

​
Project Structure

fonttrio/
├── registry/
│   ├── fonts/          # Individual font configurations
│   └── pairings/       # Font pairing combinations
├── scripts/
│   ├── build-registry.ts       # Builds registry.json
│   ├── generate-fonts.ts       # Generates font configs
│   └── sync-pairings-data.ts   # Syncs pairing data
├── public/r/           # Public registry files
└── app/                # Next.js application

​
Adding a New Pairing

To add a new font pairing to the registry:
  1. Create a pairing file in registry/pairings/your-pairing.json:
{
  "name": "pairing-your-name",
  "type": "registry:style",
  "extends": "none",
  "title": "Your Pairing — Heading Font + Body Font + Mono Font",
  "description": "Brief description of the pairing and its use case.",
  "categories": ["category1", "category2"],
  "registryDependencies": [
    "https://www.fonttrio.xyz/r/heading-font.json",
    "https://www.fonttrio.xyz/r/body-font.json",
    "https://www.fonttrio.xyz/r/mono-font.json"
  ],
  "cssVars": {
    "theme": {
      "--font-heading": "var(--font-heading-name)",
      "--font-body": "var(--font-body-name)",
      "--font-mono": "var(--font-mono-name)"
    }
  },
  "meta": {
    "mood": ["elegant", "modern"],
    "useCase": ["blog", "documentation"]
  }
}
  1. Build the registry:
bun run build:registry
  1. Test your pairing by installing it in a test project:
npx shadcn@latest add https://www.fonttrio.xyz/r/your-pairing.json

​
Code Style

  • Use TypeScript for all new code
  • Follow the existing code style
  • Run bun run lint before committing
  • Keep commits focused and atomic
  • Write clear commit messages

​
Available Scripts

  • bun run dev — Start development server
  • bun run build — Build for production
  • bun run lint — Run ESLint
  • bun run generate:fonts — Generate font configurations
  • bun run generate:candidates — Generate pairing candidates
  • bun run sync:pairings — Sync pairing data
  • bun run build:registry — Build registry.json

​
Pull Request Process

1

Create a Branch

git checkout -b feature/your-feature-name
2

Make Your Changes

Write your code, following the code style guidelines.
3

Test Thoroughly

Ensure your changes work as expected and don’t break existing functionality.
4

Commit Your Changes

git add .
git commit -m "feat: add your feature"
5

Push and Create PR

git push origin feature/your-feature-name
Then open a Pull Request on GitHub with a clear description of your changes.

​
Commit Message Convention

Use conventional commit messages:
  • feat: — New feature
  • fix: — Bug fix
  • docs: — Documentation changes
  • refactor: — Code refactoring
  • chore: — Maintenance tasks

​
Questions?

If you have questions about contributing:

​
License

By contributing to Fonttrio, you agree that your contributions will be licensed under the MIT License.
Thank you for helping make Fonttrio better!

Build docs developers (and LLMs) love

Get started for freeTalk to us