fix(ui): ship font licenses with font assets

Author: librowski

apps/docs/src/content/docs/ui-library/overview.mdx

@@ -42,12 +42,32 @@ The package has six style surfaces:
   component, typography or font rules.
 
 The stylesheets reference `./assets/*.woff2`, so preserve the package's `dist`
-layout when copying or serving them.
+layout when copying or serving them. The font assets' SIL Open Font License 1.1
+texts ship beside them as `assets/OFL-poppins.txt` and `assets/OFL-inter.txt`.
 
 Only Poppins latin 400 and 600 are inline. Other weights, Inter, and non-ASCII
 glyphs use `font-display: swap` assets, so they can briefly appear in the
-fallback font while loading. Preload the relevant `.woff2` files when that
-flash of unstyled text (FOUT) is unacceptable:
+fallback font while loading.
+
+### Shipped font faces
+
+| Family  | Weight | Subset    | File name                            | Delivery |
+| ------- | ------ | --------- | ------------------------------------ | -------- |
+| Poppins | 300    | latin     | `poppins-latin-300-normal.woff2`     | Asset    |
+| Poppins | 400    | latin     | `poppins-latin-400-normal.woff2`     | Inline   |
+| Poppins | 500    | latin     | `poppins-latin-500-normal.woff2`     | Asset    |
+| Poppins | 600    | latin     | `poppins-latin-600-normal.woff2`     | Inline   |
+| Poppins | 700    | latin     | `poppins-latin-700-normal.woff2`     | Asset    |
+| Poppins | 300    | latin-ext | `poppins-latin-ext-300-normal.woff2` | Asset    |
+| Poppins | 400    | latin-ext | `poppins-latin-ext-400-normal.woff2` | Asset    |
+| Poppins | 500    | latin-ext | `poppins-latin-ext-500-normal.woff2` | Asset    |
+| Poppins | 600    | latin-ext | `poppins-latin-ext-600-normal.woff2` | Asset    |
+| Poppins | 700    | latin-ext | `poppins-latin-ext-700-normal.woff2` | Asset    |
+| Inter   | 400    | latin     | `inter-latin-400-normal.woff2`       | Asset    |
+| Inter   | 400    | latin-ext | `inter-latin-ext-400-normal.woff2`   | Asset    |
+
+Preload the relevant `.woff2` files when that flash of unstyled text (FOUT) is
+unacceptable:
 
 ```html
 <link rel="preload" href="./assets/poppins-latin-ext-400-normal.woff2" as="font" type="font/woff2" crossorigin />

packages/ui/combine-css-bundle.mts

@@ -103,9 +103,14 @@ const FONT_FACES: FontFaceDefinition[] = [
   },
 ];
 
+const FONT_LICENSE_FILES: Record<FontFaceDefinition['packageName'], string> = {
+  '@fontsource/inter': 'OFL-inter.txt',
+  '@fontsource/poppins': 'OFL-poppins.txt',
+};
+
 const require = createRequire(import.meta.url);
 
-function emitFontAssets(distributionDirectory: string): string {
+export function emitFontAssets(distributionDirectory: string): string {
   const assetsDirectory = path.resolve(distributionDirectory, 'assets');
   fs.mkdirSync(assetsDirectory, { recursive: true });
 
@@ -116,6 +121,10 @@ function emitFontAssets(distributionDirectory: string): string {
     if (!packageDirectory) {
       packageDirectory = path.dirname(require.resolve(`${face.packageName}/package.json`));
       packageDirectories.set(face.packageName, packageDirectory);
+      fs.copyFileSync(
+        path.resolve(packageDirectory, 'LICENSE'),
+        path.resolve(assetsDirectory, FONT_LICENSE_FILES[face.packageName]),
+      );
     }
 
     let packageUnicodeRanges = unicodeRanges.get(face.packageName);

packages/ui/font-assets.decision-log.md

@@ -0,0 +1,57 @@
+# Ship common font faces inline and the rest as assets
+
+### Title: Ship common font faces inline and the rest as assets
+
+### Proposed by: Jan Librowski
+
+### Date: 31.08.2026
+
+## Context
+
+Vite library mode inlined all twelve Poppins and Inter font faces as base64.
+The built stylesheet consequently carried approximately 382 KB of fonts:
+`index.css` was 509 KB, and the SDK stylesheet that bundles it was 591 KB.
+Most consumers need only the Poppins 400 and 600 latin faces declared by the
+typography classes, while the other weights, Inter, and extended latin subsets
+can load on demand.
+
+## Decision
+
+Generate the twelve `@font-face` rules after Vite finishes. Keep Poppins 400
+and 600 latin inline, and copy the other ten `.woff2` files into `dist/assets`.
+Apply fontsource's subset-specific unicode ranges and `font-display: swap` so a
+browser requests only the faces needed by the document. Ship the Poppins and
+Inter SIL Open Font License 1.1 texts beside the font assets.
+
+This reduces `index.css` from 509 KB to 150 KB and the SDK stylesheet from 591
+KB to 230 KB while preserving existing imports and immediate rendering for the
+two common faces.
+
+## Alternative Options Considered
+
+- **Keep everything inline.** Rejected because every consumer would continue
+  downloading approximately 382 KB of font data before using any face.
+- **Ship everything as assets.** Rejected because even the common Poppins 400
+  and 600 latin faces would require additional requests before normal UI text
+  renders.
+- **Patch the Vite configuration.** Rejected because Vite library mode ignores
+  the normal asset inline limit, so configuration alone cannot produce the
+  required mix of inline and emitted faces.
+- **Use a CDN.** Rejected because it adds an external runtime dependency,
+  changes Content Security Policy requirements, and prevents the package from
+  remaining self-contained.
+
+## Consequences
+
+- Consumers that define `font-src` in Content Security Policy must allow
+  `'self'` or the package-serving origin instead of relying only on `data:`.
+- Consumers that copy stylesheets must preserve the relative `dist/assets`
+  layout.
+- A future refactor that simplifies the pipeline back to fontsource CSS imports
+  can silently reintroduce approximately 382 KB of inline font data.
+- The build must keep the font asset references and shipped license files in
+  sync with `FONT_FACES`.
+
+## Status
+
+accepted

packages/ui/font-license.spec.mts

@@ -0,0 +1,24 @@
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { afterAll, beforeAll, describe, expect, it } from 'vitest';
+
+import { emitFontAssets } from './combine-css-bundle.mts';
+
+describe('font license assets', () => {
+  const distributionDirectory = fs.mkdtempSync(path.join(os.tmpdir(), 'wb-ui-font-licenses-'));
+
+  beforeAll(() => {
+    emitFontAssets(distributionDirectory);
+  });
+
+  afterAll(() => {
+    fs.rmSync(distributionDirectory, { recursive: true, force: true });
+  });
+
+  it.each(['OFL-poppins.txt', 'OFL-inter.txt'])('emits %s with the font assets', (fileName) => {
+    const license = fs.readFileSync(path.resolve(distributionDirectory, 'assets', fileName), 'utf8');
+
+    expect(license).toContain('SIL OPEN FONT LICENSE Version 1.1');
+  });
+});