npm - @zhang_jifan/fanui - Versions diffs - 2.1.0 - Mend

@zhang_jifan/fanui 2.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (127) hide show

package/ACCESSIBILITY.md +61 -0
package/CHANGELOG.md +112 -0
package/COMMERCIAL-LICENSE.md +71 -0
package/DESIGN-SYSTEM.md +294 -0
package/LICENSE +661 -0
package/README.md +348 -0
package/USAGE.md +1926 -0
package/_index.scss +20 -0
package/dist/fanui.cjs +15 -0
package/dist/fanui.css +28209 -0
package/dist/fanui.d.ts +353 -0
package/dist/fanui.esm.js +71 -0
package/dist/fanui.js +4782 -0
package/dist/fanui.min.css +1 -0
package/dist/fanui.mjs +71 -0
package/dist/modules/fanui-advanced.css +830 -0
package/dist/modules/fanui-advanced.min.css +129 -0
package/dist/modules/fanui-alert.css +575 -0
package/dist/modules/fanui-alert.min.css +122 -0
package/dist/modules/fanui-badge.css +426 -0
package/dist/modules/fanui-badge.min.css +77 -0
package/dist/modules/fanui-base.css +1394 -0
package/dist/modules/fanui-base.min.css +236 -0
package/dist/modules/fanui-blog.css +762 -0
package/dist/modules/fanui-blog.min.css +108 -0
package/dist/modules/fanui-button.css +526 -0
package/dist/modules/fanui-button.min.css +56 -0
package/dist/modules/fanui-card.css +291 -0
package/dist/modules/fanui-card.min.css +52 -0
package/dist/modules/fanui-choice.css +539 -0
package/dist/modules/fanui-choice.min.css +83 -0
package/dist/modules/fanui-dashboard.css +1057 -0
package/dist/modules/fanui-dashboard.min.css +160 -0
package/dist/modules/fanui-data.css +687 -0
package/dist/modules/fanui-data.min.css +125 -0
package/dist/modules/fanui-feedback.css +432 -0
package/dist/modules/fanui-feedback.min.css +79 -0
package/dist/modules/fanui-form.css +779 -0
package/dist/modules/fanui-form.min.css +123 -0
package/dist/modules/fanui-glass.css +497 -0
package/dist/modules/fanui-glass.min.css +46 -0
package/dist/modules/fanui-input-plus.css +799 -0
package/dist/modules/fanui-input-plus.min.css +124 -0
package/dist/modules/fanui-interactive.css +960 -0
package/dist/modules/fanui-interactive.min.css +138 -0
package/dist/modules/fanui-layout.css +4399 -0
package/dist/modules/fanui-layout.min.css +1172 -0
package/dist/modules/fanui-marketing.css +1125 -0
package/dist/modules/fanui-marketing.min.css +144 -0
package/dist/modules/fanui-nav.css +458 -0
package/dist/modules/fanui-nav.min.css +76 -0
package/dist/modules/fanui-overlay.css +547 -0
package/dist/modules/fanui-overlay.min.css +91 -0
package/dist/modules/fanui-table.css +290 -0
package/dist/modules/fanui-table.min.css +62 -0
package/dist/modules/fanui-tabs.css +333 -0
package/dist/modules/fanui-tabs.min.css +58 -0
package/dist/modules/fanui-themes.css +2728 -0
package/dist/modules/fanui-themes.min.css +40 -0
package/dist/modules/fanui-tokens.css +587 -0
package/dist/modules/fanui-tokens.min.css +3 -0
package/dist/modules/fanui-utilities.css +6557 -0
package/dist/modules/fanui-utilities.min.css +1762 -0
package/dist/modules/sizes.json +103 -0
package/docs/MIGRATION-v2.md +179 -0
package/examples/01-script-tag.html +149 -0
package/examples/02-react/README.md +39 -0
package/examples/02-react/index.html +12 -0
package/examples/02-react/package.json +20 -0
package/examples/02-react/src/App.jsx +108 -0
package/examples/02-react/src/main.jsx +13 -0
package/examples/02-react/src/useFanUI.js +87 -0
package/examples/02-react/vite.config.js +6 -0
package/examples/03-vue3/README.md +67 -0
package/examples/03-vue3/index.html +12 -0
package/examples/03-vue3/package.json +19 -0
package/examples/03-vue3/src/App.vue +93 -0
package/examples/03-vue3/src/main.js +8 -0
package/examples/03-vue3/src/useFanUI.js +85 -0
package/examples/03-vue3/vite.config.js +6 -0
package/examples/04-vue2-cdn.html +93 -0
package/examples/README.md +34 -0
package/package.json +127 -0
package/src/_functions.scss +319 -0
package/src/_mixins.scss +1202 -0
package/src/_tokens.scss +180 -0
package/src/_variables.scss +491 -0
package/src/base/_animations.scss +210 -0
package/src/base/_reset.scss +359 -0
package/src/base/_rtl.scss +133 -0
package/src/base/_typography.scss +353 -0
package/src/components/_advanced.scss +763 -0
package/src/components/_alert.scss +322 -0
package/src/components/_badge.scss +279 -0
package/src/components/_blog.scss +693 -0
package/src/components/_button.scss +351 -0
package/src/components/_capabilities.scss +463 -0
package/src/components/_card.scss +281 -0
package/src/components/_choice.scss +444 -0
package/src/components/_dashboard.scss +950 -0
package/src/components/_data.scss +618 -0
package/src/components/_feedback.scss +403 -0
package/src/components/_form.scss +408 -0
package/src/components/_glass.scss +374 -0
package/src/components/_input-plus.scss +730 -0
package/src/components/_interactive.scss +885 -0
package/src/components/_marketing.scss +982 -0
package/src/components/_nav.scss +480 -0
package/src/components/_overlay.scss +517 -0
package/src/components/_table.scss +276 -0
package/src/components/_tabs.scss +338 -0
package/src/fanui.d.ts +353 -0
package/src/fanui.js +4782 -0
package/src/fanui.scss +79 -0
package/src/glass/_switches.scss +36 -0
package/src/glass/_tokens.scss +259 -0
package/src/layout/_container.scss +111 -0
package/src/layout/_flex.scss +164 -0
package/src/layout/_grid.scss +180 -0
package/src/themes/_accents.scss +201 -0
package/src/themes/_palettes.scss +180 -0
package/src/utilities/_borders.scss +104 -0
package/src/utilities/_display.scss +145 -0
package/src/utilities/_effects.scss +210 -0
package/src/utilities/_sizing.scss +123 -0
package/src/utilities/_spacing.scss +118 -0
package/src/utilities/_texture.scss +323 -0

