@zhang_jifan/fanui

fanUI v2.1

fanUI：一套 UI 设计系统，内置 12 套可在运行时切换的主题配色（默认 cyan）、液态玻璃质感（强度可调 + 总开关）、明暗双模式；适配官网、博客与 B 端控制台场景。 下载即可使用：可以直接用 <script> / <link> 引入编译产物（不需要构建工具），也可以装进项目走 npm + 构建（ESM / SCSS 按需）。纯 CSS 变量驱动、SCSS 可配置。

📗 调用文档（零基础开箱即用：引入方式 / React·Vue 兼容 / JS API 全参数参考）见 USAGE.md。 📘 完整设计规范（主题轴 / 玻璃材质 / 自动可达性算法 / 扩展指南）见 DESIGN-SYSTEM.md。

1. 目录结构

fanUI/
├── package.json                  # 构建脚本与元信息
├── README.md                     # 本文档
├── DESIGN-SYSTEM.md              # 设计系统规范（v2 核心）
├── theme-audit.md                # 对比度审计报告（60/60 通过）
├── src/
│   ├── fanui.scss                # 主入口（按顺序聚合全部模块）
│   ├── fanui.js                  # 可选：交互运行时（主题中枢/工作台/组件交互），无外部依赖
│   ├── _functions.scss           # 工具函数（含对比度/自动选阶色彩数学）
│   ├── _variables.scss           # SCSS 设计变量（$fanui-*）
│   ├── _mixins.scss              # 混合宏（含 fanui-liquid-glass / 主题发射器）
│   ├── _tokens.scss              # 非主题色令牌 → CSS 自定义属性
│   ├── themes/                   # ★ v2 主题系统
│   │   ├── _palettes.scss        #   12 套主题定义（数据与逻辑分离）
│   │   └── _accents.scss         #   主题发射器：12 色 × 明暗 × auto 全量输出
│   ├── glass/                    # ★ v2 液态玻璃
│   │   └── _tokens.scss          #   玻璃令牌族（强度/预设/模式感知）
│   ├── base/                     # 基础层
│   │   ├── _reset.scss           #   CSS 重置 / Normalize
│   │   ├── _typography.scss      #   字体排版体系
│   │   └── _animations.scss      #   关键帧与动效工具类
│   ├── layout/                   # 布局层
│   │   ├── _container.scss       #   容器 / 主布局骨架
│   │   ├── _grid.scss            #   12 列响应式栅格 + CSS Grid 工具
│   │   └── _flex.scss            #   Flexbox / 显示 工具类
│   ├── components/               # 组件层
│   │   ├── _button.scss          #   按钮 / 按钮组
│   │   ├── _form.scss            #   表单 / 输入框 / 文本域
│   │   ├── _choice.scss          #   选择器 / 复选 / 单选 / 开关 / 分段
│   │   ├── _card.scss            #   卡片 / 面板 / 统计卡
│   │   ├── _table.scss           #   表格
│   │   ├── _badge.scss           #   徽标 / 标签 / 状态点
│   │   ├── _alert.scss           #   警告框 / Toast
│   │   ├── _nav.scss             #   导航栏 / 侧边栏 / 面包屑 / 菜单
│   │   ├── _tabs.scss            #   选项卡 / 手风琴
│   │   ├── _overlay.scss         #   模态框 / 抽屉 / 下拉 / 气泡
│   │   ├── _feedback.scss        #   进度 / 加载 / 骨架屏 / 空状态
│   │   ├── _data.scss            #   头像 / 列表 / 分页 / 步骤条 / 时间线
│   │   ├── _glass.scss           # ★ 玻璃材质 + 5 预设 + 组件玻璃形态
│   │   ├── _input-plus.scss      # ★ 滑块/评分/上传/标签输入/步进器/验证码/色板/联想
│   │   ├── _interactive.scss     # ★ ⌘K 命令面板/Dock 放大/轮播/聚光灯/主题工作台
│   │   ├── _marketing.scss       # ★ Hero/Bento/定价/证言/FAQ 等营销场景
│   │   ├── _blog.scss            # ★ 文章卡/文章版式/目录 scrollspy/评论/订阅
│   │   └── _dashboard.scss       # ★ KPI/柱状图/环形图/看板/通知/筛选栏
│   └── utilities/                # 工具层（最后输出，保证优先级）
│       ├── _spacing.scss         #   间距
│       ├── _display.scss         #   显示 / 定位 / 溢出 / 层级
│       ├── _sizing.scss          #   尺寸 / 宽高比
│       ├── _borders.scss         #   边框 / 圆角 / 分割线
│       ├── _effects.scss         #   阴影 / 滤镜 / 背景 / 交互
│       └── _texture.scss         # ★ 极光/网格/噪点/渐变描边/流光/涟漪
├── scripts/                      # 门禁与工具链（`npm run gates` 一键全跑）
│   ├── build.cjs                 #   构建脚本（自动定位 sass）
│   ├── run-gates.cjs             #   全量门禁编排
│   ├── verify-*.cjs              #   专项验证：demo / examples / ssr / install / visual / browsers / edge …
│   ├── audit-*.cjs               #   审计：覆盖度 / 对比度 / 无障碍
│   ├── verify-published.cjs      #   发布后：把文档里每个下载入口逐条实测
│   ├── preflight-publish.cjs     #   发布资格自检
│   └── selfcheck/                #   门禁元测试（故意注入坏值，没被抓到就失败）
├── dist/                         # 编译产物
│   ├── fanui.css / fanui.min.css #   样式（展开版 / 压缩版）
│   ├── fanui.js / .mjs / .cjs    #   运行时三种入口：IIFE / ESM / CommonJS(+SSR 门面)
│   ├── fanui.d.ts                #   TypeScript 类型声明
│   └── modules/                  #   分模块 CSS（可单独引入其中一块）
├── shots/
│   └── visual-baseline/          # 视觉回归基线（其余截图都是每次跑门禁重建的产物）
└── demo/
    ├── index.html                # ★ 场景化演示站：官网/博客/控制台/组件/设计系统 5 场景
    └── components.html           # 全组件百科页（令牌/排版/栅格/组件/工具类）

