设计令牌 → 组件 → 文档工作台 → 库构建产物 → 公网可访问

// ✅ 正确：mixin 产出 CSS 变量声明
.var(@name; @value) {
  --ls-@{name}: @value;
}

// ❌ 错误：用 LESS 变量承载主题值，编译后变成字面量，换肤失效
@color-primary: #1677ff;

ls-design/                          # workspace 根，只放 workspace 级内容
├── package.json                    # private，只放脚本，不装依赖
├── pnpm-workspace.yaml             # packages: [packages/*] + allowBuilds
├── .npmrc                          # shamefully-hoist=false
├── .gitignore                      # 只忽略 node_modules / dist / storybook-static
└── packages/
    └── ls-design/                  # 唯一功能包
        ├── package.json  tsconfig.json  vite.config.ts  index.html
        ├── .storybook/             # main.ts + preview.tsx（不放 stories）
        ├── scripts/                # gen-antd-tokens.mjs 等构建期脚本
        └── src/
            ├── index.ts            # 库出口
            ├── main.tsx  App.tsx  App.less   # dev 演示页
            ├── styles/             # 编译期为主
            │   ├── index.less  base.less
            │   ├── tokens/         # 三层令牌。seed/palette 由脚本生成，alias 手写
            │   └── mixins/         # 编译期工具，必须独立成目录
            ├── theme/              # 运行时：把用户选择翻译成 html 属性 + 内联变量
            ├── utils/              # 与框架无关的纯函数
            ├── icons/              # 内联 SVG，零图标库依赖
            └── components/         # 扁平一层，每个组件一个目录
                                    # 固定 4 文件：X.tsx / X.less / X.stories.tsx / index.ts

基础令牌（Primitive）     --ls-primary-6, --ls-control-height, --ls-motion-duration-mid
        ↓ 引用
语义令牌（Semantic）      --ls-color-primary, --ls-color-text-secondary, --ls-color-border
        ↓ 引用
组件令牌（Component）     --ls-btn-padding-inline, --ls-btn-bg-color-hover

.var(@n; @v) { --ls-@{n}: @v; @ls-@{n}: @v; }

.a { .var(color-text; rgba(0, 0, 0, .88)); }
.b { color: @ls-color-text; }   // ✗ variable @ls-color-text is undefined

// 水平内边距 = 内容区内边距 - 线宽（antd: paddingContentHorizontal - lineWidth）
// 用 calc 而不是算好 15px：紧凑密度下 --ls-padding-content-horizontal 会变成 12px，
// 写死就失去了密度轴
--ls-btn-padding-inline: calc(var(--ls-padding-content-horizontal) - var(--ls-line-width));

--ls-color-text:             rgba(0, 0, 0, 0.88);
--ls-color-text-secondary:   rgba(0, 0, 0, 0.65);
--ls-color-text-tertiary:    rgba(0, 0, 0, 0.45);
--ls-color-text-quaternary:  rgba(0, 0, 0, 0.25);

/**
 * useLayoutEffect 在 SSR 时会触发 React 告警，浏览器里又必须用它 ——
 * 主题变量得在绘制前写好，否则会闪一帧无主题的样式。
 */
const useIsomorphicLayoutEffect = typeof window === 'undefined' ? useEffect : useLayoutEffect;

/* ① 属性落地。排在写变量之前，保证任何"读当前生效值"的逻辑拿到的都是新主题。 */
useIsomorphicLayoutEffect(() => {
  const el = resolveTarget();
  if (!el) return;
  el.setAttribute(THEME_ATTR, resolvedMode);
  el.setAttribute(DENSITY_ATTR, density);
  // 让原生 UI（滚动条、表单控件、自动填充底色）跟随主题
  el.style.colorScheme = resolvedMode;
}, [resolveTarget, resolvedMode, density]);

export const DARK_BG_CONTAINER = '#141414';

export function generateBrandPalettes(primaryColor: string): BrandPalettes {
  return {
    light: buildPalette(generate(primaryColor), 'light'),
    dark: buildPalette(
      generate(primaryColor, { theme: 'dark', backgroundColor: DARK_BG_CONTAINER }),
      'dark',
    ),
  };
}

