--- name: frontend-brand description: 他山前端品牌设计系统完整参考手册。包含技术框架选型、设计令牌(颜色/字体/圆角/阴影)、组件规范代码模板、响应式/无障碍约定。被 role-前端开发 和 role-UI设计师 主动调用;与 frontend-brand-guard.mdc(约束层)配套使用。 --- # 他山前端品牌设计系统(frontend-brand) 关系类型:validates `frontend-brand-guard.mdc` / extends `role-前端开发` / extends `role-UI设计师` > **本 Skill 是可复用知识层**,回答「怎么写才对」。 > 配套 Rule `frontend-brand-guard.mdc` 是约束层,回答「哪些绝对不能写」。 > **真相来源**:所有代码以 `frontend/src/index.css` 和 `frontend/tailwind.config.js` 为准。 --- ## 激活后立即执行 ``` Step 1 明确当前场景(产品内页 or 官网/主页) → 不确定时默认:产品内页(黑白极简) Step 2 定位具体需求(组件类型 / 页面类型 / 样式修改) → 查阅本 Skill 对应章节,直接使用规范类名和代码模板 Step 3 输出代码 / 设计方案 → 输出前对照第十章「禁止清单」自检 Step 4 遇到本 Skill 未覆盖的细节时,按优先级查阅: 1. frontend/src/index.css(CSS 变量/动画定义的唯一真相) 2. frontend/tailwind.config.js(Tailwind 映射的唯一真相) 3. 项目群/Tashan-TopicLab/docs/design/frontend-design-guide.md(语义说明) ``` --- ## ⚠️ 已知文档内部不一致(必须知晓) `shape-system.md` 表格中写 `rounded-lg` = Default = 12px,但实际代码 `tailwind.config.js` 将 `rounded-lg` 映射到 `var(--radius-lg)` = **16px**,`frontend-design-guide.md` 中卡片/按钮/模态框也均使用 `rounded-lg`。**以代码为准:`rounded-lg` = 16px**,是标准通用圆角。 --- ## 一、技术框架 | 技术 | 版本 | 用途 | |------|------|------| | React | 18.x | UI 框架 | | TypeScript | 5.x | 类型系统 | | Vite | 5.x | 构建工具 | | Tailwind CSS | 3.x | 样式(utility-first,不用 CSS-in-JS) | | react-router-dom | 6.x | 路由 | | react-markdown + remark-gfm | latest | Markdown 渲染 | | KaTeX + remark-math + rehype-katex | latest | 数学公式 | | Vitest + @testing-library/react | latest | 测试 | **样式分层**:Tailwind utility → `@layer components` → `@layer utilities`(动画/工具)→ `@layer base`(html/body) **文件结构**(实际项目): ``` frontend/src/ ├── api/ # axios 封装 ├── components/ # 可复用组件 ├── hooks/ # 自定义 hooks ├── modules/ # 功能模块 ├── pages/ # 页面组件 ├── utils/ # 工具函数 ├── App.tsx ├── main.tsx └── index.css # CSS 变量 / @layer base / 动画 / markdown 样式 ``` --- ## 二、设计令牌(完整以代码为准) ### 2.1 字体 ```javascript // tailwind.config.js fontFamily: { serif: ['Noto Serif SC', 'STSong', 'SimSun', 'serif'], sans: ['-apple-system', 'BlinkMacSystemFont', 'Segoe UI', 'Roboto', 'sans-serif'], } ``` ```html ``` **规则**: - 所有用户可见文字 → `font-serif`(Noto Serif SC) - 技术标识/代码片段 → `font-mono` - 禁止:Inter、Roboto、Arial 作主字体 ### 2.2 排版比例(来自 frontend-design-guide.md) | 用途 | Tailwind 类 | |------|-------------| | 页面标题 | `text-xl sm:text-2xl font-serif font-bold text-black` | | 章节标题 | `text-lg font-serif font-semibold text-black` | | 卡片标题 | `text-base font-serif font-semibold text-black` | | 正文 | `text-sm font-serif text-black` 或 `text-gray-600` | | 次要信息 | `text-xs text-gray-500` | | 技术ID | `text-[10px] text-gray-400 font-mono` | 行高与截断:正文 `leading-relaxed`,单行 `truncate`,多行 `line-clamp-2` ### 2.3 CSS 变量(`src/index.css` — 唯一真相) ```css :root { /* 主题色 (Brand) */ --brand-primary: #3B82F6; --brand-dark: #1E40AF; --brand-light: #DBEAFE; /* 强调色 (Accent) */ --accent-primary: #0EA5E9; --accent-success: #10B981; --accent-warning: #F59E0B; --accent-error: #EF4444; --accent-info: #3B82F6; /* 底色 (Background) */ --bg-page: #F8FAFC; --bg-container: #FFFFFF; --bg-secondary: #F1F5F9; --bg-tertiary: #F8FAFC; --bg-hover: #F1F5F9; --bg-selected: #E0F2FE; --bg-disabled: #E2E8F0; --bg-footer: #0E2E4F; /* 文字色 (Text) */ --text-primary: #1E293B; /* ← 注意:不是 #0F172A */ --text-secondary: #475569; --text-tertiary: #94A3B8; --text-disabled: #CBD5E1; --text-inverse: #FFFFFF; /* 边框色 (Border) */ --border-default: #E2E8F0; --border-hover: #CBD5E1; --border-focus: #3B82F6; --border-active: #0EA5E9; /* 阴影 (Shadow) */ --shadow-sm: 0 1px 2px rgba(0, 0, 0, 0.05); --shadow-md: 0 1px 3px rgba(0, 0, 0, 0.1), 0 1px 2px rgba(0, 0, 0, 0.06); --shadow-lg: 0 4px 6px rgba(0, 0, 0, 0.07), 0 2px 4px rgba(0, 0, 0, 0.06); --shadow-xl: 0 10px 15px rgba(0, 0, 0, 0.1), 0 4px 6px rgba(0, 0, 0, 0.05); /* 圆角 (Radius) — 精简三级 */ --radius-sm: 12px; /* 已废弃,映射到 --radius-md */ --radius-md: 12px; /* 12px — 理论默认(实际 rounded-lg = 16px,见顶部说明) */ --radius-lg: 16px; /* 16px — 弹窗/下拉/标准通用 */ --radius-xl: 16px; /* 已废弃,映射到 --radius-lg */ --radius-2xl: 16px; /* 已废弃,映射到 --radius-lg */ --radius-full: 9999px; /* 完全圆形 */ /* 过渡 (Transition) */ --transition-fast: 150ms ease; --transition-normal: 200ms ease; --transition-slow: 300ms ease; /* 兼容旧变量(迁移期间保留,勿在新代码中直接使用) */ --color-primary: var(--brand-primary); --color-secondary: var(--accent-primary); --color-dark: var(--text-primary); --color-darker: var(--brand-dark); --color-gray: var(--text-secondary); --color-gray-light: var(--border-default); --color-gray-dark: var(--text-tertiary); --gradient-dark: var(--bg-footer); } ``` ### 2.4 Tailwind Config(`tailwind.config.js` — 唯一真相) ```javascript export default { content: ['./index.html', './src/**/*.{js,ts,jsx,tsx}'], theme: { extend: { fontFamily: { serif: ['Noto Serif SC', 'STSong', 'SimSun', 'serif'], sans: ['-apple-system', 'BlinkMacSystemFont', 'Segoe UI', 'Roboto', 'sans-serif'], }, colors: { brand: { primary: 'var(--brand-primary)', dark: 'var(--brand-dark)', light: 'var(--brand-light)' }, accent: { primary: 'var(--accent-primary)', success: 'var(--accent-success)', warning: 'var(--accent-warning)', error: 'var(--accent-error)', info: 'var(--accent-info)' }, surface: { page: 'var(--bg-page)', container: 'var(--bg-container)', secondary: 'var(--bg-secondary)', hover: 'var(--bg-hover)', selected: 'var(--bg-selected)', disabled: 'var(--bg-disabled)' }, content: { primary: 'var(--text-primary)', secondary: 'var(--text-secondary)', tertiary: 'var(--text-tertiary)', disabled: 'var(--text-disabled)', inverse: 'var(--text-inverse)' }, line: { default: 'var(--border-default)', hover: 'var(--border-hover)', focus: 'var(--border-focus)', active: 'var(--border-active)' }, black: '#000000', white: '#FFFFFF', }, spacing: { '18': '4.5rem', '22': '5.5rem', }, borderRadius: { sm: 'var(--radius-sm)', // 12px (deprecated) md: 'var(--radius-md)', // 12px lg: 'var(--radius-lg)', // 16px ← 标准通用圆角 xl: 'var(--radius-xl)', // 16px (deprecated) '2xl':'var(--radius-2xl)', // 16px (deprecated) full: 'var(--radius-full)', // 9999px }, boxShadow: { sm: 'var(--shadow-sm)', md: 'var(--shadow-md)', lg: 'var(--shadow-lg)', xl: 'var(--shadow-xl)', }, transitionDuration: { fast: '150ms', normal: '200ms', slow: '300ms', }, }, }, plugins: [], } ``` --- ## 三、配色场景 | 场景 | 使用时机 | 核心色调 | |------|----------|---------| | **产品内页(默认)** | 话题列表/详情/配置/库 | 黑+白+灰,`black`/`white`/`gray-*` | | **官网/主页** | Landing page / 营销页 | 蓝绿渐变 `#5B9BD5` + `#9FD4C4` | **不确定时,始终用产品内页风格。** ### 产品内页速查 ``` 主色/CTA: #000000 (black) 页面背景: #FFFFFF (white) 卡片边框: gray-200 次边框: gray-100 悬停边框: gray-300 / black(激活) 主文字: text-black 描述文字: text-gray-600 / text-gray-700 次要文字: text-gray-500 技术标识: text-gray-400 font-mono 禁用: text-gray-400 opacity-50 选中背景: bg-gray-100 悬停背景: bg-gray-50 文字选中: ::selection { bg-black text-white } ``` ### 官网/主页速查 ```css --color-primary: #5B9BD5; /* 淡蓝 */ --color-secondary: #9FD4C4; /* 淡绿 */ --color-dark: #0E2E4F; /* 深海蓝(footer/heading) */ --gradient-primary: linear-gradient(135deg, #5B9BD5 0%, #9FD4C4 100%); --gradient-secondary: linear-gradient(135deg, #6BC5D6 0%, #B5E5C8 100%); --gradient-dark: linear-gradient(135deg, #0E2E4F 0%, #0A1F35 100%); /* 渐变标题文字 */ .gradient-text { background: var(--gradient-primary); -webkit-background-clip: text; -webkit-text-fill-color: transparent; background-clip: text; } ``` ### 语义状态色 | 状态 | 类 | |------|-----| | Default | `border-gray-200 text-gray-600` | | Active/Selected | `border-black text-black` 或 `bg-gray-100` | | Disabled | `text-gray-400 opacity-50` | | Open | `bg-green-50 text-green-700` | | Running | `bg-blue-50 text-blue-600` | | Completed | `bg-gray-100 text-gray-600` | > 语义色统一封装在 `.status-badge*` CSS 类(见第九章),不允许各处临时映射。 --- ## 四、圆角系统(代码实际值) | Tailwind 类 | CSS 变量 | 实际值 | 使用场景 | |------------|----------|--------|---------| | `rounded-lg` | `var(--radius-lg)` | **16px** | 卡片/按钮/输入框/模态框(指南统一用此类) | | `rounded-xl` | `var(--radius-xl)` | 16px | 已废弃,等同 `rounded-lg` | | `rounded-full` | `var(--radius-full)` | 9999px | 头像/Chip/徽章 | | `rounded-md` | `var(--radius-md)` | 12px | 理论默认,当前实际用 `rounded-lg` | **禁止**:自定义值 `rounded-[XXpx]` --- ## 五、组件代码模板(来自 frontend-design-guide.md) ### 5.1 按钮 ```tsx // 主按钮 // 次按钮 // 文字按钮 // 图标按钮 // 圆形操作按钮(+/×) ``` ### 5.2 卡片 ```tsx // 标准内容卡片(可点击,含响应式宽度)
标题 描述 元数据
// 话题列表项
{/* 内容 */}
// 选中态卡片(select 模式)
{/* 选中时按钮: bg-gray-400 text-white / 未选中: bg-black text-white */}
``` ### 5.3 输入控件 ```tsx