Skip to content
Mewx CMS UI

CSS 兼容性迁移指南 (v0.1.19)

CSS 兼容性迁移指南

Section titled “CSS 兼容性迁移指南”

适用版本：v0.1.19+

为什么要迁移？

Section titled “为什么要迁移？”

v0.1.19 之前，@goenhance/cms-ui/styles.css 是一份完整编译后的 Tailwind 输出，包含：

  • Tailwind Preflight 浏览器重置（*, ::before, ::after { box-sizing: border-box; ... }）
  • 数百个 utility 类（.absolute、.z-10、.mx-auto 等）
  • 组件 CSS 变量

当消费者项目在其 globals.css 中写入：

@import '@goenhance/cms-ui/styles.css';  /* ← 库的 utilities 在这里 */
@tailwind base;
@tailwind components;
@tailwind utilities;  /* ← 消费者自己的 utilities 在这里（后面）*/

由于 CSS 同权重规则遵循后者优先，消费者项目的 utility 类会覆盖库里相同名称的 utility 类，导致组件样式错乱。此外，Preflight 也会出现两次。

v0.1.19 修复：dist/cms-ui.css 只保留 CSS 变量，不再编译 utility 类。消费者通过 preset 自行生成所需的 utility 类，彻底消除冲突。

快速检查清单

Section titled “快速检查清单”

在迁移前，确认你的项目满足以下两个条件（通常已满足）：

  1. tailwind.config 中引入了 preset

    tailwind.config.ts
    import preset from '@goenhance/cms-ui/preset';
    

    export default {
      presets: [preset],
      content: ['./src/**/*.{ts,tsx}'],
    };

    preset 告诉 Tailwind 扫描库的组件文件，自动生成 blocks-primary、text-blocks-heading 等 utility 类。没有 preset，组件主题色不会生效。

  2. CSS 导入顺序正确

    库的 CSS 必须在 @tailwind base 之前 导入：

    /* globals.css ✅ 正确顺序 */
    @import '@goenhance/cms-ui/styles.css';
    

    @tailwind base;
    @tailwind components;
    @tailwind utilities;

迁移步骤

Section titled “迁移步骤”
/* app/globals.css 或 styles/globals.css */


/* 1. 保持此行在最前 */
@import '@goenhance/cms-ui/styles.css';


/* 2. Tailwind 三个指令照常保留 */
@tailwind base;
@tailwind components;
@tailwind utilities;


/* 3. 在 @layer base 中覆盖 CSS 变量（可选，见「自定义颜色」章节） */
@layer base {
  :root {
    --blocks-primary: 59 130 246; /* 改为蓝色，示例 */
  }
}
tailwind.config.ts
import type { Config } from 'tailwindcss';
import cmsPreset from '@goenhance/cms-ui/preset';


const config: Config = {
  presets: [cmsPreset],
  content: [
    './app/**/*.{ts,tsx}',
    './components/**/*.{ts,tsx}',
  ],
};


export default config;

自定义颜色

Section titled “自定义颜色”

库的所有颜色都通过 CSS 变量控制，在消费者项目里覆盖即可，无需修改库的源码。

颜色变量格式规范

Section titled “颜色变量格式规范”

完整变量参考