if (primaryColor === DEFAULT_PRIMARY_COLOR) {
  // 交给 tokens/palette.less 的静态声明，保持 DOM 干净，
  // 也让消费方仍能通过 CSS 层覆盖同名变量
  for (let level = 1; level <= 10; level += 1) el.style.removeProperty(`--ls-primary-${level}`);
  el.style.removeProperty(CONTROL_OUTLINE_VAR);
  return;
}

getAlphaColor('#e6f4ff', '#ffffff') = rgba(5,145,255,0.1)

export function getAlphaColor(frontColor: string, backgroundColor: string): string {
  // 从 α=0.01 起以 0.01 步长递增，取第一个能让 r/g/b 三个分量
  // 都落回 [0,255] 的 α
  for (let alpha = 0.01; alpha <= 1.0001; alpha += 0.01) {
    const r = Math.round((front.r - back.r * (1 - alpha)) / alpha);
    const g = Math.round((front.g - back.g * (1 - alpha)) / alpha);
    const b = Math.round((front.b - back.b * (1 - alpha)) / alpha);

    if (isStable(r) && isStable(g) && isStable(b)) {
      const rounded = Math.round(alpha * 100) / 100;
      return `rgba(${r},${g},${b},${rounded})`;
    }
  }
  return `rgba(${front.r},${front.g},${front.b},1)`;
}

#e6f4ff / #ffffff          → rgba(5,145,255,0.1)
#15325b / #141414          → rgba(23,117,249,0.31)
#fff2f0 / #ffffff          → rgba(255,38,5,0.06)
#2c1618 / #141414          → rgba(238,38,56,0.11)

--ls-btn-shadow-primary: 0 var(--ls-control-outline-width) 0 var(--ls-control-outline);

<script>
  (function () {
    try {
      var STORAGE_KEY = 'ls-design-theme';
      var el = document.documentElement;
      var cfg = JSON.parse(localStorage.getItem(STORAGE_KEY) || '{}');

      var mode = cfg.mode || 'system';
      var resolved =
        mode === 'system'
          ? window.matchMedia('(prefers-color-scheme: dark)').matches ? 'dark' : 'light'
          : mode;

      el.setAttribute('data-ls-theme', resolved);
      el.setAttribute('data-ls-density', cfg.density || 'default');
      el.style.colorScheme = resolved;

      var brand = cfg.brand && cfg.brand[resolved];
      if (brand && Object.prototype.toString.call(brand.palette) === '[object Array]') {
        for (var i = 0; i < brand.palette.length; i++) {
          el.style.setProperty('--ls-primary-' + (i + 1), brand.palette[i]);
        }
        // 主色阴影是色阶的派生值，算法不在这里重跑，所以必须连它一起缓存
        if (brand.outline) el.style.setProperty('--ls-control-outline', brand.outline);
      }
    } catch (e) {
      // localStorage 被禁用或数据损坏时不阻断渲染，静默用默认主题
    }
  })();
</script>

{
  mode, density,
  primaryColor,                                  // 「输入」，给 React 用
  brand: { light: { palette, outline },          // 「输出」，给防闪屏脚本用
           dark:  { palette, outline } },
}

const light = theme.getDesignToken({ ...opts, algorithm: theme.defaultAlgorithm });
const dark = theme.getDesignToken({ ...opts, algorithm: theme.darkAlgorithm });
const compact = theme.getDesignToken({
  ...opts,
  algorithm: [theme.defaultAlgorithm, theme.compactAlgorithm],
});

const ANTD_VERSION = JSON.parse(
  readFileSync(require.resolve('antd/package.json'), 'utf8'),
).version;

const assertIndex = (label, palette, index, actual) => {
  const expected = palette[index - 1];
  if (String(expected).toLowerCase() !== String(actual).toLowerCase()) {
    errors.push(`${label}  语义令牌色阶[${index}] 期望 ${actual}，实际 ${expected}`);
  }
};

const DARK_MAP = {
  colorPrimaryBg: 3, colorPrimaryBgHover: 4, colorPrimaryBorder: 3,
  colorPrimaryBorderHover: 4, colorPrimaryHover: 7,   // ← 亮色为 5
  colorPrimary: 6, colorPrimaryActive: 5,             // ← 亮色为 7
};

if (errors.length > 0) {
  console.error('\n✖ 色阶索引校验失败，已中止生成。antd 的映射关系可能已变更：\n');
  process.exit(1);
}

generate(primary, { theme: 'dark', backgroundColor: '#141414' })

