A fast, lightweight, efficient and thoughtfully built framework-agnostic component library
A headless core with Vue 3 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. The same connect() output runs one shared conformance suite on both the Vue and the Web Components side, advancing the case step by step and comparing normalized DOM, so "framework-agnostic" is a property under test rather than a slogan. 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 and Web Components behave identically
- 121 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
18 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/stylesBoth adapters share the same tokens and skins — import them once at the entry point:
import { createThemeController } from '@xihan-ui/tokens/runtime'
import '@xihan-ui/tokens/tokens.css'
import '@xihan-ui/styles'
createThemeController({ storageKey: 'app-theme' })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>Web Components: the element renders no structure of its own. You write Light-DOM children carrying data-xh-part, and the element applies the connect() output to them.
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 — every example on a component page uses the real component, with the Vue and Web Components spellings side by side:
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 68 structural checks), pnpm test, pnpm build, pnpm size and more.
In the box: 121 components with their cores and both adapters, the default 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.