218 lines
10 KiB
Markdown
218 lines
10 KiB
Markdown
---
|
||
name: DCalc frontend-ui
|
||
description: DNF 客户端质感的紧凑型双主题 Vue 组件系统
|
||
colors:
|
||
canvas-deep: "#050505"
|
||
panel-charcoal: "#131515"
|
||
row-graphite: "#1f1f1e"
|
||
title-steel: "#415272"
|
||
control-navy: "#1a2b4e"
|
||
border-brass: "#504029"
|
||
text-primary: "#f6f8f4"
|
||
text-secondary: "#d6d3c6"
|
||
text-muted: "#a7a396"
|
||
selected-gold: "#daa41d"
|
||
focus-cyan: "#4ba7d3"
|
||
danger-readable: "#ef8883"
|
||
midnight-canvas: "#080b12"
|
||
midnight-panel: "#111827"
|
||
midnight-accent: "#315c97"
|
||
typography:
|
||
body:
|
||
fontFamily: "dcalc, SimSun, serif"
|
||
fontSize: "12px"
|
||
fontWeight: 400
|
||
lineHeight: 1.4
|
||
control:
|
||
fontFamily: "dcalc, SimSun, serif"
|
||
fontSize: "13px"
|
||
fontWeight: 400
|
||
lineHeight: 1
|
||
catalog-title:
|
||
fontFamily: "Segoe UI, Microsoft YaHei, sans-serif"
|
||
fontSize: "clamp(24px, 2vw, 30px)"
|
||
fontWeight: 650
|
||
lineHeight: 1.1
|
||
rounded:
|
||
sm: "2px"
|
||
md: "2px"
|
||
lg: "2px"
|
||
spacing:
|
||
compact: "4px"
|
||
sm: "7px"
|
||
md: "10px"
|
||
lg: "14px"
|
||
components:
|
||
control-default:
|
||
backgroundColor: "{colors.control-navy}"
|
||
textColor: "{colors.text-primary}"
|
||
rounded: "{rounded.sm}"
|
||
height: "30px"
|
||
padding: "0 14px"
|
||
control-compact:
|
||
backgroundColor: "{colors.control-navy}"
|
||
textColor: "{colors.text-secondary}"
|
||
rounded: "{rounded.sm}"
|
||
height: "24px"
|
||
padding: "0 10px"
|
||
data-row:
|
||
backgroundColor: "{colors.row-graphite}"
|
||
textColor: "{colors.text-secondary}"
|
||
rounded: "{rounded.sm}"
|
||
height: "38px"
|
||
---
|
||
|
||
# Design System: DCalc frontend-ui
|
||
|
||
## Overview
|
||
|
||
**Creative North Star: "游戏内的精密计算台"**
|
||
|
||
当前系统不是通用 SaaS 皮肤，而是一套面向 DNF 密集配置与结果比对的操作界面。视觉语言来自游戏客户端：深黑工作区、蓝黑控件、黄铜边缘、像素素材和高密度数据。装饰必须服务于状态识别，不能遮盖数值、品质和选择关系。
|
||
|
||
`dcalc` 与 `midnight` 共用同一组件和 `--ui-*` 语义契约。经典主题保留黄铜与金色强调，Midnight 主题转为冷蓝层级；组件禁止按主题名分支。
|
||
|
||
**Key Characteristics:**
|
||
|
||
- 紧凑、像素对齐、数据优先。
|
||
- 近方形轮廓与一像素分层边缘。
|
||
- 品质色、选择色、焦点色和状态色职责分离。
|
||
- 原始位图素材与 CSS 构造图形并存，但不使用近似 emoji 或随意替代图标。
|
||
- 组件目录是可交互回归面，不是静态样例墙。
|
||
|
||
## Colors
|
||
|
||
经典 DCalc 使用暖金和黄铜在近黑表面上建立层级，Midnight 使用冷蓝映射相同语义。
|
||
|
||
### Primary
|
||
|
||
- **控制台深蓝：**用于主控件静止态与可操作区域，保持沉稳，不扩散成大面积装饰。
|
||
- **选中金：**只表达已选内容和关键数值，不兼任键盘焦点。
|
||
- **焦点青：**只表达 focus-visible、输入聚焦和可访问性定位。
|
||
|
||
### Secondary
|
||
|
||
- **黄铜边缘：**用于经典主题中的边框、分隔和像素层次。
|
||
- **午夜蓝：**用于第二主题的激活面、浮层和控件状态，保持与经典主题相同的信息结构。
|
||
|
||
### Tertiary
|
||
|
||
- **可读危险色：**用于深色表面上的失败与危险文本；破坏性按钮表面继续使用独立的 destructive Token。
|
||
|
||
### Neutral
|
||
|
||
- **深黑画布：**页面最底层背景。
|
||
- **炭黑面板：**承载组件组、表格和对话框内容。
|
||
- **主文本 / 次文本 / 弱文本：**形成三级阅读层级；弱文本仍需达到普通文本对比度要求。
|
||
|
||
### Named Rules
|
||
|
||
**The Semantic Boundary Rule.** 组件只消费 `--ui-*` 语义 Token；`--dcalc-*` 只保留物理色和品质数据语义。
|
||
|
||
**The Rarity Is Data Rule.** 品质颜色代表物品数据，不得用于普通按钮、装饰线或营销强调。
|
||
|
||
## Typography
|
||
|
||
**Display Font:** Segoe UI（Microsoft YaHei 回退，仅用于组件目录标题）
|
||
**Body Font:** dcalc（SimSun 回退）
|
||
**Label/Mono Font:** Consolas（仅用于编号、索引和测量信息）
|
||
|
||
**Character:** 业务界面以 DCalc 像素字体保持游戏内质感；目录页标题使用清晰的系统无衬线字体承担文档层级。等宽字体只服务于技术索引与数值，不作为“科技感”装饰。
|
||
|
||
### Hierarchy
|
||
|
||
- **Catalog title：**中高字重、流式 24–30px，只用于目录页主标题。
|
||
- **Panel heading：**由 46px 标题栏承载，文本层级高于内容但不追求超大字号。
|
||
- **Control：**13px/1，适用于默认高度控件和密集输入。
|
||
- **Body：**12px/1.4，适用于说明、数据标签和表格内容。
|
||
- **Micro label：**原则上不低于 10px；低于该值只允许用于已有像素图形内部且同时提供可访问名称的装饰性字形。
|
||
|
||
### Named Rules
|
||
|
||
**The Readable Density Rule.** 紧凑来自间距和布局，不以牺牲正文可读性换取密度。
|
||
|
||
## Layout
|
||
|
||
页面采用流式网格承载组件组合，像素素材、1px 边框、控件高度和纹理对齐保留物理尺寸。默认控件高度分为 24px、30px 和 44px；页面 gutter、列宽和面板间距使用 `clamp()` 与 `minmax(0, 1fr)` 响应变化。
|
||
|
||
桌面允许多列高密度工作区；900px 以下将主要双列组合收为单列；520px 以下优先保证独立操作目标和可读顺序。宽表格与状态矩阵使用组件内部横向滚动，页面本身不得出现横向溢出。
|
||
|
||
应用根到路由页的 Flex/Grid 高度链必须保留 `min-height: 0`，每个页面只有一个主要纵向滚动所有者。Portal 内容不能进入会裁剪它的局部容器。
|
||
|
||
### Calculation Workspace
|
||
|
||
角色计算页遵循“配置 → 结果”的连续任务路径。901px 及以上使用两列工作区：左列承载装备、技能或打造配置，右列结果占满剩余空间；角色背景只作为氛围层，不得用空白结构列把输入和结果分隔到视口两端。全局计算开关与导入操作放在顶部导航工具区，避免为少量操作保留整条底栏。
|
||
|
||
900px 及以下改为单一纵向滚动流：配置在前、结果在后，配置面板按路由使用有界宽度并居中。结果概览与技能表依次排列且都保留独立内部滚动；页面宽度不得超过视口。伤害表使用容器宽度而非浏览器宽度决定信息密度：容器达到 620px 时直接展示技能、CD、次数、秒伤、总伤害和占比，窄容器保留技能、次数和占比三项核心列。
|
||
|
||
## Elevation & Depth
|
||
|
||
系统以色调分层、内描边和一像素边缘为主，阴影只用于浮层、选中反馈和必要的空间分离。普通面板不叠加“边框加大面积柔光”的通用卡片效果。
|
||
|
||
### Shadow Vocabulary
|
||
|
||
- **Control inset：**一像素内高光，表达游戏控件的凹凸边缘。
|
||
- **Popup lift：**带向下偏移的柔和阴影，仅用于 Select、Popover、Menu 与 Tooltip 等浮层。
|
||
- **Selected glow：**低范围辉光，只跟随选中或焦点状态，不作为静态装饰。
|
||
|
||
### Named Rules
|
||
|
||
**The State Earns Depth Rule.** 深度必须对应浮层、焦点、悬停或选择状态；静止内容默认依靠色调和边缘分层。
|
||
|
||
## Shapes
|
||
|
||
组件轮廓以 2px 近方角为默认，配合一像素边框、内描边和少量 `clip-path` 斜切形成游戏客户端的机械感。圆形仅用于单选点、滑块拇指和评分胶囊等具有明确交互语义的部件；普通卡片与面板不使用大圆角或药丸轮廓。
|
||
|
||
## Components
|
||
|
||
### Buttons
|
||
|
||
- **Shape:** 近方角、30px 默认高度，紧凑与大型尺寸分别为 24px 和 44px。
|
||
- **Primary:** 蓝黑渐变表面、黄铜边缘和高对比文本；变体由 CVA 管理。
|
||
- **Hover / Focus:** 悬停提升边缘与表面亮度；focus-visible 使用语义焦点色；按下只产生 1px 位移。
|
||
- **Disabled:** 同时移除可操作暗示并保留可辨识标签，不使用不可读文字伪装禁用。
|
||
|
||
### Cards / Containers
|
||
|
||
- **Corner Style:** 2px 近方角或像素斜切。
|
||
- **Background:** 画布、面板、行三层深色表面。
|
||
- **Shadow Strategy:** 默认平面分层，浮层和状态反馈才使用阴影。
|
||
- **Border:** 1px 语义边缘；避免与宽柔光重复表达同一层级。
|
||
- **Internal Padding:** 以 4、7、10、14px 为主要密度节奏，具体像素素材可保留源尺寸。
|
||
|
||
### Inputs / Fields
|
||
|
||
- **Style:** 30px 默认高度、深色内凹表面、1px 边框与紧凑内边距。
|
||
- **Focus:** 边缘切换到 focus Token，并增加一像素可见外沿。
|
||
- **Error / Disabled:** 错误和不可用分别使用独立语义前景；不可用信息仍需可读。
|
||
|
||
### Navigation
|
||
|
||
导航使用与内容一致的像素字体和表面层级。当前项使用 selected 语义，键盘位置使用 ring 语义；两者不可合并。窄屏允许重新编排，但不改变路由与业务层级。
|
||
|
||
### Data and Selection Components
|
||
|
||
表格、树、级联、商店行和物品槽是系统的签名组件。它们保留品质色、像素素材、紧凑行高与明确的 selected/disabled 状态。含有次级操作的可选行必须把“选择”和“查看”实现为两个同级可聚焦操作，禁止在 `option` 内嵌套按钮。
|
||
|
||
### Portal Components
|
||
|
||
Select、Autocomplete、Tooltip、DropdownMenu、Popover 与 Dialog 通过 Reka UI 保留键盘和焦点语义。普通浮层使用受控层级 80，Tooltip 使用更高但有界的层级；必须验证四边碰撞、Escape 关闭和焦点恢复。
|
||
|
||
## Do's and Don'ts
|
||
|
||
### Do:
|
||
|
||
- **Do** 使用 Primitive → Semantic 两层 Token，并用同一组件代码验证 DCalc 与 Midnight。
|
||
- **Do** 保留真实 PNG、字体、光标、品质色和像素对齐尺寸。
|
||
- **Do** 在组件目录展示默认、悬停、按下、焦点、禁用、选中、打开和 reduced-motion 状态。
|
||
- **Do** 为图形按钮、评分项和复合行操作提供独立的可读名称与焦点位置。
|
||
- **Do** 把连续几何变化交给 CSS Variable 或 transform，把有限变体交给 CVA。
|
||
|
||
### Don't:
|
||
|
||
- **Don't** 在通用组件中请求接口、读取业务 Store、绑定路由或加入单页面兼容逻辑。
|
||
- **Don't** 按主题名分支组件样式，也不要在组件中直接使用主题专属装饰色。
|
||
- **Don't** 用 emoji、近似图标、大圆角卡片或通用 SaaS 模板替代 DNF 视觉事实。
|
||
- **Don't** 通过缩小正文、隐藏焦点或使用低对比禁用色来换取紧凑感。
|
||
- **Don't** 用构建成功代替浏览器验证；Portal、滚动、键盘、主题和窄屏都必须实际操作。
|