theme.getDesignToken({ components: { Button: {...} } })

// ① 危险「填充」态 hover 用的是 colorErrorBgFilledHover，不是 colorErrorBgHover
//    两者不同名，也不同值（#ffdfdc / #441e1f）
// ② box-shadow 只在 solid / outlined / dashed 三种变体上投射
//    filled / text / link 没有阴影
// ③ antd 里三个「同名等价 / 从未被读取」的中间变量可以跳过：
//    dashedBgDisabled ≡ defaultBgDisabled ≡ colorBgContainerDisabled
//    --btn-border-color-disabled / --btn-text-color-disabled 被赋值但从不被读取

# 保持 pnpm 的符号链接严格布局。组件里 import 了未声明的包，本地直接报错，
# 而不是静默通过。这是发布质量的前置防线。
shamefully-hoist=false
auto-install-peers=true
strict-peer-dependencies=false   # 阶段 10 依赖树定型后改 true

packages:
  - "packages/*"

# ⚠️ 语法是 map（name: true），不是数组
allowBuilds:
  esbuild: true

// ① external 写在 rolldownOptions 下
//    build.rollupOptions 仍存在但已标注 @deprecated，写它等于走兼容层
rolldownOptions: {
  external: [
    'react', 'react-dom',
    // ② React 19 的自动 JSX 运行时。这两条极容易漏，漏了会把整份 jsx-runtime 打进产物
    'react/jsx-runtime', 'react/jsx-dev-runtime',
    '@ant-design/colors',
  ],
},

// ③ 库构建选项必须按 mode === 'lib' 隔离
//    原因：Storybook 会合并 vite.config，若 build.lib 无条件存在，会干扰它自己的打包
const isLib = mode === 'lib';
export default defineConfig(({ mode }) => ({
  build: { ...(isLib && { /* lib 相关全部选项 */ }) },
}));

{
  "type": "module",
  "sideEffects": ["**/*.css", "**/*.less"],
  "exports": {
    ".": {
      "types": "./dist/index.d.ts",
      "import": "./dist/ls-design.js",
      "require": "./dist/ls-design.cjs"
    },
    "./style.css": "./dist/ls-design.css"
  }
}

const config: StorybookConfig = {
  stories: ['../src/**/*.mdx', '../src/**/*.stories.@(ts|tsx)'],
  addons: ['@storybook/addon-docs', '@storybook/addon-a11y'],
  framework: { name: '@storybook/react-vite', options: {} },
  typescript: {
    // ⚠️ 必须是 'react-docgen'，不能用 'react-docgen-typescript'
    reactDocgen: 'react-docgen',
  },
};

error TS5102: Option 'baseUrl' has been removed

{
  "compilerOptions": {
    "paths": { "@/*": ["./src/*"] }
  }
}

[unplugin-dts] The installed "typescript" package does not provide
the JavaScript Compiler API (this happens with TypeScript 7+)

pnpm -F ls-design add -D @typescript/typescript6

const MIXINS_ENTRY = fileURLToPath(new URL('./src/styles/mixins/index.less', import.meta.url));

css: {
  preprocessorOptions: {
    less: {
      javascriptEnabled: true,
      additionalData: (content, filename) =>
        filename === MIXINS_ENTRY
          ? content
          : `@import (reference) "${MIXINS_ENTRY}";\n${content}`,
    },
  },
}

variant: 'outlined' | 'dashed' | 'solid' | 'filled' | 'text' | 'link'   // 外形
color:   'default' | 'primary' | 'danger'                              // 语义色

/**
 * 原生 `type`。默认 `'button'`。
 * 为什么改名：`type` 在旧版 antd 里被用作「按钮外观」，
 * 且 <form> 内不写 type 的原生按钮默认是 `submit`，会意外提交表单 ——
 * 所以默认值必须是 `button`，名字也必须让位。
 */
htmlType?: 'submit' | 'reset' | 'button';

export interface ButtonProps
  extends Omit<ButtonHTMLAttributes<HTMLButtonElement>, 'type' | 'color'> {
  // 'type' 与 htmlType 语义重复且极易误用（不写等于 submit）；
  // 'color' 在 DOM 上是 CSS 颜色字符串，与语义色枚举完全不是一回事
}

