A fast, lightweight, efficient and thoughtfully built framework-agnostic component library
A headless core with Vue 3, React 19 and Web Components adapters — composable, accessible and themeable UI infrastructure
English | 简体中文
XiHan.UI is built around a framework-agnostic headless core: a component's state, interaction and accessibility logic live in that core, and every framework only gets a thin adapter. Vue, React and Web Components run the shared conformance suite against the same connect() output, advancing the case step by step and comparing normalized DOM. XiHan.UI is the component layer of the XiHanFun open-source ecosystem, which spans foundation, components and applications.
- Framework-agnostic - state and accessibility live in the headless core; Vue, React and Web Components share the same component contracts
- 128 components - covering general, layout, navigation, data entry, data display, feedback, overlay and AI chat — eight groups
- Almost dependency-free - the only third-party runtime dependency is
@internationalized/date; floating positioning, pointer sessions, code highlighting and streaming markdown are all first-party - Build-time styling - tokens are generated from DTCG sources into CSS variables and skins are layered with
@layer; no CSS-in-JS at runtime - Themeable - color mode, brand, density, contrast and writing direction switch independently
- Accessible - keyboard interaction follows the W3C APG; accessibility is scanned in real Chromium
- TypeScript - fully typed, discoverable in the editor
17 public packages, all published to npm; the current version is on the npm badge above.
pnpm add @xihan-ui/vue @xihan-ui/tokens @xihan-ui/stylesAll three adapters share the same tokens and skins — import them once at the entry point:
import { createVisualEnvironmentController } from '@xihan-ui/tokens/runtime'
import '@xihan-ui/tokens/tokens.css'
import '@xihan-ui/styles'
createVisualEnvironmentController({
root: document.documentElement,
initial: { mode: 'system', motion: 'system', transparency: 'system' },
})Vue:
<script setup lang="ts">
import { XhDialogContent, XhDialogRoot, XhDialogTitle, XhDialogTrigger } from '@xihan-ui/vue'
</script>
<template>
<XhDialogRoot v-slot="{ setOpen }">
<XhDialogTrigger>Open dialog</XhDialogTrigger>
<XhDialogContent>
<XhDialogTitle>Confirm</XhDialogTitle>
<button @click="setOpen(false)">Close</button>
</XhDialogContent>
</XhDialogRoot>
</template>React 19:
pnpm add @xihan-ui/react @xihan-ui/tokens @xihan-ui/stylesimport { XhDialogCloseTrigger, XhDialogContent, XhDialogRoot, XhDialogTitle, XhDialogTrigger } from '@xihan-ui/react'
export function Example() {
return (
<XhDialogRoot>
<XhDialogTrigger>打开对话框</XhDialogTrigger>
<XhDialogContent>
<XhDialogTitle>确认操作</XhDialogTitle>
<XhDialogCloseTrigger>关闭</XhDialogCloseTrigger>
</XhDialogContent>
</XhDialogRoot>
)
}Web Components: write Light-DOM children carrying data-xh-part; the element applies the connect() output and adds the internal parts defined by each component's contract.
import { defineXhElements } from '@xihan-ui/web-components/define'
defineXhElements()<xh-dialog>
<button data-xh-part="trigger">Open dialog</button>
<div data-xh-part="backdrop"></div>
<div data-xh-part="positioner">
<div data-xh-part="content">
<h2 data-xh-part="title">Confirm</h2>
<button data-xh-part="close-trigger">Close</button>
</div>
</div>
</xh-dialog>https://ui.docs.xihanfun.com — component pages are generated from the headless output and the type definitions, and include the connect API, keyboard tables and state charts.
The styling floor is Chrome 111, Firefox 113 and Safari 16.2 (the bar for oklch, @layer and :where); below that line you get no styling rather than a degraded one. Local development requires Node.js 24+ and pnpm 11+.
The package catalog, directory layout and development commands live in ui/README.md.
To see the components running locally, first cd ui && pnpm build, then start the documentation site, which includes Vue, React and Web Components examples using real components:
cd docs
pnpm install
pnpm devChanges must pass the full CI gate, and CI runs the same commands you do locally: pnpm lint, pnpm typecheck, pnpm boundaries, pnpm gate (one command runs 111 structural checks), pnpm test, pnpm build, pnpm size and more.
In the box: 128 components with their cores and three adapters, 127 visual-component skins, design tokens and the theme runtime, the cross-adapter conformance suite, the accessibility sweep and floating-position contract in real Chromium, and the documentation site.
Not in the box: bundled language packs (component copy ships English only; other languages need your own translations, though the global injection point is in place), the token browser, the AI family's MarkdownStream / Reasoning and ToolCall collapsing / tool approval, and enterprise business components.
- XiHan.Framework - modular development framework for .NET
- XiHan.BasicApp - enterprise admin kernel built on XiHan.Framework and Vue 3
Issues and pull requests are welcome. Commits follow conventional commits, and changes must pass the gates listed above.
In no particular order.
| Project | Thanks for |
|---|---|
| Zag.js | Reference specs for component state charts and ARIA wiring |
| W3C APG | The normative basis for accessible interaction patterns |
| CommonMark | The source of markdown semantics and the conformance benchmark |
| axe-core | The engine behind automated accessibility scanning |
| Other third-party dependencies | Being the foundation this project is built upon |
If this project helps your work, feel free to buy the author a coffee.
Official sponsorship page: https://docs.xihanfun.com/cosmos/sponsor
Copyright (c) 2021-Present XiHanFun and contributors.
Released under the MIT License — see License.
The XiHan.UI logo, name, interface visual design and original visual expression belong to the author; third-party dependencies and services are governed by their own licenses and terms.
This project is provided for study and reference; the author assumes no liability for any use of the software.