package/examples/02-react/src/useFanUI.js ADDED Viewed

@@ -0,0 +1,87 @@
+/* =============================================================================
+ * fanUI · React 适配 Hook（React 16.8+ 全版本通用）
+ * -----------------------------------------------------------------------------
+ * 设计要点：
+ *   1. fanUI 的样式挂在 <html> 的 data-fanui-* 属性上，与 React 树无关 ——
+ *      所以三轴状态用一个「全局单例」保存，React 只负责把状态映射到 DOM。
+ *   2. SSR 下 FanUI 可能为 null（服务端无 DOM），全部走空值兜底。
+ *   3. init() 幂等（内部有 __fanuiInit 防重复标记），React 18 StrictMode
+ *      的 double-effect 也不会重复初始化。
+ * ========================================================================== */
+import { useEffect, useState, useCallback } from "react";
+import FanUI from "@zhang_jifan/fanui";
+/** 挂载一次：初始化声明式组件 + 主题工作台；SSR 安全 */
+export function useFanUI(options) {
+  useEffect(() => {
+    if (!FanUI) return;                       // SSR / 非浏览器环境
+    FanUI.init();                             // 幂等：重复调用无副作用
+    if (options && options.studio) FanUI.studio.mount({ defaultOpen: false });
+  }, []);
+}
+/** 订阅主题三轴状态（12 主题色 / 深浅模式 / 玻璃），返回 [状态, 操作方法] */
+export function useFanTheme() {
+  const read = useCallback(() => {
+    if (!FanUI) return null;
+    const s = FanUI.theme.snapshot();
+    return {
+      ...s,
+      accents: FanUI.theme.accents,            // 12 套主题元数据
+      presets: FanUI.theme.glassPresets,       // 5 个玻璃预设
+    };
+  }, []);
+  const [state, setState] = useState(read);
+  useEffect(() => {
+    if (!FanUI) return;
+    const sync = () => setState(read());
+    ["fanui:accentchange", "fanui:themechange", "fanui:glasschange"]
+      .forEach((ev) => document.addEventListener(ev, sync));
+    return () => {
+      ["fanui:accentchange", "fanui:themechange", "fanui:glasschange"]
+        .forEach((ev) => document.removeEventListener(ev, sync));
+    };
+  }, [read]);
+  return {
+    state,
+    setAccent: (k) => FanUI && FanUI.theme.setAccent(k),
+    nextAccent: () => FanUI && FanUI.theme.nextAccent(),
+    setMode: (m) => FanUI && FanUI.theme.setMode(m),
+    toggleMode: () => FanUI && FanUI.theme.toggleMode(),
+    setGlass: (on) => FanUI && FanUI.theme.setGlass(on),
+    setGlassIntensity: (v) => FanUI && FanUI.theme.setGlassIntensity(v),
+    setGlassPreset: (p) => FanUI && FanUI.theme.setGlassPreset(p),
+    createAccent: (hex, name) => FanUI && FanUI.theme.createAccent(hex, name),
+    reset: () => FanUI && FanUI.theme.reset(),
+  };
+}
+/** 命令式浮层：返回 { open, close }，组件卸载时自动关闭 */
+export function useFanOverlay(selector, options) {
+  const [inst, setInst] = useState(null);
+  useEffect(() => {
+    if (!FanUI) return;
+    const o = new FanUI.overlay(selector, options);
+    setInst(o);
+    return () => o.close();                    // 卸载时收尾，防滚动锁残留
+  }, [selector]);                              // eslint-disable-line react-hooks/exhaustive-deps
+  return {
+    open: () => inst && inst.open(),
+    close: () => inst && inst.close(),
+    toggle: () => inst && inst.toggle(),
+    instance: inst,
+  };
+}
+/** Toast 捷径 */
+export function useToast() {
+  return {
+    success: (t, d) => FanUI && FanUI.toast.success(t, d),
+    error: (t, d) => FanUI && FanUI.toast.error(t, d),
+    info: (t, d) => FanUI && FanUI.toast.info(t, d),
+    warning: (t, d) => FanUI && FanUI.toast.warning(t, d),
+  };
+}

