Skip to content

Jixoai UI v0.3.0：图、表、公式能自动编号和引用了

jixoai v0.3.0 ui

jixoai-ui v0.3.0 让文档里的图、表、公式与代码清单自动编号，正文任何位置都能引用它们。章节换序后编号跟着重排、锚点不失效，CSS counters 与 PagedRef 两套旧编号机制退役。registry 收录 113 个条目，@jixoai/vite-plugin 0.2.0 随本版发布。含一次破坏性变更。

$ git log v0.2.0..v0.3.0 --oneline | wc -l
786

jixoai-ui v0.3.0 发布了（2026-09-05）。从这一版起，文档里的图、表、公式与代码清单可以自动编号，正文任何位置都能引用它们。章节换序后编号跟着重排，链接锚点不失效。这一版共 786 个提交，registry 收录 113 个条目。

背景：文档需要一套结构本体

jixoai-ui 之前是 shadcn registry 形式的设计语言：终端美学、OKLCH 单色相法则、拷贝即所有的组件。这一版要解决的问题来自一个研究问题（2026-09-02 设计轨）：「假如你是创作者，你需要什么样的结构化表达？」词典学家要的是词头、词性和分义号，以及书证；作曲家要的是乐章、小节与排练标记。今天的 web 文档只给他们标题和代码块。

设计轨的答案是三层本体。最小的一层是 CodeBlock，一个表达原子；中间一层是 SectionCard，承载跨行业提取出的 7 种结构原语（节 / 条 / 列 / 浮 / 注 / 引 / 断）；最上一层是 PrintDoc，即整篇文档的体裁预设。

第一个消费者是收割合同，也就是把渲染后 DOM 里的结构数据收进静态语料的契约。结构一旦落地，搜索、llms.txt 与打印目录会跟着变准，不需要返工。

编号与交叉引用：计数域 + Figure（浮）+ Reference（引）

从这一版起，文档里的图、表、公式与代码清单自动编号，正文任何位置都能引用。编号引用一直是旧编号机制退役后的未尽事宜。没有本体归属，工具书与教材页无从谈起（变更提案的原始动机）。这一阶段在本版全量落地，落在三件事上。

  • Section 计数域：numbering 声明让一个节成为编号子树的根，同时是浮动件的计数域，十进制编号逐级自动生成（3 → 3.2 → 3.2.1）。不在任何计数域内的节逐字节不变。

  • Figure 家族（kind：figure | table | equation | listing）：SectionCard 承载结构，也就是编号、锚点与图注，CodeBlock 嵌在内容槽里；另有 citedIn 手动反链标注。

  • Reference 家族：目标自述语法，解析完全跟随目标。指向编号 Figure 渲染成 Eq (4.5)，指向编号节渲染成 § 3.2.1，指向无编号目标则渲染成目标标题。id 缺失时显式回退（console.warn + 可见标记，永不阻塞）。

来自 v0.3.0 文档页的真实用法：

<NumberingProvider>
  <Section numbering="decimal" title="Results">
    <Figure kind="equation" id="eq-1" caption="the momentum balance">
      <CodeCard lang="ts">p = m·v</CodeCard>
    </Figure>
    <p>see <Reference to="eq-1" /></p>
  </Section>
</NumberingProvider>

收割侧配套两趟预扫描。第一趟建全文档可引目标的索引，第二趟把 data-ref-to 映射进语料，前向引用在 SSR 回退态里也保留指向关系，静态语料保持完整。Figure 的 number、引用点块的 refids[] 与 Section 的 number 都进了收割合同，复用已落地的 data 标记。

编号跟随 DOM 顺序：CSS counters 与 PagedRef 退役

编号直接跟随 DOM 顺序，换序即重排、id 不动，所以章节换位后编号自动重排、链接锚点不失效、打印也不必为编号做任何特殊处理。编号已经在 DOM 里，打印管线原样捕获；页码仍归布局事实，永不预收割。CSS counters 与 PagedRef 两套旧编号机制正式退役，替代写法是上一节的 numbering 声明与 Reference。

不止编号：786 个提交的其余变更

  • press physics（按压物理）：raised/flat 双区、engrave 成对效果，icon-button 加入，按压物理从单组件规则扩展为全库规则

  • scroll-run：所有可滚动区域统一到一套共享法则（新 registry 条目 @jixoai/scroll-run），tabs 与 button-group 都成了它的消费者；slide/blur/blurSlide/progressBlur/shadow 五种效果由同一法则集供给，RTL 在三引擎上规范化（aeb747f2）

  • 2xs 密度档：第五档密度，面向专业工具操作面最紧凑的一档。文字 10px（9px 保持不发，作为绝对下限），行高 24px 落在 WCAG 2.5.8 AA 下限，命中下限按非触控指针立场在档内重声明（c8749f86）

  • 打印确定性：viewport 无关的打印输出

  • defaults-economy 三项变更 + 单一 paint key；control-chrome（行内控件壳层的溶解/自持二态）

  • ghostty 版本 pin 与 lock 链的 CI 修复

  • 全仓测试套件 2185/2185（604f9e01）

786 个提交里，270 个是 feat、261 个是 fix。

随本版一起发布：@jixoai/vite-plugin 0.2.0

用 Vite 的项目现在可以把 jixoai-ui 的终端组件与图标系统直接接进构建。vite-plugin 0.2.0 随本版一起发布：钉版本的 ghostty-vt wasm（resolve → serve → emit → 经 virtual:jixoai-ghostty 交 URL）、图标系统（svg/lucide/font providers）与 jixoai-ghostty-probe ABI 哨兵 bin。ghostty pin 解析器与 lucide lock 同步修复了它的安装问题（release commit 原话）。

迁移（破坏性：data-jx 钩子）

这一版的窗口内含一次破坏性变更（2026-08-25）：css-less 的 .jx-* 钩子类全面退役，语义锚改为 data-jx-* 属性，不保留兼容类。查询迁移：

  document.querySelector('[data-jx-kbd]')
  '[data-jx-badge="tonal"]'
  el.setAttribute('data-jx-foo', '')
  el.hasAttribute('data-jx-foo')

变体族合并为单一有值属性（data-jx-badge={variant}，阶梯 fill | tonal | outline 只含结构值，语义色名不进阶梯；error 状态 = variant="tonal" + jx-hue-error 注入）。最低摩擦路径：npx shadcn add @jixoai/<item> 重拉条目，再按上表迁移查询。

致谢

README 的原话：这里的一切都毕业于 unipty 与 openspecui 的生产工作。

链接

jixoai logo jixoai jixoai.com