### Installation

Source: https://github.com/seek-oss/capsize/blob/master/packages/metrics/README.md

Install the @capsizecss/metrics package using npm.

```APIDOC
## Installation

Install the @capsizecss/metrics package using npm.

### Method

```bash
npm install @capsizecss/metrics
```
```

--------------------------------

### Install Capsize Packages

Source: https://github.com/seek-oss/capsize/blob/master/README.md

Installation commands for the metrics and unpack packages used to retrieve or extract font data.

```bash
npm install @capsizecss/metrics
npm install @capsizecss/unpack
```

--------------------------------

### Install @capsizecss/metrics

Source: https://github.com/seek-oss/capsize/blob/master/packages/metrics/README.md

The command to install the metrics package via npm.

```bash
npm install @capsizecss/metrics
```

--------------------------------

### Migration Guide

Source: https://github.com/seek-oss/capsize/blob/master/packages/core/CHANGELOG.md

Instructions for migrating from older versions of capsize to the new @capsizecss/core package.

```APIDOC
## Installation

Replace the previous `capsize` dependency with the new scoped version of the package `@capsizecss/core`:

```bash
npm uninstall capsize
npm install @capsizecss/core
```

## API Changes

There is no longer a default export; this behavior is now available via the `createStyleObject` named export.

```diff
- import capsize from 'capsize';
+ import { createStyleObject } from '@capsizecss/core';

