19 · 设计变量、配置与魔法数值

适用：统一调整成本高、同一个限制出现多个版本、计时器与动画不同步，或代码里出现无法解释的数值。目标是让数值有含义、单位、来源和作用域。

VAL-01 · 数值按所有者分类

数值类型	例子	来源与放置位置
基础设计尺度	间距阶梯、字重、圆角	设计系统基础变量
语义设计变量	控件高度、帮助文字、焦点宽度	基础变量的语义映射
组件局部变量	画布工具条密度、阅读主栏宽度	组件或页面模式作用域
交互策略	搜索延迟、长按阈值、重试间隔	行为策略模块，写明单位
业务限制	名称长度、附件数量、授权范围	领域规则或服务端能力，不以 CSS 决定
环境与服务配置	API 地址、轮询能力、功能开放	环境或服务配置，按项目发布规则管理
算法与素材几何	对比度公式系数、SVG 坐标	原算法或素材中，解释出处与用途

0、网格的 1fr、边框的局部几何并不天然是魔法数。不要把所有字面量包装成 NUMBER_16；应处理无法解释或需要共同变化的数值。

VAL-02 · 命名表达语义、单位与范围

.product-ui {
  --space-3: .75rem;
  --space-4: 1rem;
  --font-body-size: 1rem;
  --font-help-size: .875rem;
  --control-min-block-size: 2.75rem;
  --field-inline-gap: var(--space-3);
}
.field-help { font-size: var(--font-help-size); }

--field-inline-gap 比 --gap-12 更能说明影响。需要调密度时映射语义变量；只改变品牌色，不应该连同字段长度一起改变。

const projectNamePolicy = { maxGraphemes: 60 };
const searchPolicy = { debounceMs: 250, minimumQueryGraphemes: 1 };

数值是示例，不是通用最佳值。saveDelay 没说明单位；limit 没说明限制什么，应避免。模拟请求延迟与生产超时时间分别管理。

VAL-03 · 同一规则贯穿提示、校验与测试

名称长度限制只能有一个权威来源，字段提示、计数器、校验与边界测试引用它。前后端需要一致的计量单位和规则版本；后端仍做最终验证，不能把客户端配置当成授权。

服务端返回能力时，界面读取经过验证的能力描述；加载中和能力变化要有策略。不要出现提示 60、浏览器 maxlength 40、提交校验 80 的三个版本。

VAL-04 · 不要把不同语义绑在一起

搜索防抖和动画时长可能恰好都是 200ms，但它们解决不同问题。更改动画不应让搜索变慢。全局 MAX_TEXT_LENGTH 也不能同时控制用户名、文章标题和退款原因。

共享值用语义引用表达；相同字面值可以属于不同规则。反过来，一个业务限制不能仅因为在两个文件中出现就被视为两个独立值。

VAL-05 · CSS 与 JavaScript 各有边界

字号、间距、表面颜色优先由 CSS 变量和布局控制，避免在每次窗口变化时由 JS 重算所有像素。JS 中的手势阈值、排队与超时归行为策略。动画时间需要由 JS 控制时，可从同一配置向局部 CSS 变量输出带单位的值。

普通 CSS 自定义属性不能直接替代媒体查询中的断点。需要统一断点时使用构建期变量、生成工具或有文档依据的共享定义，不能写无效的 @media (width < var(--breakpoint)) 后声称已抽象。

动态尺寸优先由内容、容器和 CSS 布局决定，确需测量时明确观察对象、节流策略和销毁。不要用固定超时猜测字体加载、键盘弹出或布局完成。

VAL-06 · 修改数值时验证实际影响

为每个公共变量记录用途、默认值、单位、覆盖方式和影响页面。修改后检查正常、长内容、大字号、明暗与特殊变体，不能以“只改了一个数字”免除回归。

检查候选裸值时区分设计遗漏、合理局部值与算法常量。验收目标是可理解、可调整且不误伤个例，不是把数值搜索结果清零。