InsightReply/rules/frontend-guidelines.md

description: InsightReply 前端 UI/UX 编码规范与实现方案 globs: *.ts, *.tsx, *.vue, *.css, *.html

InsightReply 前端 UI/UX 编码规范与实现方案

本文档基于 ui-ux-pro-max 高级设计理念以及现代前端工程化标准，定义了 InsightReply 浏览器插件和 Web 后台的开发规范。

一、 核心视觉原则 (ui-ux-pro-max 特性)

1. 极致暗黑与毛玻璃 (Premium Dark Mode & Glassmorphism)

我们致力于打造充满极客感、空间感和现代感的界面。

• 色彩体系：
  • 主背景色：采用深度黑或深炭灰（例如 #0A0A0A 到 #171717），坚决避免使用死板的纯黑 (#000000)。
  • 次级面板：使用比背景稍亮的一级的灰色区分层级。
  • 强调文字：避免纯白，使用柔和的高反差灰色（如 #E5E5E5 或 #D4D4D4）减轻视觉疲劳。
• 毛玻璃效果 (Glassmorphism)：
  • 重点应用场景：浏览器插件悬浮弹窗、侧边通知、下拉菜单。
  • CSS 标准：background-color: rgba(23, 23, 23, 0.7); backdrop-filter: blur(12px); border: 1px solid rgba(255, 255, 255, 0.1);。

2. 动态交互与微动画 (Micro-Interactions)

所有交互必须平滑且具有生命力。

• 过渡动画 (Transitions)：
  • 所有按钮悬停 (Hover)、面板展开 (Expand) 等状态变化必须带有过渡。
  • 标准推荐：transition-all duration-200 ease-in-out。
• 状态反馈 (Feedback)：
  • 点击事件触发时提供细微的尺寸缩小反馈 (如 active:scale-95)。
  • Loading 或 Success 状态需辅以平滑的 SVG 骨架或打勾动画。

3. 排版体系与强调色 (Typography & Accent)

• 现代无衬线字体：
  • 优先字体栈：Inter, Geist, 或 Apple 原生 SF Pro。确保字母间距 (Tracking) 在小号字时适当放宽，大标题时适当收紧。
• 品牌强调色 (Accent Colors)：
  • 主推 AI 科技质感的渐变色。例如：紫蓝渐变 from-violet-500 to-blue-500。
  • 应用于：核心 Call To Action (CTA) 按钮、选中的 Tab 下划线、高亮的重要标签。

---

二、 技术栈实现规范 (Tailwind CSS 最佳实践)

我们将使用 Tailwind CSS (v3 / v4)，结合以下工程化工具链，系统化落地 ui-ux-pro-max：

1. 原子化运用与 Design Tokens

• 禁止硬编码魔法值。所有的自定义颜色（如品牌色紫蓝）、特殊间距，尽其所能都在 tailwind.config.ts (或 js) 的 theme.extend 中被转换为 Tokens。
• 例子：bg-brand-primary 替代 bg-[#8B5CF6]。

2. 动态类名管理的终极方案

所有复用性高、含动态计算逻辑的 UI 组件，必须引入 clsx 和 tailwind-merge 这个组合包（通常约定以 cn 函数导出）。

• 原因：避免你在子组件传参时（例如 class="bg-red-500"），因为和组件内部默认的 bg-blue-500 发成 Tailwind 权重冲突导致样式失效。
• lib/utils.ts 工具函数标准写法：

  import { clsx, type ClassValue } from "clsx"
  import { twMerge } from "tailwind-merge"
  
  export function cn(...inputs: ClassValue[]) {
    return twMerge(clsx(inputs))
  }
  

3. 组件化结构

高频 UI 实体必须封装。以 Vue 3 + Tailwind 为例：

• 所有属性 (Props) 变化带来的 UI 变化，结合上述的 cn 在 <script setup> 顶部计算完毕。
• 如非极其生僻或庞大的样式块，尽量不要使用 <style> 块里的 @apply，坚持 Inline Tailwind classes，保证组件的可移植性。

---

三、 浏览器插件 (Chrome Extension) 特定架构规范

由于 InsightReply 需要在强敌环伺的第三方页面（如 X / Twitter）上运行，前端注入策略尤为关键。

1. UI 隔离：必须采用 Shadow DOM

• 痛点：Twitter 原生大量的 CSS 选择器极易破坏我们插件的排版（例如它的 div, span 默认样式），同时我们的样式如果泄漏也可能打乱 Twitter。
• 规范强制： 所有注入到宿主页面的 Content Scripts 最终挂载点 (Mount Root) 必须被包装在 ShadowRoot 之内。所有的 Tailwind 打包产物 CSS 将局部单向注入到该 ShadowTree 内。

2. 轻量化与按需加载

• 插件端对体积非常敏感。
• 绝不全量引入极其庞大的组件库包（如不按需加载全量导入 Element Plus）。
• 页面侧边栏组件与 Background Service Worker (Go 通讯代理层) 通过标准 chrome.runtime.sendMessage 保持极简高效的通讯。