web-font/README.en.md

WebFont — Runtime Font Delivery + AI Typography Skill

Subset Chinese fonts on demand — 6 characters ≈ 6KB. Use premium Chinese fonts on any web page.

中文

Chinese fonts are huge (Source Han Sans: 16MB+). You can't just @font-face them like English fonts.

This project subsets fonts on the server side — pass in the text you need, get back only those glyphs. A poster with 20 characters? The font file is 20KB, not 16MB.

<!-- One CSS block to use any Chinese font -->
<style>
@font-face {
  font-family: "MyFont";
  src: url("https://webfont.shenzilong.cn/api?font=令东齐伋复刻体&text=静心茶舍&outType=woff2") format("woff2");
}
.title { font-family: "MyFont", serif; }
</style>
<h1 class="title">静心茶舍</h1>

Who Is This For

Any project that needs Chinese Web Fonts:

• Posters / H5 pages — a few characters subset to a few KB
• Brand websites — premium fonts no longer limited by file size
• Mini apps / PWA — bandwidth-sensitive, load on demand
• Static blogs / CMS — content is known, CSS-only output
• AI-generated pages — let AI output well-designed Chinese font solutions

Features

Live Typography Skill Demo — same content, different fonts, completely different feel

Runtime Font Delivery

Server-side subsetting + client-side incremental loading.

6 characters → server subsets font → returns ~6KB (not 16MB)

JS SDK with three loading modes:

<script src="https://webfont.shenzilong.cn/webfont-sdk.js"></script>
<script>
  // Recommended: MutationObserver-driven, auto-loads new characters on DOM change
  WebFont.observeFont({ fontName: "令东齐伋复刻体.ttf", selector: ".content", family: "MySerif" });

  // Polling mode
  WebFont.loadFont({ fontName: "令东齐伋复刻体.ttf", selector: ".title", family: "MySerif" });

  // Manual text mode
  var loader = WebFont.loadText({ fontName: "令东齐伋复刻体.ttf", text: "你好世界", family: "MySerif" });
  loader.update("追加文字");
</script>

All modes share the same character set per font — zero duplicate requests, zero flicker.

Typography Presets

Pre-defined font style configs for common scenarios:

Preset	Style	Heading	Body	Use Cases
zen	Oriental / Zen	Noto Serif CJK SC	LXGW WenKai	Tea, culture, meditation
luxury	Luxury / High-end	Noto Serif CJK SC	Noto Serif CJK SC	Brand sites, fashion
editorial	Editorial / Content	Noto Serif CJK SC	Noto Sans CJK SC	News, blogs, magazines
modern-tech	Modern Tech	Alibaba PuHuiTi	Noto Sans CJK SC	SaaS, dev tools
cyberpunk	Cyberpunk	ZCOOL KuaiLe	Noto Sans CJK SC	Games, street culture
minimal	Minimal	Noto Sans CJK SC	Noto Sans CJK SC	Portfolios, design
warm	Warm / Humanistic	LXGW WenKai	LXGW WenKai	Education, community
startup	Startup Energy	Noto Sans CJK SC Bold	Noto Sans CJK SC	Startups, events

Each preset includes font pairing, type scale, line height, spacing, fallback chain, runtime strategy, and ready-to-use CSS.

AI Typography Skill

Inject Chinese typography intelligence into AI (Claude, Cursor, Copilot, etc.). With the Skill Prompt, AI can:

• Auto-select fonts matching the scene
• Handle Chinese-English mixed typesetting
• Build proper typography hierarchy
• Generate fallback chains and runtime loading strategies

Prompt: "Build a zen-style tea brand website"

Without Skill: font-family: sans-serif → system default → looks generic

With Skill: zen preset → serif heading + kai body → auto subset → visual quality leap

Quick Start

API Only

No SDK needed. One CSS block to use any Chinese font. Server returns only the character subset you need.

@font-face {
  font-family: "MyFont";
  src: url("https://webfont.shenzilong.cn/api?font=令东齐伋复刻体&text=你的文字&outType=woff2") format("woff2");
}

Self-hosted

# Node.js / LLRT
pnpm install && pnpm build && pnpm build_backend
node ./dist_backend/app.cjs

Docker (~30MB image):

services:
  webfont:
    image: docker.io/llej0/web-font:latest
    ports:
      - "8087:8087"
    volumes:
      - ./fonts:/home/font
    environment:
      - ENABLE_TEMP_UPLOAD=true
      - ADMIN_API_KEY=your-secret-key
      - SUBSET_CACHE_MAX_SIZE=10485760

API Reference

Endpoint	Description
GET /api?font={name}&text={chars}&outType={woff2|ttf}	Subset font to specified characters
GET /api/fonts	List available fonts
GET /api/config	Get server configuration
POST /api/upload?mode=temp	Temporary font upload (auto-cleanup)
POST /api/upload?mode=admin	Permanent font upload (requires API key)

Font name supports fuzzy matching: exact → prefix → contains.

Architecture

┌──────────────────────────────────────────────────────────────┐
│                        Use Cases                              │
│  Posters/H5  ·  Brand Sites  ·  Blogs  ·  Mini Apps  ·  AI  │
└──────────────────────────┬───────────────────────────────────┘
                           │
              ┌────────────┴────────────┐
              │   Typography Presets    │ ← Font style configs
              │   + AI Skill Prompt     │ ← Chinese typography intelligence
              └────────────┬────────────┘
                           │
              ┌────────────┴────────────┐
              │   Runtime Font Delivery │ ← On-demand subsetting + incremental loading
              │   SDK + API             │
              └────────────┬────────────┘
                           │
              ┌────────────┴────────────┐
              │   Subset Engine         │ ← fonteditor-core
              │   parse → subset →      │   Font parsing, subsetting, format conversion
              │   optimize → serialize  │
              └─────────────────────────┘

Project Structure

web-font/
├── backend/            # Server: HTTP API + font subsetting engine
│   ├── routes/         # API route handlers
│   ├── font_util/      # Font subsetting core
│   └── server/         # HTTP server (Node.js + LLRT dual runtime)
├── src/                # Frontend: Vue 3 SPA
├── public/
│   └── webfont-sdk.js  # Runtime Font Delivery SDK
├── skills/             # AI Typography Skill Prompts
├── examples/           # Before/After demo pages
└── vendor/             # fonteditor-core

Roadmap

Current (MVP)

• Font subsetting API
• Runtime Font Delivery SDK (incremental loading, zero flicker)
• Docker deployment (LLRT, ~30MB image)
• Typography Presets
• AI Typography Skill Prompt

Next

• MCP Tool integration
• Vite Plugin for build-time font optimization
• CLI tool for batch font operations

Future

• AI Website Builder integration
• Runtime Glyph Streaming
• Edge Cache / CDN Strategy
• Variable Font support

Acknowledgments

• kekee000/fonteditor-core — Font parsing, subsetting, and format conversion
• 字体天下 — Free commercial-use Chinese fonts
• Featured in 阮一峰科技爱好者周刊第 100 期

License

MIT © 崮生