cinafonts

Cina Group 字体中台仓库 —— 品牌字体的单一事实来源。字形源文件、编译流水线、Web 切字、分发与包发布都在这里完成。

仓库内构建代码以 MIT 许可发布；字体文件本身的许可证在每个家族目录中单独声明（通常为 SIL OFL 1.1 或公司内部专有许可），两者互不覆盖。

架构总览

flowchart LR
    subgraph SRC["fonts/<family>/sources"]
        G[".glyphs / .ufo / .designspace"]
        PRE["prebuilt/*.ttf 成品"]
    end

    B["build.py<br/>fontmake 编译"]
    OUT["fonts/<family>/build"]
    CFG["config/unicode-ranges.yaml<br/>切片预设（配置驱动）"]
    SUB["subset.py<br/>fonttools 切字 + CSS 生成"]
    QA["qa/check.py<br/>字体质检"]
    PACK["pack.py<br/>npm 打包"]
    DIST["dist/<slug>/<preset>/<style><br/>woff2 切片 + fonts.css"]

    G --> B --> OUT
    PRE --> OUT
    OUT --> QA --> SUB
    CFG --> SUB
    SUB --> DIST
    DIST --> PACK --> NPM["npm @cina/font-*"]
    DIST --> REL["GitHub Releases<br/>（tag 触发）"]
    DIST --> PAGE["GitHub Pages 预览<br/>demo/"]

Loading

设计原则：

1. 源文件即真相 —— 字体只从 fonts/<family>/sources/ 构建，任何产物都可删除后一键重建。
2. 配置驱动切片 —— 切字方案全部由 config/unicode-ranges.yaml 声明，不写死在脚本里。
3. 产物不进 git —— build/、dist/ 均在 .gitignore 中，由 CI 构建并经 npm / Releases / Pages 分发。
4. 二进制走 LFS —— .ttf/.otf/.woff2/.glyphs 由 Git LFS 管理（见 .gitattributes）。

目录结构

cinafonts/
├── fonts/                  # 字体家族（每个家族一个目录，接入方式见 fonts/README.md）
│   └── <slug>/             # 如 cina-sans/
│       ├── config.yaml     # 家族元数据 + 构建/切字/打包配置
│       ├── sources/        # 字形源（Glyphs/UFO/designspace 或 prebuilt 成品）
│       └── build/          # 编译产物（gitignore）
├── templates/font-family/  # 新家族脚手架，scripts/new_font.py 从这里生成
├── config/
│   ├── unicode-ranges.yaml # 字符集与切片预设（切片策略的唯一出处）
│   └── charsets/           # 字符表（高频字表等），generated/ 由脚本生成
├── scripts/                # 流水线
│   ├── build.py            # 编排：编译 → 质检 → 切字 → manifest
│   ├── subset.py           # 按 unicode-range 切片输出 woff2 + CSS
│   ├── gen_ranges.py       # 把切片预设编译为区间数据
│   ├── gen_charsets.py     # 生成可程序化推导的字符表（GB2312 等）
│   ├── pack.py             # 生成 npm 包到 packages/
│   ├── new_font.py         # 脚手架新字体家族
│   └── qa/check.py         # 字体质检（cmap 覆盖 / 命名 / OS/2 / 度量）
├── packages/               # npm 包输出（pack.py 生成，入库可复用缓存）
├── demo/                   # 预览页（GitHub Pages 部署）
├── docs/                   # 架构与流程文档
└── .github/workflows/      # CI / 构建 / 发布 / Pages

快速开始

# 0) 环境要求：Python 3.8+、Git LFS；编译字形源另需 fontmake（见 requirements-build.txt）
git clone https://github.com/cinagroup/cinafonts.git
cd cinafonts
git lfs install
make setup                    # pip install -r requirements.txt -r requirements-build.txt

# 1) 接入一个新字体家族（脚手架）
make new-font SLUG=cina-sans  # 然后把字形源放进 fonts/cina-sans/sources/

# 2) 构建：编译（如有源）→ 质检 → 切字，输出到 dist/
make build

# 3) 预览
make demo                     # http://localhost:8080

Windows 下没有 make 时直接运行对应 python 命令即可，例如 python scripts/build.py --all。

常用命令

命令	作用
python scripts/new_font.py --slug <slug>	脚手架新字体家族
python scripts/gen_charsets.py	生成 GB2312 等可推导字符表
python scripts/gen_ranges.py --all	把切片预设编译为区间数据（CI 冒烟检查）
python scripts/build.py --all	完整构建：编译 → 质检 → 切字 → manifest
python scripts/qa/check.py --all	单独跑字体质检
python scripts/subset.py --slug <slug>	单独切字
python scripts/pack.py --all	生成 npm 包

分发通道

通道	内容	触发方式
npm @cina/font-*	woff2 切片 + CSS，前端 @font-face 直引	推送 v* tag（需配置 NPM_TOKEN secret）
GitHub Releases	全量 dist zip	推送 v* tag
GitHub Pages	demo/ 预览页 + dist	推送 main
内部 CDN	将 dist/ 同步至 CDN（人工或后续 workflow）	—

前端接入示例（npm 包）：

@import "@cina/font-cina-sans/web-cjk/regular/css/fonts.css";

body {
  font-family: "Cina Sans", sans-serif;
}

CI 一览

Workflow	触发	内容
CI	push / PR	脚本语法、YAML lint、切片配置可编译、字体质检
Build fonts	main 更新 fonts/**	完整构建，dist 上传为 artifact
Release	tag v*	构建 + 打包 → GitHub Release + npm publish
Pages	main 更新	demo 预览页部署

文档

• 架构设计 —— 目录职责、数据流、决策记录
• 构建流水线 —— 每一步做了什么、如何本地复现
• CJK 切字方案 —— unicode-range 切片策略与自定义
• 版本与发布 —— 字体语义化版本与发布流程
• 新字体接入指南 —— 从源文件到上线的 checklist
• 贡献指南

License

• 仓库构建代码与文档：MIT
• 字体文件：以各家族目录内 OFL.txt 或同等许可证声明为准