docs: enrich tailwindcss topic visuals

sonofmagic · sonofmagic · commit 4c18b564ca87 · 2026-04-02T00:29:01.000+08:00
diff --git a/website/docs/tailwindcss/ai-friendly-and-demos.mdx b/website/docs/tailwindcss/ai-friendly-and-demos.mdx
@@ -21,9 +21,12 @@ keywords:
   - mpx
 ---
 
+import TailwindTopicHero from '@site/src/components/docs/TailwindTopicHero'
 import Tabs from '@theme/Tabs'
 import TabItem from '@theme/TabItem'
 
+<TailwindTopicHero topicId="tailwindcss/ai-friendly-and-demos" title="AI 友好提示与 Demo 运行指南" />
+
 ## 让模型写得像人
 
 - 原子类天然适合 AI 生成，因为它们是稳定、可组合、低歧义的语料。
diff --git a/website/docs/tailwindcss/bem-and-oocss.mdx b/website/docs/tailwindcss/bem-and-oocss.mdx
@@ -20,6 +20,10 @@ keywords:
   - mpx
 ---
 
+import TailwindTopicHero from '@site/src/components/docs/TailwindTopicHero'
+
+<TailwindTopicHero topicId="tailwindcss/bem-and-oocss" title="BEM 与 OOCSS 方法论" />
+
 ## BEM（Block / Element / Modifier）
 
 - 目标：通过约定命名减少层级选择器，保证组件内聚且易于组合。
diff --git a/website/docs/tailwindcss/best-practices.mdx b/website/docs/tailwindcss/best-practices.mdx
@@ -19,6 +19,10 @@ keywords:
   - mpx
 ---
 
+import TailwindTopicHero from '@site/src/components/docs/TailwindTopicHero'
+
+<TailwindTopicHero topicId="tailwindcss/best-practices" title="原子化 CSS 最佳实践" />
+
 ## 先给结论
 
 - 如果你只打算记住这一页的 3 件事，就记下面这 3 条：
diff --git a/website/docs/tailwindcss/css-origin-evolution.mdx b/website/docs/tailwindcss/css-origin-evolution.mdx
@@ -20,6 +20,10 @@ keywords:
   - mpx
 ---
 
+import TailwindTopicHero from '@site/src/components/docs/TailwindTopicHero'
+
+<TailwindTopicHero topicId="tailwindcss/css-origin-evolution" title="CSS 的诞生与演化" />
+
 ## 要点
 
 - 起因：HTML 早期的表现与结构耦合（`<font>`、table 布局），浏览器厂商私有标签泛滥，缺少跨页面的样式复用。
diff --git a/website/docs/tailwindcss/demos.mdx b/website/docs/tailwindcss/demos.mdx
@@ -20,9 +20,12 @@ keywords:
   - mpx
 ---
 
+import TailwindTopicHero from '@site/src/components/docs/TailwindTopicHero'
 import Tabs from '@theme/Tabs'
 import TabItem from '@theme/TabItem'
 
+<TailwindTopicHero topicId="tailwindcss/demos" title="各样式方案 Demo 与产物对照" />
+
 ## 目标与产物
 
 - 统一用一张「卡片 + 按钮」UI，展示不同样式方案的实现方式。
diff --git a/website/docs/tailwindcss/history/history-component-evolution.mdx b/website/docs/tailwindcss/history/history-component-evolution.mdx
@@ -20,6 +20,10 @@ keywords:
   - mpx
 ---
 
+import TailwindTopicHero from '@site/src/components/docs/TailwindTopicHero'
+
+<TailwindTopicHero topicId="tailwindcss/history/history-component-evolution" title="组件库的演进" />
+
 ## 要点
 
 - 组件库从「组件 + 样式捆绑」到「主题化」再到「Headless Primitives」，逐步把 API、样式与 design tokens 解耦。