package/examples/02-react/vite.config.js ADDED Viewed

@@ -0,0 +1,6 @@
+import { defineConfig } from "vite";
+import react from "@vitejs/plugin-react";
+export default defineConfig({
+  plugins: [react()],
+});

package/examples/03-vue3/README.md ADDED Viewed

@@ -0,0 +1,67 @@
+# fanUI × Vue 3 示例（Vite + Vue 3.5）
+## 运行
+```bash
+cd examples/03-vue3
+npm install        # fanui 通过 "file:../.." 直接引用仓库源码
+npm run dev
+```
+## Vue 2 的写法差异
+fanUI 本身与 Vue 版本无关（CSS 全局 + 命令式 JS），差异只在「初始化时机」：
+**Vue 2.7（内置组合式 API）**：本目录的 `useFanUI.js` 把 `vue` 的导入换成 Vue 2.7 的
+`import { ref, onMounted, onBeforeUnmount, reactive } from "vue"` 即可，其余不变。
+**Vue 2.6 及以下（Options API）**：
+```js
+// main.js
+import Vue from "vue";
+import App from "./App.vue";
+import "@zhang_jifan/fanui/style.css";
+Vue.config.productionTip = false;
+new Vue({
+  mounted() {
+    if (window.FanUI) window.FanUI.init();   // 初始化声明式组件
+  },
+  beforeDestroy() {
+    // 组件卸载前关闭浮层，避免滚动锁残留
+  },
+  render: (h) => h(App),
+}).$mount("#app");
+```
+```html
+<!-- App.vue 里的用法与 Vue 3 完全一致 -->
+<template>
+  <button class="fanui-btn fanui-btn--primary" @click="$fanui.toast.success('ok')">确定</button>
+</template>
+<script>
+export default {
+  data: () => ({ theme: null }),
+  mounted() {
+    this.theme = window.FanUI ? window.FanUI.theme.snapshot() : null;
+    // 订阅主题变化（可选）
+    if (window.FanUI) {
+      this._onAccent = () => { this.theme = window.FanUI.theme.snapshot(); };
+      document.addEventListener("fanui:accentchange", this._onAccent);
+    }
+  },
+  beforeDestroy() {
+    if (this._onAccent) document.removeEventListener("fanui:accentchange", this._onAccent);
+  },
+};
+</script>
+```
+## Nuxt 3 / Nuxt 2
+- 样式：`nuxt.config.ts` → `css: ["@zhang_jifan/fanui/style.css"]`。
+- JS：写一个客户端插件 `plugins/fanui.client.ts`，内容为 `import FanUI from "@zhang_jifan/fanui"; export default () => FanUI && FanUI.init();`
+- fanUI 在无 DOM 环境安全导出 `null`，SSR 阶段不会报错。

package/examples/03-vue3/index.html ADDED Viewed

