# Color ## Description Color 模块提供围绕颜色值（color value）的构造、转换、解析、序列化、分析与派生能力，用于在明确颜色空间拓扑之上建立稳定、可解释且可扩展的公共颜色语义。 这个模块不把某一种显示层颜色表示当作事实核心，而是以 `XYZ` 作为唯一绝对参考层，再从 `XYZ` 发散出不同颜色空间支线。当前已稳定落地的是 `RGB` 支线，其中 `Linear RGB` 是计算核心，`sRGB` 是显示与字符串语义层，`HSL` 与 `HSV` 是交互语义层。 ## For Understanding 理解 Color 模块时，最重要的不是记住有哪些颜色函数，而是先接受它的颜色空间拓扑。这个模块要解决的问题不是“让任意颜色表示之间都能方便互转”，而是“让颜色值沿着清楚、合法、长期稳定的路径被构造、移动和分析”。 当前拓扑的核心结论如下： - `XYZ` 是唯一绝对核心，不需要额外加 `CIE` 前缀来区分语义。 - `RGB` 是从 `XYZ` 发散出去的一条独立支线。 - `Linear RGB` 是 `RGB` 支线的计算核心。 - `sRGB` 是显示层与字符串层的核心表示。 - `HSL` 与 `HSV` 是从 `sRGB` 派生出的交互层表示。 在当前阶段，合法主链应被理解为： - `XYZ <-> Linear RGB` - `Linear RGB <-> sRGB` - `sRGB <-> HSL` - `sRGB <-> HSV` 这套拓扑不是实现细节，而是模块语义的一部分。它意味着不应把跨级捷径视为独立公共能力，也不应为了方便而让解析、序列化、分析或派生偷偷依赖未声明的跨级路径。未来如果扩展 `Lab` 等其它支线，也必须继续直接从 `XYZ` 出发，而不是附着在现有 `RGB` 支线上。 ## For Using 当应用需要围绕颜色值本身工作，并且希望这些工作建立在明确颜色空间语义之上时，可以使用这个模块，而不是在业务代码里混合使用一批语义不清的颜色工具。 当前公共能力大致可以按以下几类理解： - 颜色值类型与构造：用于显式创建 `XYZ`、`Linear RGB`、`sRGB`、`HSL`、`HSV` 这些不同层级的颜色值。 - 合法颜色转换：用于沿着颜色空间树的合法边移动，例如 `XYZ` 与 `Linear RGB` 之间，或 `sRGB` 与 `HSL`、`HSV` 之间。 - 字符串解析与序列化：用于在十六进制颜色、`rgb(...)`、`rgba(...)`、`hsl(...)`、`hsla(...)`、`hsv(...)`、`hsva(...)` 等外部格式与其对应颜色值之间转换。 - 颜色分析：用于相对亮度、三刺激总量、`xy` 色度坐标、对比度、可读文本颜色选择等分析场景。 - 颜色派生：用于线性混色、透明度合成、fade、tint、shade、tone、lighten、darken 等建立在清楚层级上的稳定派生。 - 显示层归一化特例：如果你的目标就是把多种颜色字符串归一化为最终显示层颜色，可以使用专门返回 `sRGB` 的入口；这种入口属于有意接受语义折叠的特例，而不是默认解析原则。 这个模块不适合承载主题系统、设计令牌（design token）管理、品牌配色规则、组件语义色映射或其它与具体产品设计体系强耦合的内容。这些能力应建立在 Color 之上，而不是写入 Color 本身。 ## For Contributing 贡献 Color 模块时，首要任务不是添加一个“颜色工具”，而是判断该能力在颜色空间树上的位置是否清楚、依赖哪条合法路径、以及它是否值得成为长期公共承诺。只要这三个问题里有一个回答不清，它通常就还不适合进入这个模块。 在扩展时，应优先遵守以下边界： - `XYZ` 是唯一绝对核心，不需要再引入其它并列的绝对参考层。 - 任何新能力都应能在颜色空间树上找到清楚位置，而不是以便捷函数的形式漂浮在树外。 - 不要把跨级转换捷径公开成独立 API，即使它内部只是串联了多步合法转换。 - 解析、序列化、分析与派生也必须服从颜色空间拓扑，而不是只对转换函数保持克制。 - 当前稳定承诺的是 `XYZ` 核心层与 `RGB` 支线；未来方向可以说明，但不能在文档和导出层面写成既有事实。 ### JSDoc 注释格式要求 - 每个公开导出的目标（类型、函数、变量、类等）都应包含 JSDoc 注释，让人在不跳转实现的情况下就能理解用途。 - JSDoc 注释第一行应为清晰且简洁的描述，该描述优先使用中文（英文也可以）。 - 如果描述后还有其他内容，应在描述后加一个空行。 - 如果有示例，应使用 `@example` 标签，后接三重反引号代码块（不带语言标识）。 - 如果有示例，应包含多个场景，展示不同用法，尤其要覆盖常见组合方式或边界输入。 - 如果有示例，应使用注释格式说明每个场景：`// Expect: `。 - 如果有示例，应将结果赋值给 `example1`、`example2` 之类的变量，以保持示例易读。 - 如果有示例，`// Expect: ` 应该位于 `example1`、`example2` 之前，以保持示例的逻辑清晰。 - 如果有示例，应优先使用确定性示例；避免断言精确的随机输出。 - 如果函数返回结构化字符串，应展示其预期格式特征。 - 如果有参考资料，应将 `@see` 放在 `@example` 代码块之后，并用一个空行分隔。 ### 实现规范要求 - 不同程序元素之间使用一个空行分隔，保持结构清楚。这里的程序元素，通常指函数、类型、常量，以及直接服务于它们的辅助元素。 - 某程序元素独占的辅助元素与该程序元素本身视为一个整体，不要在它们之间添加空行。 - 程序元素的辅助元素应该放置在该程序元素的上方，以保持阅读时的逻辑顺序。 - 若辅助元素被多个程序元素共享，则应将其视为独立的程序元素，放在这些程序元素中第一个相关目标的上方，并与后续程序元素之间保留一个空行。 - 辅助元素也应该像其它程序元素一样，保持清晰的命名和适当的注释，以便在需要阅读实现细节时能够快速理解它们的作用和使用方式。 - 辅助元素的命名必须以前缀 `internal` 开头（或 `Internal`，大小写不敏感）。 - 辅助元素永远不要公开导出。 - 被模块内多个不同文件中的程序元素共享的辅助元素，应该放在一个单独的文件中，例如 `./src/color/internal.ts`。 - 模块内可以包含子模块。Color 已经具有 `xyz` 与 `rgb` 这类稳定子问题域，后续扩展也应继续沿语义分层组织。 - 子模块包含多个文件时，应该为其单独创建子文件夹，并为其创建单独的 Barrel 文件；父模块的 Barrel 文件再重导出子模块的 Barrel 文件。 - 子模块不需要有自己的 `README.md`。 - 子模块可以有自己的 `internal.ts` 文件，多个子模块共享的辅助元素应该放在父模块的 `internal.ts` 文件中，单个子模块共享的辅助元素应该放在该子模块的 `internal.ts` 文件中。 - 对模块依赖关系的要求（通常是不循环依赖或不反向依赖）与对 DRY 的要求可能产生冲突。此时，若复用的代码数量不大，可以适当牺牲 DRY，复制粘贴并保留必要的注释说明；若复用的代码数量较大，则可以将其抽象到新的文件或子模块中，如 `common.ts`，并在需要的地方导入使用。 - 所有转换、解析、序列化、分析与派生实现都应服从颜色空间树，不允许通过跨级公式或包装函数引入语义捷径。 ### 导出策略要求 - 保持内部辅助项和内部符号为私有，不要让外部接入依赖临时性的内部结构。 - 每个模块都应有一个用于重导出所有公共 API 的 Barrel 文件。 - Barrel 文件应命名为 `index.ts`，放在模块目录根部，并且所有公共 API 都应从该文件导出。 - 新增公共能力时，应优先检查它是否表达稳定、清楚且值得长期维护的颜色语义，而不是某段实现细节的便捷暴露；仅在确认需要长期对外承诺时再加入 Barrel 导出。 ### 测试要求 - 若程序元素是函数，则只为该函数编写一个测试，如果该函数需要测试多个用例，应放在同一个测试中。 - 若程序元素是类，则至少要为该类的每一个方法编写一个测试，如果该方法需要测试多个用例，应放在同一个测试中。 - 若程序元素是类，除了为该类的每一个方法编写至少一个测试之外，还可以为该类编写任意多个测试，以覆盖该类的不同使用场景或边界情况。 - 若编写测试时需要用到辅助元素（Mock 或 Spy 等），可以在测试文件中直接定义这些辅助元素。若辅助元素较为简单，则可以直接放在每一个测试内部，优先保证每个测试的独立性，而不是追求极致 DRY；若辅助元素较为复杂或需要在多个测试中复用，则可以放在测试文件顶部，供该测试文件中的所有测试使用。 - 测试顺序应与源文件中被测试目标的原始顺序保持一致。 - 若该模块不需要测试，必须在说明文件中明确说明该模块不需要测试，并说明理由。一般来说，只有在该模块没有可执行的公共函数、只承载类型层表达，或其语义已被上层模块的测试完整覆盖且重复测试几乎不再带来额外价值时，才适合这样处理。 - 模块的单元测试文件目录是 `./tests/unit/color`，若模块包含子模块，则子模块的单元测试文件目录为 `./tests/unit/color/`。 - 对颜色转换，应重点验证每一条合法边本身，而不是依赖跨级捷径拼结果。 - 对颜色解析、序列化、分析与派生，应重点验证它们所依赖的颜色层级是否明确，以及结果是否稳定、可解释。