菜单
DropdownMenu, Select, and Popover share one visual recipe (bg-surface-elevated-2 + border-border/60 dark:border-border/30 + shadow-md). Change them together. Trigger when editing any of those three Shade files.
用 Codex 或 Claude 帮你安装 复制这段 Prompt，粘贴到 Codex、Claude 或其他助手里，让它检查 Skill 页面并帮你完成安装。
基于 SOC 职业分类
| name | Shade dropdown surface contract |
| description | DropdownMenu, Select, and Popover share one visual recipe (bg-surface-elevated-2 + border-border/60 dark:border-border/30 + shadow-md). Change them together. Trigger when editing any of those three Shade files. |
| autoTrigger | [{"fileEdit":"apps/shade/src/components/ui/{dropdown-menu,select,popover}.tsx"}] |
DropdownMenu, Select, and Popover are the three Radix-backed floating menus that Filters and the rest of admin use. They share one visual recipe:
bg-surface-elevated-2
border border-border/60 dark:border-border/30
shadow-md
Treat them as one component for any surface decision. If you change the surface for one, change all three.
Floating menus open ON TOP of an already-elevated surface (sidebars, cards, top bars). They need to read as floating above their trigger. --surface-elevated-2 is reserved for exactly this — popovers, dropdown content, and the sidebar user menu.
In light mode the three surface tokens (background / surface-elevated / surface-elevated-2) flatten to near-white; the border + shadow-md carry elevation. In dark mode they're three distinct colours so layered surfaces stay legible without relying on borders alone.
| Concern | Class |
|---|---|
| Background | bg-surface-elevated-2 |
| Border | border border-border/60 dark:border-border/30 |
| Shadow | shadow-md baseline. DropdownMenuContent is the exception — it uses shadow-lg. DropdownMenuSubContent, SelectContent, and PopoverContent all use shadow-md. |
| Radius | rounded-md (component default) |
| Animation | Standard Radix data-[state=open]: enter/exit set |
The shadow split is intentional: the top-level DropdownMenuContent opens straight out of an unelevated trigger (a button on the page canvas) and needs the stronger drop. DropdownMenuSubContent already pops from inside a floating menu, so it uses the lighter shadow-md to avoid double-stacking elevation. Select and Popover also open from low-elevation triggers but their content sits closer to the trigger surface, so shadow-md is enough.
The dark:border-border/30 is a legitimate exception to the no-dark:-for-colour rule — it's an opacity modifier on an existing semantic token. See shade-no-dark-variants.
If a design change touches the floating-menu surface (background, border, shadow, elevation), edit all three files:
apps/shade/src/components/ui/dropdown-menu.tsx (DropdownMenuContent and DropdownMenuSubContent)apps/shade/src/components/ui/select.tsx (SelectContent)apps/shade/src/components/ui/popover.tsx (PopoverContent)If a fourth Radix-backed surface needs the same recipe, extract it as a floatingSurface recipe under apps/shade/src/components/ui/. Two consumers is too thin to justify a Recipe; three is the current count and just covered by mirroring.
Hover state on menu items uses --interactive-hover (bg-interactive-hover) — the generic hover token. Don't use raw greys or apply ad-hoc opacity modifiers (hover:bg-gray-900/30). The interactive tokens already handle dark-mode translucency so they composite over the floating surface correctly.
// BAD — changing dropdown surface but not Select / Popover
// In dropdown-menu.tsx:
'bg-surface-elevated border border-border/40 shadow-xl' // <-- drifted from contract
// BAD — raw greys for hover instead of the interactive token
'hover:bg-gray-100 dark:hover:bg-gray-800'
// BAD — surface-elevated (not -2) on a floating menu
// loses the visual elevation above already-elevated triggers
'bg-surface-elevated'
Hover/active/selected state tokens (--interactive-hover, --button-hover, --tab-hover, --table-row-hover): see shade-tokens-not-hex.
apps/shade/AGENTS.md (Tokens & dark mode → Dropdown surface contract). Storybook → Tokens / Tokens Guide.
Decide which Shade layer (Token, Primitive, Component, Recipe, Pattern) a new piece of UI belongs in — and whether it should be added to Shade at all. Trigger when creating new files in apps/shade/src/components, or proposing to add a new Shade component.
Import Shade from layer-specific subpaths (primitives, components, patterns, page-templates, utils), never the root barrel. Trigger when editing TSX/TS in Shade-consuming apps.
Use the inputSurface() recipe for form-control chrome (border, background, radius, focus ring, invalid state) — don't roll your own. Trigger when editing form-control-shaped files in Shade.
Acceptance checklist for adding or editing a Shade component or pattern file — naming, sibling story, className forwarding, cva variants, required states, recipe usage. Trigger when editing files in apps/shade/src/components.
Don't write dark: Tailwind variants for colour in Shade or admin apps — semantic tokens flip in dark mode automatically. Trigger when editing TSX in Shade-consuming apps.
Pick the right Shade page template (ListPage, PageHeader) for a new admin page instead of inventing chrome. Trigger when creating new admin pages or routes in apps/admin, apps/admin-x-settings, apps/posts, apps/stats, apps/activitypub.