@@ -0,0 +1,12 @@
+<!DOCTYPE html>
+<html lang="zh-CN" data-fanui-theme="light" data-fanui-accent="cyan" data-fanui-glass="on">
+<head>
+  <meta charset="UTF-8" />
+  <meta name="viewport" content="width=device-width, initial-scale=1" />
+  <title>fanUI · Vue 3 示例</title>
+</head>
+<body>
+  <div id="app"></div>
+  <script type="module" src="/src/main.js"></script>
+</body>
+</html>

package/examples/03-vue3/package.json ADDED Viewed

@@ -0,0 +1,19 @@
+{
+  "name": "fanui-example-vue3",
+  "private": true,
+  "version": "2.1.0",
+  "type": "module",
+  "scripts": {
+    "dev": "vite",
+    "build": "vite build",
+    "preview": "vite preview"
+  },
+  "dependencies": {
+    "@zhang_jifan/fanui": "file:../..",
+    "vue": "^3.5.13"
+  },
+  "devDependencies": {
+    "@vitejs/plugin-vue": "^5.2.1",
+    "vite": "^5.4.11"
+  }
+}

package/examples/03-vue3/src/App.vue ADDED Viewed

@@ -0,0 +1,93 @@
+<script setup>
+/* =============================================================================
+ * fanUI × Vue 3（<script setup> 组合式 API）
+ * 模板里的 class 与官方文档完全一致，无需任何改写。
+ * ========================================================================== */
+import { ref } from "vue";
+import { useFanUI, useFanTheme, useFanOverlay, useToast } from "./useFanUI.js";
+useFanUI({ studio: true });
+const theme = useFanTheme();
+const toast = useToast();
+const modal = useFanOverlay("#demoModal");
+const brand = ref("#ff6b35");
+function applyBrand() {
+  const name = theme.createAccent(brand.value);
+  toast.success("已生成主题：" + name);
+}
+</script>
+<template>
+  <main class="fanui-container" style="padding: 32px 16px">
+    <h1 class="fanui-fs-3xl fanui-fw-bold">fanUI × Vue 3 示例</h1>
+    <p class="fanui-text-muted" v-if="theme.ready.value">
+      主题色 {{ theme.state.accent }} · 模式 {{ theme.state.mode }}（实际
+      {{ theme.state.effectiveMode }}）· 玻璃 {{ theme.state.glass ? "on" : "off" }}
+    </p>
+    <!-- 主题色 12 选 1 -->
+    <section class="fanui-card fanui-p-6" style="margin-top: 24px">
+      <h2 class="fanui-fs-xl fanui-fw-semibold">主题色</h2>
+      <div class="fanui-flex fanui-flex-wrap fanui-gap-2" style="margin-top: 12px">
+        <button
+          v-for="a in theme.state.accents"
+          :key="a.key"
+          type="button"
+          class="fanui-btn fanui-btn--sm"
+          :class="theme.state.accent === a.key ? 'fanui-btn--primary' : 'fanui-btn--neutral'"
+          :title="a.vibe"
+          @click="theme.setAccent(a.key)"
+        >
+          {{ a.label }} {{ a.en }}
+        </button>
+      </div>
+      <div class="fanui-flex fanui-flex-wrap fanui-gap-2" style="margin-top: 16px">
+        <button class="fanui-btn fanui-btn--neutral" @click="theme.toggleMode">浅色 / 深色</button>
+        <button class="fanui-btn fanui-btn--neutral" @click="theme.setGlass(!theme.state.glass)">
+          玻璃{{ theme.state.glass ? "关" : "开" }}
+        </button>
+        <button class="fanui-btn fanui-btn--ghost" @click="theme.nextAccent">下一个主题色</button>
+      </div>
+      <!-- 任意品牌色 → 主题 -->
+      <div class="fanui-flex fanui-gap-2" style="margin-top: 16px">
+        <input v-model="brand" class="fanui-form-control" style="max-width: 200px" placeholder="#ff6b35" />
+        <button class="fanui-btn fanui-btn--primary" @click="applyBrand">由品牌色生成主题</button>
+      </div>
+    </section>
+    <!-- 玻璃卡片 -->
+    <section class="fanui-card fanui-card--glass fanui-p-6" style="margin-top: 20px">
+      <h2 class="fanui-fs-xl fanui-fw-semibold">液态玻璃卡片</h2>
+      <div class="fanui-flex fanui-flex-wrap fanui-gap-2" style="margin-top: 12px">
+        <span class="fanui-badge fanui-badge--primary">Vue 3.0+</span>
+        <span class="fanui-badge fanui-badge--success fanui-badge--soft">组合式 API</span>
+        <span class="fanui-badge fanui-badge--warning fanui-badge--outline">模板零改写</span>
+      </div>
+    </section>
+    <div class="fanui-flex fanui-gap-2" style="margin-top: 20px">
+      <button class="fanui-btn fanui-btn--primary" @click="modal.open">打开模态框</button>
+      <button class="fanui-btn fanui-btn--neutral" @click="toast.success('操作成功', '来自 Vue 事件')">弹 Toast</button>
+    </div>
+    <!-- 浮层 DOM：class 与官方文档一致 -->
+    <div class="fanui-modal fanui-modal--md" id="demoModal" aria-hidden="true">
+      <div class="fanui-modal__backdrop"></div>
+      <div class="fanui-modal__dialog">
+        <header class="fanui-modal__header">
+          <h3 class="fanui-modal__title">Vue 3 中的模态框</h3>
+          <button class="fanui-modal__close" data-fanui-dismiss aria-label="关闭">×</button>
+        </header>
+        <div class="fanui-modal__body">
+          <p>Esc / 遮罩 / 关闭按钮都能退出；组件卸载时 Hook 会自动 close。</p>
+        </div>
+        <footer class="fanui-modal__footer">
+          <button class="fanui-btn fanui-btn--primary" data-fanui-dismiss>知道了</button>
+        </footer>
+      </div>
+    </div>
+  </main>
+</template>

