用途:定义 Shade 中 DropdownMenu、Select、Popover 三个 Radix 浮动菜单统一的外观契约。浮动菜单浮于已抬升表面(侧栏、卡片、顶栏)之上,需读作悬浮于触发器上方,--surface-elevated-2 即为此保留。亮色模式下三个表面令牌趋近白色,靠边框与阴影承载层级;暗色模式下颜色区分明显,分层更清晰。
契约要点:背景 bg-surface-elevated-2;边框 border border-border/60 dark:border-border/30;阴影 shadow-md,DropdownMenuContent 例外用 shadow-lg,DropdownMenuSubContent、SelectContent、PopoverContent 用 shadow-md;圆角 rounded-md(组件默认);动画为标准 Radix data-[state=open] 进入/退出。阴影差异属有意:顶层菜单从非抬升触发器打开需更强投影,子菜单已在浮动菜单内,用较轻 shadow-md 避免叠加。菜单项 hover 用 --interactive-hover(bg-interactive-hover),不要用原始灰色或临时透明度修饰。
使用方式:若设计改动涉及浮动菜单表面(背景、边框、阴影、层级),需同时编辑三个文件:apps/shade/src/components/ui/dropdown-menu.tsx(DropdownMenuContent 与 DropdownMenuSubContent)、apps/shade/src/components/ui/select.tsx(SelectContent)、apps/shade/src/components/ui/popover.tsx(PopoverContent)。若未来有第四个 Radix 表面需同一配方,再抽为 floatingSurface recipe;两个消费者不足以支撑,三个当前以镜像维护。
限制与禁止:不要只改 dropdown 而不同步 Select/Popover;不要用 hover:bg-gray-100 dark:hover:bg-gray-800 等原始灰色;不要在浮动菜单用 bg-surface-elevated(丢失层级)。dark:border-border/30 是对既有语义令牌的透明度修饰,属合理例外。相关技能为 shade-tokens-not-hex。当前表面契约以这三个组件文件为准,Storybook → Tokens / Tokens Guide 解释令牌模型。