# @fiscozen/style 中文文档

规范地址：https://npmcn.com/package/%40fiscozen/style/

版本：0\.5\.0
npm 元数据更新时间：2026-09-07T07:16:50.244Z
中文译文更新时间：2026-11-14T20:24:45.536Z
软件包许可：ISC

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40fiscozen/style
原文对照：https://npmcn.com/package/%40fiscozen/style/?lang=original

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：332 kB，35 个文件
- 模块格式：CommonJS
- TypeScript 类型：未声明
- 运行依赖：0 个
- peer 依赖：tailwindcss ^3\.4\.1，vue ^3\.4\.13
- 首次发布：2024-05-08T15:56:30.781Z
- 最新版本发布：2026-09-07T07:16:50.045Z
- 近 30 天下载量：12596（2026-10-15 至 2026-11-13，npm 官方下载统计）
- 已发布版本数：14（近 12 个月 5 个）

## 中文简介

设计系统包提供设计令牌,CSS变量和Vue.js自定义指令

## 安装

```sh
npm install @fiscozen/style
```

也可以使用：`pnpm add @fiscozen/style`、`yarn add @fiscozen/style`、`bun add @fiscozen/style`

## README

# @ fiscozen/ 风格

设计系统包提供设计令牌,CSS变量,和Vue.js自定义指令,以保持所有FiscoZen项目的视觉一致性.

## 特征