.ls-btn {
  /* 语义槽位分两层是刻意的：
       color-*         由「语义色」块设置（default / primary / danger）
       border/text/bg  由「变体」块把 color-* 映射上来
     于是新增一个语义色只需写一个色块，新增一个变体只需写一个变体块 */
  --ls-btn-color-base: var(--ls-color-border);
  --ls-btn-color-hover: var(--ls-color-primary-hover);
  --ls-btn-border-color: var(--ls-color-border);
  --ls-btn-text-color: var(--ls-color-text);
  --ls-btn-bg-color: var(--ls-color-bg-container);
}

/**
 * ⚠️ 参数用 `;` 分隔：值里有逗号（calc、rgba）时用逗号会被 LESS 当作多个参数。
 */
.btn-size(@height; @font-size; @padding-inline; @radius) {
  height: @height;
  font-size: @font-size;
  padding: 0 @padding-inline;
  border-radius: @radius;

  /* 纯图标按钮：宽高相等成正方形。图标字号用 inherit —— antd 的
     onlyIconSize 值就是 'inherit'，不需要为每个尺寸再配一套图标字号 */
  &.ls-btn-icon-only {
    width: @height;
    .ls-icon { font-size: inherit; }
  }

  /* 直径以控件高度为准，必须逐档重算 */
  &.ls-btn-circle { min-width: @height; }

  /* 胶囊：圆角半径取整个高度（远大于一半，因此必为胶囊） */
  &.ls-btn-round {
    border-radius: @height;
    &:not(.ls-btn-icon-only) { padding-inline: @padding-inline; }
  }
}

/* 收起来的关键是 width: 0 + opacity: 0 + 负 margin 吃掉 flex gap，
   否则图标"消失"后仍占着间距，文字会跳位 */

// ① 从隔离的 workspace 解析 happy-dom，不污染项目 node_modules
const require = createRequire('/path/to/isolated/workspace/package.json');
const { Window } = require('happy-dom');

const window = new Window();
const document = window.document;

// ② 装全局量
globalThis.window = window;
globalThis.document = document;

// ⚠️ Node 22 的 navigator 只有 getter，直接赋值报 "Cannot set property navigator"
Object.defineProperty(globalThis, 'navigator', {
  value: window.navigator, configurable: true, writable: true,
});

globalThis.IS_REACT_ACT_ENVIRONMENT = true;   // 否则 act() 会告警

// ③ 用 Vite 的 ssrLoadModule 加载 TSX（自动处理 LESS / TS / JSX）
const server = await vite.createServer({ middlewareMode: true });
const { Button } = await server.ssrLoadModule('/src/components/button/Button.tsx');

// ④ 真渲染 + act() 刷 effects
const { createRoot } = await server.ssrLoadModule('react-dom/client');
const root = createRoot(document.getElementById('root'));
await act(async () => { root.render(<Button loading>提交</Button>); });

// ⑤ 断言：类名、属性、内联变量、计算后的 style 值

# 依赖安装（一律在 workspace 根）
pnpm install

# 装到子包
pnpm -F ls-design add -D <pkg>

# 从 antd 重新生成令牌（seed.less / palette.less）
pnpm -F ls-design tokens

# 类型检查（走 TS 7，快）
pnpm -F ls-design typecheck

# 库构建（产出 dist/：ESM + CJS + CSS + d.ts）
pnpm -F ls-design build

# 组件工作台
pnpm -F ls-design storybook          # dev，:6006
pnpm -F ls-design build-storybook    # 静态构建，可直投静态托管

# 演示页
pnpm -F ls-design dev                # :5173

dist/
├── ls-design.js        11.15 kB │ gzip 4.68 kB   # ESM（主产物）
├── ls-design.cjs        8.93 kB │ gzip 4.18 kB   # CJS
├── ls-design.css       21.19 kB │ gzip 3.70 kB   # 单份样式，不按 chunk 切分
├── index.d.ts                                     # 类型入口
└── components/ theme/ utils/ icons/  …            # 逐模块 d.ts

<ThemeProvider
  defaultMode="system"          // 'light' | 'dark' | 'system'
  defaultDensity="default"      // 'default' | 'compact'
  defaultPrimaryColor="#1677ff"
  persist={true}                // 是否写入 localStorage
  target={undefined}            // 属性落地元素，默认 document.documentElement
  storageKey="ls-design-theme"  // 与防闪屏脚本共用
>
  {children}
</ThemeProvider>