Fonts

@pikacss/plugin-fonts 讓 hosted fonts、local @font-face 定義，以及語意化 font tokens 都能進入和其他 PikaCSS configuration 一樣的 build-time workflow。

什麼時候該用它

當你想要下面這些能力時，就用 fonts plugin：

用 provider 驅動的方式匯入 web fonts，而不是手動維護 URL
使用像 sans、mono、display 這類會變成可重用 utilities 的語意化 tokens
用同一份 config 管 hosted fonts 與 local @font-face families
為 provider-specific options 與 custom provider definitions 保留擴充空間

Install

pnpmnpmyarn

pnpm add @pikacss/plugin-fonts

npm install @pikacss/plugin-fonts

yarn add @pikacss/plugin-fonts

最小設定

// pika.config.ts
import { defineEngineConfig } from '@pikacss/core'
import { fonts } from '@pikacss/plugin-fonts'

export default defineEngineConfig({
	plugins: [fonts()],
	fonts: {
		fonts: {
			sans: 'Roboto:400,500,700',
			mono: ['IBM Plex Mono:400,500', 'ui-monospace'],
		},
	},
})

每個 token 都會同時產生 font-{token} shortcut 與對應的 --pk-font-{token} CSS variable。

Provider-specific options

Google Fonts 是預設 provider，而 Bunny、Fontshare 與 Coollabs 也都已經內建。

當某個 provider 需要自己的 query 參數時，應該透過 providerOptions 傳入，而不是把 URL 組裝邏輯直接寫死在 config 裡。

// pika.config.ts
import { defineEngineConfig } from '@pikacss/core'
import { fonts } from '@pikacss/plugin-fonts'

export default defineEngineConfig({
	plugins: [fonts()],
	fonts: {
		provider: 'coollabs',
		providerOptions: {
			coollabs: {
				text: 'PikaCSS',
			},
		},
		fonts: {
			brand: 'Roboto:400,700',
		},
	},
})

Custom providers

v2 provider interface 讓你可以註冊自己的 import builder，同時沿用同一套 token model 與產生出的 utilities。

// pika.config.ts
import { defineEngineConfig } from '@pikacss/core'
import { defineFontsProvider, fonts } from '@pikacss/plugin-fonts'

export default defineEngineConfig({
	plugins: [fonts()],
	fonts: {
		provider: 'acme',
		providerOptions: {
			acme: {
				text: 'PikaCSS',
			},
		},
		providers: {
			acme: defineFontsProvider({
				buildImportUrls(fonts, context) {
					return `https://cdn.example.com/fonts.css?family=${fonts.map(font => font.name).join(',')}&display=${context.display}&text=${context.options.text}&subset=${fonts[0]?.options?.subset}`
				},
			}),
		},
		fonts: {
			brand: {
				name: 'Acme Sans',
				providerOptions: {
					subset: 'latin',
				},
			},
		},
	},
})

手動 `@font-face` 與本地檔案

如果字體檔已經放在你的專案或 CDN 上，就直接定義 faces，再把它們映射到語意化 family tokens。

// pika.config.ts
import { defineEngineConfig } from '@pikacss/core'
import { fonts } from '@pikacss/plugin-fonts'

export default defineEngineConfig({
	plugins: [fonts()],
	fonts: {
		faces: [{
			fontFamily: 'Satoshi',
			src: 'url("/fonts/satoshi.woff2") format("woff2")',
			fontWeight: 500,
			fontStyle: 'normal',
			fontDisplay: 'swap',
		}],
		families: {
			display: ['Satoshi', 'sans-serif'],
		},
	},
})

Fonts ​

什麼時候該用它 ​

Install ​

最小設定 ​

Provider-specific options ​

Custom providers ​

手動 @font-face 與本地檔案 ​

Next ​