2. 命名规范

2.1 总原则

2.2 类名结构（BEM 变体）

.fanui-block                    块
.fanui-block__element           元素（双下划线）
.fanui-block--modifier          修饰符（双连字符）
.fanui-block.is-state           状态（独立类，便于 JS 切换）

2.3 工具类命名

.fanui-<属性简写>-<值>              .fanui-mt-4   .fanui-text-center   .fanui-gap-6
.fanui-<属性简写>-<断点>-<值>       .fanui-mt-md-4  .fanui-flex-lg-col  .fanui-order-lg-2
.fanui-<属性简写><方向>-<值>        .fanui-px-6   .fanui-my-auto

方向简写：t 上 · r 右 · b 下 · l 左 · x 左右 · y 上下 · 缺省 四向

断点简写：xs(≥0) · sm(≥576) · md(≥768) · lg(≥992) · xl(≥1200) · xxl(≥1400)

3. 快速开始

逐步可照做的完整接入说明（含包管理器 / CDN / React 多版本 / Vue2·Vue3 写法）见 USAGE.md；下面是最短路径。

3.0 零安装：CDN 直接引用（最快验证）

不想装任何东西？把下面两行贴进 HTML 就能看到完整效果（包已发布到 npm，CDN 可用）：

<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@zhang_jifan/fanui@2.1.1/dist/fanui.min.css">
<script src="https://cdn.jsdelivr.net/npm/@zhang_jifan/fanui@2.1.1/dist/fanui.js"></script>

也可换用 unpkg：把域名换成 https://unpkg.com，路径完全相同。 @2.1.1 可写成 @2 自动跟进 2.x；正式项目建议锁定完整版本号。 内网或离线环境请看 USAGE.md §1.2 的本地镜像写法。 不确定这几条链接是否可用？ npm run verify:published 会把本文档里的每个下载入口真跑一遍；手工验证方法见 USAGE.md §1.2.1。

