diff --git a/README.md b/README.md index 01b7d2a..029af3e 100644 --- a/README.md +++ b/README.md @@ -19,7 +19,8 @@ GrandClaw 是一个企业级AI智能助手平台的前端原型项目，主要 ### UI与样式 - **react-icons 5.5.0**：图标库（Feather + FontAwesome图标集） - **Sass 1.98.0**：CSS预处理器 -- **SCSS模块化**：变量、混入、组件、布局、页面分离 +- **五层分层架构**：tokens → core → layouts → components → pages +- **BEM 命名规范**：所有组件类名遵循 `.block__element--modifier` 格式 ### 构建优化 - **vite-plugin-singlefile 2.3.2**：单文件打包，解决CORS问题 @@ -70,59 +71,55 @@ grandclaw-archtype/ │ │ ├── AdminPage.jsx # 管理台主页面 │ │ ├── DeveloperPage.jsx # 开发台主页面 │ │ ├── console/ # 工作台子页面 -│ │ │ ├── ChatPage.jsx # 聊天页面 -│ │ │ ├── SkillsPage.jsx # 技能市场 -│ │ │ ├── SkillDetailPage.jsx # 技能详情 -│ │ │ ├── MySkillsPage.jsx # 我的技能管理（NEW） -│ │ │ ├── SkillConfigPage.jsx # 技能配置（NEW） -│ │ │ ├── LogsPage.jsx # 日志查询 -│ │ │ ├── TasksPage.jsx # 定时任务 -│ │ │ ├── TaskDetailPage.jsx # 任务详情 -│ │ │ ├── AccountPage.jsx # 账号管理 -│ │ │ ├── ProjectsPage.jsx # 项目管理 -│ │ │ ├── MemberConfigPage.jsx # 成员配置 -│ │ │ └── AddMemberPage.jsx # 增加成员 │ │ ├── admin/ # 管理台子页面 -│ │ │ ├── OverviewPage.jsx # 运营总览 -│ │ │ ├── DepartmentsPage.jsx # 部门管理 -│ │ │ ├── AddDepartmentPage.jsx # 新增/编辑部门 -│ │ │ ├── UsersPage.jsx # 用户管理 -│ │ │ ├── AddUserPage.jsx # 新增/编辑用户 -│ │ │ ├── AdminProjectsPage.jsx # 项目管理 -│ │ │ ├── AddProjectPage.jsx # 新增/编辑项目 -│ │ │ ├── AdminLogsPage.jsx # 全局日志查询 -│ │ │ ├── ModelConfigsPage.jsx # 模型配置列表 -│ │ │ └── AddModelConfigPage.jsx # 新增/编辑模型配置 -│ │ ├── console/ # 工作台子页面 -│ │ │ ├── ChatPage.jsx # 聊天页面 -│ │ │ ├── SkillsPage.jsx # 技能市场 -│ │ │ ├── SkillDetailPage.jsx # 技能详情 -│ │ │ ├── LogsPage.jsx # 日志查询 -│ │ │ ├── TasksPage.jsx # 定时任务 -│ │ │ ├── TaskDetailPage.jsx # 任务详情 -│ │ │ ├── AccountPage.jsx # 账号管理 -│ │ │ ├── ProjectsPage.jsx # 项目管理 -│ │ │ ├── MemberConfigPage.jsx # 成员配置 -│ │ │ ├── AddMemberPage.jsx # 增加成员 -│ │ │ ├── ConsoleReviewListPage.jsx # 审核管理列表（NEW） -│ │ │ └── ConsoleReviewDetailPage.jsx # 审核详情（NEW） │ │ └── developer/ # 开发台子页面 -│ │ ├── DevOverviewPage.jsx # 开发者总览 -│ │ ├── MySkillsPage.jsx # 我的技能（筛选+分页） -│ │ ├── SkillEditorPage.jsx # 技能详情（只读+操作） -│ │ ├── UploadSkillPage.jsx # 创建技能（基本信息） -│ │ ├── UpdateSkillInfoPage.jsx # 更新基本信息 -│ │ ├── UploadVersionPage.jsx # 上传新版本（NEW） -│ │ ├── DevDocsPage.jsx # 开发文档 -│ │ └── DevAccountPage.jsx # 开发者设置 -│ └── styles/ # SCSS样式模块 -│ ├── _variables.scss # 设计系统变量 -│ ├── _mixins.scss # 可复用混入 -│ ├── _base.scss # 基础重置和全局样式 -│ ├── _components.scss # 通用组件样式 -│ ├── _layout.scss # 布局相关样式 -│ ├── _pages.scss # 页面特定样式 -│ └── global.scss # 主样式文件，导入所有模块 +│ └── styles/ # SCSS样式系统（分层架构） +│ ├── tokens/ # 第1层：设计令牌 +│ │ ├── _colors.scss # 品牌色、功能色、中性色 +│ │ ├── _spacing.scss # 间距系统（4px基数） +│ │ ├── _shadows.scss # 阴影层级 +│ │ ├── _radius.scss # 圆角系统 +│ │ ├── _typography.scss # 字体、字号、字重 +│ │ ├── _z-index.scss # 层级系统 +│ │ ├── _transitions.scss # 过渡动画参数 +│ │ ├── _breakpoints.scss # 响应式断点 +│ │ ├── _mixins.scss # 可复用混入 +│ │ └── _index.scss # 统一导出 +│ ├── core/ # 第2层：核心样式 +│ │ ├── _reset.scss # CSS重置 +│ │ ├── _css-variables.scss # :root CSS变量 +│ │ ├── _base.scss # body全局样式 +│ │ └── _index.scss +│ ├── layouts/ # 第3层：布局系统 +│ │ ├── _app-shell.scss # 主框架（sidebar+header+main） +│ │ ├── _chat-layout.scss # 聊天页面布局 +│ │ ├── _admin-layout.scss # 管理台布局 +│ │ └── _index.scss +│ ├── components/ # 第4层：组件库 +│ │ ├── button/ # 按钮（.btn, .btn--primary, .btn--ghost） +│ │ ├── card/ # 卡片（.card, .card__header, .card__body） +│ │ ├── table/ # 表格（.table, .table-actions, .col-actions） +│ │ ├── form/ # 表单（.form-group, .form__input, .form__label） +│ │ ├── tag/ # 标签（.tag--running, .tag--admin） +│ │ ├── modal/ # 弹窗（.modal, .modal__overlay） +│ │ ├── toast/ # 提示（.toast--success, .toast--error） +│ │ ├── pagination/ # 分页 +│ │ ├── empty-state/ # 空状态 +│ │ ├── switch/ # 开关 +│ │ ├── skill-card/ # 技能卡片 +│ │ ├── nav/ # 导航项 +│ │ ├── detail/ # 详情页组件 +│ │ ├── password-input/ # 密码输入框 +│ │ ├── search-bar/ # 搜索栏 +│ │ ├── stat-card/ # 统计卡片 +│ │ └── _index.scss # 统一导出 +│ ├── pages/ # 第5层：页面特有样式 +│ │ ├── _console.scss # 工作台特有组件 +│ │ ├── _admin.scss # 管理台特有组件 +│ │ ├── _developer.scss # 开发台特有组件 +│ │ ├── _home.scss # 首页特有组件 +│ │ └── _index.scss +│ └── global.scss # 主入口文件（仅 @use，无直接样式） ├── index.html # HTML入口文件 ├── package.json # 项目配置和依赖 ├── vite.config.js # Vite配置 @@ -500,52 +497,367 @@ const [currentPage, setCurrentPage] = useState(() => { ## 样式系统 -### SCSS模块化结构 +### 分层架构 + +样式采用五层架构，依赖方向自上而下：`tokens → core → layouts → components → pages` + ``` -src/styles/ -├── _variables.scss # 设计系统变量（颜色、间距、阴影等） -├── _mixins.scss # 可复用混入（媒体查询、弹性布局等） -├── _base.scss # 基础重置、CSS变量定义、body样式 -├── _components.scss # 通用组件（按钮、卡片、表单、状态标签） -├── _layout.scss # 布局相关（侧边栏、主内容区） -├── _pages.scss # 页面特定样式（首页、管理台等） -└── global.scss # 主文件，导入所有模块 +┌─────────────────────────────────────────┐ +│ pages/ 页面特有组件，仅覆盖模式 │ ← 最上层 +├─────────────────────────────────────────┤ +│ components/ 可复用UI组件库，BEM命名 │ +├─────────────────────────────────────────┤ +│ layouts/ 布局系统（shell/chat/admin） │ +├─────────────────────────────────────────┤ +│ core/ 重置、CSS变量、body样式 │ +├─────────────────────────────────────────┤ +│ tokens/ 设计令牌（颜色/间距/阴影...） │ ← 最底层 +└─────────────────────────────────────────┘ ``` -### 设计系统变量（_variables.scss） +### 第1层：Tokens（设计令牌） + +所有设计决策集中定义，禁止在组件或页面中硬编码值。 + ```scss -// 品牌主色 +// src/styles/tokens/_colors.scss $primary: #3B82F6; -$primary-light: #EFF6FF; $primary-dark: #2563EB; - -// 功能色 $success: #10B981; -$warning: #F59E0B; $danger: #EF4444; - -// 中性色 $text-1: #1E293B; -$text-2: #475569; $text-3: #94A3B8; -// 布局尺寸 -$sidebar-width: 240px; -$header-height: 60px; -$radius-md: 8px; +// src/styles/tokens/_spacing.scss +$spacing-1: 4px; +$spacing-2: 8px; +$spacing-4: 16px; + +// src/styles/tokens/_typography.scss +$font-size-base: 14px; +$font-weight-semibold: 600; ``` -### 状态标签样式 -支持多种状态标签： -- `status-running` - 成功/运行中（绿色） -- `status-stopped` - 停止/禁用（灰色） -- `status-warning` - 警告（黄色） -- `status-error` - 失败/错误（红色） +**使用方式：** 通过 `@use` 引入，直接使用变量名。 -### 角色标签样式 -- `role-admin` - 管理员（蓝色） -- `role-member` - 成员（灰色） -- `role-developer` - 开发者（橙色） +```scss +@use '../../tokens' as *; + +.my-component { + color: $text-1; + padding: $spacing-4; + font-weight: $font-weight-semibold; +} +``` + +**同时提供 CSS 变量**（core 层定义），供运行时和 JSX 内联场景使用： + +```scss +// core/_css-variables.scss 自动从 tokens 生成 :root 变量 +:root { + --color-primary: #{$primary}; + --color-text-1: #{$text-1}; +} + +// JSX 中可通过 style 使用 +
+``` + +### 第2层：Core（核心样式） + +包含 CSS 重置、`:root` CSS 变量定义、body 全局样式。无业务逻辑。 + +``` +core/ +├── _reset.scss # * { margin:0; padding:0; box-sizing:border-box; } +├── _css-variables.scss # :root { --color-primary: ...; } +├── _base.scss # body { font-family, color, background } +└── _index.scss # @forward 所有 core 模块 +``` + +### 第3层：Layouts（布局系统） + +页面骨架布局，不包含具体UI组件样式。 + +| 文件 | 职责 | +|------|------| +| `_app-shell.scss` | 主框架：sidebar + header + main-content + 响应式 | +| `_chat-layout.scss` | 聊天页：chat-sidebar + chat-content + conversation-list | +| `_admin-layout.scss` | 管理台：admin-sidebar + admin-nav + member-selection | + +**关键类名：** +- `.layout` / `.app-shell` — 主布局容器 +- `.sidebar` — 侧边栏 +- `.main-content` — 主内容区 +- `.header` — 顶部栏 +- `.page-content` — 页面内容区 + +### 第4层：Components（组件库） + +每个组件一个目录，内部 `_index.scss` 包含该组件的完整样式。 + +``` +components/ +├── button/_index.scss +├── card/_index.scss +├── table/_index.scss +├── form/_index.scss +├── tag/_index.scss +├── modal/_index.scss +├── toast/_index.scss +└── _index.scss # @forward 所有组件 +``` + +**组件目录创建规则：** +``` +components/ +└── {component-name}/ + └── _index.scss # 必须存在，包含组件全部样式 +``` + +### 第5层：Pages（页面特有样式） + +仅包含**页面独有的组件样式**，不放可复用组件。 + +``` +pages/ +├── _console.scss # 聊天消息、欢迎区、输入框等 +├── _admin.scss # 总览统计、异常列表等 +├── _developer.scss # 技能概览卡片、版本历史卡片等 +├── _home.scss # 首页英雄区、特性卡片等 +└── _index.scss +``` + +### 主入口文件 + +`global.scss` 是纯入口文件，**仅包含 `@use` 语句**，无任何直接样式定义： + +```scss +// src/styles/global.scss +@use 'tokens' as *; +@use 'core' as *; +@use 'layouts' as *; +@use 'components' as *; +@use 'pages/console' as *; +@use 'pages/admin' as *; +@use 'pages/developer' as *; +@use 'pages/home' as *; +``` + +--- + +## 样式开发规范 + +### BEM 命名规范 + +所有组件类名必须遵循 BEM 格式：`.block__element--modifier` + +```scss +// Block — 组件根节点 +.card { } + +// Element — 组件内部元素，用双下划线连接 +.card__header { } +.card__body { } +.card__footer { } + +// Modifier — 变体/状态，用双连字符连接 +.card--flat { } +.card--elevated { } +.btn--primary { } +.btn--danger { } +.tag--running { } +.tag--admin { } +``` + +**JSX 对应写法：** +```jsx +
+
+ 标题 +
+
+ 内容 +
+
+ + + +运行中 +``` + +### 组件文件内部结构 + +每个组件的 `_index.scss` 按以下顺序组织： + +```scss +// 1. 依赖引入 +@use '../../tokens' as *; + +// 2. Block — 组件根节点 +.btn { } + +// 3. Elements — 内部元素 +.btn__icon { } + +// 4. Modifiers — 变体（按语义分组） +// 颜色变体 +.btn--primary { } +.btn--danger { } + +// 尺寸变体 +.btn--sm { } +.btn--lg { } + +// 状态变体 +.btn--loading { } + +// 5. Legacy 兼容别名（过渡期） +.text-btn { @extend .btn--ghost; } +``` + +### 新增组件开发流程 + +1. **确认组件层级**：属于 tokens/core/layouts/components/pages 哪一层 +2. **创建目录**：`src/styles/components/{name}/` +3. **创建 `_index.scss`**：按 BEM 结构编写样式 +4. **引入 tokens**：`@use '../../tokens' as *;` 使用设计令牌 +5. **在 `_index.scss` 中注册**：`components/_index.scss` 添加 `@forward '{name}';` +6. **在 JSX 中使用**：`className="block__element--modifier"` +7. **验证构建**：`pnpm build` + +### 新增页面样式开发流程 + +1. **优先复用组件库**：先检查 `components/` 是否已有可用组件 +2. **页面特有组件**：在 `pages/_{page}.scss` 中定义 +3. **仅放页面独有的样式**：可复用的应提取到 `components/` +4. **不硬编码值**：使用 tokens 中的变量或 CSS 变量 + +### 内联样式规则 + +**禁止使用内联 style 的场景：** +- 可复用的组件样式（按钮、卡片、表格操作列等） +- 使用 tokens 中已有变量的值 +- 多个页面/组件中重复出现的模式 + +**允许使用内联 style 的场景：** +- 各表特有的内容列宽（如 `style={{ width: '180px' }}`） +- 动态计算值（如进度条宽度 `width: 65%`） +- 聊天消息内容中的排版（通过 `dangerouslySetInnerHTML` 渲染） + +### 表格操作列规范 + +表格操作列统一使用以下类名，禁止写内联样式： + +```jsx +// 表头 — 操作列宽度 +操作 // 200px +操作 // 120px +操作 // 80px + +// 单元格 — 操作按钮容器 + +
+ + +
+ + +// 可点击行 + +``` + +### 按钮使用规范 + +| 场景 | 类名 | 颜色 | +|------|------|------| +| 主操作（确认、提交） | `btn btn--primary` | 蓝色实心 | +| 次要操作（取消、重置） | `btn` | 灰色边框 | +| 表格内编辑 | `text-btn text-btn-primary` | 蓝色文字 | +| 表格内删除/禁用 | `text-btn text-btn-danger` | 红色文字 | +| 危险操作确认 | `btn btn--danger` | 红色实心 | +| 警告操作 | `btn btn--warning` | 橙色实心 | + +### 状态标签规范 + +```jsx +// 运行状态 +运行中 +已停止 +失败 +警告 + +// 用户角色 +管理员 +成员 +开发者 +``` + +### 引用 Tokens 的方式 + +```scss +// 在组件或页面文件中 +@use '../../tokens' as *; + +// 直接使用 SCSS 变量 +.my-class { + color: $primary; + padding: $spacing-4; + border-radius: $radius-md; + font-weight: $font-weight-semibold; + box-shadow: $shadow-card; +} + +// 使用 CSS 变量（适合需要运行时切换的场景） +.my-class { + color: var(--color-primary); + background: var(--color-bg-1); +} +``` + +### 样式文件引用规则 + +```scss +// tokens 层：无依赖 +@use 'colors' as *; + +// core 层：依赖 tokens +@use '../tokens' as *; + +// layouts 层：依赖 tokens +@use '../tokens' as *; + +// components 层：依赖 tokens +@use '../../tokens' as *; + +// pages 层：依赖 tokens +@use '../tokens' as *; +``` + +**禁止**：跨层引用（如 components 直接引用 pages） + +### 响应式开发 + +使用 tokens 中定义的断点，通过 mixins 调用： + +```scss +@use '../../tokens' as *; + +@include mobile { + // <= 768px + .my-component { + flex-direction: column; + } +} + +@include tablet { + // 769px ~ 1024px +} + +@include desktop { + // >= 1025px +} +``` ## 数据访问层 @@ -658,20 +970,30 @@ export default defineConfig({ ### 添加新页面 1. 在 `src/pages/` 目录下创建页面组件 -2. 在父页面组件（如ConsolePage、AdminPage）中添加路由逻辑 -3. 如果需要持久化状态，添加localStorage逻辑 -4. 在 `src/styles/global.scss` 中添加页面特定样式 +2. 在父页面组件（如 ConsolePage、AdminPage）中添加路由逻辑 +3. 如果需要持久化状态，添加 localStorage 逻辑 +4. 页面特有样式添加到 `src/styles/pages/_{module}.scss`（优先复用组件库） ### 添加新组件 1. 在 `src/components/` 目录下创建组件 -2. 在 `src/styles/global.scss` 中添加组件样式 -3. 使用设计系统变量保持一致性 +2. 在 `src/styles/components/{name}/` 下创建 `_index.scss` +3. 使用 `@use '../../tokens' as *;` 引入设计令牌 +4. 使用 BEM 命名：`.block__element--modifier` +5. 在 `src/styles/components/_index.scss` 中添加 `@forward '{name}';` ### 修改样式 -1. 优先修改 `src/styles/_variables.scss` 中的变量 -2. 添加新的混入到 `src/styles/_mixins.scss` -3. 组件样式添加到 `_components.scss` -4. 页面特定样式添加到 `global.scss` +1. **全局调整**：修改 `src/styles/tokens/` 中的令牌变量 +2. **组件调整**：修改 `src/styles/components/{name}/_index.scss` +3. **页面调整**：修改 `src/styles/pages/_{module}.scss` +4. 禁止直接修改 `global.scss`（它是纯入口文件） + +### 样式验证清单 +- [ ] 类名是否遵循 BEM 规范 +- [ ] 颜色/间距/字号是否使用 tokens 变量 +- [ ] 是否存在重复定义的样式 +- [ ] 可复用样式是否放在 `components/` 而非 `pages/` +- [ ] 表格操作列是否使用 `.col-actions` + `.table-actions` +- [ ] `pnpm build` 是否通过 --- diff --git a/openspec/config.yaml b/openspec/config.yaml index 7c2b47e..2c7374b 100644 --- a/openspec/config.yaml +++ b/openspec/config.yaml @@ -5,12 +5,12 @@ context: | - 纯前端展示原型项目（非功能原型），无后端交互，供内部开发人员参考UI界面使用，目标在于展示页面布局、样式和组件能力 - 允许轻量级交互展示（如表单验证、弹框），状态展示策略：不重叠的状态通过静态数据驱动展示，重叠/覆盖类状态（弹框、下拉、抽屉等）允许简单交互切换 - 示例数据应精心设计，展示不同的页面元素状态 - - 新增代码要遵循原有代码的设计风格和模式 + - 新增代码要遵循原有代码的设计风格和模式，优先考虑复用已有页面或组件的布局，优先考虑复用已有样式（src/styles） - 不引入UI库，使用当前SCSS样式方案 - 使用pnpm作为包管理器，javascript作为开发语言，不引入typescript或eslint - 不构建测试，使用pnpm build验证打包即可，AI禁止运行pnpm dev（会挂起流程） - 不做性能优化，保持vite-plugin-singlefile单文件打包 - 不做安全防御性编程，eval/dangerouslySetInnerHTML等按需使用 - - README.md是项目的开发文档，记录代码结构和关键开发模式，优先读取获取上下文 + - **优先阅读README.md**，README.md文档是项目的开发文档，记录代码结构和关键开发模式，优先读取获取上下文 - 涉及页面/路由/组件/功能模块变更或技术栈调整时，同步更新README.md - Git提交: 仅中文; 格式为"类型: 简短描述",类型可选: feat(新功能)/fix(修复)/refactor(重构)/docs(文档)/style(格式)/test(测试)/chore(构建/工具); 多行描述空行后加详细说明; 禁创建git操作task diff --git a/openspec/specs/component-library/spec.md b/openspec/specs/component-library/spec.md new file mode 100644 index 0000000..451b22d --- /dev/null +++ b/openspec/specs/component-library/spec.md @@ -0,0 +1,238 @@ +## ADDED Requirements + +### Requirement: 按钮组件 +组件库 SHALL 提供完整的按钮组件系统，支持多种变体和尺寸。 + +#### Scenario: 基础按钮 +- **WHEN** 开发者需要标准按钮 +- **THEN** 系统 SHALL 提供 `.btn` 类，包含基础样式（flex布局、居中、间距、过渡动画） + +#### Scenario: 颜色变体 +- **WHEN** 开发者需要不同用途的按钮 +- **THEN** 系统 SHALL 提供 `.btn--primary`、`.btn--success`、`.btn--danger`、`.btn--warning`、`.btn--ghost` 等变体 + +#### Scenario: 尺寸变体 +- **WHEN** 开发者需要不同大小的按钮 +- **THEN** 系统 SHALL 提供 `.btn--sm`、`.btn--lg` 尺寸变体 + +#### Scenario: 图标按钮 +- **WHEN** 开发者需要仅含图标的按钮 +- **THEN** 系统 SHALL 提供 `.btn--icon-only` 修饰符 + +#### Scenario: 块级按钮 +- **WHEN** 开发者需要宽度占满的按钮 +- **THEN** 系统 SHALL 提供 `.btn--block` 修饰符 + +#### Scenario: 加载状态 +- **WHEN** 按钮处于加载中状态 +- **THEN** 系统 SHALL 提供 `.btn--loading` 修饰符，显示加载动画并禁用点击 + +### Requirement: 卡片组件 +组件库 SHALL 提供卡片容器组件。 + +#### Scenario: 基础卡片 +- **WHEN** 开发者需要内容容器 +- **THEN** 系统 SHALL 提供 `.card` 类，包含背景、边框、圆角、阴影 + +#### Scenario: 卡片区块 +- **WHEN** 卡片需要头部、主体、底部结构 +- **THEN** 系统 SHALL 提供 `.card__header`、`.card__body`、`.card__footer` 元素类 + +#### Scenario: 卡片变体 +- **WHEN** 开发者需要不同视觉风格的卡片 +- **THEN** 系统 SHALL 提供 `.card--flat`（无阴影）、`.card--elevated`（高阴影）等变体 + +### Requirement: 表格组件 +组件库 SHALL 提供数据表格组件。 + +#### Scenario: 基础表格 +- **WHEN** 开发者需要展示数据列表 +- **THEN** 系统 SHALL 提供 `.table` 类，包含表头、行、单元格样式 + +#### Scenario: 表格包装器 +- **WHEN** 表格需要横向滚动 +- **THEN** 系统 SHALL 提供 `.table__wrapper` 类，处理溢出和滚动 + +#### Scenario: 行悬停效果 +- **WHEN** 表格需要行悬停反馈 +- **THEN** 系统 SHALL 在 `.table tbody tr` 上提供悬停背景色变化 + +### Requirement: 表单组件 +组件库 SHALL 提供表单元素组件。 + +#### Scenario: 表单组 +- **WHEN** 开发者需要将标签和输入框组合 +- **THEN** 系统 SHALL 提供 `.form-group` 类，设置间距 + +#### Scenario: 标签 +- **WHEN** 表单需要字段标签 +- **THEN** 系统 SHALL 提供 `.form__label` 类，包含必填标记样式 + +#### Scenario: 输入框 +- **WHEN** 开发者需要文本输入 +- **THEN** 系统 SHALL 提供 `.form__input` 类，包含聚焦、错误状态样式 + +#### Scenario: 表单行 +- **WHEN** 表单项需要横向排列 +- **THEN** 系统 SHALL 提供 `.form__row` 和 `.form__col` 类 + +### Requirement: 状态标签组件 +组件库 SHALL 提供状态指示标签。 + +#### Scenario: 状态展示 +- **WHEN** 开发者需要展示运行/停止/错误等状态 +- **THEN** 系统 SHALL 提供 `.tag` 类和 `.tag--running`、`.tag--stopped`、`.tag--error`、`.tag--warning` 等变体 + +#### Scenario: 角色标签 +- **WHEN** 开发者需要展示用户角色 +- **THEN** 系统 SHALL 提供 `.tag--admin`、`.tag--member`、`.tag--developer` 等变体 + +### Requirement: 弹窗组件 +组件库 SHALL 提供模态弹窗组件。 + +#### Scenario: 弹窗容器 +- **WHEN** 开发者需要显示模态弹窗 +- **THEN** 系统 SHALL 提供 `.modal` 和 `.modal__overlay` 类 + +#### Scenario: 弹窗结构 +- **WHEN** 弹窗需要标题、内容、操作区 +- **THEN** 系统 SHALL 提供 `.modal__header`、`.modal__body`、`.modal__footer` 元素类 + +### Requirement: 提示组件 +组件库 SHALL 提供 Toast 提示组件。 + +#### Scenario: 提示消息 +- **WHEN** 开发者需要显示操作反馈 +- **THEN** 系统 SHALL 提供 `.toast` 类和 `.toast--success`、`.toast--error`、`.toast--warning`、`.toast--info` 等变体 + +### Requirement: 分页组件 +组件库 SHALL 提供分页导航组件。 + +#### Scenario: 分页导航 +- **WHEN** 列表需要分页 +- **THEN** 系统 SHALL 提供 `.pagination` 类和 `.pagination__item`、`.pagination__item--active` 元素类 + +### Requirement: 空状态组件 +组件库 SHALL 提供空状态展示组件。 + +#### Scenario: 无数据展示 +- **WHEN** 列表或页面无数据时 +- **THEN** 系统 SHALL 提供 `.empty-state` 类，包含图标、文字、可选操作按钮区域 + +### Requirement: 开关组件 +组件库 SHALL 提供切换开关组件。 + +#### Scenario: 布尔切换 +- **WHEN** 开发者需要开关控件 +- **THEN** 系统 SHALL 提供 `.switch` 类，包含滑块和选中状态样式 + +### Requirement: 技能卡片组件 +组件库 SHALL 提供技能展示专用卡片。 + +#### Scenario: 技能展示 +- **WHEN** 工作台需要展示技能列表 +- **THEN** 系统 SHALL 提供 `.skill-card` 类，包含图标区、信息区、统计区布局 + +### Requirement: 导航项组件 +组件库 SHALL 提供统一的侧边栏导航项组件。 + +#### Scenario: 导航菜单 +- **WHEN** 侧边栏需要导航菜单项 +- **THEN** 系统 SHALL 提供 `.nav-item` 类，统一替换 `.menu-item`、`.chat-nav-item`、`.admin-nav-item` + +#### Scenario: 导航图标 +- **WHEN** 导航项需要图标 +- **THEN** 系统 SHALL 提供 `.nav-item__icon` 元素类 + +#### Scenario: 激活状态 +- **WHEN** 导航项需要显示激活状态 +- **THEN** 系统 SHALL 提供 `.nav-item--active` 修饰符类 + +### Requirement: 详情页头部组件 +组件库 SHALL 提供详情页头部布局组件。 + +#### Scenario: 详情头部布局 +- **WHEN** 详情页需要展示标题、图标、标签、统计 +- **THEN** 系统 SHALL 提供 `.detail-header` 类，替换内联样式 `display: flex; gap: 20px; align-items: flex-start` + +#### Scenario: 详情图标 +- **WHEN** 详情头部需要大图标 +- **THEN** 系统 SHALL 提供 `.detail-header__icon` 元素类 + +#### Scenario: 详情标签组 +- **WHEN** 详情头部需要展示标签 +- **THEN** 系统 SHALL 提供 `.detail-tags` 类，替换内联样式 + +#### Scenario: 详情统计 +- **WHEN** 详情头部需要展示统计信息 +- **THEN** 系统 SHALL 提供 `.detail-stats` 类，替换内联样式 + +### Requirement: 文件列表组件 +组件库 SHALL 提供文件列表展示组件。 + +#### Scenario: 文件列表项 +- **WHEN** 详情页需要展示文件列表 +- **THEN** 系统 SHALL 提供 `.file-list__item` 类，包含图标、文件名、文件大小布局 + +#### Scenario: 文件图标 +- **WHEN** 文件项需要类型图标 +- **THEN** 系统 SHALL 提供 `.file-list__icon` 元素类 + +#### Scenario: 文件信息 +- **WHEN** 文件项需要展示名称和大小 +- **THEN** 系统 SHALL 提供 `.file-list__info`、`.file-list__name`、`.file-list__size` 元素类 + +### Requirement: 版本列表组件 +组件库 SHALL 提供版本历史列表组件。 + +#### Scenario: 版本列表项 +- **WHEN** 详情页需要展示版本历史 +- **THEN** 系统 SHALL 提供 `.version-list__item` 类，包含版本号、描述、日期布局 + +#### Scenario: 版本标签 +- **WHEN** 需要标记当前版本 +- **THEN** 系统 SHALL 提供 `.version-list__tag` 和 `.version-list__tag--current` 类 + +### Requirement: 返回按钮组件 +组件库 SHALL 提供统一的返回按钮样式。 + +#### Scenario: 返回按钮 +- **WHEN** 详情页需要返回按钮 +- **THEN** 系统 SHALL 提供 `.back-btn` 类，替换内联样式 `display: inline-flex; align-items: center; gap: 6px; color: #3B82F6` + +### Requirement: 表单提示组件 +组件库 SHALL 提供表单辅助提示样式。 + +#### Scenario: 表单提示文字 +- **WHEN** 表单字段需要辅助说明 +- **THEN** 系统 SHALL 提供 `.form__hint` 类，替换内联样式 `font-size: 12px; color: #6B7280; margin-top: 4px` + +### Requirement: 密码输入框组件 +组件库 SHALL 提供密码输入框组件，支持显示/隐藏切换功能。 + +#### Scenario: 基础密码输入框 +- **WHEN** 表单需要密码输入 +- **THEN** 系统 SHALL 提供 `type="password"` 的 `.form__input` 输入框 + +#### Scenario: 带切换的密码输入框 +- **WHEN** 表单需要密码输入并支持显示/隐藏切换 +- **THEN** 系统 SHALL 提供 `.password-input` 容器，包含 `.form__input` 和 `.password-toggle` 按钮 + +#### Scenario: 切换按钮样式 +- **WHEN** 用户需要切换密码可见性 +- **THEN** 系统 SHALL 提供 `.password-toggle` 类，定位在输入框右侧，包含眼睛图标 + +#### Scenario: 输入框错误状态 +- **WHEN** 密码验证失败 +- **THEN** 系统 SHALL 提供 `.form__input--error` 修饰符，输入框边框变红，并通过 `.form__error` 显示错误提示 + +### Requirement: 类名规范检查 +组件库 SHALL 确保所有样式类名符合 BEM 规范，无分散的内联样式。 + +#### Scenario: BEM 命名验证 +- **WHEN** 检查组件类名 +- **THEN** 所有类名 SHALL 遵循 `.block__element--modifier` 格式 + +#### Scenario: 分散样式收拢 +- **WHEN** 检查 HTML/JSX 文件 +- **THEN** 所有样式定义 SHALL 集中在样式文件中，无独立 `