@xwink/ui

开始使用

安装

本 monorepo 通过 workspace 直连（@xwink/ui: workspace:*），改组件后 HMR 即时生效。仓外项目从私有 CNB 制品库安装同一个包名，并固定到经过远端矩阵验收的精确 beta 版本。

json
// apps/* 的 package.json
{ "dependencies": { "@xwink/ui": "workspace:*" } }

三件套接入

@xwink/ui 在 workspace 与 tgz 中都是源码依赖，.vue / .ts 由宿主编译。宿主要做的是一个模块（组件编译 + X* 全局注册）+ 两段 CSS（token 生效 + 原子类生成）：

1. @xwink/ui/nuxt 模块

在 modules 里加 '@xwink/ui/nuxt'，模块自动完成两件事：

  • X 组件全局注册*：模板直接写 <XButton> / <XTable>，无需逐文件 import——漏 import 会让 Vue 把组件当原生自定义元素渲染成小写空壳（如 <xinput>），全局注册后这类静默故障从机制上消失；
  • build.transpile 自动补上：源码 SFC 不能进 esbuild 的依赖预构建（不认 .vue 直接炸），模块替你交给主构建管道。
ts
// nuxt.config.ts
export default defineNuxtConfig({
  modules: ['@xwink/ui/nuxt'],
})

模块不接管 tokens.css 与 tailwind.css 的导入顺序（见下两节）——宿主要按「import 之后覆写品牌色」的顺序控制，模块注入会失去这层可控性。

2. tokens.css import

组件只消费 --ui-* 语义 token，默认值集中在包的 tokens.css。默认已经使用 xwink.fun 的琥珀铜品牌；宿主只有在确有独立品牌时才在 app 级入口覆写（写在 import 之后，靠顺序取胜，不用 !important）：

css
/* app/assets/css/main.css */
@import 'tailwindcss';
@import '@xwink/ui/tokens.css';
@import '@xwink/ui/tailwind.css';

/* 独立品牌宿主才覆写主题色与次级色；强调渐变由两者自动生成 */
:root {
  --ui-primary: #059669;
  --ui-primary-fg: #ffffff;
  --ui-secondary: #047857;
  --ui-secondary-fg: #ffffff;
}

3. tailwind.css 扫描包源码

组件样式是 Tailwind 原子类。@xwink/ui/tailwind.css 内部以 @source "./" 扫描包源码；路径相对包自身解析，因此 workspace 和 tgz 无需两套宿主路径：

css
@import '@xwink/ui/tailwind.css';

深色模式

组件库通过 token 适配明暗，组件代码零分支：html 上的 data-theme="dark" 启用深色档（tokens.css 的 [data-theme="dark"] 块）。

Nuxt 宿主启用 @xwink/ui/nuxt 后不用自己写这个属性：模块按全站共享的主题 Cookie 定档（默认跟随系统），首帧、SSR 与切换都已接好，详见 useTheme。不要在 htmlAttrs 里写死档位，那会和用户偏好打架。

本站在右上角「调试面板」可实时切换四维适配（明暗 / 尺寸 / 对比度 / 主题色），所见即宿主可配置的全部维度。