DiAL/openspec/specs/css-utility-classes/spec.md

Purpose

定义 styles.css 中集中管理的前端样式工具类和 CSS 自定义属性，供 TDesign 组件之外的自定义组件（StatusDot、StatusBar 等）引用。

Requirements

Requirement: 状态色 CSS 类

styles.css SHALL 定义状态指示相关的 CSS 类，颜色使用 TDesign tokens。

Scenario: StatusDot 颜色类

• WHEN StatusDot 组件渲染
• THEN 组件 SHALL 使用 .status-dot 基础类 + .status-dot--up（background: --td-success-color）或 .status-dot--down（background: --td-error-color）修饰类，不使用内联 style

Scenario: StatusDot 发光阴影

• WHEN StatusDot 组件渲染
• THEN .status-dot--up SHALL 定义 box-shadow 使用 --td-success-color，.status-dot--down SHALL 定义 box-shadow 使用 --td-error-color

Scenario: StatusBar 色块类

• WHEN StatusBar 组件渲染色块
• THEN 组件 SHALL 使用 .status-bar-block 基础类 + .status-bar-block--up（background: --td-success-color）、.status-bar-block--down（background: --td-error-color）或 .status-bar-block--empty（background: --td-bg-color-component-disabled）修饰类，不使用内联 style

Requirement: 可用率色阶 CSS 变量

styles.css SHALL 定义 10 级可用率色阶 CSS 自定义属性，使用项目自定义色值。

Scenario: 色阶变量定义

• WHEN 可用率进度条渲染
• THEN 色阶 SHALL 通过 CSS 自定义属性 --avail-0 到 --avail-9 定义，值为项目自定义色值（#d54941 到 #3dba60）

Scenario: 色阶渐变方向

• WHEN 色阶变量被引用
• THEN 色阶 SHALL 从红色（0-30%）经橙色（30-60%）过渡到绿色（60-100%）

Requirement: 辅助工具类

styles.css SHALL 定义前端组件复用的工具类，包含页面布局相关类。

Scenario: 文本禁用色类

• WHEN 延迟列无数据需要显示占位符
• THEN 组件 SHALL 使用 .text-disabled 类（color: --td-text-color-disabled）

Scenario: 等宽数字类

• WHEN 数值需要等宽显示
• THEN 组件 SHALL 使用 .tabular-nums 类（font-variant-numeric: tabular-nums）

Scenario: 延迟色值类

• WHEN 延迟数值渲染
• THEN 组件 SHALL 使用 .latency-ok、.latency-warn 或 .latency-error 类

Scenario: 延迟值容器类

• WHEN 延迟数值需要固定宽度对齐
• THEN 组件 SHALL 使用 .latency-value 类（display: inline-block; min-width: 7ch; white-space: nowrap）

Scenario: 全宽布局类

• WHEN 组件需要占满父容器宽度
• THEN 组件 SHALL 使用 .full-width 类（width: 100%）

Scenario: 可点击表格类

• WHEN PrimaryTable 行支持点击交互
• THEN 表格 SHALL 使用 .clickable-table 类（cursor: pointer）

Scenario: Tab 面板内边距类

• WHEN Drawer 内 Tabs 面板需要内边距
• THEN TabPanel SHALL 使用 className="tab-panel-padded" prop 传入类名

Scenario: 内容区居中类

• WHEN Dashboard 内容区需要居中且限制最大宽度
• THEN 内容区 SHALL 使用 .dashboard-content 类（max-width: 1400px; margin: 0 auto; padding: var(--td-comp-paddingTB-xl) var(--td-comp-paddingLR-xl)）

Scenario: 页面背景色

• WHEN Dashboard 页面渲染
• THEN .dashboard 类 SHALL 设置 background: var(--td-bg-color-page)，min-height: 100vh，width: 100%

Scenario: 品牌标识类

• WHEN HeadMenu logo 区域渲染品牌名和副标题
• THEN 品牌 SHALL 使用 .dashboard-brand 类（display: inline-flex; align-items: baseline; gap: var(--td-comp-margin-s)），品牌名 SHALL 使用 .dashboard-logo 类（font-size: calc(var(--td-font-size-title-large) + 6px); font-weight: 700），副标题 SHALL 使用 .dashboard-subtitle 类（font-size: var(--td-font-size-body-medium); color: var(--td-text-color-secondary)）

Scenario: Header 右侧操作区类

