本文へスキップ
fontstay.dev
GitHub のソースコード
テーマ
色覚シミュレーション

デザイン確認用です。色覚を補正するものではありません。

読みやすさの補助

CLI と Node ライブラリ

fontstay パッケージは、このサイトの調整エンジンからブラウザーを取り除いたものです。フォントファイルを読み取り、アプリと同じ @font-face ルールとエクスポートを出力するコマンドラインツールと Node ライブラリです。DOM は不要でネットワークリクエストも行わないため、ビルドパイプラインや CI に向いています。

インストール

パッケージはまだ npm に公開されていません。Node 24 以降が必要です。リポジトリのチェックアウトからビルドしてください。以下の例では、node packages/fontstay/dist/bin.js を fontstay と書いています。

git clone https://github.com/fogrew/fontstay.dev.git
cd fontstay.dev
pnpm install
pnpm cli:build
node packages/fontstay/dist/bin.js --version

コマンド

fit は 1 つ以上のフォントファイル(WOFF2、WOFF、TTF、OTF)を読み取り、フォールバック CSS を出力します。複数のファイルは、アプリと同じく 1 つのスタイルシートにまとめられます。mcp は、コーディングエージェント向けに stdio で MCP サーバーを起動し、オプションは取りません。

キリル文字とギリシャ文字のフェイスを除いて、Windows と macOS 向けにフォントを調整します。出力は、アプリの CSS エクスポートと同じテキストです。

$ fontstay fit font.woff2 --systems windows,macos --no-scripts
@font-face {
  font-family: "Source Sans Pro Fallback";
  src: local("Arial"), local("ArialMT");
  size-adjust: 93.697%;
  ascent-override: 105.0194%;
  descent-override: 29.1365%;
  line-gap-override: 0%;
}

body {
  font-family: "Source Sans Pro", "Source Sans Pro Fallback", sans-serif;
  /* Safari has no vertical overrides: match the x-height and fix the line box */
  font-size-adjust: 0.48;
  line-height: 1.4;
}

.fonts-loading {
  letter-spacing: -0.0003em;
  word-spacing: -0.0025em;
}
fontstay fit Inter.woff2 -o fallbacks.css
fontstay fit regular.woff2 bold.woff2 --format tailwind
fontstay fit font.woff2 -a 'last 2 chrome versions, os windows' --json

オプション

オプション意味
-s, --systems <list>調整するシステム:windows、macos、ios、android、linux、chromeos。既定:対象ユーザーのシェアが 1% 以上のすべてのシステム。
-a, --audience <query>Browserslist クエリ。「os <system>」と「not os <system>」の部分を付けることもできます。既定:Baseline 広く利用可能。
-f, --format <format>出力形式。下記を参照してください。既定:css。
-k, --kind <kind>フォールバックの汎用ファミリー:sans-serif、serif、monospace、cursive。既定:フォントから検出。
--locale <en|ru>調整に使う頻度プロファイル:en または ru。既定:en。
--unicode-range各フォントがカバーするグリフを持つ unicode-range を追加します。
--no-scriptsキリル文字とギリシャ文字の個別のフェイスを出力しません。
-o, --out <file>出力を stdout ではなくファイルに書き込みます。
--jsonファイルのテキストの代わりに、JSON レポートを出力します。
-h, --help / -v, --versionヘルプまたはバージョンを表示します。

出力形式

--format には、次のいずれかの値を指定します。アプリのエクスポート形式に対応し、同じ調整結果から作られます。

サンプルの Fira Sans フォントを使い、形式ごとにこのコマンドを実行します。表示している出力は、ビルド済みの CLI によるものです。

コマンド

fontstay fit tests/fixtures/fonts/FiraSans-Regular.ttf --systems windows --no-scripts --format css

CLI の出力

@font-face {
  font-family: "Fira Sans Fallback";
  src: local("Trebuchet MS"), local("TrebuchetMS");
  size-adjust: 100.3942%;
  ascent-override: 93.1328%;
  descent-override: 26.3959%;
  line-gap-override: 0%;
}

body {
  font-family: "Fira Sans", "Fira Sans Fallback", sans-serif;
  /* Safari has no vertical overrides: match the x-height and fix the line box */
  font-size-adjust: 0.527;
  line-height: 1.4;
}

.fonts-loading {
  letter-spacing: -0.0019em;
}

出力とレポート

ファイルのテキストは stdout に出力されます。--json を付けると、CLI は代わりにレポートを出力します。キーは file(選択した形式の出力)、fonts(フォントごとのファミリー、検出された種類、グリフのカバー率、システムごとに選ばれたフォールバック)、shares(システムごとの対象ユーザーのシェア、単位は %)、systems、uncovered(対象ユーザーにいるが、フォールバックフォントのないシステム)、audience(解決されたクエリと、一致したブラウザー数)です。シェアは、実行時点のブラウザーデータに左右されます。

警告は stderr に出力されるため、出力に混ざることはありません。フォールバックと共有するグリフが 90% 未満のフォント、およびフォールバックフォントのないシステムが対象です。--out を付けた場合、CLI は書き込んだファイルについても stderr に報告します。

Node ライブラリ

fit はフォントのバイト列を受け取り、fitFiles はファイルを読み取ります。どちらも、CSS、指定した形式の出力、フォントごとのレポート、対象ユーザーのシェアを返します。失敗すると、FitRunError(invalid-audience、no-systems、no-fit)または FontParseError(例:invalid-font)をスローします。型は index.d.ts にあります。

import { fit, fitFiles } from 'fontstay';
import { readFile } from 'node:fs/promises';

const { css, fonts, shares } = await fit({
  fonts: [{ fileName: 'font.woff2', data: await readFile('font.woff2') }],
  audience: 'defaults',
  systems: ['windows', 'macos'],
});

const tailwind = (await fitFiles(['font.woff2'], { format: 'tailwind' })).file.text;

終了コード

コード意味
0成功。
1失敗:読み取れないファイル、無効なフォント、無効な対象ユーザー。
2使い方のエラー:不明なコマンド、フォントファイルの指定なし、オプションの値が無効。

MCP サーバーをセットアップする