package/examples/03-vue3/src/main.js ADDED Viewed

@@ -0,0 +1,8 @@
+import { createApp } from "vue";
+import App from "./App.vue";
+/* ① 样式必须在 Vue 之前引入（全局 CSS） */
+import "@zhang_jifan/fanui/style.css";
+/* ② 挂载 Vue 3 应用 */
+createApp(App).mount("#app");

package/examples/03-vue3/src/useFanUI.js ADDED Viewed

@@ -0,0 +1,85 @@
+/* =============================================================================
+ * fanUI · Vue 3 组合式 API 适配（Vue 3.0+）
+ * ========================================================================== */
+import { ref, onMounted, onBeforeUnmount, reactive } from "vue";
+import FanUI from "@zhang_jifan/fanui";
+/** 初始化一次：挂到组件的 onMounted 里（幂等，重复调用无副作用） */
+export function useFanUI(options) {
+  onMounted(() => {
+    if (!FanUI) return;                        // SSR 空值兜底
+    FanUI.init();
+    if (options && options.studio) FanUI.studio.mount({ defaultOpen: false });
+  });
+}
+/** 主题三轴响应式状态（12 主题色 / 深浅 / 玻璃） */
+export function useFanTheme() {
+  const ready = ref(!!FanUI);
+  const state = reactive({
+    accent: "cyan",
+    mode: "auto",
+    effectiveMode: "light",
+    glass: true,
+    glassIntensity: 1,
+    glassPreset: "regular",
+    accents: [],
+    presets: {},
+  });
+  function sync() {
+    if (!FanUI) return;
+    Object.assign(state, FanUI.theme.snapshot());
+    state.accents = FanUI.theme.accents;
+    state.presets = FanUI.theme.glassPresets;
+  }
+  onMounted(() => {
+    if (!FanUI) return;
+    sync();
+    ["fanui:accentchange", "fanui:themechange", "fanui:glasschange"]
+      .forEach((ev) => document.addEventListener(ev, sync));
+  });
+  onBeforeUnmount(() => {
+    if (!FanUI) return;
+    ["fanui:accentchange", "fanui:themechange", "fanui:glasschange"]
+      .forEach((ev) => document.removeEventListener(ev, sync));
+  });
+  return {
+    ready,
+    state,
+    setAccent: (k) => FanUI && FanUI.theme.setAccent(k),
+    nextAccent: () => FanUI && FanUI.theme.nextAccent(),
+    setMode: (m) => FanUI && FanUI.theme.setMode(m),
+    toggleMode: () => FanUI && FanUI.theme.toggleMode(),
+    setGlass: (on) => FanUI && FanUI.theme.setGlass(on),
+    setGlassIntensity: (v) => FanUI && FanUI.theme.setGlassIntensity(v),
+    setGlassPreset: (p) => FanUI && FanUI.theme.setGlassPreset(p),
+    createAccent: (hex, name) => FanUI && FanUI.theme.createAccent(hex, name),
+    reset: () => FanUI && FanUI.theme.reset(),
+  };
+}
+/** 命令式浮层：组件卸载自动 close，防滚动锁残留 */
+export function useFanOverlay(selector, options) {
+  let inst = null;
+  onMounted(() => { if (FanUI) inst = new FanUI.overlay(selector, options); });
+  onBeforeUnmount(() => { if (inst) inst.close(); });
+  return {
+    open: () => inst && inst.open(),
+    close: () => inst && inst.close(),
+    toggle: () => inst && inst.toggle(),
+  };
+}
+/** Toast 捷径 */
+export function useToast() {
+  return {
+    success: (t, d) => FanUI && FanUI.toast.success(t, d),
+    error: (t, d) => FanUI && FanUI.toast.error(t, d),
+    info: (t, d) => FanUI && FanUI.toast.info(t, d),
+    warning: (t, d) => FanUI && FanUI.toast.warning(t, d),
+  };
+}