- const styles = capsize({
+ const styles = createStyleObject({
  fontSize: 18,
  fontMetrics: {
    // ...
  }
});
```

## Import Changes

Both the `getCapHeight` function and `FontMetrics` type still exist, but the package name will need to be updated.

```diff
- import { getCapHeight, FontMetrics } from 'capsize';
+ import { getCapHeight, FontMetrics } from '@capsizecss/core';
```

## Type Removals

The `CapsizeOptions` type has been removed. You can infer this from the first argument passed to `createStyleObject` using TypeScript's built-in `Parameters` utility:

```diff
- import type { CapsizeStyles } from 'capsize';
+ import type { createStyleObject } from '@capsizecss/core';

+ type CapsizeOptions = Parameters<typeof createStyleObject>[0];
```

The `CapsizeStyles` type has been removed. You can infer this from `createStyleObject` using TypeScript's built-in `ReturnType` utility:

```diff
- import type { CapsizeStyles } from 'capsize';
+ import type { createStyleObject } from '@capsizecss/core';

+ type CapsizeStyles = ReturnType<typeof createStyleObject>;
```
```

--------------------------------

### Install Capsize Core

Source: https://github.com/seek-oss/capsize/blob/master/README.md

Installs the Capsize core package using npm. This package contains the necessary functions for applying capsize styling.

```bash
npm install @capsizecss/core
```

--------------------------------

### Install Scoped Capsize Package

Source: https://github.com/seek-oss/capsize/blob/master/packages/core/CHANGELOG.md

Instructions for migrating from the previous `capsize` package to the new scoped package `@capsizecss/core`. This involves uninstalling the old package and installing the new one using npm.

```bash
npm uninstall capsize
npm install @capsizecss/core
```

--------------------------------

### Install @capsizecss/unpack

Source: https://github.com/seek-oss/capsize/blob/master/packages/unpack/README.md

Install the @capsizecss/unpack package using npm. This package is used to unpack font metrics from font files.

```bash
npm install @capsizecss/unpack
```

--------------------------------

### Using Font Metrics in CSS @font-face

Source: https://github.com/seek-oss/capsize/blob/master/packages/unpack/CHANGELOG.md

Example of using extracted postscriptName and fullName properties to construct local font-face declarations in CSS.

```css
@font-face {
  font-family: "Web Font Fallback";
  src: local("Arial Bold"), local("Arial-BoldMT");
  font-weight: 700;
  ascent-override: 89.3502%;
  descent-override: 23.1683%;
  size-adjust: 108.3377%;
}
```

--------------------------------

### Using createFontStack with CSS Stylesheet

Source: https://github.com/seek-oss/capsize/blob/master/README.md

Provides an example of how to integrate the output of createFontStack into a CSS stylesheet or style tag, typically using a templating engine like Handlebars. This includes defining the font-family and @font-face rules.

```html
<style type="text/css">
  .heading {
    font-family: {{ fontFamily }}
  }

  {{ fontFaces }}
</style>

```

--------------------------------

### Update Font Metric Imports: System Fonts (TypeScript)

Source: https://github.com/seek-oss/capsize/blob/master/packages/metrics/CHANGELOG.md

This example shows a change in importing system font metrics, specifically for the 'brushScriptMT' font. The import path has been updated to align with the common system name for this font, ensuring consistency when referencing system fonts.

```typescript
-import metrics from '@capsizecss/metrics/brushScriptMT';
+import metrics from '@capsizecss/metrics/brushScript';
```

--------------------------------

### Responsive Typography with vanilla-extract and Capsize

Source: https://github.com/seek-oss/capsize/blob/master/packages/vanilla-extract/README.md

Demonstrates creating responsive text styles using Capsize and vanilla-extract. `createTextStyle` accepts a base style and a media query object to define different text styles for various screen sizes.

```typescript
import { createTextStyle } from '@capsizecss/vanilla-extract';

const fontMetrics = {
  capHeight: 700,
  ascent: 1058,
  descent: -291,
  lineGap: 0,
  unitsPerEm: 1000,
};

const textDefinitions = {
  mobile: { fontSize: 18, leading: 24, fontMetrics },
  tablet: { fontSize: 16, leading: 22, fontMetrics },
  desktop: { fontSize: 14, leading: 18, fontMetrics },
};

export const text = createTextStyle(textDefinitions.mobile, {
  '@media': {
    'screen and (min-width: 768px)': textDefinitions.tablet,
    'screen and (min-width: 1024px)': textDefinitions.desktop,
  },
});
```

--------------------------------

### Importing fromFile for File System Access

Source: https://github.com/seek-oss/capsize/blob/master/packages/unpack/CHANGELOG.md

Demonstrates the updated import path for the fromFile function, which was moved to a separate entry point to isolate file system dependencies.

```diff
-import { fromFile } from '@capsizecss/unpack';
+import { fromFile } from '@capsizecss/unpack/fs';
```

--------------------------------

### Importing Font Metrics

Source: https://github.com/seek-oss/capsize/blob/master/packages/metrics/CHANGELOG.md

Demonstrates how to import standard font metrics as well as specific weight and italic variants from the @capsizecss/metrics package.

```APIDOC
## Import Font Metrics

### Description
Access font-specific metric data for various weights and styles to ensure precise typography calculations.

### Usage
```ts
import arial from "@capsizecss/metrics/arial";
import arialItalic from "@capsizecss/metrics/arial/italic";
import arialBold from "@capsizecss/metrics/arial/700";
import arialBoldItalic from "@capsizecss/metrics/arial/700italic";
```

### Parameters
- **fontName** (string) - Required - The name of the font package (e.g., 'arial', 'montserrat').
- **variant** (string) - Optional - The specific weight (e.g., '700') or style (e.g., 'italic') to import.
```

--------------------------------

### Define Incomplete Font Metrics

Source: https://github.com/seek-oss/capsize/blob/master/packages/metrics/CHANGELOG.md

An example of a font metrics object that is missing the required capHeight property, which will now trigger a TypeScript error.

```javascript
{
  familyName: 'My Incomplete Font',
  ascent: 860,
  descent: -348,
  lineGap: 0,
  unitsPerEm: 1024
}
```

--------------------------------

### Responsive Themed Typography with vanilla-extract and Capsize

Source: https://github.com/seek-oss/capsize/blob/master/packages/vanilla-extract/README.md

Shows how to implement responsive typography within a vanilla-extract theme using Capsize. It precomputes values for different breakpoints and applies them responsively using media queries.

```typescript
import { createTheme } from '@vanilla-extract/css';
import { createTextStyle, precomputeValues } from '@capsizecss/vanilla-extract';

const fontMetrics = {
  capHeight: 700,
  ascent: 1058,
  descent: -291,
  lineGap: 0,
  unitsPerEm: 1000,
};

const [themeClass, vars] = createTheme({
  bodyText: {
    mobile: precomputeValues({ fontSize: 18, leading: 24, fontMetrics }),
    tablet: precomputeValues({ fontSize: 16, leading: 22, fontMetrics }),
    desktop: precomputeValues({ fontSize: 14, leading: 18, fontMetrics }),
  },
});

export const text = createTextStyle(vars.bodyText.mobile, {
  '@media': {
    'screen and (min-width: 768px)': vars.bodyText.tablet,
    'screen and (min-width: 1024px)': vars.bodyText.desktop,
  },
});
```

--------------------------------

### Configure createFontStack with custom size-adjust

Source: https://github.com/seek-oss/capsize/blob/master/packages/core/CHANGELOG.md

Demonstrates how to provide a custom size-adjust value via fontFaceProperties when creating a font stack, ensuring metric overrides are calculated correctly.

```typescript
createFontStack([merriweatherSans, arial], {
  fontFaceProperties: {
    sizeAdjust: "300%",
  },
});
```

--------------------------------

### Converting Font Family Name to Camel Case (TypeScript)

Source: https://github.com/seek-oss/capsize/blob/master/packages/metrics/README.md

A helper function to convert font family names into camel case, suitable for importing font metrics. It shows an example of using the converted name to dynamically import metrics.

```typescript
import { fontFamilyToCamelCase } from '@capsizecss/metrics';

const familyName = fontFamilyToCamelCase('--apple-system'); // => `appleSystem`
const metrics = await import(`@capsizecss/metrics/${familyName}`);
```

--------------------------------

### Accessing xWidthAvg and Subset Metrics (TypeScript)

Source: https://github.com/seek-oss/capsize/blob/master/packages/metrics/README.md

Demonstrates how to import font metrics and access the default xWidthAvg, as well as specific subset metrics like latin and thai.

```typescript
import arial from '@capsizecss/metrics/arial';

const xWidthAvgDefault = arial.xWidthAvg;
const xWidthAvgLatin = arial.subsets.latin.xWidthAvg; // Same as above
const xWidthAvgThai = arial.subsets.thai.xWidthAvg;
```

--------------------------------

### Importing Font Metrics with @capsizecss/metrics

Source: https://github.com/seek-oss/capsize/blob/master/README.md

Demonstrates how to import font metrics for Google Fonts or system fonts using the @capsizecss/metrics package. This is the first step in utilizing Capsize for precise typography control.

```typescript
import arialMetrics from '@capsizecss/metrics/arial';

```

--------------------------------

### Create Text Style with vanilla-extract

Source: https://github.com/seek-oss/capsize/blob/master/packages/vanilla-extract/README.md

Demonstrates how to import and use `createTextStyle` from the @capsizecss/vanilla-extract package to apply capsized typography to elements within a vanilla-extract stylesheet. It requires font metrics and text style options as input.

```typescript
import { createTextStyle } from '@capsizecss/vanilla-extract';

export const text = createTextStyle({
  fontSize: 16,
  leading: 24,
  fontMetrics: {
    capHeight: 700,
    ascent: 1058,
    descent: -291,
    lineGap: 0,
    unitsPerEm: 1000,
  },
});
```

--------------------------------

### Themed Typography with vanilla-extract and Capsize

Source: https://github.com/seek-oss/capsize/blob/master/packages/vanilla-extract/README.md

Illustrates how to integrate Capsize with vanilla-extract themes. It uses `precomputeValues` to generate theme-level typography settings, which are then passed to `createTextStyle` for consistent themed text styles.

```typescript
import { createTheme } from '@vanilla-extract/css';
import { createTextStyle, precomputeValues } from '@capsizecss/vanilla-extract';

const [themeClass, vars] = createTheme({
  bodyText: precomputeValues({
    fontSize: 18,
    leading: 24,
    fontMetrics: {
      capHeight: 700,
      ascent: 1058,
      descent: -291,
      lineGap: 0,
      unitsPerEm: 1000,
    },
  }),
});

export const text = createTextStyle(vars.bodyText);
```

--------------------------------

### Creating Font Stacks

Source: https://github.com/seek-oss/capsize/blob/master/packages/metrics/CHANGELOG.md

Shows how to use imported metrics with the createFontStack API to generate font-face overrides for fallback fonts.

```APIDOC
## createFontStack

### Description
Generates a font stack configuration including font-family strings and @font-face overrides for fallback fonts.

### Usage
```ts
import { createFontStack } from "@capsizecss/core";
import montserrat600 from "@capsizecss/metrics/montserrat/600";
import arialBold from "@capsizecss/metrics/arial/700";

const bold = createFontStack([montserrat600, arialBold], {
  fontFaceProperties: {
    fontWeight: 700,
  },
});
```

### Parameters
- **metrics** (Array) - Required - An array of font metric objects.
- **options** (Object) - Optional - Configuration object for fontFaceProperties.
```

--------------------------------

### Creating Font Stacks with Metrics

Source: https://github.com/seek-oss/capsize/blob/master/packages/metrics/CHANGELOG.md

Shows how to use createFontStack from @capsizecss/core with specific font metrics to generate CSS font-face properties for fallback fonts.

```typescript
import { createFontStack } from "@capsizecss/core";
import montserrat from "@capsizecss/metrics/montserrat";
import montserrat600 from "@capsizecss/metrics/montserrat/600";
import arial from "@capsizecss/metrics/arial";
import arialBold from "@capsizecss/metrics/arial/700";

const regular = createFontStack([montserrat, arial]);

const bold = createFontStack([montserrat600, arialBold], {
  fontFaceProperties: {
    fontWeight: 700,
  },
});
```

--------------------------------

### Options for Unpacking

Source: https://github.com/seek-oss/capsize/blob/master/packages/unpack/README.md

Details on the optional parameters that can be passed to the unpacking functions.

```APIDOC
## Options for Unpacking

All of the above APIs accept an optional second parameter with the following options:

### `postscriptName`

Capsize can extract the metrics for a single font from a TrueType Collection (TTC) file by providing the `postscriptName`.

### Method

`POST` (Conceptual)

### Endpoint

`@capsizecss/unpack` or `@capsizecss/unpack/fs`

### Parameters

#### Request Body

- **postscriptName** (string) - Optional - The PostScript name of the font to extract from a TTC file.

### Request Example

```ts
import { fromFile } from '@capsizecss/unpack/fs';

const metrics = await fromFile('AvenirNext.ttc', {
  postscriptName: 'AvenirNext-Bold',
});
```
```

--------------------------------

### precomputeValues

Source: https://github.com/seek-oss/capsize/blob/master/README.md

Calculates the necessary values for leading trim styles based on font metrics and desired font size.

```APIDOC
## precomputeValues

### Description
Returns all the information required to create leading trim styles for a specific font size given the provided font metrics.

### Method
Function Call

### Parameters
#### Request Body
- **fontSize** (number) - Required - The target font size in pixels.
- **leading** (number) - Required - The desired line height.
- **fontMetrics** (object) - Required - The metrics object for the specific font.

### Request Example
{
  "fontSize": 16,
  "leading": 24,
  "fontMetrics": "arialMetrics"
}

### Response
#### Success Response (200)
- **fontSize** (string) - Calculated font size.
- **lineHeight** (string) - Calculated line height.
- **capHeightTrim** (string) - Trim value for cap height.
- **baselineTrim** (string) - Trim value for baseline.

#### Response Example
{
  "fontSize": "16px",
  "lineHeight": "24px",
  "capHeightTrim": "...",
  "baselineTrim": "..."
}
```

--------------------------------

### Import Font Metrics for System and Google Fonts

Source: https://context7.com/seek-oss/capsize/llms.txt

Imports pre-computed font metrics for various system and Google fonts. These metrics, including cap height, ascent, descent, and line gap, are essential for precise text trimming and typographic control. The structure of the metrics object is also demonstrated.

```typescript
// Import system fonts
import arial from '@capsizecss/metrics/arial';
import helveticaNeue from '@capsizecss/metrics/helveticaNeue';
import timesNewRoman from '@capsizecss/metrics/timesNewRoman';

// Import Google fonts
import roboto from '@capsizecss/metrics/roboto';
import openSans from '@capsizecss/metrics/openSans';
import lobster from '@capsizecss/metrics/lobster';

// Import specific font variants
import arialBold from '@capsizecss/metrics/arial/700';
import arialItalic from '@capsizecss/metrics/arial/italic';
import arialBoldItalic from '@capsizecss/metrics/arial/700italic';

// Metrics object structure
console.log(arial);
// {
//   familyName: 'Arial',
//   fullName: 'Arial',
//   postscriptName: 'ArialMT',
//   category: 'sans-serif',
//   capHeight: 1467,
//   ascent: 1854,
//   descent: -434,
//   lineGap: 67,
//   unitsPerEm: 2048,
//   xHeight: 1062,
//   xWidthAvg: 935,
//   subsets: { latin: { xWidthAvg: 935 }, thai: { xWidthAvg: 200 } }
// }

// Access subset-specific metrics
const latinAvgWidth = arial.subsets.latin.xWidthAvg;
const thaiAvgWidth = arial.subsets.thai.xWidthAvg;
```

--------------------------------

### Precompute Values with vanilla-extract Themes

Source: https://context7.com/seek-oss/capsize/llms.txt

Stores precomputed Capsize values within vanilla-extract themes for consistent typography across components. This enables theme-driven responsive typography with type safety, allowing for the creation of styles from theme values and responsive themed typography.

```typescript
// theme.css.ts
import { createTheme } from '@vanilla-extract/css';
import { createTextStyle, precomputeValues } from '@capsizecss/vanilla-extract';

const fontMetrics = {
  capHeight: 700,
  ascent: 1058,
  descent: -291,
  lineGap: 0,
  unitsPerEm: 1000,
};

// Define typography in theme
export const [themeClass, vars] = createTheme({
  typography: {
    body: precomputeValues({ fontSize: 16, leading: 24, fontMetrics }),
    heading: precomputeValues({ fontSize: 32, leading: 40, fontMetrics }),
    small: precomputeValues({ fontSize: 12, leading: 16, fontMetrics }),
  },
});

// Create styles from theme values
export const bodyText = createTextStyle(vars.typography.body);
export const headingText = createTextStyle(vars.typography.heading);

// Responsive themed typography
export const [responsiveTheme, responsiveVars] = createTheme({
  bodyText: {
    mobile: precomputeValues({ fontSize: 14, leading: 20, fontMetrics }),
    tablet: precomputeValues({ fontSize: 16, leading: 24, fontMetrics }),
    desktop: precomputeValues({ fontSize: 18, leading: 28, fontMetrics }),
  },
});

export const responsiveBody = createTextStyle(responsiveVars.bodyText.mobile, {
  '@media': {
    'screen and (min-width: 768px)': responsiveVars.bodyText.tablet,
    'screen and (min-width: 1024px)': responsiveVars.bodyText.desktop,
  },
});
```

--------------------------------

### Using createFontStack with CSS-in-JS (Emotion)

Source: https://github.com/seek-oss/capsize/blob/master/README.md

Demonstrates integrating createFontStack output with a CSS-in-JS library like Emotion. The fontFaces are provided as a JavaScript style object, and the fontFamily is applied to elements.

```tsx
import { Global } from '@emotion/core';
import { createFontStack } from '@capsizecss/core';
import lobster from '@capsizecss/metrics/lobster';
import helveticaNeue from '@capsizecss/metrics/helveticaNeue';
import arial from '@capsizecss/metrics/arial';

const { fontFaces, fontFamily } = createFontStack(
  [lobster, helveticaNeue, arial],
  {
    fontFaceFormat: 'styleObject',
  },
);

export const App = () => (
  <>
    <Global styles={fontFaces} />
    <p css={{ fontFamily }}>...</p>
  </>
);

```

--------------------------------

### Importing fromBuffer for Metric Extraction

Source: https://github.com/seek-oss/capsize/blob/master/packages/unpack/CHANGELOG.md

Shows how to import and use the fromBuffer function to extract font metrics from a buffer, supporting both modern ESM projects and legacy CommonJS environments.

```javascript
// For CJS projects before Node 20
const { fromBuffer } = await import("@capsizecss/unpack");

// For all other projects
import { fromBuffer } from "@capsizecss/unpack";
```

```typescript
import { fromBuffer } from "@capsizecss/unpack";

const metrics = await fromBuffer(buffer);
```

--------------------------------

### Generate Style Object with Font Metrics

Source: https://github.com/seek-oss/capsize/blob/master/packages/metrics/README.md

Demonstrates how to import font metrics and pass them into the createStyleObject function to generate typography styles.

```typescript
import { createStyleObject } from '@capsizecss/core';
import arialMetrics from '@capsizecss/metrics/arial';

const capsizeStyles = createStyleObject({
  fontSize: 16,
  leading: 24,
  fontMetrics: arialMetrics,
});
```

--------------------------------

### Apply Font Metrics with Type Checking

Source: https://github.com/seek-oss/capsize/blob/master/packages/metrics/CHANGELOG.md

Demonstrates how createStyleObject enforces font metric completeness and how to resolve missing values using manual overrides in TypeScript.

```typescript
import myIncompleteFontMetrics from "@capsizecss/metrics/myIncompleteFont";
import { createStyleObject } from "@capsizecss/core";

createStyleObject({
  fontSize: 16,
  leading: 24,
  fontMetrics: myIncompleteFontMetrics,
});

createStyleObject({
  fontSize: 16,
  leading: 24,
  fontMetrics: {
    ...myIncompleteFontMetrics,
    capHeight: 594,
  },
});
```

--------------------------------

### Importing Font Metric Variants

Source: https://github.com/seek-oss/capsize/blob/master/packages/metrics/CHANGELOG.md

Demonstrates how to import specific font metric variants such as regular, italic, and bold versions from the @capsizecss/metrics package.

```typescript
import arial from "@capsizecss/metrics/arial";
import arialItalic from "@capsizecss/metrics/arial/italic";
import arialBold from "@capsizecss/metrics/arial/700";
import arialBoldItalic from "@capsizecss/metrics/arial/700italic";
```

--------------------------------

### Accessing Entire Metrics Collection (TypeScript)

Source: https://github.com/seek-oss/capsize/blob/master/packages/metrics/README.md

Shows how to import the entire metrics collection, which is a large JSON object keyed by font family name. It also demonstrates accessing specific variants of a font.

```typescript
import { entireMetricsCollection } from '@capsizecss/metrics/entireMetricsCollection';

const metrics = entireMetricsCollection['arial'];
```

```typescript
import { entireMetricsCollection } from '@capsizecss/metrics/entireMetricsCollection';

const arialBoldItalic = entireMetricsCollection['arial'].variants['700italic'];
```

--------------------------------

### Create TextStyle with vanilla-extract

Source: https://context7.com/seek-oss/capsize/llms.txt

Generates a vanilla-extract class with Capsize trimming styles, integrating directly with vanilla-extract's styling API for type-safe, zero-runtime CSS. Supports basic usage, debug identifiers for class names, and responsive typography with media queries.

```typescript
// Text.css.ts
import { createTextStyle } from '@capsizecss/vanilla-extract';
import arialMetrics from '@capsizecss/metrics/arial';

// Basic usage
export const bodyText = createTextStyle({
  fontSize: 16,
  leading: 24,
  fontMetrics: arialMetrics,
});

// With debug identifier for better class names
export const heading = createTextStyle(
  { fontSize: 32, leading: 40, fontMetrics: arialMetrics },
  'heading'
);
// Produces class name like: Text_heading__1bese54h

// Responsive typography with media queries
const fontMetrics = arialMetrics;
export const responsiveText = createTextStyle(
  { fontSize: 14, leading: 20, fontMetrics },
  {
    '@media': {
      'screen and (min-width: 768px)': { fontSize: 16, leading: 24, fontMetrics },
      'screen and (min-width: 1024px)': { fontSize: 18, leading: 28, fontMetrics },
    },
  }
);

// Text.ts - Apply the styles
import * as styles from './Text.css';

const element = document.createElement('p');
element.className = styles.bodyText;
element.textContent = 'Capsized text with vanilla-extract';
```

--------------------------------

### Importing Specific Font Variants

Source: https://github.com/seek-oss/capsize/blob/master/packages/metrics/README.md

Shows how to import specific font weights and styles using the path convention @capsizecss/metrics/{font-family}/{variant}.

```typescript
import arialRegular from '@capsizecss/metrics/arial/regular';
import arialItalic from '@capsizecss/metrics/arial/italic';
import arialBold from '@capsizecss/metrics/arial/700';
import arialBoldItalic from '@capsizecss/metrics/arial/700italic';
```

--------------------------------

### Usage with Google Fonts

Source: https://github.com/seek-oss/capsize/blob/master/packages/metrics/README.md

Import and use metrics for Google Fonts like Lobster with the createStyleObject function.

```APIDOC
## Usage with Google Fonts

Import and use metrics for Google Fonts like Lobster with the `createStyleObject` function.

### Method

```ts
import { createStyleObject } from '@capsizecss/core';
import lobsterMetrics from '@capsizecss/metrics/lobster';

const capsizeStyles = createStyleObject({
  fontSize: 16,
  leading: 24,
  fontMetrics: lobsterMetrics,
});
```
```

--------------------------------

### Generate font stacks with subset support

Source: https://github.com/seek-oss/capsize/blob/master/packages/metrics/CHANGELOG.md

The createFontStack API in @capsize/core now accepts a 'subset' option. This allows for the generation of fallback font stacks that utilize the correct xWidthAvg metric for the specified character subset, improving text rendering for diverse languages.

```typescript
import { createFontStack } from '@capsize/core';

const { fontFamily, fontFaces } = createFontStack([lobster, arial], {
  subset: "thai",
});
```

--------------------------------

### Generate Fallback Font Stacks with Subset Support in Capsize Core

Source: https://github.com/seek-oss/capsize/blob/master/packages/unpack/CHANGELOG.md

Updates the @capsizecss/core package to allow generating fallback font stacks with specific subset support. The `createFontStack` API now accepts a `subset` option, enabling the use of the correct xWidthAvg metric for the specified character set.

```typescript
const { fontFamily, fontFaces } = createFontStack([lobster, arial], {
  subset: "thai",
});
```

--------------------------------

### Update Capsize Imports

Source: https://github.com/seek-oss/capsize/blob/master/packages/core/CHANGELOG.md

Demonstrates how to update import statements after migrating to the `@capsizecss/core` package. Named imports like `createStyleObject`, `createStyleString`, and `getCapHeight` are now used instead of the default export.

```typescript
// Old import:
// import capsize from 'capsize';
// import { getCapHeight, FontMetrics } from 'capsize';

// New import:
import { createStyleObject, createStyleString, getCapHeight, FontMetrics } from '@capsizecss/core';
```

--------------------------------

### Usage with System Fonts

Source: https://github.com/seek-oss/capsize/blob/master/packages/metrics/README.md

Import and use metrics for common system fonts like Arial with the createStyleObject function from @capsizecss/core.

```APIDOC
## Usage with System Fonts

Import and use metrics for common system fonts like Arial with the `createStyleObject` function from `@capsizecss/core`.

### Method

```ts
import { createStyleObject } from '@capsizecss/core';
import arialMetrics from '@capsizecss/metrics/arial';

const capsizeStyles = createStyleObject({
  fontSize: 16,
  leading: 24,
  fontMetrics: arialMetrics,
});
```
```

--------------------------------

### Create CSS-in-JS Style Object with Capsize

Source: https://github.com/seek-oss/capsize/blob/master/README.md

Demonstrates how to use the `createStyleObject` function from Capsize to generate a CSS-in-JS style object. This function takes font size, leading, and font metrics as input to create styles that trim whitespace around text.

```typescript
import { createStyleObject } from '@capsizecss/core';
import arialMetrics from '@capsizecss/metrics/arial';

const capsizeStyles = createStyleObject({
  fontSize: 16,
  leading: 24,
  fontMetrics: arialMetrics,
});

// Usage example:
// <div css={{ ...capsizeStyles }}>My capsized text 🛶</div>
```

--------------------------------

### Capsize Core API

Source: https://github.com/seek-oss/capsize/blob/master/packages/core/CHANGELOG.md

This section details the core functions provided by the @capsizecss/core package for generating CSS styles.

```APIDOC
## createStyleObject

### Description
Accepts capsize `options` and returns a JS object representation of the capsize styles that is compatible with most css-in-js frameworks.

### Method
`createStyleObject`

### Parameters
#### Request Body
- **fontSize** (number) - Required - The font size in pixels.
- **fontMetrics** (object) - Required - An object containing font metrics.
  - **capHeight** (number) - Required - The cap height of the font.
  - **ascent** (number) - Required - The ascent of the font.
  - **descent** (number) - Required - The descent of the font.
  - **lineGap** (number) - Required - The line gap of the font.
  - **unitsPerEm** (number) - Required - The units per em of the font.
  - **familyName** (string) - Optional - The font family name.
  - **category** (string) - Optional - The font category.
  - **xHeight** (number) - Optional - The x-height of the font.
  - **xWidthAvg** (number) - Optional - The average width of characters in the font.

### Request Example
```json
{
  "fontSize": 18,
  "fontMetrics": {
    "capHeight": 1000,
    "ascent": 800,
    "descent": -200,
    "lineGap": 0,
    "unitsPerEm": 1000
  }
}
```

### Response
#### Success Response (200)
- **object** (object) - A JavaScript object containing CSS properties for capsize styles.

#### Response Example
```json
{
  "lineHeight": "1.2",
  "fontSize": "1.125rem",
  "::before": {
    "content": "__APP_VERSION__",
    "display": "table",
    "height": 0
  }
}
```

## createStyleString

### Description
Accepts capsize `options` and returns a string representation of the capsize styles that can then be templated into a HTML `style` tag or appended to a stylesheet.

### Method
`createStyleString`

### Parameters
#### Request Body
- **className** (string) - Required - The name of the CSS class to generate.
- **options** (object) - Required - Capsize options object (same as `createStyleObject`).

### Request Example
```javascript
createStyleString("capsizedText", {
  fontSize: 18,
  fontMetrics: {
    capHeight: 1000,
    ascent: 800,
    descent: -200,
    lineGap: 0,
    unitsPerEm: 1000
  }
});
```

### Response
#### Success Response (200)
- **string** (string) - A CSS string representing the capsize styles.

#### Response Example
```css
.capsizedText {
  line-height: 1.2;
  font-size: 1.125rem;
}
.capsizedText::before {
  content: "__APP_VERSION__";
  display: table;
  height: 0;
}
```

## precomputeValues

### Description
Accepts capsize `options` and returns all the information required to create styles for a specific font size given the provided font metrics. This is useful for integrations with different styling solutions.

### Method
`precomputeValues`

### Parameters
#### Request Body
- **options** (object) - Required - Capsize options object (same as `createStyleObject`).

### Request Example
```javascript
precomputeValues({
  fontSize: 18,
  fontMetrics: {
    capHeight: 1000,
    ascent: 800,
    descent: -200,
    lineGap: 0,
    unitsPerEm: 1000
  }
});
```

### Response
#### Success Response (200)
- **object** (object) - An object containing precomputed values for styling.

#### Response Example
```json
{
  "capHeight": 1000,
  "fontSize": 18,
  "leadingTrim": {
    "before": 0.2,
    "after": 0.2
  },
  "trim": {
    "top": 0.2,
    "bottom": 0.2
  },
  "lineHeight": 1.2,
  "fontSizeTrimmed": "1.125rem"
}
```
```

--------------------------------

### Generate Font Stacks for Character Subsets

Source: https://github.com/seek-oss/capsize/blob/master/README.md

Shows how to scale fallback font stacks for specific unicode subsets, such as Thai, to ensure accurate character frequency adjustments.

```typescript
const { fontFamily, fontFaces } = createFontStack([lobster, arial], {
  subset: 'thai',
});
```

--------------------------------

### POST /createStyleString

Source: https://github.com/seek-oss/capsize/blob/master/README.md

Generates a CSS string rule for a specific class name to be used in standard stylesheets.

```APIDOC
## POST /createStyleString

### Description
Generates a CSS string rule that can be injected into a style tag or stylesheet to apply capsize trimming to a specific class.

### Method
POST

### Parameters
#### Request Body
- **className** (string) - Required - The CSS class name to apply the styles to.
- **options** (object) - Required - Configuration including fontSize/capHeight, leading, and fontMetrics.

### Request Example
{
  "className": "capsizedText",
  "options": {
    "fontSize": 16,
    "leading": 24,
    "fontMetrics": { "capHeight": 700, "ascent": 1058, "descent": -291, "lineGap": 0, "unitsPerEm": 1000 }
  }
}

### Response
#### Success Response (200)
- **CSSString** (string) - A complete CSS rule string.

#### Response Example
".capsizedText { line-height: 24px; } .capsizedText::before { ... }"
```

--------------------------------

### Precompute Font Trimming Values with Capsize Core

Source: https://context7.com/seek-oss/capsize/llms.txt

Returns the raw computed values for font trimming, such as fontSize, lineHeight, capHeightTrim, and baselineTrim, without wrapping them in style objects or CSS rules. This is ideal for custom styling solutions, theming systems, or storing precomputed values. It requires styling parameters and font metrics.

```typescript
import { precomputeValues } from '@capsizecss/core';
import arialMetrics from '@capsizecss/metrics/arial';

const values = precomputeValues({
  fontSize: 16,
  leading: 24,
  fontMetrics: arialMetrics,
});

// Returns:
// {
//   fontSize: '16px',
//   lineHeight: '24px',
//   capHeightTrim: '-0.2753em',
//   baselineTrim: '-0.2626em'
// }

// Use in a theming system
const theme = {
  typography: {
    body: precomputeValues({
      fontSize: 16,
      leading: 24,
      fontMetrics: arialMetrics,
    }),
    heading: precomputeValues({
      fontSize: 32,
      leading: 40,
      fontMetrics: arialMetrics,
    }),
  },
};

// Apply precomputed values manually
const customStyles = {
  fontSize: values.fontSize,
  lineHeight: values.lineHeight,
  '::before': {
    content: "''",
    marginBottom: values.capHeightTrim,
    display: 'table',
  },
  '::after': {
    content: "''",
    marginTop: values.baselineTrim,
    display: 'table',
  },
};
```

--------------------------------

### Creating Font Stacks with createFontStack (Core)

Source: https://github.com/seek-oss/capsize/blob/master/README.md

Illustrates the usage of the createFontStack function from the Capsize core package. This function generates metrics-based @font-face declarations and a font family string to ensure consistent font fallback behavior and reduce Cumulative Layout Shift.

```typescript
import { createFontStack } from '@capsizecss/core';
import lobster from '@capsizecss/metrics/lobster';
import helveticaNeue from '@capsizecss/metrics/helveticaNeue';
import arial from '@capsizecss/metrics/arial';

const { fontFamily, fontFaces } = createFontStack([
  lobster,
  helveticaNeue,
  arial,
]);

```

--------------------------------

### Create CSS Style String with Capsize

Source: https://github.com/seek-oss/capsize/blob/master/packages/core/CHANGELOG.md

Illustrates the usage of `createStyleString` from `@capsizecss/core` to generate a CSS string for styling elements. This string can be directly inserted into a `<style>` tag or appended to a stylesheet, providing a way to apply capsize styles globally or to specific classes.

```typescript
import { createStyleString } from "@capsizecss/core";

const capsizedStyleRule = createStyleString("capsizedText", {
  fontSize: 18,
  fontMetrics: {
    // ... font metrics data
  },
});

// Example of writing the style rule to the document:
document.write(`
  <style type="text/css">
    ${capsizedStyleRule}
  </style>
  <div class="capsizedText">
    My capsized text 🛶
  </div>
`);
```

--------------------------------

### POST /createStyleObject

Source: https://github.com/seek-oss/capsize/blob/master/README.md

Generates a CSS-in-JS style object that trims whitespace around text based on font metrics.

```APIDOC
## POST /createStyleObject

### Description
Generates a JavaScript object containing CSS properties to trim the space above capital letters and below the baseline of text.

### Method
POST

### Parameters
#### Request Body
- **fontSize** (number) - Optional - The desired font size.
- **capHeight** (number) - Optional - The desired height of capital letters. (Use either fontSize or capHeight).
- **leading** (number) - Optional - The desired line height.
- **fontMetrics** (object) - Required - Font metrics object containing capHeight, ascent, descent, lineGap, and unitsPerEm.

### Request Example
{
  "fontSize": 16,
  "leading": 24,
  "fontMetrics": {
    "capHeight": 700,
    "ascent": 1058,
    "descent": -291,
    "lineGap": 0,
    "unitsPerEm": 1000
  }
}

### Response
#### Success Response (200)
- **Object** (object) - A CSS-in-JS style object containing calculated margins and line-height properties.

#### Response Example
{
  "lineHeight": "24px",
  "::before": { "content": "'\"'", "display": "table", "marginBottom": "-0.25em" },
  "::after": { "content": "'\"'", "display": "table", "marginTop": "-0.25em" }
}
```

--------------------------------

### Extracting Font Metrics with @capsizecss/unpack

Source: https://github.com/seek-oss/capsize/blob/master/README.md

Shows how to extract font metrics directly from a font file using the @capsizecss/unpack package. This method is useful for custom or local font files.

```typescript
import { fromFile } from '@capsizecss/unpack';

const metrics = await fromFile(filePath);

```

--------------------------------

### Precompute Leading Trim Values

Source: https://github.com/seek-oss/capsize/blob/master/README.md

Uses precomputeValues to calculate the necessary CSS values for leading trim based on font size, leading, and specific font metrics.

```typescript
import { precomputeValues } from '@capsizecss/core';
import arialMetrics from '@capsizecss/metrics/arial';

const capsizeValues = precomputeValues({
  fontSize: 16,
  leading: 24,
  fontMetrics: arialMetrics,
});
```

--------------------------------

### Apply Capsized Text Style in vanilla-extract

Source: https://github.com/seek-oss/capsize/blob/master/packages/vanilla-extract/README.md

Shows how to import and apply a previously defined capsized text style class (created using `createTextStyle`) to a DOM element within a TypeScript file when using vanilla-extract.

```typescript
import * as styles from './Text.css';

document.write(`
  <div class="${styles.text}">
    My capsized text 🛶
  </div>
`);
```

--------------------------------

### Importing Font Variants

Source: https://github.com/seek-oss/capsize/blob/master/packages/metrics/README.md

Import specific font variants by weight and style, following Google Fonts naming conventions.

```APIDOC
## Importing Font Variants

Import specific font variants by weight and style, following Google Fonts naming conventions.

### Endpoint

`@capsizecss/metrics/{font-family}/{weight}{style}`

### Description

The format follows the convention used by Google Fonts for variant names: either a standalone weight or style (e.g. `regular`, `italic`), a specific weight (e.g. numeric `100` to `900`), or a combination of both (e.g. `100italic`-`900italic`).

### Examples

```ts
import arialRegular from '@capsizecss/metrics/arial/regular';
import arialItalic from '@capsizecss/metrics/arial/italic';
import arialBold from '@capsizecss/metrics/arial/700';
import arialBoldItalic from '@capsizecss/metrics/arial/700italic';
```

> Note: Each font only includes the variants that are available for that specific font.

The top-most import path for a font family (e.g. without a variant: `@capsizecss/metrics/arial`) will return the `regular` variant. In the case of a Google Font that has no `regular` variant, the first variant in the variants array is returned.
```

--------------------------------

### createFontStack

Source: https://context7.com/seek-oss/capsize/llms.txt

Generates CSS @font-face declarations with metric overrides to align fallback fonts with primary web fonts.

```APIDOC
## createFontStack

### Description
Generates CSS font stacks that include metric overrides. This helps minimize Cumulative Layout Shift (CLS) by ensuring fallback fonts occupy the same space as the intended web font.

### Method
Function Call

### Parameters
#### Request Body
- **fontMetricsArray** (array) - Required - An array of font metrics objects.
- **options** (object) - Optional - Configuration for output format (CSS string or style object), font-face properties, and character subsets.

### Request Example
{
  "fontMetrics": ["lobster", "arial"],
  "options": { "fontFaceFormat": "styleObject" }
}

### Response
- **fontFamily** (string) - The generated font-family CSS string.
- **fontFaces** (string|array) - The @font-face declarations or style objects.
```

--------------------------------

### Infer Capsize Options and Styles Types

Source: https://github.com/seek-oss/capsize/blob/master/packages/core/CHANGELOG.md

Shows how to infer the `CapsizeOptions` and `CapsizeStyles` types using TypeScript's built-in utility types (`Parameters` and `ReturnType`) when using the `@capsizecss/core` package. This replaces the previously exported `CapsizeOptions` and `CapsizeStyles` types.

```typescript
import type { createStyleObject } from '@capsizecss/core';

// Inferring CapsizeOptions type:
type CapsizeOptions = Parameters<typeof createStyleObject>[0];

// Inferring CapsizeStyles type:
type CapsizeStyles = ReturnType<typeof createStyleObject>;
```

--------------------------------

### createStyleObject

Source: https://context7.com/seek-oss/capsize/llms.txt

Generates a CSS-in-JS style object for trimming whitespace above capital letters and below the baseline. This object includes font size, line height, and pseudo-element styles.

```APIDOC
## createStyleObject

### Description
Creates a CSS-in-JS style object that trims the whitespace above capital letters and below the baseline. The returned object includes the font size, line height, and pseudo-element styles that create the trimming effect using negative margins.

### Method
`createStyleObject`

### Parameters
- **fontSize** (number) - Optional - The font size in pixels.
- **leading** (number) - Optional - The line height (distance from baseline to baseline) in pixels.
- **capHeight** (number) - Optional - The desired height of capital letters in pixels.
- **lineGap** (number) - Optional - The desired gap between lines in pixels.
- **fontMetrics** (object) - Required - An object containing font metrics.

### Request Example
```javascript
import { createStyleObject } from '@capsizecss/core';
import arialMetrics from '@capsizecss/metrics/arial';

// Using fontSize with leading
const headingStyles = createStyleObject({
  fontSize: 32,
  leading: 40,
  fontMetrics: arialMetrics,
});

// Using capHeight to size by capital letter height
const preciseStyles = createStyleObject({
  capHeight: 24,
  lineGap: 16,
  fontMetrics: arialMetrics,
});
```

### Response Example
```json
{
  "fontSize": "32px",
  "lineHeight": "40px",
  "::before": {
    "content": "''",
    "marginBottom": "-0.2753em",
    "display": "table"
  },
  "::after": {
    "content": "''",
    "marginTop": "-0.2626em",
    "display": "table"
  }
}
```
```

--------------------------------

### Configure Font-Face Properties in Capsize

Source: https://github.com/seek-oss/capsize/blob/master/README.md

Demonstrates how to inject additional CSS properties into generated @font-face declarations using the fontFaceProperties option in createFontStack.

```typescript
const { fontFamily, fontFaces } = createFontStack(
  [lobster, helveticaNeue, arial],
  {
    fontFaceProperties: {
      fontDisplay: 'swap',
    },
  },
);
```

--------------------------------

### Unpack Font Metrics

Source: https://github.com/seek-oss/capsize/blob/master/packages/unpack/README.md

This section covers the primary functions for unpacking font metrics using different input types.

```APIDOC
## Unpack Font Metrics

This API provides functions to unpack font metrics from various sources.

### `fromBuffer`

Takes a buffer and returns the resolved font metrics.

### Method

`POST` (Conceptual, as it's a function call, not a direct HTTP endpoint)

### Endpoint

`@capsizecss/unpack`

### Parameters

#### Request Body

- **buffer** (Buffer) - Required - The font file content as a buffer.

### Request Example

```ts
import { fromBuffer } from '@capsizecss/unpack';

const metrics = await fromBuffer(buffer);
```

### `fromBlob`

Takes a file blob and returns the resolved font metrics.

### Method

`POST` (Conceptual)

### Endpoint

`@capsizecss/unpack`

### Parameters

#### Request Body

- **file** (Blob) - Required - The font file as a Blob object.

### Request Example

```ts
import { fromBlob } from '@capsizecss/unpack';

const metrics = await fromBlob(file);
```

### `fromUrl`

Takes a url string and returns the resolved font metrics.

### Method

`POST` (Conceptual)

### Endpoint

`@capsizecss/unpack`

### Parameters

#### Request Body

- **url** (string) - Required - The URL of the font file.

### Request Example

```ts
import { fromUrl } from '@capsizecss/unpack';

const metrics = await fromUrl(url);
```

### `fromFile`

Takes a file path string and returns the resolved font metrics. This function is available in `@capsizecss/unpack/fs`.

### Method

`POST` (Conceptual)

### Endpoint

`@capsizecss/unpack/fs`

### Parameters

#### Request Body

- **filePath** (string) - Required - The path to the font file on the file system.

### Request Example

```ts
import { fromFile } from '@capsizecss/unpack/fs';

const metrics = await fromFile(filePath);
```
```