3.1 直接使用编译产物（不接构建流程）

<html data-fanui-theme="dark" data-fanui-accent="cyan" data-fanui-glass="on">
<head>
  <link rel="stylesheet" href="dist/fanui.css">
</head>
<body>
  <button class="fanui-btn fanui-btn--primary">主要按钮</button>
  <script src="dist/fanui.js"></script>
  <script>
    FanUI.studio.mount();                 // 可选：挂载「主题工作台」悬浮面板
  </script>
</body>
</html>

3.2 SCSS 引入（整库 + 可配置）

// 覆盖默认设计变量（必须在其它 fanui 模块之前 @use）
@use "@zhang_jifan/fanui/src/fanui" with (
  $fanui-primary: #7c3aed,
  $fanui-radius-base: 8px,
  $fanui-grid-columns: 24,
  $fanui-enable-dark-mode: true
);

3.3 按需引入单个模块

@use "@zhang_jifan/fanui/src/functions" as fn;
@use "@zhang_jifan/fanui/src/mixins" as mx;
@use "@zhang_jifan/fanui/src/variables" as v;

.my-panel {
  @include mx.fanui-flex(column, flex-start, stretch, nowrap, v.$fanui-spacer);
  padding: fn.fanui-px2rem(24px);
  border-radius: fn.fanui-px2rem(8px);
  color: fn.fanui-var("color-text");          // var(--fanui-color-text)
  background: fn.fanui-alpha(v.$fanui-primary, 0.08);

  @include mx.fanui-media("md") {            // @media (min-width: 768px)
    flex-direction: row;
  }
}

4. 工具函数 API（fanui-*()）

5. Mixin API（@include fanui-*）

布局：fanui-flex() · fanui-inline-flex() · fanui-center-flex() · fanui-flex-item() · fanui-flex-fill() · fanui-grid() · fanui-grid-auto() · fanui-container() · fanui-container-fluid() · fanui-make-row() · fanui-make-col()

尺寸定位：fanui-size() · fanui-square() · fanui-absolute-fill() · fanui-abs-center() · fanui-fixed-fill() · fanui-aspect-ratio()

响应式：fanui-media() · fanui-media-down() · fanui-media-between() · fanui-media-only() · fanui-each-breakpoint() · fanui-prefers-dark() · fanui-motion-safe()

文本外观：fanui-truncate() · fanui-font() · fanui-text-gradient() · fanui-visually-hidden() · fanui-placeholder() · fanui-clearfix()

外观：fanui-appearance-none() · fanui-focus-ring() · fanui-elevation() · fanui-border() · fanui-border-radius() · fanui-transition() · fanui-disabled() · fanui-scrollbar() · fanui-gradient() · fanui-glass() · fanui-pressable()

组件生成器：fanui-button-variant() · fanui-button-outline-variant() · fanui-button-text-variant() · fanui-button-size() · fanui-badge-variant() · fanui-badge-soft-variant() · fanui-alert-variant() · fanui-form-control() · fanui-form-validation() · fanui-card-variant() · fanui-interactive-surface() · fanui-backdrop() · fanui-table-variant() · fanui-progress-variant() · fanui-switch-variant()

令牌输出：fanui-emit-theme() · fanui-emit-palette() · fanui-emit-semantic-colors()

6. 设计令牌（CSS 自定义属性）

运行时可通过覆盖 :root 或任意容器上的变量实现免编译换肤：

:root {
  --fanui-primary: #7c3aed;               /* 品牌主色 */
  --fanui-radius-base: 8px;               /* 全局圆角 */
  --fanui-color-bg: #0b1120;              /* 页面底色 */
  --fanui-space-4: 18px;                  /* 基础间距 */
  --fanui-font-size-base: 15px;
}

主题切换

<!-- 三条运行时轴，可任意组合 -->
<html data-fanui-theme="auto" data-fanui-accent="violet" data-fanui-glass="on">

