LibKa

LibKa 设计平台

只需用 Markdown 编写一次文档，即可生成网页、A4 PDF、16:9 幻灯片和可编辑 Word 文件；每种输出都会经过无障碍检查，并附有记录检查内容的签名记录。

LibKa 是一个设计系统（W3C DTCG 设计令牌）和文档平台。你只需编写一个 Markdown 文件，并使用 LibKa 块：步骤、提示框、表格、图表、示意图、时间线、比较、发行说明等（总计 35 种块类型）。构建过程会生成文档所需的输出。随后，Guard 会检查每种输出、在真实浏览器中检查页面，并为通过检查的输出签署一份记录检查内容的清单。LibKa Studio 让任何人都能以可视化方式编写相同的文档，无需接触 Markdown。

• 网站： https://libka.aivigator.ai/
• 在浏览器中试用 LibKa Studio： https://libka-studio.aivigator.ai/
• 文档： docs/，请从快速入门和块目录开始

状态： 版本 2.0.1。在 Windows 上开发和测试；CI 在 Linux（Ubuntu）上运行完整测试套件，并在 Windows 上运行健康检查；未在 macOS 上测试。

为什么选择 LibKa

Markdown 发布工具早已能将单一源文件转换为网页、PDF 和幻灯片。LibKa 的不同之处在于，它会检查每种输出，并明确说明检查了什么：

• **可自动化的规则会强制执行；其余规则则会列出，供人工检查：**块包含自身的无障碍规则（图片必须提供替代文本），构建过程遇到问题时会停止并显示 file:line 消息，Guard 会在 Chrome 中测量渲染结果，而非源文件；符合性报告则会列出仍需人工检查的内容。
• **PDF 会经过修复和验证：**Chrome 生成的带标签 PDF 会修复为符合 PDF/UA-1，并由 PDF Association 的参考验证器 veraPDF 验证所有可由机器检查的规则（PDF/UA 的其余要求，例如有意义的阅读顺序，需要人工检查）。
• **每种输出都有记录：**每次构建都会生成一份签名清单，记录检查内容，并附上一份 WCAG 2.2 / EN 301 549 符合性报告。
• **这是设计系统，而非主题：**颜色、字体和间距均来自 DTCG 令牌；令牌构建会在浅色、深色和高对比度模式下对令牌的对比度进行门控检查。
• **让从未接触过 Markdown 的人也能进行可视化编辑，**在 LibKa Studio 中实时执行相同的检查，同时保持 Markdown 为唯一的事实来源。

LibKa 适用于必须满足无障碍要求并保持一致性的手册、指南、政策、报告和演示文稿。它不是页面布局工具：你选择的是块，而非位置。

LibKa Studio

一款可安装的 Web 应用，将文档保存在你自己的设备上：可使用视觉编辑器、源码编辑器，或将两者并排显示；实时预览网页、手机、A4 页面和幻灯片；输入时执行相同的 Guard 检查，可安全修复的问题可一键修复，否则会以通俗易懂的文字说明；支持版本管理、命令面板、英语和捷克语、浅色、深色和高对比度模式，打开后即可离线使用。Studio 还有自己的无障碍自审报告（docs/acr/studio.md），并已通过纯键盘操作、NVDA、强制颜色、重排和触摸模拟测试。

在本地运行：npx -y @libka/cli studio，然后打开它显示的地址。

快速开始

你需要	用途
Node.js 22.18 或更新版本、Google Chrome	构建和检查文档（libka doctor 会显示你的电脑已安装哪些内容）
Java 21 和 veraPDF（无需管理员权限即可安装）	根据 PDF/UA-1 验证 PDF（构建时可选：没有它们仍会构建 PDF，但其清单、符合性报告和 verify 会说明该 PDF 未经过验证；check.py 必须使用它们）
Python 3.12 或更新版本	开发 LibKa 本身（check.py）

启动项目：

npm create libka@latest my-docs        # add -- --lang cs for the example in Czech
cd my-docs
npm install
npm run build                          # web page, PDF, slides and Word file in dist/, checked and signed
npm run verify                         # the files (the slides too) are the ones that were checked and signed

初始项目包含一个示例文档、npm run check（只检查源文件，只需几秒钟，无需浏览器）、一个 GitHub Actions 工作流，可使用 LibKa Guard action 检查每次推送和拉取请求，并在问题所在行标记问题，以及一份后续步骤说明。文档在 front matter 中选择输出格式，outputs: [web, pdf, deck, docx]；如果没有这一行，则会生成网页和 PDF。每个项目都使用自己的密钥签名，该密钥由首次构建生成在 .libka/ 中，并受信任于 .libka/trusted-keys.json（签名密钥）。

从本仓库的克隆版本开始：

git clone https://github.com/aivigator-ai/open-libka-design-platform.git && cd open-libka-design-platform
npx --yes [email protected] install
node packages/cli/src/libka.ts build examples/manual/guide.md     # the outputs land in examples/manual/dist/

编写文档

文档采用带 front matter 和块的 Markdown 格式：

---
title: Setting up the router
lang: en
outputs: [web, pdf, docx]
---

## Connect it

:::steps
1. **Plug in the power** The light turns orange.
2. **Connect the cable** Use the yellow port.
:::

:::callout[Before you start]{variant=important}
Keep the box: the Wi-Fi password is on its label.
:::