package/examples/03-vue3/vite.config.js ADDED Viewed

@@ -0,0 +1,6 @@
+import { defineConfig } from "vite";
+import vue from "@vitejs/plugin-vue";
+export default defineConfig({
+  plugins: [vue()],
+});

package/examples/04-vue2-cdn.html ADDED Viewed

@@ -0,0 +1,93 @@
+<!DOCTYPE html>
+<!-- =============================================================================
+     fanUI · 示例 04：Vue 2 全局构建（CDN）+ fanUI script 引入
+     -----------------------------------------------------------------------------
+     - 无需打包器：Vue 2 用官方全局构建（vue@2.7），fanUI 用 dist 产物
+     - 除 fanUI 本地文件外，Vue 来自 CDN（首次打开需要联网）
+     - 直接双击即可运行；适用于老旧 Vue 2.6/2.7 项目无法升级构建链的场景
+     ========================================================================== -->
+<html lang="zh-CN" data-fanui-theme="light" data-fanui-accent="cyan" data-fanui-glass="on">
+<head>
+  <meta charset="UTF-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1">
+  <title>fanUI 示例 04 · Vue 2（CDN 全局构建）</title>
+  <link rel="stylesheet" href="../dist/fanui.css">
+  <style>
+    body { padding: 32px; max-width: 900px; margin: 0 auto; }
+    .muted { color: var(--fanui-color-text-muted); font-size: .875rem; }
+  </style>
+</head>
+<body>
+  <div id="app">
+    <!-- Vue 2 模板语法 + fanUI 类名混用，完全无冲突 -->
+    <main class="fanui-container">
+      <h1 class="fanui-fs-3xl fanui-fw-bold">fanUI × Vue 2（CDN）</h1>
+      <p class="muted">
+        主题色 {{ snapshot.accent }} · 模式 {{ snapshot.mode }} · 玻璃 {{ snapshot.glass ? 'on' : 'off' }}
+      </p>
+      <section class="fanui-card fanui-p-6" style="margin-top: 24px">
+        <h2 class="fanui-fs-xl fanui-fw-semibold">12 主题色</h2>
+        <div style="display:flex;flex-wrap:wrap;gap:8px;margin-top:12px">
+          <button v-for="a in accents" :key="a.key" type="button"
+                  class="fanui-btn fanui-btn--sm"
+                  :class="snapshot.accent === a.key ? 'fanui-btn--primary' : 'fanui-btn--neutral'"
+                  :title="a.vibe" @click="setAccent(a.key)">
+            {{ a.label }} {{ a.en }}
+          </button>
+        </div>
+        <div style="display:flex;flex-wrap:wrap;gap:8px;margin-top:16px">
+          <button class="fanui-btn fanui-btn--neutral" @click="toggleMode">浅色 / 深色</button>
+          <button class="fanui-btn fanui-btn--neutral" @click="toggleGlass">玻璃 开 / 关</button>
+        </div>
+      </section>
+      <section class="fanui-card fanui-card--glass fanui-p-6" style="margin-top: 20px">
+        <h2 class="fanui-fs-xl fanui-fw-semibold">液态玻璃卡片</h2>
+        <p class="muted" style="margin-top:8px">
+          Vue 的响应式只负责「自己的数据」；fanUI 的主题状态走它自己的事件系统，
+          两者互不干扰、按需同步。
+        </p>
+        <span class="fanui-badge fanui-badge--primary">Vue 2.7</span>
+        <span class="fanui-badge fanui-badge--success fanui-badge--soft" style="margin-left:8px">Vue 2.6 同样可用</span>
+      </section>
+    </main>
+  </div>
+  <!-- fanUI 运行时（可选，用于主题控制与声明式组件） -->
+  <script src="../dist/fanui.js"></script>
+  <!-- Vue 2 官方全局构建（首次打开需联网；内网环境请改为本地文件） -->
+  <script src="https://unpkg.com/vue@2.7.16/dist/vue.min.js"></script>
+  <script>
+    new Vue({
+      el: "#app",
+      data: function () {
+        return {
+          accents: window.FanUI ? window.FanUI.theme.accents : [],
+          snapshot: window.FanUI
+            ? window.FanUI.theme.snapshot()
+            : { accent: "-", mode: "-", glass: false },
+        };
+      },
+      mounted: function () {
+        var vm = this;
+        if (!window.FanUI) return;
+        window.FanUI.init();                    // 初始化声明式组件（幂等）
+        // 把 fanUI 主题事件同步进 Vue 响应式数据
+        ["fanui:accentchange", "fanui:themechange", "fanui:glasschange"].forEach(function (ev) {
+          document.addEventListener(ev, function () {
+            vm.snapshot = window.FanUI.theme.snapshot();
+          });
+        });
+        window.FanUI.studio.mount({ defaultOpen: false });
+      },
+      methods: {
+        setAccent: function (k) { window.FanUI && window.FanUI.theme.setAccent(k); },
+        toggleMode: function () { window.FanUI && window.FanUI.theme.toggleMode(); },
+        toggleGlass: function () { window.FanUI && window.FanUI.theme.toggleGlass(); },
+      },
+    });
+  </script>
+</body>
+</html>

