R1.04.1negative usage guideline设计
准则需包含何时不用
别名: 何时不用 · API 负空间 · do not use when
概念解释
组件说明如果只写「可以用来提交、可以用来跳转、可以用来打开菜单」,合法集合会一直膨胀。准则必须划出何时不用:按钮不用来做导航,链接不拿来提交表单,菜单项不拿来当页内筛选。这段负空间和必填属性一样,属于接口合同,不是礼貌性的补充说明。
它要求的是排除规则写进用法本身,不是反例截图该挂在文档站还是挂在代码旁边——那是文档放在哪的问题。
机制
正例教的是一条合法路径,读者会按类比外推:看见按钮能点,就把所有能点的都做成按钮。产品里于是出现「看起来像按钮的链接」「看起来像链接的菜单项」,键盘预期、语义角色和爬虫行为跟着错位。排除规则把邻近组件的职责切开:导航走链接(可新开、可复制 URL),提交走按钮(不产生地址),页内动作走菜单项(不离开当前上下文)。
负空间还有一个作用:挡住为了眼前页面硬塞进来的用法。没有「不要把按钮当标签用」,筛选芯片就会被做成一排主按钮。合同里缺排除项,等于默许一切尚未被禁止的类比。必填 prop 限制的是传值形状,排除规则限制的是选用这个组件的情境,两层一起才构成可执行的 API。
边界
平台原生控件的排除规则已被系统文档写过(系统分享表不拿来当设置页),产品准则只需指向,不必复述。实验性组件在探索期可以只有正例,但一旦进入稳定渠道,排除规则必须补上,否则探索期的类比会冻成惯例。视觉上极度相似、职责也故意重叠的一对组件(两种强调程度的按钮)排除项会很短,重点改写在程度上,而不是互斥选用。无障碍替代(为读屏另提供的隐藏按钮)看起来违反「一处一个主按钮」,但这是通道补偿,要在排除规则里写成合法例外,不能靠口头传达。
怎么落地
- 每个稳定组件的用法页用「用于 / 不用于」对开:不用于一侧点名邻近组件,并写清改用谁。
- 把排除规则写进类型或 lint 能碰到的地方(禁止在
href存在时用 Button 包一层假链接),不要只写在散文里。 - 评审新调用点时先问「是否落在不用于一侧」,命中则改选组件,而不是加一个新变体把误用合法化。
- 验证:抽十条近期把按钮当导航、把链接当提交的调用,对照「不用于」能否直接判否。判不了的,负空间还没写成合同。