vite-plugin-capsize-radix

Generate bulletproof typography css for @radix-ui/themes

Now changing fonts is as easy as changing colors.

Why

Getting fonts to look right on the web is _hard_ — so most peoply rely on
a few typography frameworks and fonts. But it doesn't have to be that way.
Capsize fixes text sizing and layout
allowing for precise text alignment so changing fonts is as easy as changing
colors.

https://github.com/KyleAMathews/vite-plugin-capsize-radix-ui/assets/71047/3ec5d6ca-bf00-4b79-8552-4e3da3454f52

Capsize makes fonts render the way you expect them to. With Capsize, if you
assign a font to occupy 16px of height, it _actually_ will.

This plugin glues Capsize with the fantastic Radix theming components.

Similar plugins could be built for other meta-frameworks & component libraries — open an issue
if you're interested on collaborating on one.

How to use

$3

npm install vite-plugin-capsize-radix

$3

A sample React config:

``ts
import { defineConfig } from "vite"
import react from "@vitejs/plugin-react-swc"
import { capsizeRadixPlugin } from "vite-plugin-capsize-radix"
import merriweather from "@capsizecss/metrics/merriweather"
import merriweatherSans from "@capsizecss/metrics/merriweatherSans"
import sourceCodePro from "@capsizecss/metrics/sourceCodePro"
import arial from "@capsizecss/metrics/arial"

export default defineConfig({
plugins: [
react(),
capsizeRadixPlugin({
// Import this file into your app after you import Radix's CSS.
outputPath: ./public/merriweather.css,
// Pass in Capsize font metric objects.
defaultFontStack: [merriweather, arial],
headingFontStack: [merriweatherSans, arial],
codingFontStack: [sourceCodePro, arial],
}),
],
})
`

$3

For open source fonts, use @fontsource:

`bash
pnpm add @fontsource/merriweather @fontsource/merriweather-sans @fontsource/source-code-pro
`

$3

In your entry file (e.g., main.tsx), the import order matters:

`typescript
// 1. Radix base styles FIRST
import "@radix-ui/themes/styles.css"

// 2. Your font CSS from Fontsource
import "@fontsource/merriweather/latin.css"

// 3. Generated typography CSS LAST (overrides Radix variables)
import "/merriweather.css"
`

Critical: The generated typography CSS must come AFTER @radix-ui/themes/styles.css to properly override the CSS variables.

$3

This plugin overrides all typography related CSS for Radix so you can simply
use their typography components as normal (e.g. , , , etc)

The plugin sets the variables for Radix's Type scale and Font family for Radix.
It doesn't set Font weight. It sets the strong, em, and quote to use the default font family.
You can set the default, heading, and coding font stacks separately.

See e.g. the documentation for .

They all share a size prop from "1" to "10". This corresponds to the optional
fontSizes array passed to the plugin e.g. size="0" is the first value of
the array, etc. defaults to size="2" and defaults to
size="6".

$3

Because Capsize trims the invisible whitespace above and below text, adjacent text elements will sit directly against each other without any natural spacing. This is by design—it gives you precise control over layout.

You must explicitly add spacing between text elements using :

`tsx
// Without gap - heading and text will touch

Title
Body text...


// With gap - natural spacing between elements

Title
Body text...

`

$3

Capsize trims text to the cap-height (top) and alphabetic baseline (bottom). This can clip descenders (the tails of letters like "g", "y", "p") on large headings with tight line-heights.

Add the preserve-descenders class to keep descenders visible:

`tsx

Signal Sky

`

This disables the bottom trim while keeping the top tight.

$3

Another great freebie Capsize gives you is it automatically generates CSS for
aligning your fallback font with your main font, which can dramatically improve
the Cumulative Layout Shift metric for sites that depend on a web font

$3

Capsize has precalculated metrics for system and many open source fonts. If you're
using a custom font, you can calculate the font metrics using their @capsizecss/unpack package.

Responsive styles

This plugin automatically generates responsive styles. Typically you want your mobile font-size
to be slightly smaller than on desktop. We do that by shifting the text a size smaller on mobile.

Parameters:

- outputPath (string): Required. The file path where the generated CSS or design tokens should be saved.
- textStyles (TextStyle[]): Optional. An array of objects, each representing a text style. Each object contains two properties: fontSize and lineHeight, which are numerical values, pixels for fontSize and pixels or relative value for lineHeight. Defaults to:
`ts
;[
{ fontSize: 9, lineHeight: 19 },
{ fontSize: 11, lineHeight: 23 },
{ fontSize: 12, lineHeight: 25 },
{ fontSize: 14, lineHeight: 28 },
{ fontSize: 18, lineHeight: 30 },
{ fontSize: 24, lineHeight: 36 },
{ fontSize: 36, lineHeight: 44 },
{ fontSize: 48, lineHeight: 52 },
{ fontSize: 64, lineHeight: 64 },
]
`
- defaultFontStack (FontMetrics[]): Optional. An array of FontMetrics objects. Defaults to a System Font stack.
- headingFontStack (FontMetrics[]): Optional. An array of FontMetrics objects. Defaults to your defaultFontStack.
- codingFontStack (FontMetrics[]): Optional. An array of FontMetrics objects. Defaults to your defaultFontStack`.