尧图网站建设 
Astryx组件命名规范深潜让人类和AI都能预测行为的10条约定【免费下载链接】astryxAn open source design system thats fully customizable and agent ready项目地址: https://gitcode.com/GitHub_Trending/as/astryxAstryx 是一个完全可定制、面向 AI 智能体友好的开源设计系统design system。它最有意思的一点是它的组件命名规范不只是给人看的文档而是被写成了一组可自动执行的 ESLint 规则——人类写代码时收到温和的警告AI 智能体写代码时则直接报错挡下。这篇文章带你深潜 Astryx 组件命名规范的 10 条核心约定看看它如何让看到名字就能预测行为成为可能。为什么命名必须可预测在 Astryx 的公开组件 API 架构文档 public-component-api.md 中有一条目标写得很直白使用者应当能在不学习组件内部实现的情况下预测一个 Astryx 组件会被如何导入、控制、扩展和组合。它甚至为此单独立了一条不变式INV2——名字承载相同的含义组件、Hook、布尔值、回调、Action、方向等都遵循同一套命名语法。更妙的是这套约定不是停留在文档里。Astryx 自研了一个 ESLint 插件 internal/eslint-plugin-astryx/把命名规则变成可执行的检查规范源头则记录在 api-conventions.md。下面这 10 条约定几乎每一条都能在规则源码中找到对应物。约定 1一个名字只表达一个概念Astryx 规定一个 prop 只控制一个独立的概念。如果两个输入各自独立地由调用方决定就必须用两个输入表示而不能让一个属性看值切换控制轴——因为那会迫使消费者必须了解实现细节才能预测输出详见 AST-002 规范 中的 FR8结果是可预测的。反例在官方评审味道清单里被点名status属性在某些取值下控制颜色、另一些取值下又控制图标就是典型的可预测性破坏。约定 2组件用无前缀的 PascalCaseProps 类型同名可推表面命名约定示例组件无前缀 PascalCaseButton、TextInputProps 类型组件名PropsButtonProps这意味着你不需要查文档就能猜对类型名看到DialogDialogProps一定存在。这个机械可推导正是 AI 友好命名的精髓。约定 3布尔值分状态与能力前缀 is / has这是被 boolean-prop-naming.js 规则硬性执行的约定isName表示状态/条件isDisabled、isLoadinghasName表示功能开关/能力hasClear、hasAutoFocusdefaultIsName/defaultHasName表示非受控默认值defaultIsOpen。规则甚至会给你自动建议写成disabled就会提示你改成isDisabled。对人类是警告对 AI 是错误——稍后细说。约定 4回调一律 on动词必要时加作用域同步回调统一onVerbonChange当动词可能指向多个部件时才追加作用域onSidebarCollapsedChange。注意两条纪律作用域只在有歧义时使用别过度装饰以及永远不要命名成onChangeAction见约定 5。约定 5Action 用 动词Action绝不以 on 开头Astryx 区分两类动作接口CallbackonChange同步地报告事件ActionchangeAction、clickAction启动感知过渡transition-aware的工作可返回 Promise。命名上 Action 绝不允许带on前缀——changeAction而不是onChangeAction。当两者同时存在时回调先执行Action 后执行顺序在契约中写死。名字即语义语义即执行顺序。约定 6方向一律用逻辑方向 start / end公共 API 里不允许出现物理方向词。startIcon、paddingEnd是标准写法——这样同一份代码在 LTR 和 RTL阿拉伯语、希伯来语等从右到左的语言下都自动镜像正确。配套的no-physical-properties规则会拦截物理方向属性漏进公共 API。约定 7工具函数用结果动词命名api-conventions.md 给模块/工具函数动词做了一张对照表核心思想是按调用方可观察的结果命名而不是按内部步骤命名resolve*从输入/注册表里选出一个具体值parse*把字符串转成结构化表示format*把值序列化为展示文本不改变源值validate*/check*检查并返回结构化结果get*只读获取不暗示持久化。resolve、parse、format三个词各管一段读到函数名就知道它产出什么。约定 8国际化键名是 camelCase 路径所有面向用户的文案必须走翻译目录键名格式为astryx.组件.叶子且每一段都必须是 camelCase。这条由 i18n-key-format.js 检查✅astryx.pagination.next、astryx.powersearch.operator.isAnyOf❌astryx.power_search.operatorsnake_case❌astryx.PowerSearch.operatorPascalCase 段姊妹规则 no-hardcoded-i18n-string.js 则负责文案该放哪凡是label、*Label、*Placeholder、*Tooltip这类用户可见属性里写死英文字符串一律被标记。一个管位置一个管格式双保险。约定 9双层 Lint——人类看警告AI 看错误这是 Astryx agent ready 最直观的体现。eslint-plugin README 描述了双层策略模式受众行为触发条件Recommended人类仅警告本地开发默认StrictAI 智能体 / CI报错并挡下构建CItrue或ASTRYX_STRICT_LINT1设计哲学一句话智能体必须完美遵守严格规则因为它们没有借口人类在开发时需要灵活性警告能提示而不阻塞。同一份命名规范两种执行力度——人类获得自由AI 获得纪律。约定 10等价概念必须等价命名public-component-api.md 的常见评审味道清单里专门列了一条等价概念使用了不同名字比如出现onChangeAction而别处用changeAction。Astryx 的答案很简单粗暴——同一个语义动作在一个模块内只允许一个规范名内部实现可以接受更宽的参数但公开名字必须统一。对 AI 来说这一条价值最大名字空间没有同义词陷阱它生成的代码不会在两个看起来都对的名字之间摇摆。小结可预测性是一种工程产物把 10 条约定串起来看Astryx 的命名哲学可以浓缩成三句话名字即契约——每个前缀is、has、on、defaultIs都有精确语义没有模糊地带规范即代码——约定不只写在 docs/ 里而是以可执行规则internal/eslint-plugin-astryx/ 双层强度落地人类与 AI 共享同一语法——唯一区别只是违规时的代价人得到提醒智能体得到红灯。如果你的团队正在为 AI 辅助开发设计组件库这套机械可推导 自动强制执行的命名约定非常值得借鉴。【免费下载链接】astryxAn open source design system thats fully customizable and agent ready项目地址: https://gitcode.com/GitHub_Trending/as/astryx创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 Astryx组件命名规范深潜：让人类和AI都能“预测“行为的10条约定
Astryx组件命名规范深潜让人类和AI都能预测行为的10条约定【免费下载链接】astryxAn open source design system thats fully customizable and agent ready项目地址: https://gitcode.com/GitHub_Trending/as/astryxAstryx 是一个完全可定制、面向 AI 智能体友好的开源设计系统design system。它最有意思的一点是它的组件命名规范不只是给人看的文档而是被写成了一组可自动执行的 ESLint 规则——人类写代码时收到温和的警告AI 智能体写代码时则直接报错挡下。这篇文章带你深潜 Astryx 组件命名规范的 10 条核心约定看看它如何让看到名字就能预测行为成为可能。为什么命名必须可预测在 Astryx 的公开组件 API 架构文档 public-component-api.md 中有一条目标写得很直白使用者应当能在不学习组件内部实现的情况下预测一个 Astryx 组件会被如何导入、控制、扩展和组合。它甚至为此单独立了一条不变式INV2——名字承载相同的含义组件、Hook、布尔值、回调、Action、方向等都遵循同一套命名语法。更妙的是这套约定不是停留在文档里。Astryx 自研了一个 ESLint 插件 internal/eslint-plugin-astryx/把命名规则变成可执行的检查规范源头则记录在 api-conventions.md。下面这 10 条约定几乎每一条都能在规则源码中找到对应物。约定 1一个名字只表达一个概念Astryx 规定一个 prop 只控制一个独立的概念。如果两个输入各自独立地由调用方决定就必须用两个输入表示而不能让一个属性看值切换控制轴——因为那会迫使消费者必须了解实现细节才能预测输出详见 AST-002 规范 中的 FR8结果是可预测的。反例在官方评审味道清单里被点名status属性在某些取值下控制颜色、另一些取值下又控制图标就是典型的可预测性破坏。约定 2组件用无前缀的 PascalCaseProps 类型同名可推表面命名约定示例组件无前缀 PascalCaseButton、TextInputProps 类型组件名PropsButtonProps这意味着你不需要查文档就能猜对类型名看到DialogDialogProps一定存在。这个机械可推导正是 AI 友好命名的精髓。约定 3布尔值分状态与能力前缀 is / has这是被 boolean-prop-naming.js 规则硬性执行的约定isName表示状态/条件isDisabled、isLoadinghasName表示功能开关/能力hasClear、hasAutoFocusdefaultIsName/defaultHasName表示非受控默认值defaultIsOpen。规则甚至会给你自动建议写成disabled就会提示你改成isDisabled。对人类是警告对 AI 是错误——稍后细说。约定 4回调一律 on动词必要时加作用域同步回调统一onVerbonChange当动词可能指向多个部件时才追加作用域onSidebarCollapsedChange。注意两条纪律作用域只在有歧义时使用别过度装饰以及永远不要命名成onChangeAction见约定 5。约定 5Action 用 动词Action绝不以 on 开头Astryx 区分两类动作接口CallbackonChange同步地报告事件ActionchangeAction、clickAction启动感知过渡transition-aware的工作可返回 Promise。命名上 Action 绝不允许带on前缀——changeAction而不是onChangeAction。当两者同时存在时回调先执行Action 后执行顺序在契约中写死。名字即语义语义即执行顺序。约定 6方向一律用逻辑方向 start / end公共 API 里不允许出现物理方向词。startIcon、paddingEnd是标准写法——这样同一份代码在 LTR 和 RTL阿拉伯语、希伯来语等从右到左的语言下都自动镜像正确。配套的no-physical-properties规则会拦截物理方向属性漏进公共 API。约定 7工具函数用结果动词命名api-conventions.md 给模块/工具函数动词做了一张对照表核心思想是按调用方可观察的结果命名而不是按内部步骤命名resolve*从输入/注册表里选出一个具体值parse*把字符串转成结构化表示format*把值序列化为展示文本不改变源值validate*/check*检查并返回结构化结果get*只读获取不暗示持久化。resolve、parse、format三个词各管一段读到函数名就知道它产出什么。约定 8国际化键名是 camelCase 路径所有面向用户的文案必须走翻译目录键名格式为astryx.组件.叶子且每一段都必须是 camelCase。这条由 i18n-key-format.js 检查✅astryx.pagination.next、astryx.powersearch.operator.isAnyOf❌astryx.power_search.operatorsnake_case❌astryx.PowerSearch.operatorPascalCase 段姊妹规则 no-hardcoded-i18n-string.js 则负责文案该放哪凡是label、*Label、*Placeholder、*Tooltip这类用户可见属性里写死英文字符串一律被标记。一个管位置一个管格式双保险。约定 9双层 Lint——人类看警告AI 看错误这是 Astryx agent ready 最直观的体现。eslint-plugin README 描述了双层策略模式受众行为触发条件Recommended人类仅警告本地开发默认StrictAI 智能体 / CI报错并挡下构建CItrue或ASTRYX_STRICT_LINT1设计哲学一句话智能体必须完美遵守严格规则因为它们没有借口人类在开发时需要灵活性警告能提示而不阻塞。同一份命名规范两种执行力度——人类获得自由AI 获得纪律。约定 10等价概念必须等价命名public-component-api.md 的常见评审味道清单里专门列了一条等价概念使用了不同名字比如出现onChangeAction而别处用changeAction。Astryx 的答案很简单粗暴——同一个语义动作在一个模块内只允许一个规范名内部实现可以接受更宽的参数但公开名字必须统一。对 AI 来说这一条价值最大名字空间没有同义词陷阱它生成的代码不会在两个看起来都对的名字之间摇摆。小结可预测性是一种工程产物把 10 条约定串起来看Astryx 的命名哲学可以浓缩成三句话名字即契约——每个前缀is、has、on、defaultIs都有精确语义没有模糊地带规范即代码——约定不只写在 docs/ 里而是以可执行规则internal/eslint-plugin-astryx/ 双层强度落地人类与 AI 共享同一语法——唯一区别只是违规时的代价人得到提醒智能体得到红灯。如果你的团队正在为 AI 辅助开发设计组件库这套机械可推导 自动强制执行的命名约定非常值得借鉴。【免费下载链接】astryxAn open source design system thats fully customizable and agent ready项目地址: https://gitcode.com/GitHub_Trending/as/astryx创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考