Portable UI Contract

以下 ID 是各自规则的权威归属。

可移植性

FE-PORT-001：可移植是默认要求

一个合规模块无需修改模块代码、也无需依赖某个项目私有的 facade 类，即可与另一个合规的 facade 主题协同工作。

FE-STYLE-001：不得依赖私有 facade

可移植模块不能要求仅由某一个 facade 定义的任意类或选择器。共享的 PrimeVue .p-* 主题规则不属于私有类。某个模块所需的非 PrimeVue 样式应放在该模块中，但应通过遵循共享组件和语义来尽量减少。

当你自己的多个模块需要同一份非 PrimeVue 样式时，它既不属于 facade 也不属于每个模块：参见设计层。

组件与可供性

FE-UI-001：当 PrimeVue 能满足控件需求时就使用它

如果 PrimeVue 提供了所需的语义、交互和预期可供性，模块必须使用它。

FE-UI-002：数据形态不等于可供性

能够表示相同的取值并不能让两个控件等价。当预期的可供性在外观和行为上就是一个滑动开关时，SelectButton 并不能自动替代一个三位滑动开关。

FE-UI-003：语义与可供性相同就意味着外观相同

等价的控件必须共享尺寸、间距、颜色、排版、边框、阴影、焦点、悬停、禁用、无效状态和动效行为。自定义组合控件应指明其 PrimeVue 视觉同类，并继承每一项适用的共享运行时属性。

FE-UI-004：省略 PrimeVue 的范围很窄

只有当模块渲染的内容在物理上或语义上都不像 PrimeVue 时，才可以省略 PrimeVue。仅绘图的组件符合条件；带按钮或表单字段的图表不符合。

FE-UI-005：绝不臆造组件 API

未文档化的 prop 或行为不是捷径。PrimeVue 的 ToggleSwitch 不会因为臆造一个新的 positions prop 就变成三位控件。当没有任何 PrimeVue 组件或组合能提供所需可供性时，请走经过评审的自定义同类流程。

Tailwind 与令牌

FE-TW-001：Wippy Tailwind 受支持

共享的 Wippy preset 是受支持的构建期契约。模块可以使用其文档化的工具类，并为领域布局、应用特定断点、装饰和新型可视化扩展它。

FE-TW-002：编译后的取值不是运行时令牌

诸如 px-3、rounded-md 和 duration-200 之类的工具类通常编译为常量。它们提供一致的基线，但不会因 facade 替换运行时主题变量而改变。

FE-TW-003：共享同类的外观应跟随运行时语义

当某个外观属性必须跨主题跟随其 PrimeVue 同类时，请使用有文档记载的、由运行时支持的语义工具类或直接使用公开令牌。只有当该属性被明确归类为 platform-invariant 时，才允许使用固定的工具类。

FE-TW-004：受保护的映射必须保持其含义

模块可以扩展 preset，但不能以不兼容的方式重新定义受保护的 primary、surface、severity、text、content、highlight 或可移植控件语义。

FE-TOKEN-001：每个令牌都必须存在

每一处 --p-* 引用都必须存在于所选的生成清单中。

FE-TOKEN-002：令牌名不是可以猜出来的 API

绝不要按类比构造令牌。请检索令牌目录或所选包的清单。

无障碍

自定义控件例外必须保留有效的 HTML、键盘交互、焦点、可访问名称、状态和禁用行为。可交互元素不得嵌套。