workspace/code/g3soft-libs/packages/ui/README.md

@g3soft/ui

G3Soft 通用 UI 组件库（Vue 3 + TypeScript）。

安装

pnpm add @g3soft/ui @g3soft/tokens

vue 通过 peerDependencies 声明，由宿主项目提供，请确保宿主已安装 Vue 3。

使用

样式变量来自 @g3soft/tokens，在应用入口引入一次：

import '@g3soft/tokens'

按需引入组件：

<script setup lang="ts">
import { G3Button } from '@g3soft/ui'
</script>

<template>
  <G3Button type="primary" @click="handleClick">主要按钮</G3Button>
</template>

也可以全量注册：

import { G3UI } from '@g3soft/ui'
import { createApp } from 'vue'

createApp(App).use(G3UI).mount('#app')

主题

只暴露一个主色 primary，色阶、交互态、on-primary、氛围色与中性灰全部自动派生 （OKLab 空间计算，success / warning / danger 为独立固定语义色，不参与派生）：

<G3ConfigProvider :theme="{ primary: '#18181b' }">
  <App />
</G3ConfigProvider>

• theme.scope 默认 local：变量挂到子树根，支持同页多主题；传 global 则挂到 :root 做整站换肤。
• theme.dark 复用同一派生算法切换到暗色。
• 不传 theme 时，@g3soft/tokens 的静态默认值即权威来源，外观零漂移。

命名空间（前缀）

类名 / CSS 变量 / @keyframes 前缀统一由编译期 $namespace（默认 g3）派生， 消费方不能单独配置 CSS 变量前缀。换前缀需重编译样式：

// 你的样式桥接文件，例如 src/styles/g3.scss
@forward '@g3soft/tokens/scss' with ($namespace: 'xx');

// vite.config.ts
// additionalData 只能 @use 桥接文件；with 不能写在 additionalData 里（会被重复配置而报错）
css: { preprocessorOptions: { scss: { additionalData: `@use "@/styles/g3.scss" as *;` } } },

再用相同的 $namespace 重编译 @g3soft/ui 源码，并设置运行时命名空间：

import { G3UI } from '@g3soft/ui'
G3UI.config({ namespace: 'xx' })

dev 模式下运行时前缀与编译期前缀不一致会告警。该校验是启发式：能发现「改了运行时前缀却 仍在用预编译 g3 样式」，但无法感知「重编译了 SCSS 却跑预编译 JS」——两者必须手动保持一致。

全局配置

组件树外的实例（未来 Message.xxx() 等）拿不到 inject 上下文，用静态方法写全局兜底：

import { G3UI, zhCN } from '@g3soft/ui'

G3UI.config({ namespace: 'g3', zIndex: 2000, locale: zhCN })

构建

pnpm build

产物在 dist/，包含 ESM 入口与类型声明。发布前会由 prepublishOnly 执行 publint 校验包结构。

约定

• 样式不写 scoped，统一用命名空间前缀（默认 g3-）+ BEM 命名，便于消费方覆盖。
• 组件内部拼类名一律走 useNamespace()，不在模板里硬编码前缀。
• 每个 CSS 变量都带兜底值，保证未引入 tokens 时组件仍可正常显示。
• 组件不写死颜色与尺寸，一律引用 --g3-* 变量；文案一律走 useLocale()。