Skip to content

Jixoai UI v0.3：扩展文档表达，改进视觉质感

jixoai v0.3.0 ui

文档里的插图、表格、公式与代码清单自动编号，正文随处引用；章节换序后编号与锚点照常工作。@jixoai/vite-plugin 0.2.0 随版发布，Vite 项目直接接入终端组件与图标系统。registry 收录 113 个条目，一次破坏性变更。

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

jixoai-ui 0.3.0 发布了（2026-09-05）。文档里的插图、表格、公式与代码清单从这一版起自动编号，正文任何位置都能引用它们；章节换序后编号跟着重排，链接锚点不失效。按压质感、滚动与密度也各有一轮统一。registry 收录 113 个条目，@jixoai/vite-plugin 0.2.0 随版发布。窗口内有一次破坏性变更，迁移见文末。

插图、表格与公式自动编号

旧编号机制退役后，编号引用一直没有归属，教材与工具书式的页面写不出来。这一版把它补齐了。

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

  • Figure 家族：按 kind（figure, table, equation, listing）在域内计数。编号、锚点与图注由包装组件承载，代码块嵌在内容槽里；citedIn 槽手动标注反链。

  • Reference 家族：引用渲染成什么由目标自己决定。指向编号浮动件渲染成 Eq (4.5)，指向编号节渲染成 § 3.2.1，指向无编号目标渲染成目标标题。id 缺失时回退为可见标记并 console.warn，不阻塞渲染。

来自 0.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>

编号与引用数据同时进入收割合同，即把渲染后 DOM 里的结构数据收进静态语料的那份契约。收割侧两趟预扫描先建全文档可引目标的索引，再把 data-ref-to 映射进语料，前向引用在 SSR 回退态里也保留指向关系；Figure 的 number、引用点块的 refids[] 与 Section 的 number 都是合同成员。结构落地后，搜索、llms.txt 与打印目录随之变准。

设计背景：文档结构本体

设计轨从一个问题出发（Owner 原话）：「假如你是创作者，你需要什么样的结构化表达？」词典学家要词头、词性与书证，作曲家要乐章、小节与排练标记，web 文档此前只给标题和代码块。答案是三层本体：CodeBlock 是表达原子，SectionCard 承载七种结构原语（节 / 条 / 列 / 浮 / 注 / 引 / 断），PrintDoc 是整篇文档的体裁预设。本轮落地的编号与引用属于「浮」「引」两个原语。提案原文见文末链接栏的设计档案。

章节换序，编号跟着重排

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

Vite 构建直接接入

用 Vite 的项目现在能把 jixoai-ui 的终端组件与图标系统接进构建。@jixoai/vite-plugin 0.2.0 随版发布：钉版本的 ghostty-vt wasm 走 resolve → serve → emit 管线，经 virtual:jixoai-ghostty 模块把资源 URL 交给页面。

图标系统带 svg, lucide, font 三种 provider，jixoai-ghostty-probe 是 ABI 哨兵 bin。此前的安装问题由 ghostty pin 解析与 lucide lock 同步一并修复（发布提交 125e31f1）。

其余变更

  • 按压质感成为全库规则：按钮质感有了 raised / flat 两个区域，flat 静止无阴影、按下呈现 engrave 内阴影；icon-button 加入该轴，Card 与 Dialog 脚区的按钮默认 flat。

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

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

  • 打印确定性：打印输出与视口无关。

  • defaults-economy 三项变更与单一 paint key 落地；control-chrome 让行内控件壳层在溶解与自持之间二选一。

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

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

提交类型统计（conventional 严格口径 grep -cE '^(type)(\(|!|:)'）：feat 270 / fix 262 / docs 146 / test 16 / chore 46 / refactor 28 / style 3，其余 16 个为 tune, spec, merge 与无前缀提交，合计 787。

迁移（破坏性：钩子类改属性）

破坏性口径：窗口内带 ! 标记的提交是 0 个，唯一的破坏性变更是 2026-08-25 的钩子迁移，README 以破坏性 markup 契约变更记录它。内容是 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