package/examples/README.md ADDED Viewed

@@ -0,0 +1,34 @@
+# fanUI · 示例总览
+| 目录 / 文件 | 引入方式 | 技术栈 | 运行方式 |
+|---|---|---|---|
+| [`01-script-tag.html`](./01-script-tag.html) | `<script>` + `<link>` 本地文件 | 原生 HTML/JS | **双击直接打开，不需要构建、不需要联网** ✅ |
+| [`02-react/`](./02-react/) | npm（`file:../..` 本地包） | React 18 + Vite | `npm install && npm run dev` |
+| [`03-vue3/`](./03-vue3/) | npm（`file:../..` 本地包） | Vue 3 + Vite | `npm install && npm run dev` |
+| [`04-vue2-cdn.html`](./04-vue2-cdn.html) | `<script>` 全局构建 | Vue 2.7（CDN） | 双击打开（Vue 来自 CDN，需联网） |
+> 建议先跑 `01`（保证零门槛跑通），再按项目技术栈选 `02/03/04`。
+> ⚠️ **两个实测结论（避免踩坑）**
+>
+> 1. **`<script type="module">` 不能用 `file://` 双击打开。** 浏览器对 `file://` 下的
+>    ES Module 有 CORS 限制，会直接报
+>    `Access to script ... has been blocked by CORS policy`，
+>    页面表现为「样式正常但 JS 完全没生效」。示例 `02` / `03` 请用 `npm run dev`
+>    （或任意 http 服务）打开；只有用经典 `<script src>` 的 `01` / `04` 才能双击运行。
+> 2. **走 npm 引入时用这些路径**（都已实测）：样式 `@zhang_jifan/fanui/dist/fanui.css`
+>    （或 `@zhang_jifan/fanui/style.css` / `@zhang_jifan/fanui/style.min.css`）；JS 用 `@zhang_jifan/fanui/dist/fanui.js`
+>    （`<script>` 标签）或 `import ... from "@zhang_jifan/fanui"`（ESM/打包器）。
+>    包内自带可直接打开的示例：`node_modules/@zhang_jifan/fanui/examples/01-script-tag.html`。
+## 各示例演示内容
+- **01 / 04**：三轴主题控制（12 主题色、深浅模式、玻璃开关与强度）、液态玻璃卡片、
+  表单校验、声明式模态框、Toast、12 色卡快捷切换、主题工作台悬浮面板。
+- **02（React）**：React Hook 适配层（`useFanUI` / `useFanTheme` / `useFanOverlay` / `useToast`）、
+  品牌色一键生成主题、React 16/17/18/19 版本差异说明。
+- **03（Vue 3）**：组合式 API 适配层、Vue 2 Options API 等价写法、Nuxt 3 接入说明。
+## 截图
+浏览器回归产物由 `node scripts/verify-examples.cjs` 生成到 `shots/`（属测试产物，**不随 npm 包发布**）。

package/package.json ADDED Viewed