Section titled “完整变量参考”
/* globals.css — 在 @layer base 或 :root 中覆盖 */
@layer base {
  :root {
    /* ─── 品牌主色 ─────────────────────────────────── */
    --blocks-primary:         219 87 153;  /* 主色（默认樱花粉）*/
    --blocks-primary-light:   236 114 175; /* 浅一级 */
    --blocks-primary-lighter: 251 207 232; /* 浅二级，用于背景 */
    --blocks-primary-lightest:253 242 248; /* 浅三级，用于 hover 背景 */
    --blocks-primary-dark:    199 55 125;  /* 深一级，用于 hover 按钮 */


    /* ─── 强调色 ─────────────────────────────────── */
    --blocks-accent:          139 92 246;  /* 强调色（默认紫罗兰）*/
    --blocks-accent-light:    167 139 250;
    --blocks-accent-lightest: 245 243 255;


    /* ─── 文字颜色 ─────────────────────────────────── */
    --blocks-text-heading:    15 23 42;    /* 标题文字 */
    --blocks-text-body:       51 65 85;    /* 正文文字 */
    --blocks-text-muted:      100 116 139; /* 次要文字 */
    --blocks-text-light:      148 163 184; /* 最浅文字 */


    /* ─── 背景色 ─────────────────────────────────── */
    --blocks-bg-page:         255 255 255; /* 页面底色 */
    --blocks-bg-section:      248 250 252; /* 区块底色（斑马条纹）*/
    --blocks-bg-card:         255 255 255; /* 卡片底色 */
    --blocks-bg-card-hover:   253 242 248; /* 卡片 hover 底色 */


    /* ─── 边框色 ─────────────────────────────────── */
    --blocks-border:          241 245 249;
    --blocks-border-hover:    251 207 232;


    /* ─── 渐变（使用完整 CSS 渐变语法）─────────────── */
    --blocks-gradient-primary: linear-gradient(135deg, rgb(219,87,153), rgb(236,114,175));
    --blocks-gradient-hero:    linear-gradient(135deg, rgba(219,87,153,.1), rgba(139,92,246,.15));


    /* ─── 阴影 ─────────────────────────────────── */
    --blocks-shadow-card:      0 2px 12px rgba(0,0,0,.03);
    --blocks-shadow-card-hover:0 12px 30px rgba(219,87,153,.1);
    --blocks-shadow-button:    0 4px 20px rgba(219,87,153,.25);


    /* ─── 布局 ─────────────────────────────────── */
    --blocks-section-padding:       6rem;  /* 区块上下 padding */
    --blocks-container-max-width:  80rem;  /* 内容区最大宽度 */
    --blocks-radius-sm:  0.5rem;
    --blocks-radius-md:  1rem;
    --blocks-radius-lg:  1.5rem;
    --blocks-radius-xl:  2rem;
    --blocks-radius-2xl: 2.5rem;
  }
}

预置主题示例

Section titled “预置主题示例”
@layer base {
  :root {
    --blocks-primary:          59 130 246;
    --blocks-primary-light:    96 165 250;
    --blocks-primary-lighter:  191 219 254;
    --blocks-primary-lightest: 239 246 255;
    --blocks-primary-dark:     37 99 235;
    --blocks-accent:           139 92 246;
    --blocks-accent-light:     167 139 250;
    --blocks-accent-lightest:  245 243 255;
    --blocks-bg-card-hover:    239 246 255;
    --blocks-border-hover:     191 219 254;
    --blocks-gradient-primary: linear-gradient(135deg, rgb(59,130,246), rgb(96,165,250));
    --blocks-gradient-hero:    linear-gradient(135deg, rgba(59,130,246,.1), rgba(139,92,246,.15));
    --blocks-shadow-card-hover:0 12px 30px rgba(59,130,246,.1);
    --blocks-shadow-button:    0 4px 20px rgba(59,130,246,.25);
  }
}

局部区域覆盖

Section titled “局部区域覆盖”

如果只想让页面中的某个区域使用不同的主题色：

// React / Next.js
<div style={{ '--blocks-primary': '59 130 246' } as React.CSSProperties}>
  <RenderComponent component={block} />
</div>
<!-- Astro -->
<div style="--blocks-primary: 59 130 246;">
  <slot />
</div>

常见问题排查

Section titled “常见问题排查”

组件颜色变成默认粉色，没有跟随我的配置

Section titled “组件颜色变成默认粉色，没有跟随我的配置”

确认 CSS 变量覆盖写在 @import '@goenhance/cms-ui/styles.css' 之后（否则被库的默认值覆盖）：

/* ✅ 正确顺序 */
@import '@goenhance/cms-ui/styles.css';
@tailwind base;
@tailwind utilities;


@layer base {
  :root {
    --blocks-primary: 59 130 246; /* ← 在导入之后生效 */
  }
}

组件完全没有样式（布局正常但无颜色）

Section titled “组件完全没有样式（布局正常但无颜色）”

说明 preset 未生效，Tailwind 没有生成 text-blocks-primary 等类名。检查 tailwind.config.ts：

import cmsPreset from '@goenhance/cms-ui/preset'; // ← 必须引入


export default {
  presets: [cmsPreset], // ← 必须在 presets 中
  content: ['./src/**/*.{ts,tsx}'],
};

bg-blocks-primary/50 透明度不生效

Section titled “bg-blocks-primary/50 透明度不生效”

说明颜色变量格式错误，必须是空格分隔的 RGB 值：

/* ✅ */  --blocks-primary: 59 130 246;
/* ❌ */  --blocks-primary: #3b82f6;
/* ❌ */  --blocks-primary: rgb(59, 130, 246);

版本对照

Section titled “版本对照”
版本dist/cms-ui.css 内容是否需要 preset
≤ v0.1.18Preflight + 所有 utility 类 + CSS 变量可选（但推荐）
≥ v0.1.19仅 CSS 变量必须