• WHEN HeadMenu operations 区域渲染主题模式选择器、刷新频率选择器和倒计时/按钮
• THEN 容器 SHALL 使用 .dashboard-header-controls 类（display: inline-flex; align-items: center; gap: var(--td-comp-margin-s); margin-right: var(--td-comp-margin-xxl)）

Scenario: Header 右侧操作区单行布局

• WHEN Header 右侧操作区渲染
• THEN .dashboard-header-controls SHALL 保持桌面单行水平布局，不为该区域新增窄屏换行或收纳规则

Scenario: 倒计时文本类

• WHEN 倒计时文本或刷新按钮渲染
• THEN 容器 SHALL 使用 .dashboard-countdown 类（display: inline-flex; align-items: center; font-variant-numeric: tabular-nums; min-width: 5ch），确保数字等宽且格式切换不抖动

Scenario: SummaryCard 居中类

• WHEN SummaryCards 内 Statistic 需要居中
• THEN Statistic 所在的 Col SHALL 使用 .summary-stat-col 类（text-align: center）

Scenario: SummaryCards 行间距类

• WHEN SummaryCards 容器需要与下方内容保持间距
• THEN 容器 SHALL 使用 .summary-cards-row 类（margin-bottom: var(--td-comp-margin-xl)）

Scenario: Drawer 时间控件单行类

• WHEN Drawer 时间选择器需要单行布局
• THEN 控件容器 SHALL 使用 .drawer-time-controls 类（display: flex; align-items: center; gap: var(--td-comp-margin-m); width: 100%），日期选择器 SHALL 使用 .drawer-date-range 类（flex: 1; min-width: 360px）

Scenario: Drawer 时间控件响应式

• WHEN 视口宽度 ≤ 768px
• THEN .drawer-time-controls SHALL 启用 flex-wrap，.drawer-date-range min-width 改为 100%

Scenario: 概览统计卡片类

• WHEN Drawer 概览统计区渲染
• THEN 统计卡片 SHALL 使用 .overview-stat-card 类（background: var(--td-bg-color-container-hover)），并使用 TDesign Statistic 组件自带的上下布局（title 在上、value 在下），通过 .summary-stat-col 类（text-align: center）实现内容居中。系统 SHALL NOT 使用已移除的 .overview-stat-item 和 .overview-stat-value 类。

Requirement: NumberFlow 倒计时样式类

styles.css SHALL 定义 NumberFlow 倒计时相关样式类，供 Header 倒计时组件使用。样式 SHALL 继承 TDesign 文本颜色或使用 TDesign CSS tokens，不得使用组件内联 style、硬编码色值、!important 或覆盖 TDesign 内部类名。

Scenario: 倒计时滚动容器类

• WHEN Header 自动刷新倒计时以 NumberFlow 形式渲染
• THEN 倒计时 SHALL 使用集中定义的滚动容器类，保持 inline-flex、baseline 对齐、nowrap 和 tabular-nums

Scenario: 倒计时数字类

• WHEN NumberFlow 数字渲染
• THEN 数字 SHALL 使用集中定义的数字类配置 line-height 和 NumberFlow mask CSS 变量，减少滚动边缘突兀感

Scenario: 倒计时单位类

• WHEN 分钟或秒单位文本渲染
• THEN 单位 SHALL 使用集中定义的单位类与数字保持基线对齐，并继承当前 TDesign 文本色

Scenario: 不使用内联样式

• WHEN RefreshCountdown 组件渲染 NumberFlow 倒计时
• THEN 组件 SHALL 通过 className 引用 styles.css 中的样式类，不得通过 React style prop 设置 NumberFlow 展示样式

Requirement: 异常行背景类

styles.css SHALL 定义 DOWN 行的背景色和左侧竖线，使用安全选择器且不使用 !important。

Scenario: DOWN 行背景色

• WHEN 表格行标记为 DOWN 状态
• THEN 行 SHALL 通过 .t-table tr.row-down 选择器获得浅红色背景

Scenario: DOWN 行左侧竖线

• WHEN 表格行标记为 DOWN 状态
• THEN 行 SHALL 通过 .t-table tr.row-down 选择器获得 border-left: 3px solid var(--td-error-color)

Scenario: DOWN 行 hover 状态

• WHEN 鼠标悬停在 DOWN 行上
• THEN 行背景 SHALL 通过 .t-table--hoverable tbody tr.row-down:hover 选择器显示 hover 状态色