@@ -0,0 +1,127 @@
+{
+  "name": "@zhang_jifan/fanui",
+  "version": "2.1.0",
+  "description": "fanUI —— 一套 UI 设计系统，内置 12 套可在运行时切换的主题配色，支持液态玻璃质感、明暗双模式；适配官网、博客与 B 端控制台场景。下载即可使用：可直接用 script/link 引入编译产物，也可通过 npm + ESM / SCSS 接入项目。",
+  "keywords": [
+    "css",
+    "scss",
+    "ui",
+    "framework",
+    "design-system",
+    "design-tokens",
+    "theme",
+    "dark-mode",
+    "glassmorphism",
+    "grid",
+    "components",
+    "vanilla-js",
+    "react",
+    "vue"
+  ],
+  "license": "AGPL-3.0-or-later",
+  "author": {
+    "name": "zhang_jifan",
+    "url": "https://gitee.com/zhang_jifan"
+  },
+  "homepage": "https://gitee.com/zhang_jifan/fan-ui#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://gitee.com/zhang_jifan/fan-ui.git"
+  },
+  "bugs": {
+    "url": "https://gitee.com/zhang_jifan/fan-ui/issues"
+  },
+  "main": "dist/fanui.cjs",
+  "module": "dist/fanui.esm.js",
+  "browser": "dist/fanui.esm.js",
+  "types": "dist/fanui.d.ts",
+  "unpkg": "dist/fanui.js",
+  "jsdelivr": "dist/fanui.js",
+  "style": "dist/fanui.css",
+  "sass": "src/fanui.scss",
+  "sideEffects": [
+    "dist/fanui.js",
+    "dist/fanui.mjs",
+    "dist/fanui.esm.js",
+    "dist/fanui.cjs",
+    "**/*.css",
+    "**/*.scss"
+  ],
+  "exports": {
+    ".": {
+      "types": "./dist/fanui.d.ts",
+      "sass": "./src/fanui.scss",
+      "import": "./dist/fanui.mjs",
+      "require": "./dist/fanui.cjs",
+      "default": "./dist/fanui.mjs"
+    },
+    "./style": "./dist/fanui.css",
+    "./style.min": "./dist/fanui.min.css",
+    "./style.css": "./dist/fanui.css",
+    "./style.min.css": "./dist/fanui.min.css",
+    "./js": "./dist/fanui.js",
+    "./scss": "./src/fanui.scss",
+    "./src/*": "./src/*",
+    "./dist/*": "./dist/*",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "src",
+    "dist",
+    "docs",
+    "examples",
+    "!examples/shots",
+    "_index.scss",
+    "!**/*.map",
+    "README.md",
+    "CHANGELOG.md",
+    "COMMERCIAL-LICENSE.md",
+    "ACCESSIBILITY.md",
+    "DESIGN-SYSTEM.md",
+    "USAGE.md"
+  ],
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/",
+    "tag": "latest"
+  },
+  "scripts": {
+    "build": "node scripts/build.cjs",
+    "watch": "node scripts/build.cjs --watch",
+    "serve": "npx --yes serve .",
+    "audit": "node scripts/audit-coverage.cjs",
+    "audit:contrast": "node scripts/audit-theme.cjs",
+    "lint": "node scripts/lint.cjs",
+    "verify": "node scripts/verify-demo.cjs",
+    "verify:matrix": "node scripts/verify-matrix.cjs",
+    "verify:examples": "node scripts/verify-examples.cjs",
+    "verify:ssr": "node scripts/verify-ssr.cjs",
+    "verify:entries": "node scripts/probe-entries.cjs",
+    "verify:install": "node scripts/verify-install.cjs",
+    "verify:components": "node scripts/verify-components.cjs",
+    "verify:browsers": "node scripts/verify-browsers.cjs",
+    "verify:visual": "node scripts/verify-visual.cjs",
+    "verify:edge": "node scripts/verify-edge.cjs",
+    "audit:a11y": "node scripts/audit-a11y.cjs",
+    "test:unit": "node scripts/test-unit.cjs",
+    "check:size": "node scripts/check-size.cjs",
+    "check": "npm run build && npm run lint && npm run audit && npm run verify && npm run verify:matrix && npm run verify:examples && npm run verify:ssr && npm run verify:entries && npm run verify:install && npm run verify:components && npm run check:size && npm run test:unit",
+    "check:full": "npm run check && npm run audit:a11y && npm run verify:browsers && npm run verify:visual && npm run verify:edge",
+    "gates": "node scripts/run-gates.cjs",
+    "preflight": "node scripts/preflight-publish.cjs",
+    "prepublishOnly": "npm run build && npm run lint && npm run check:size && npm run verify:install"
+  },
+  "devDependencies": {
+    "sass": "^1.90.0"
+  },
+  "engines": {
+    "node": ">=20",
+    "npm": ">=9"
+  },
+  "browserslist": [
+    "last 2 Chrome versions",
+    "last 2 Firefox versions",
+    "last 2 Safari versions",
+    "last 2 Edge versions"
+  ]
+}