diff --git a/website/docs/tailwindcss/history/history-css-in-js.mdx b/website/docs/tailwindcss/history/history-css-in-js.mdx
@@ -21,6 +21,10 @@ keywords:
   - mpx
 ---
 
+import TailwindTopicHero from '@site/src/components/docs/TailwindTopicHero'
+
+<TailwindTopicHero topicId="tailwindcss/history/history-css-in-js" title="CSS-in-JS 阶段" />
+
 ## 要点
 
 - 组件边界天然隔离，props 可驱动样式；动态主题/状态友好。
diff --git a/website/docs/tailwindcss/history/history-css-modules.mdx b/website/docs/tailwindcss/history/history-css-modules.mdx
@@ -23,6 +23,10 @@ keywords:
   - mpx
 ---
 
+import TailwindTopicHero from '@site/src/components/docs/TailwindTopicHero'
+
+<TailwindTopicHero topicId="tailwindcss/history/history-css-modules" title="CSS Modules / Scoped 阶段" />
+
 ## 要点
 
 - 类名哈希化实现作用域隔离，天然防止全局污染；适合可发布组件库。
diff --git a/website/docs/tailwindcss/history/history-future-generative-css.mdx b/website/docs/tailwindcss/history/history-future-generative-css.mdx
@@ -22,6 +22,10 @@ keywords:
   - mpx
 ---
 
+import TailwindTopicHero from '@site/src/components/docs/TailwindTopicHero'
+
+<TailwindTopicHero topicId="tailwindcss/history/history-future-generative-css" title="生成式 CSS / 原生能力融合" />
+
 ## 要点
 
 - 核心思想：CSS 将越来越生成式——tokens/设计意图 → 构建器/AI 生成规则 → @layer/@scope 限界 → 运行时仅保留需要的原子或组件级片段。
diff --git a/website/docs/tailwindcss/history/history-headless-tokens.mdx b/website/docs/tailwindcss/history/history-headless-tokens.mdx
@@ -23,6 +23,10 @@ keywords:
   - mpx
 ---
 
+import TailwindTopicHero from '@site/src/components/docs/TailwindTopicHero'
+
+<TailwindTopicHero topicId="tailwindcss/history/history-headless-tokens" title="Token 化与 Headless 组件阶段" />
+
 ## 要点
 
 - API 与样式解耦的 Headless 组件（Radix、Headless UI、shadcn/ui、reka-ui）+ Tailwind/Uno，让设计 token 可直连类名。
diff --git a/website/docs/tailwindcss/history/history-preprocessors.mdx b/website/docs/tailwindcss/history/history-preprocessors.mdx
@@ -22,6 +22,10 @@ keywords:
   - mpx
 ---
 
+import TailwindTopicHero from '@site/src/components/docs/TailwindTopicHero'
+
+<TailwindTopicHero topicId="tailwindcss/history/history-preprocessors" title="Sass / Less 预处理阶段" />
+
 ## 要点
 
 - 变量/混入/函数提升复用度，BEM/OOCSS 更易落地；仍是全局作用域。
diff --git a/website/docs/tailwindcss/history/history-raw-css.mdx b/website/docs/tailwindcss/history/history-raw-css.mdx
@@ -23,6 +23,10 @@ keywords:
   - mpx
 ---
 
+import TailwindTopicHero from '@site/src/components/docs/TailwindTopicHero'
+
+<TailwindTopicHero topicId="tailwindcss/history/history-raw-css" title="Raw CSS / BEM / OOCSS" />
+
 ## 要点
 
 - 全局样式 + 命名约定（BEM/OOCSS）降低心智负担，工具链简单。
diff --git a/website/docs/tailwindcss/history/history-utility-first.mdx b/website/docs/tailwindcss/history/history-utility-first.mdx
@@ -23,6 +23,10 @@ keywords:
   - mpx
 ---
 