• examples/manual/guide.md 是一份介绍语法的简短示例；examples/open-source-guide/guide.md 是一份真实的长篇指南：将 GitHub 的两份 Open Source Guides（CC BY 4.0）制作成手册和幻灯片。
• 每个块都只定义一次，位于 packages/blocks：包括语法、属性、JSON schema、无障碍规则、反模式，以及网页、PDF、幻灯片和 Word 文件如何处理该块。
• 幻灯片使用同一个文件生成： 每个 ## 和 ### 都是一张幻灯片，:::notes 用于记录演讲者备注，内容过多的幻灯片会略微缩小字体或拆分成多张。
• 捷克语文档（lang: cs）会使用捷克语标签和捷克语排版。

每份输出包含的内容

• **在真实浏览器中进行检查：**使用 axe-core 检查 WCAG 2.2 A 级和 AA 级规则；检查每段可见文本与其实际背景的对比度，达到 4.5:1；读者要求更高对比度时达到 7:1；检查 LibKa 的结构规则；确保页面适配宽 320 像素的屏幕，无需横向滚动（重排）；确保幻灯片适配；采用严格的内容安全策略。
• 通过 veraPDF 验证符合 PDF/UA-1（ISO 14289-1）的 PDF：涵盖所有可由机器检查的规则。
• **结构规范的 Word 文件：**包含标题、列表、脚注、重复显示表头行的表格、带替代文本的图片以及文档语言；Guard 会检查其结构和对比度。
• **已签名的清单：**记录源文件、LibKa 版本、每项输出的哈希值以及每项检查的结果。它可以证明这些文件正是经过检查的文件，以及运行过哪些检查；它无法证明的内容也有明确说明。
• 一致性报告列出全部 55 项 WCAG 2.2 A/AA 级成功准则及其对应的 EN 301 549 条款，并标明其状态：自动检查通过、未通过、需要人工检查或不适用。
• **逐字节一致的构建：**相同的源文件会生成相同的网页和 Word 文件；使用相同版本的 Chrome 时，也会生成相同的 PDF。

**LibKa 不会声称什么。**自动化检查只能覆盖无障碍方面的一部分。输出通过检查，代表“通过了这些测试”，而非“无障碍”或“符合标准”：一致性报告会说明仍需人工审查的内容。LibKa 输出的报告草案见 docs/acr/libka-outputs.md。

AI 创作

• .claude/skills/libka-author/ 中的 Agent Skill：包含工作流，以及每种区块的精确语法（由注册表生成）。
• MCP 服务 @libka/mcp（位于 packages/mcp）：列出并描述区块、检查文档、构建文档。
• **对于 Claude Code，**两者以一个插件的形式提供：先运行 /plugin marketplace add aivigator-ai/open-libka-design-platform，再运行 /plugin install libka@libka。Claude Desktop、claude.ai、API 和其他 MCP 客户端请参阅 docs/ai-tools.md。
• AI 编写的内容会经过相同的检查。文档声明为 AI 编写的内容（如注明审阅者的 AI 摘要、AI 徽章）会列入已签名的清单。

仓库目录说明

路径	内容
tokens/、libka.resolver.json、generate.py	DTCG 设计令牌及其构建流程：CSS、SCSS、Tailwind（docs/tokens.md、设计系统手册）
packages/blocks	区块注册表、目录和技能参考生成器
packages/model	将 Markdown 转换为带类型的区块，按行列出问题，并为每个问题提供代码和安全修复方案（docs/problem-codes.md）
packages/render	网页、幻灯片、图表、幻灯片适配、内容安全策略、排版、区块样式
packages/guard	浏览器检查、Word 文件检查、WCAG / EN 301 549 映射、已签名的清单
packages/pdf、packages/docx	PDF/UA 修复和 veraPDF 验证；Word 文件
packages/editor	可视化编辑：ProseMirror schema、与 Markdown 的无损往返转换、区块命令
packages/cli、packages/mcp	libka build | lint | check | verify | studio | doctor；MCP 服务
packages/create-libka	入门模板，npm create libka
npm/、plugins/libka、.claude-plugin/	npm 包的构建和快速入门测试；Claude Code 插件及其市场配置文件
apps/studio	LibKa Studio
examples/、docs/	示例；文档和维护者指南

贡献

欢迎提交问题和拉取请求：请先阅读 CONTRIBUTING.md；AI 编码 Agent 请从 AGENTS.md 开始。问题和想法请提交到讨论区（SUPPORT.md 说明了预期情况）；新模块和功能发布时会列在 CHANGELOG.md 中。请先了解以下两点：

• 此仓库由维护者的开发仓库发布。获批的拉取请求会应用到该仓库，并随下一次发布一同推出；你将作为该发布提交的共同作者获得署名，并在变更日志中受到感谢。
• 每次提交都必须签署（git commit -s）。Signed-off-by 行证明你遵守了开发者原创证书：你有权根据项目许可协议贡献此更改。拉取请求检查会要求提供该签署；无需另行签署协议。

check.py 会运行拉取请求必须通过的所有检查：Python 测试、严格的 TypeScript 类型检查、所有测试（包括 Chrome 测试）、令牌构建，以及检查是否有生成文件未更新。

许可协议

Apache License 2.0（LICENSE）；第三方材料列于 NOTICE 中。字体采用 SIL Open Font License 许可。LibKa、LibKa Design Platform 和 LibKa Studio 是发布方的产品名称，许可协议并未授予这些名称的使用权：你发布修改后的版本时，必须为其另取名称（NOTICE）。

由 aivigator.ai 创建