-   **设计托肯斯**: 颜色、间距、打字和更多真实的单一来源
-   **CSS 变量**: CSS 自定义属性中所有可用的符号
-   **Vue 自定义指令**: 字法定型指令(`v-color`, (中文(简体) ), `v-bold`, (中文(简体) ), `v-small`(中文(简体) )
-   **尾风集成**: 与 Tailwind CSS 通用类的无缝集成
-   **类型安全**: 有验证规则的完整类型脚本支持
-   **构建管道**: 自动令牌转换和CSS生成

## 安装

```bash
npm install @fiscozen/style
```

## 设置

在您的 Vue 申请中注册指令 :

```typescript
// main.ts
import { createApp } from 'vue'
import { setupFzStyle } from '@fiscozen/style'
import '@fiscozen/style/output/global.css'
import App from './App.vue'

const app = createApp(App)

// Register FiscoZen custom directives
setupFzStyle(app)

app.mount('#app')
```

## 基本用途

### v 颜色

对文本元素应用设计系统颜色 :

```vue
<template>
  <!-- Default weights (500 for base colors, 200 for semantic) -->
  <p v-color:blue>Blue text</p>
  <h1 v-color:semantic-error>Error heading</h1>
  
  <!-- Explicit weights -->
  <p v-color:blue="300">Light blue text</p>
  <h2 v-color:purple="700">Dark purple heading</h2>
</template>
```

### 粗体

对段落应用半粗体字体重:

```vue
<template>
  <p v-bold>This text is bold</p>
  <p v-bold="false">This text is normal weight</p>
</template>
```

### 小型

对段落应用小的文本大小 :

```vue
<template>
  <p v-small>This text is small</p>
  <p v-small="false">This text is normal size</p>
</template>
```

## Vue 自定义指令

### v 颜色

对标题和段落元素应用设计系统文本颜色.

**支持的元素 :**

-   段 次 页 次`<p>`(中文(简体) )
-   标题(`<h1>`, (中文(简体) ), `<h2>`, (中文(简体) ), `<h3>`(中文(简体) )

**可用颜色 :**

**基色 :**

-   `blue`, (中文(简体) ), `purple`, (中文(简体) ), `orange`, (中文(简体) ), `pink`, (中文(简体) ), `yellow`, (中文(简体) ), `grey`, (中文(简体) ), `core`
-   重量 : `50`, (中文(简体) ), `100`, (中文(简体) ), `200`, (中文(简体) ), `300`, (中文(简体) ), `400`, (中文(简体) ), `500` (违约), `600`, (中文(简体) ), `700`, (中文(简体) ), `800`, (中文(简体) ), `900`
-   对于 `core`数字 : `white`, (中文(简体) ), `black` (名称值而不是数字权重)

**语义颜色 :**

-   `semantic-error`, (中文(简体) ), `semantic-warning`, (中文(简体) ), `semantic-success`, (中文(简体) ), `semantic-info`
-   重量 : `50`, (中文(简体) ), `100`, (中文(简体) ), `200` (违约), `300`

**默认重量 :**

-   底色 − `500`
-   语义颜色 − `200`
-   核心颜色 `black`

**实例:**

```vue
<template>
  <!-- Base colors with default weight -->
  <p v-color:blue>Blue text (weight 500)</p>
  <p v-color:purple>Purple text (weight 500)</p>
  
  <!-- Explicit weights -->
  <p v-color:blue="300">Light blue text</p>
  <p v-color:blue="700">Dark blue text</p>
  
  <!-- Semantic colors -->
  <p v-color:semantic-error>Error message</p>
  <p v-color:semantic-success>Success message</p>
  <h3 v-color:semantic-error="300">Critical error</h3>
  
  <!-- Headings -->
  <h1 v-color:blue="700">Main title</h1>
  <h2 v-color:grey="600">Subtitle</h2>
  
  <!-- Remove color classes -->
  <p v-color:blue="false">Removes all color classes</p>
</template>
```

### 粗体

应用半粗体字体重量( N)`font-semibold`页:1.

**支持的元素 :**

-   段 次 页 次`<p>`(中文(简体) )

**实例:**

```vue
<template>
  <p v-bold>This text is bold</p>
  <p v-bold="false">This text is normal weight</p>
</template>
```

### 小型

应用小文本大小( E)`text-sm`页:1.

**支持的元素 :**

-   段 次 页 次`<p>`(中文(简体) )

**实例:**

```vue
<template>
  <p v-small>This text is small</p>
  <p v-small="false">This text is normal size</p>
</template>
```

## 合并指令

在同一要素上,可以结合多个指令:

```vue
<template>
  <p v-bold v-small v-color:blue>Bold, small, blue text</p>
  <p v-bold v-color:semantic-error>Bold error message</p>
</template>
```

## 实例

### 基本打字风格

```vue
<template>
  <div>
    <h1 v-color:blue>Welcome to FiscoZen</h1>
    <h2 v-color:grey="600">Your Financial Partner</h2>
    
    <p>Standard paragraph text</p>
    <p v-bold>Bold paragraph for emphasis</p>
    <p v-small>Small paragraph for secondary information</p>
    
    <p v-color:semantic-error>Error: Please check your input</p>
    <p v-color:semantic-success>Success: Changes saved!</p>
  </div>
</template>
```

### 格式反馈信件

```vue
<template>
  <form>
    <div v-if="error">
      <p v-color:semantic-error v-bold>Error: {{ error }}</p>
    </div>
    <div v-if="success">
      <p v-color:semantic-success>Success: {{ success }}</p>
    </div>
  </form>
</template>
```

### 动态颜色变化

```vue
<script setup>
import { ref } from 'vue'

const status = ref('info')
const colorMap = {
  info: 'semantic-info',
  success: 'semantic-success',
  error: 'semantic-error',
  warning: 'semantic-warning'
}
</script>

<template>
  <p :v-color="colorMap[status]">Status message</p>
</template>
```

## 验证

这些指令自动验证它们是否用于所支持的元素类型。 无效的使用会日志控制台错误 :

-   `v-color` 可用于 `<p>`, (中文(简体) ), `<h1>`, (中文(简体) ), `<h2>`, (中文(简体) ), `<h3>`
-   `v-bold` 只能用于 `<p>`
-   `v-small` 只能用于 `<p>`

## 无障碍

所有指令都保持语义HTML结构,不干扰屏幕阅读器:

-   色彩指令只应用视觉造型,维护文本内容
-   粗体和小指令保留文字语义
-   已登录无效的元素使用, 但不会中断功能
-   所有样式通过 CSS 类应用,保留语义意义

## 建筑

### 移动

```
tokens.json (Design tokens)
    ↓
token-transformer (Figma format → Style Dictionary format)
    ↓
tokens/global.json
    ↓
Style Dictionary (Custom formatters & transformers)
    ↓
    ├── output/global.css (CSS variables)
    └── output/global.json (JSON tokens)
    ↓
tailwind.config.js (Integrates tokens with Tailwind)
    ↓
Utility classes (text-blue-500, gap-4, etc.)
```

### 关键部件

**1\. 设计托肯斯`tokens.json`(中文(简体) )**

-   设计值的单一真理来源
-   通过Figma管理 托肯斯插件或手动编辑
-   包含颜色,间距,打字等.

**2\. 修建管道(`build.js`(中文(简体) )**

-   管弦乐符号转换
-   生成 CSS 变量和 JSON 输出
-   追加 CSS( 类型、 组件)

**3\. 尾风一体化`tailwind.config.js`(中文(简体) )**

-   将令牌转换成 Tailwind 主题
-   生成动态使用类的安全列表
-   提供语义间隔和颜色默认值

**4\. 指令`src/custom-directives/`(中文(简体) )**

-   `v-color`: 对文本应用设计系统颜色
-   `v-bold`: 应用半粗体字体重
-   `v-small`: 应用小文本大小

## 构建自定义( C)

### 重生成托肯斯

如果您修改了符号源文件 :

```bash
cd packages/style
npm run build
```

### 构建步骤

1.  **`build:transform`**: 转换 `tokens.json` 转到样式词典格式
2.  **`build-sd`**: 运行样式词典以生成 CSS 和 JSON
3.  **`tsc`**: 编译 TypeScript 指令到 JavaScript

### 扩展系统

**添加新颜色 :**

1.  添加颜色到 `tokens.json`
2.  添加颜色名称到 `safe-colors.json` (用于安全清单)
3.  运行 `npm run build`

**添加新语义颜色 :**

1.  添加语义颜色到 `tokens.json` 下级 `semantic.*`
2.  添加语义类型到 `safe-semantic-colors.json`
3.  运行 `npm run build`

**添加自定义 CSS :**

1.  创建 CSS 文件于 `src/` (例如, `components.css`(中文(简体) )
2.  添加文件名到 `ADDITIONAL_CSS_FILES` 内 `build.js`
3.  运行 `npm run build`

## 参考资料

-   **设计托肯斯**数字 : [W3C 设计托肯斯社区小组](https://www.w3.org/community/design-tokens/)
-   **样式词典**数字 : [https://amzn.github.io/style-词典/](https://amzn.github.io/style-dictionary/)
-   **切换器**数字 : [https://github.com/tokens-studio/figma-plugin 页面存档备份,存于互联网档案馆](https://github.com/tokens-studio/figma-plugin)

## 常见问题

### @fiscozen/style 是什么？

设计系统包提供设计令牌,CSS变量和Vue\.js自定义指令

### 如何安装 @fiscozen/style？

在项目目录运行 npm install @fiscozen/style，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：tailwindcss（^3\.4\.1）、vue（^3\.4\.13）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。

### @fiscozen/style 支持 TypeScript 吗？

该包的 package\.json 没有声明类型入口。需要类型提示时，可以在 npm 上查找社区维护的 @types/fiscozen\_\_style 是否存在。

### @fiscozen/style 支持 ESM 还是 CommonJS？

以 CommonJS 形式发布，可以直接 require\(\)；在 ES Module 项目中也可以用 import 引入（Node\.js 会把 module\.exports 作为默认导出）。

### @fiscozen/style 可以商用吗？

@fiscozen/style 使用 ISC 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### @fiscozen/style 的下载量有多少？

根据 npm 官方下载统计，@fiscozen/style 在 2026/10/15 – 2026/11/13 这 30 天内被下载 12,596 次，日均约 420 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @fiscozen/style 还在维护吗？

最新版本 0\.5\.0 发布于 2026/09/07（2 个月前）；至今共发布 14 个版本，其中过去 12 个月发布了 5 个；首次发布于 2024/05/08。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。