UI 套件文档

指南

• shadcn 迁移

  把 shadcn/ui React 组件转换为可在任何技术栈中使用的 Chiralkit 模块。

可安装的组件

每个组件都以你拥有的源代码形式落入你的项目——可评审、可编辑，由你来做版本管理。

• badge

  用于标注类型、状态或类别的小型标签。

• button

  设计系统的基础按钮——提供 primary/secondary 变体及 disabled 状态。

• card

  带边框的圆角表面，用于组合内容——无 props，单一 default slot，无 ARIA role。使用者在内部自行组织标题结构。

• checkbox

  原生 <input type="checkbox">，封装为设计系统的自定义元素——checked/indeterminate props 会转发到 DOM，dsChange 发出新的布尔状态。保留浏览器默认的 checkbox 渲染，以维持辅助技术（AT）和 forced-colors 模式下的行为。

• code-block

  带语言标签和内置复制按钮的代码块。

• dialog

  原生 <dialog> 元素，封装为设计系统的自定义元素——showModal() 借助浏览器平台提供模态状态机（焦点陷阱、按 Escape 关闭、背景 inert、焦点归还），而非从零构建的 ARIA。Props：open、label|labelledBy、describedBy。事件：dsOpen、dsClose。

• figure-canvas

  可复用的图形视口，支持缩放、检查控件和可选的水平拖动旋转。

• input

  原生 <input>，封装为设计系统的自定义元素——支持 text/email/password/search/tel/url/number 类型，用 invalid+describedBy 表示错误状态，并在每次按键时发出携带当前值的 dsInput。

• loader

  由 chiralkit 标志的 path 构成的不确定加载指示器——两个镜像对称的半边围绕圆环中心摆动。

• select

  原生 <select>，封装为设计系统的自定义元素——选项通过 prop 传入，发出携带新值的 dsChange。

• tabs

  WAI-ARIA Tabs 模式（从零构建）——仅包含 tablist，支持 roving tabindex、方向键导航、Home/End 和自动激活。使用者在 light DOM 中自行渲染 tabpanel，并在 dsChange 时切换其可见性。设为 shadow:false，以便 tabpanel 通过 aria-labelledby 引用各个 tab 的 id。

• textarea

  原生 <textarea>，封装为设计系统的自定义元素——带 rows prop 的多行文本框，用 invalid+describedBy 表示错误状态，并在每次按键时触发 dsInput 事件。

• tooltip

  WAI-ARIA Tooltip 模式（从零构建）——将使用者的第一个 Element 子节点包装为触发器，hover 时打开（带 openDelay），focus 时立即打开；按 Escape 关闭，焦点仍留在触发器上；在 blur 或真正的 mouseleave 时关闭。设为 shadow:false，以便触发器上的 aria-describedby 能引用 tooltip 的 id。