Front-End-Checklist 实战指南用 property 注册 CSS 自定义属性实现动画插值与类型安全【免费下载链接】Front-End-Checklist The essential checklist for modern web development, for humans and AI agents项目地址: https://gitcode.com/gh_mirrors/fr/Front-End-ChecklistCSS 自定义属性custom properties默认只是字符串替换浏览器并不知道--brand-color是颜色、长度还是数字。Front-End-Checklist 的css-at-property规则规则文档Skill 定义教你用property和 Properties Values API 把自定义属性注册为带类型的真实值从而解锁渐变动画、类型化设计令牌与作用域隔离的主题系统。读完本文你将掌握property的完整语法、CSS.registerProperty()的 JS 等价用法以及如何通过 DevTools 验证注册与类型强制是否生效。背景自定义属性为什么动不起来CSS 自定义属性变量本质上是字符串替换。浏览器不知道--brand-color是颜色、长度还是数字这正是property与 Properties Values API 规范 存在的意义它们让引擎把自定义属性当作真实带类型的值来处理。在默认情况下未注册的自定义属性无法在 transition 或 animation 中被插值interpolate——它们会作为不透明的离散字符串直接跳变。注册一个属性等于告诉浏览器它需要的一切信息值类型、初始值、是否继承从而把自定义属性从字符串宏升级为一等公民的带类型值。这正是 Front-End-Checklist 将本规则归入css/design-tokens子类目、标记为priority: low、difficulty: advanced、预估耗时 30 分钟的原因——它是进阶特性但回报极高。最小注册示例property --property-name { syntax: color; /* 类型 —— 合法的 syntax 描述符见下文 */ initial-value: #000; /* 必填 —— 属性的默认值 */ inherits: true; /* 值是否会级联到子元素 */ }三个描述符缺一不可描述符作用取值要点syntax声明属性值的类型可用的 syntax 字符串见下一节initial-value属性的默认值只要syntax不是*就必须提供否则注册无效inherits是否向子元素级联true时子元素可读取父级值false时每个元素独立持有为什么重要从字符串宏到一等值注册property后浏览器终于有了足够的信息来在值之间平滑插值颜色、角度、长度等类型化值可以逐帧过渡校验令牌赋值给color属性赋一个px长度会变成可见的校验错误而不是静默失效干净地控制继承范围通过inherits: false阻止值向子树传播。这三个能力分别对应本规则在规则库中声明的关联规则见 css-at-property.mdx 的relatedRulescss-custom-propertiesproperty为自定义属性补充类型信息两条规则配合才能构成完整的令牌体系animation-performance注册后的属性允许部分类型走 GPU 加速的合成插值dark-mode-css用property注册的类型化颜色令牌保证暗色模式覆盖始终类型正确。syntax 描述符全表/* 基本类型 */ syntax: color; /* #hex、rgb()、hsl()、oklch()、颜色名 */ syntax: length; /* px、em、rem、vw 等 */ syntax: number; /* 无单位数字 */ syntax: integer; /* 仅整数 */ syntax: percentage; /* 0% 到 100% */ syntax: angle; /* deg、rad、turn */ syntax: time; /* s、ms */ syntax: length-percentage; /* 长度或百分比 */ /* 复合类型 */ syntax: color; /* 一个或多个空格分隔的颜色 */ syntax: length#; /* 一个或多个逗号分隔的长度 */ /* 通用兜底 —— 行为等同于未注册属性 */ syntax: *;选择原则能用具体类型就不用*。只有当你确实需要任何值例如动态生成的内容时才使用*兜底——它的行为与未注册属性完全一致无法触发插值与类型校验。实战一用自定义属性动画化渐变没有property时渐变停靠点无法动画因为浏览器把整个渐变当作不透明字符串处理/* ❌ 未注册 property —— 动画在离散值之间跳变 */ .card { --gradient-angle: 135deg; background: linear-gradient(var(--gradient-angle), #667eea, #764ba2); transition: --gradient-angle 0.6s ease; /* 无效 —— 字符串过渡 */ } .card:hover { --gradient-angle: 225deg; }注册为angle类型后角度值被平滑插值/* ✅ 注册 property —— 角度平滑过渡 */ property --gradient-angle { syntax: angle; initial-value: 135deg; inherits: false; } .card { background: linear-gradient(var(--gradient-angle), #667eea, #764ba2); transition: --gradient-angle 0.6s ease; /* 平滑动画 */ } .card:hover { --gradient-angle: 225deg; }核心差异在注册那一行浏览器现在知道--gradient-angle是角度可以按度数逐帧计算中间值而不是在两个整串之间跳变。实战二动画化颜色令牌色相轮转property --accent-hue { syntax: number; initial-value: 220; inherits: true; /* 子元素继承动画中的中间值 */ } :root { --accent-hue: 220; --accent: oklch(60% 0.2 var(--accent-hue)); transition: --accent-hue 0.4s ease; } /* 在特定区块内把色相移向暖色 */ .section--warm:hover { --accent-hue: 30; /* 橙色 */ } /* 使用 --accent 的组件在过渡中看到被插值的色相 */ .button { background: var(--accent); }这个例子展示了inherits: true与transition的配合:root上的--accent-hue变化会沿继承链传播任何读取--accent的子组件都能在过渡过程中实时看到中间色相。注意这里--accent本身没有被注册——它只是派生变量真正被动画化的是注册过的--accent-hue。实战三类型化设计令牌用property注册设计令牌可以当场抓住错误给颜色属性赋一个长度DevTools 会显示校验错误而不是静默无效/* 注册颜色令牌并显式声明类型 */ property --color-brand-primary { syntax: color; initial-value: oklch(55% 0.25 265); inherits: true; } property --color-surface { syntax: color; initial-value: #ffffff; inherits: true; } /* 注册间距令牌 */ property --spacing-base { syntax: length; initial-value: 1rem; inherits: true; } /* 暗色模式覆盖 —— 类型仍然被强制校验 */ media (prefers-color-scheme: dark) { :root { --color-brand-primary: oklch(70% 0.25 265); --color-surface: #0f172a; } }类型化令牌让设计系统具备编译期检查的体验令牌的合法取值域被语法显式约束覆盖值如暗色模式也会被同等的类型校验把关。这与本仓库 dark-mode-css 规则的设计意图一脉相承——语义化颜色令牌 类型约束比dark-blue这类魔法值更可靠。实战四inherits: false实现组件级作用域令牌/* 一个可动画填充的进度条 */ property --progress-fill { syntax: percentage; initial-value: 0%; inherits: false; /* 每个 .progress-bar 持有自己的值 —— 互不共享 */ } .progress-bar { --progress-fill: 0%; background: linear-gradient( to right, var(--color-brand-primary) var(--progress-fill), var(--color-surface) var(--progress-fill) ); transition: --progress-fill 0.5s ease; } /* JS 按实例设置值 */ /* element.style.setProperty(--progress-fill, 72%) */inherits: false的价值在于隔离多个进度条实例各自持有独立的--progress-fill不会因继承相互污染。JS 通过element.style.setProperty()按实例写入值配合已注册的类型浏览器会在写入时校验其确实是一个百分比。注意syntax非*时initial-value必填只要指定了类型化的 syntax 描述符任何非*的值就必须同时提供initial-value。缺失时注册无效浏览器会把该属性当作未注册属性处理。这是初写property规则时最常见的静默失败来源——务必两者都写上。CSS.registerProperty()JavaScript 等价 API同样的注册在 JavaScript 中也可完成适合程序化生成令牌的场景// 等价于 property at-rule CSS.registerProperty({ name: --gradient-angle, syntax: angle, initialValue: 135deg, inherits: false, })注意参数名的差异CSS 中叫initial-valueJS API 中叫initialValue驼峰。工程实践建议静态令牌优先用 CSSproperty规则声明声明式、可被样式表工具链静态分析CSS.registerProperty()仅在需要动态计算令牌注册时使用例如运行时按用户配置生成主题令牌。浏览器支持截至 2024 年property已获所有主流浏览器支持Chrome / Edge 85Firefox 128Safari 16.4Firefox 是最晚落地该特性的主流浏览器128 版本因此在做跨浏览器验证时Firefox 应作为关键回归目标。本仓库的规则元数据css-at-property.mdx将 MDNproperty参考、web.dev 注册指南与 W3C Properties Values API 规范列为三类权威来源reference / implementation / standard可作为合法性判定的基线。验证步骤如何确认注册真正生效参照 MDNproperty参考与 Properties Values API 规范作为合法注册的判定基线按以下四步验证检查类型化解析打开 DevTools检查一个持有已注册自定义属性的元素。Computed Styles 面板应显示解析后的类型化值如oklch(55% 0.25 265)而不是原始变量字符串。检查平滑插值对已注册属性应用 CSS transition确认动画在值之间平滑过渡而不是离散跳变。检查类型强制故意向已注册属性赋一个错误类型的值例如把px长度赋给color属性确认浏览器忽略无效值并回退到initial-value——这证明类型校验真实生效。跨浏览器回归在 Firefox最晚支持property的主流浏览器128 版本中测试确认注册有效且动画行为一致。在 Front-End-Checklist 中的落地方式本规则在仓库中是一个可被 Agent 直接执行的 Skillskills/css-at-property/SKILL.md其元数据声明了四个标准操作可直接用于审查任意 CSS 文件Check审查文件中的 CSS 自定义属性找出所有用于 transition 或 animation 的属性——这些属性必须注册property才能正确动画Fix为用于过渡或动画的自定义属性补充property注册包含正确的 syntax 描述符、initial-value与合适的inherits值Explain解释property的工作原理、未注册属性为何无法动画、各 syntax 描述符的含义以及inherits如何控制级联行为Code Review检查所有引用自定义属性的 transition 与 animation标记两类问题——用于过渡/动画但未注册的属性以及缺少initial-value的注册。仓库的工具链也将本规则纳入了规则支持数据映射scripts/lib/rule-support-data.ts 将css-at-property映射到css.at-rules.property并出现在生成的 rules-catalog 中标注为 Low 优先级——适合在完成css-custom-properties基础令牌化之后作为进阶优化项引入。建议的落地顺序先按 css-custom-properties 把硬编码值提取为:root上的自定义属性再对其中参与动画、渐变与主题切换的属性逐个补充property注册最终形成语义令牌 类型约束 作用域隔离的完整设计系统。【免费下载链接】Front-End-Checklist The essential checklist for modern web development, for humans and AI agents项目地址: https://gitcode.com/gh_mirrors/fr/Front-End-Checklist创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 Front-End-Checklist 实战指南：用 @property 注册 CSS 自定义属性，实现动画插值与类型安全
Front-End-Checklist 实战指南用 property 注册 CSS 自定义属性实现动画插值与类型安全【免费下载链接】Front-End-Checklist The essential checklist for modern web development, for humans and AI agents项目地址: https://gitcode.com/gh_mirrors/fr/Front-End-ChecklistCSS 自定义属性custom properties默认只是字符串替换浏览器并不知道--brand-color是颜色、长度还是数字。Front-End-Checklist 的css-at-property规则规则文档Skill 定义教你用property和 Properties Values API 把自定义属性注册为带类型的真实值从而解锁渐变动画、类型化设计令牌与作用域隔离的主题系统。读完本文你将掌握property的完整语法、CSS.registerProperty()的 JS 等价用法以及如何通过 DevTools 验证注册与类型强制是否生效。背景自定义属性为什么动不起来CSS 自定义属性变量本质上是字符串替换。浏览器不知道--brand-color是颜色、长度还是数字这正是property与 Properties Values API 规范 存在的意义它们让引擎把自定义属性当作真实带类型的值来处理。在默认情况下未注册的自定义属性无法在 transition 或 animation 中被插值interpolate——它们会作为不透明的离散字符串直接跳变。注册一个属性等于告诉浏览器它需要的一切信息值类型、初始值、是否继承从而把自定义属性从字符串宏升级为一等公民的带类型值。这正是 Front-End-Checklist 将本规则归入css/design-tokens子类目、标记为priority: low、difficulty: advanced、预估耗时 30 分钟的原因——它是进阶特性但回报极高。最小注册示例property --property-name { syntax: color; /* 类型 —— 合法的 syntax 描述符见下文 */ initial-value: #000; /* 必填 —— 属性的默认值 */ inherits: true; /* 值是否会级联到子元素 */ }三个描述符缺一不可描述符作用取值要点syntax声明属性值的类型可用的 syntax 字符串见下一节initial-value属性的默认值只要syntax不是*就必须提供否则注册无效inherits是否向子元素级联true时子元素可读取父级值false时每个元素独立持有为什么重要从字符串宏到一等值注册property后浏览器终于有了足够的信息来在值之间平滑插值颜色、角度、长度等类型化值可以逐帧过渡校验令牌赋值给color属性赋一个px长度会变成可见的校验错误而不是静默失效干净地控制继承范围通过inherits: false阻止值向子树传播。这三个能力分别对应本规则在规则库中声明的关联规则见 css-at-property.mdx 的relatedRulescss-custom-propertiesproperty为自定义属性补充类型信息两条规则配合才能构成完整的令牌体系animation-performance注册后的属性允许部分类型走 GPU 加速的合成插值dark-mode-css用property注册的类型化颜色令牌保证暗色模式覆盖始终类型正确。syntax 描述符全表/* 基本类型 */ syntax: color; /* #hex、rgb()、hsl()、oklch()、颜色名 */ syntax: length; /* px、em、rem、vw 等 */ syntax: number; /* 无单位数字 */ syntax: integer; /* 仅整数 */ syntax: percentage; /* 0% 到 100% */ syntax: angle; /* deg、rad、turn */ syntax: time; /* s、ms */ syntax: length-percentage; /* 长度或百分比 */ /* 复合类型 */ syntax: color; /* 一个或多个空格分隔的颜色 */ syntax: length#; /* 一个或多个逗号分隔的长度 */ /* 通用兜底 —— 行为等同于未注册属性 */ syntax: *;选择原则能用具体类型就不用*。只有当你确实需要任何值例如动态生成的内容时才使用*兜底——它的行为与未注册属性完全一致无法触发插值与类型校验。实战一用自定义属性动画化渐变没有property时渐变停靠点无法动画因为浏览器把整个渐变当作不透明字符串处理/* ❌ 未注册 property —— 动画在离散值之间跳变 */ .card { --gradient-angle: 135deg; background: linear-gradient(var(--gradient-angle), #667eea, #764ba2); transition: --gradient-angle 0.6s ease; /* 无效 —— 字符串过渡 */ } .card:hover { --gradient-angle: 225deg; }注册为angle类型后角度值被平滑插值/* ✅ 注册 property —— 角度平滑过渡 */ property --gradient-angle { syntax: angle; initial-value: 135deg; inherits: false; } .card { background: linear-gradient(var(--gradient-angle), #667eea, #764ba2); transition: --gradient-angle 0.6s ease; /* 平滑动画 */ } .card:hover { --gradient-angle: 225deg; }核心差异在注册那一行浏览器现在知道--gradient-angle是角度可以按度数逐帧计算中间值而不是在两个整串之间跳变。实战二动画化颜色令牌色相轮转property --accent-hue { syntax: number; initial-value: 220; inherits: true; /* 子元素继承动画中的中间值 */ } :root { --accent-hue: 220; --accent: oklch(60% 0.2 var(--accent-hue)); transition: --accent-hue 0.4s ease; } /* 在特定区块内把色相移向暖色 */ .section--warm:hover { --accent-hue: 30; /* 橙色 */ } /* 使用 --accent 的组件在过渡中看到被插值的色相 */ .button { background: var(--accent); }这个例子展示了inherits: true与transition的配合:root上的--accent-hue变化会沿继承链传播任何读取--accent的子组件都能在过渡过程中实时看到中间色相。注意这里--accent本身没有被注册——它只是派生变量真正被动画化的是注册过的--accent-hue。实战三类型化设计令牌用property注册设计令牌可以当场抓住错误给颜色属性赋一个长度DevTools 会显示校验错误而不是静默无效/* 注册颜色令牌并显式声明类型 */ property --color-brand-primary { syntax: color; initial-value: oklch(55% 0.25 265); inherits: true; } property --color-surface { syntax: color; initial-value: #ffffff; inherits: true; } /* 注册间距令牌 */ property --spacing-base { syntax: length; initial-value: 1rem; inherits: true; } /* 暗色模式覆盖 —— 类型仍然被强制校验 */ media (prefers-color-scheme: dark) { :root { --color-brand-primary: oklch(70% 0.25 265); --color-surface: #0f172a; } }类型化令牌让设计系统具备编译期检查的体验令牌的合法取值域被语法显式约束覆盖值如暗色模式也会被同等的类型校验把关。这与本仓库 dark-mode-css 规则的设计意图一脉相承——语义化颜色令牌 类型约束比dark-blue这类魔法值更可靠。实战四inherits: false实现组件级作用域令牌/* 一个可动画填充的进度条 */ property --progress-fill { syntax: percentage; initial-value: 0%; inherits: false; /* 每个 .progress-bar 持有自己的值 —— 互不共享 */ } .progress-bar { --progress-fill: 0%; background: linear-gradient( to right, var(--color-brand-primary) var(--progress-fill), var(--color-surface) var(--progress-fill) ); transition: --progress-fill 0.5s ease; } /* JS 按实例设置值 */ /* element.style.setProperty(--progress-fill, 72%) */inherits: false的价值在于隔离多个进度条实例各自持有独立的--progress-fill不会因继承相互污染。JS 通过element.style.setProperty()按实例写入值配合已注册的类型浏览器会在写入时校验其确实是一个百分比。注意syntax非*时initial-value必填只要指定了类型化的 syntax 描述符任何非*的值就必须同时提供initial-value。缺失时注册无效浏览器会把该属性当作未注册属性处理。这是初写property规则时最常见的静默失败来源——务必两者都写上。CSS.registerProperty()JavaScript 等价 API同样的注册在 JavaScript 中也可完成适合程序化生成令牌的场景// 等价于 property at-rule CSS.registerProperty({ name: --gradient-angle, syntax: angle, initialValue: 135deg, inherits: false, })注意参数名的差异CSS 中叫initial-valueJS API 中叫initialValue驼峰。工程实践建议静态令牌优先用 CSSproperty规则声明声明式、可被样式表工具链静态分析CSS.registerProperty()仅在需要动态计算令牌注册时使用例如运行时按用户配置生成主题令牌。浏览器支持截至 2024 年property已获所有主流浏览器支持Chrome / Edge 85Firefox 128Safari 16.4Firefox 是最晚落地该特性的主流浏览器128 版本因此在做跨浏览器验证时Firefox 应作为关键回归目标。本仓库的规则元数据css-at-property.mdx将 MDNproperty参考、web.dev 注册指南与 W3C Properties Values API 规范列为三类权威来源reference / implementation / standard可作为合法性判定的基线。验证步骤如何确认注册真正生效参照 MDNproperty参考与 Properties Values API 规范作为合法注册的判定基线按以下四步验证检查类型化解析打开 DevTools检查一个持有已注册自定义属性的元素。Computed Styles 面板应显示解析后的类型化值如oklch(55% 0.25 265)而不是原始变量字符串。检查平滑插值对已注册属性应用 CSS transition确认动画在值之间平滑过渡而不是离散跳变。检查类型强制故意向已注册属性赋一个错误类型的值例如把px长度赋给color属性确认浏览器忽略无效值并回退到initial-value——这证明类型校验真实生效。跨浏览器回归在 Firefox最晚支持property的主流浏览器128 版本中测试确认注册有效且动画行为一致。在 Front-End-Checklist 中的落地方式本规则在仓库中是一个可被 Agent 直接执行的 Skillskills/css-at-property/SKILL.md其元数据声明了四个标准操作可直接用于审查任意 CSS 文件Check审查文件中的 CSS 自定义属性找出所有用于 transition 或 animation 的属性——这些属性必须注册property才能正确动画Fix为用于过渡或动画的自定义属性补充property注册包含正确的 syntax 描述符、initial-value与合适的inherits值Explain解释property的工作原理、未注册属性为何无法动画、各 syntax 描述符的含义以及inherits如何控制级联行为Code Review检查所有引用自定义属性的 transition 与 animation标记两类问题——用于过渡/动画但未注册的属性以及缺少initial-value的注册。仓库的工具链也将本规则纳入了规则支持数据映射scripts/lib/rule-support-data.ts 将css-at-property映射到css.at-rules.property并出现在生成的 rules-catalog 中标注为 Low 优先级——适合在完成css-custom-properties基础令牌化之后作为进阶优化项引入。建议的落地顺序先按 css-custom-properties 把硬编码值提取为:root上的自定义属性再对其中参与动画、渐变与主题切换的属性逐个补充property注册最终形成语义令牌 类型约束 作用域隔离的完整设计系统。【免费下载链接】Front-End-Checklist The essential checklist for modern web development, for humans and AI agents项目地址: https://gitcode.com/gh_mirrors/fr/Front-End-Checklist创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考