+import TailwindTopicHero from '@site/src/components/docs/TailwindTopicHero'
+
+<TailwindTopicHero topicId="tailwindcss/history/history-utility-first" title="Utility-first / Tailwind / UnoCSS 阶段" />
+
 ## 要点
 
 - 类名即样式，JIT + content 精准摇树；与设计 tokens/variants 易对齐。
diff --git a/website/docs/tailwindcss/history/index.mdx b/website/docs/tailwindcss/history/index.mdx
@@ -19,6 +19,10 @@ keywords:
   - mpx
 ---
 
+import TailwindTopicHero from '@site/src/components/docs/TailwindTopicHero'
+
+<TailwindTopicHero topicId="tailwindcss/history/history-style-evolution" title="样式方案的演化" />
+
 ## 要点
 
 - 这页不是为了背历史，而是为了回答一个现实问题：为什么今天越来越多团队会走向原子化 CSS。
diff --git a/website/docs/tailwindcss/index.mdx b/website/docs/tailwindcss/index.mdx
@@ -18,9 +18,12 @@ keywords:
   - mpx
 ---
 
+import TailwindTopicHero from '@site/src/components/docs/TailwindTopicHero'
 import Tabs from '@theme/Tabs'
 import TabItem from '@theme/TabItem'
 
+<TailwindTopicHero topicId="tailwindcss/index" title="原子化 CSS 专题导览" />
+
 ## 为什么读这份专题
 
 - 如果你刚接触原子化 CSS，这组文档会帮你先建立判断标准，再看工具细节，不会一上来就陷进类名和术语里。
diff --git a/website/docs/tailwindcss/merge-and-variants.mdx b/website/docs/tailwindcss/merge-and-variants.mdx
@@ -21,6 +21,10 @@ keywords:
   - mpx
 ---
 
+import TailwindTopicHero from '@site/src/components/docs/TailwindTopicHero'
+
+<TailwindTopicHero topicId="tailwindcss/merge-and-variants" title="tailwind-merge、cva、tailwind-variants 精要" />
+
 ## 要点
 
 - `tailwind-merge` 负责 class 冲突/去重，是安全拼 class 的底座；推荐封装 `cn = twMerge(clsx(...))`。
diff --git a/website/docs/tailwindcss/postcss.mdx b/website/docs/tailwindcss/postcss.mdx
@@ -22,6 +22,10 @@ keywords:
   - mpx
 ---
 
+import TailwindTopicHero from '@site/src/components/docs/TailwindTopicHero'
+
+<TailwindTopicHero topicId="tailwindcss/postcss" title="PostCSS：插件化 CSS 引擎、历史地位与生态" />
+
 ## 为什么关注 PostCSS
 
 - 它是一个 AST 驱动的「二次加工」引擎，不是预处理器；你可以在标准 CSS 之上插入插件，完成兼容性、未来语法、定制输出等任务。
diff --git a/website/docs/tailwindcss/shadcn-ui.mdx b/website/docs/tailwindcss/shadcn-ui.mdx
@@ -20,6 +20,10 @@ keywords:
   - mpx
 ---
 
+import TailwindTopicHero from '@site/src/components/docs/TailwindTopicHero'
+
+<TailwindTopicHero topicId="tailwindcss/shadcn-ui" title="shadcn/ui 的出现与意义" />
+
 ## 背景：复制源码，而非安装依赖
 
 - 模式：shadcn/ui 不发布 npm 包，而是提供可复制的源码和 CLI，生成组件文件后由团队自行维护、改造。
diff --git a/website/docs/tailwindcss/style-isolation.mdx b/website/docs/tailwindcss/style-isolation.mdx
@@ -18,6 +18,10 @@ keywords:
   - mpx
 ---
 
+import TailwindTopicHero from '@site/src/components/docs/TailwindTopicHero'
+
+<TailwindTopicHero topicId="tailwindcss/style-isolation" title="样式隔离方案与原理" />
+
 ## 什么时候需要隔离
 
 - 微前端/Widget/站外嵌入：宿主可能有全局 reset 或 UI 库，必须避免互相覆盖。