// 深浅模式（v1 兼容 API 保留）
FanUI.theme.set("dark");
FanUI.theme.toggle();

// v2：12 主题色 / 深浅 / 玻璃 三轴控制
FanUI.theme.setAccent("emerald");      // 12 选 1，全组件即时生效
FanUI.theme.setMode("dark");           // light / dark / auto
FanUI.theme.setGlass(false);           // 玻璃总开关
FanUI.theme.setGlassIntensity(1.4);    // 液态强度 0–2
FanUI.theme.setGlassPreset("lens");    // thin/regular/thick/ultra/lens
FanUI.theme.createAccent("#ff6b35");   // 任意品牌色 → 合规主题（自动对比度选阶）

document.addEventListener("fanui:accentchange", e => console.log(e.detail));

主题角色令牌 / 玻璃令牌 / 自动可达性算法等完整规范见 DESIGN-SYSTEM.md。

7. 组件清单

8. 构建与质量验证

npm install          # 安装 dart-sass（唯一开发依赖）
npm run build        # 产出 dist/fanui.css + fanui.min.css + fanui.js
npm run watch        # 监听编译
npm run serve        # 本地起服务预览 demo/index.html

node scripts/audit-theme.cjs       # 对比度审计：12 主题 × 明暗，60/60 项 ≥4.5:1 → theme-audit.md
node scripts/verify-demo.cjs       # 真实浏览器回归：0 console error · 48 组合遍历 · 交互回归 · 14 张截图
node scripts/verify-examples.cjs   # 示例页回归（examples/01、04 的结构断言 + 截图）
node scripts/probe-entries.cjs     # 打包入口验证：ESM（浏览器原生模块）/ CJS（Node 安全空导出）

版本要求：sass >= 1.79.0（项目使用 color.channel() 等现代色彩 API，编译零弃用告警）。 浏览器验证：需本机安装 Chrome；verify-demo.cjs 自动定位托管工作区的 playwright-core，产物输出到 demo/shots/。

9. 设计约定

• 三条正交运行时轴：主题色（data-fanui-accent）· 深浅模式（data-fanui-theme）· 玻璃（data-fanui-glass），相互独立、运行时切换、零重编译。
• 组件只消费角色令牌：任何组件不得写死主题色值，保证换主题全组件一致生效。
• 自动可达性：实心色由色阶中自动挑选对比度达标（≥4.5:1）的一阶，任意品牌色接入即合规。
• 移动优先：所有断点媒体查询均为 min-width，基础样式面向最窄屏。
• 零 !important 滥用：仅在工具类与显示控制等必要处使用。
• 可访问性：全部交互控件保留原生语义（<button>/<input>/<label>），提供 .fanui-visually-hidden、.fanui-skip-link、:focus-visible 焦点环（随主题色）、forced-colors 高对比模式与 prefers-reduced-motion / prefers-reduced-transparency 自动降级。
• 动效克制：统一 --fanui-duration-* / --fanui-ease-*。
• 中国市场约定：.fanui-stat__trend--up 为红色（涨），--down 为绿色（跌）。

授权（License）

fanUI 采用 AGPL-3.0-or-later 与商业许可的双许可模式 —— 同一个软件，两条授权路径，按使用场景选一条：

逐场景的选择指引、商业授权获取方式与贡献者条款见 COMMERCIAL-LICENSE.md。 package.json 中对应声明为 "license": "AGPL-3.0-or-later"（标准 SPDX 标识，企业合规扫描器可识别）。

AGPL 与 GPL 的关键差异在「第 13 条 远程网络交互」：即使你不分发代码， 只要把 fanUI 用在对外提供服务的网络应用里（网站 / SaaS），也必须向这些用户提供完整对应源码。 这正是「闭源商用需要购买商业许可」的根源 —— 购买商业许可后，该范围内的 AGPL 开源义务被商业条款替代。

授权询价见官网「定价」分区的联系渠道（微信 / QQ）；企业采购可开具发票。