Tailwind v4 主题命名约定

[!info] related notes

• 概念与版本边界：tailwind-theme-and-design-tokens。
• 设计系统入口：tailwind-design-system-moc；暗色激活：tailwind-dark-mode。

命名空间与用途

@theme 的命名空间决定设计值可用于哪些工具类；生成哪些具体类还取决于源码检测。以下是 v4 约定：

变量前缀	常见工具类
--color-*	bg-*、text-*、border-*、ring-*
--spacing-*	p-*、m-*、gap-*、top-* 等
--radius-*	rounded-*
--shadow-*	shadow-*
--font-*	字体家族，如 font-sans
--text-*	字号，如 text-sm

原始色板可以使用 green-500 这类名称；组件用途可使用 primary、surface、muted 等语义名。两层可以共存，不必把所有颜色强制改成语义名。项目选择一套稳定映射，并明确明暗主题如何切换。

保留的深色配色示例

以下保留原笔记的深色、半透明卡片与绿色发光方案，作为一个具体视觉方案，不代表全库项目已经采用，也不是普适设计规范。间距、透明度、对比度和发光效果需在实际页面验收。

/* src/styles/global.css */
@import "tailwindcss";

@theme {
  /* =========================================
     1. 表面与底色 (Surfaces & Backgrounds)
     命名逻辑：从最底层的背景，到上面悬浮的卡片
     ========================================= */
  --color-background: #0a0a0a; /* 页面背景 */
  --color-surface: rgba(255, 255, 255, 0.02); /* 卡片表面 */
  --color-surface-hover: rgba(255, 255, 255, 0.05); /* 卡片鼠标悬浮时的提亮状态 */
  --color-surface-sunken: rgba(0, 0, 0, 0.2); /* 凹陷的搜索框或内部输入区 */

  /* =========================================
     2. 品牌与强调色 (Brand & Accents)
     命名逻辑：代表品牌强调色
     ========================================= */
  --color-primary: #10B981; /* 品牌强调色 */
  --color-primary-glow: rgba(16, 185, 129, 0.3); /* 专供阴影发光的透明绿 */

  /* =========================================
     3. 文本层级 (Typography Colors)
     命名逻辑：按阅读的重要程度划分
     ========================================= */
  --color-text-base: #f3f4f6; /* 主标题、卡片名字的亮白色 */
  --color-text-muted: #9ca3af; /* Description、辅助信息的低调灰 */

  /* =========================================
     4. 物理边界与圆角 (Borders & Radii)
     命名逻辑：按组件的体型划分
     ========================================= */
  --color-border-ghost: rgba(255, 255, 255, 0.05); /* 极细的幽灵边框 */

  --radius-card: 12px; /* 示例卡片圆角 */
  --radius-icon: 8px;  /* 内部 Logo 容器的小圆角 */

  /* =========================================
     5. 发光效果 (Shadows)
     命名逻辑：直接将发光效果封装成一个 Token
     ========================================= */
  --shadow-neon: 0 0 20px var(--color-primary-glow);
}

/* 示例页面默认底色 */
@layer base {
  body {
    background-color: var(--color-background);
    color: var(--color-text-base);
    @apply antialiased selection:bg-primary/30;
  }
}

对应标记：

<div class="bg-surface hover:bg-surface-hover border border-border-ghost rounded-card text-text-base group relative">
  <div class="absolute inset-0 opacity-0 group-hover:opacity-100 shadow-neon rounded-card transition-opacity duration-300"></div>

  <div class="rounded-icon bg-surface-sunken">…</div>

  <p class="text-text-muted">…</p>
</div>

--color-text-base 会对应 text-text-base；这在语法上有效，但是否采用这种命名取决于团队约定。--color-surface-hover 定义颜色值，只有 hover:bg-surface-hover 才附加 hover 条件。

此示例直接设置深色底色；若需运行时多主题，参考主题 Token 笔记中的普通 CSS 变量映射，而不是把深色常量当作完整的主题切换机制。

参考

• Tailwind v4 Theme variables
• Functions and directives