diff --git a/website/docs/tailwindcss/tailwind-core.mdx b/website/docs/tailwindcss/tailwind-core.mdx
@@ -19,6 +19,10 @@ keywords:
   - mpx
 ---
 
+import TailwindTopicHero from '@site/src/components/docs/TailwindTopicHero'
+
+<TailwindTopicHero topicId="tailwindcss/tailwind-core" title="Tailwind 设计理念" />
+
 ## Tailwind 本质是什么
 
 - 可以把 Tailwind 理解成一条“压缩再展开”的流水线。
diff --git a/website/docs/tailwindcss/tailwind-vs-unocss.mdx b/website/docs/tailwindcss/tailwind-vs-unocss.mdx
@@ -21,6 +21,10 @@ keywords:
   - mpx
 ---
 
+import TailwindTopicHero from '@site/src/components/docs/TailwindTopicHero'
+
+<TailwindTopicHero topicId="tailwindcss/tailwind-vs-unocss" title="Tailwind vs UnoCSS 对比" />
+
 ## 要点
 
 - Tailwind 提供「开箱即用」的 preset、插件、`tailwind-merge`、IDE 支持和社区范式；UnoCSS 提供高度可定制的 rules/variants/preset，但 merge/提示需自养。
diff --git a/website/sidebars/tailwindcss.ts b/website/sidebars/tailwindcss.ts
@@ -4,18 +4,19 @@ const tailwindcssSidebar: SidebarConfig = [
   {
     type: 'doc',
     id: 'tailwindcss/index',
+    label: '◉ 专题导览',
   },
   {
     type: 'category',
-    label: '样式方案与组件库演进',
+    label: '◫ 样式方案与组件库演进',
     collapsed: false,
     link: { type: 'doc', id: 'tailwindcss/history/history-style-evolution' },
     items: [
       'tailwindcss/css-origin-evolution',
       'tailwindcss/history/history-component-evolution',
       {
         type: 'category',
-        label: 'Raw CSS / BEM / OOCSS',
+        label: '◌ Raw CSS / BEM / OOCSS',
         collapsed: false,
         link: { type: 'doc', id: 'tailwindcss/history/history-raw-css' },
         items: [
@@ -33,7 +34,7 @@ const tailwindcssSidebar: SidebarConfig = [
   },
   {
     type: 'category',
-    label: 'Tailwind 设计与对比',
+    label: '◭ Tailwind 设计、生态与对比',
     collapsed: false,
     link: { type: 'doc', id: 'tailwindcss/tailwind-core' },
     items: [
@@ -43,20 +44,22 @@ const tailwindcssSidebar: SidebarConfig = [
     ],
   },
   {
-    type: 'doc',
-    id: 'tailwindcss/best-practices',
-  },
-  {
-    type: 'doc',
-    id: 'tailwindcss/style-isolation',
-  },
-  {
-    type: 'doc',
-    id: 'tailwindcss/ai-friendly-and-demos',
+    type: 'category',
+    label: '◪ 工程约束与样式边界',
+    collapsed: false,
+    items: [
+      'tailwindcss/best-practices',
+      'tailwindcss/style-isolation',
+    ],
   },
   {
-    type: 'doc',
-    id: 'tailwindcss/demos',
+    type: 'category',
+    label: '◬ AI 与对照实验',
+    collapsed: false,
+    items: [
+      'tailwindcss/ai-friendly-and-demos',
+      'tailwindcss/demos',
+    ],
   },
 ]
 
diff --git a/website/src/components/docs/TailwindTopicHero.tsx b/website/src/components/docs/TailwindTopicHero.tsx
diff --git a/website/src/components/docs/tailwindTopicData.ts b/website/src/components/docs/tailwindTopicData.ts
diff --git a/website/src/css/custom/_docs.scss b/website/src/css/custom/_docs.scss
