{
  "id": "split-button",
  "type": "components",
  "status": "published",
  "name": {
    "zh": "分体按钮",
    "en": "Split Button"
  },
  "aliases": [
    "分裂按钮",
    "组合按钮",
    "带下拉的按钮",
    "主副按钮",
    "split button"
  ],
  "category": [
    "Action"
  ],
  "description": {
    "zh": "由主操作区与附属箭头组成的复合按钮：主区直接执行默认动作，箭头展开同组的备选菜单。比「按钮加独立下拉」少一次定位，比整键打开菜单的下拉按钮更快命中高频操作，常用于保存、发送、新建等带变体的动作。",
    "en": "A two-part button whose main area runs the default action while an attached arrow opens a menu of related ones. It saves a targeting step compared with a separate button and menu, and hits the frequent action faster than a dropdown whose whole face opens a list. Common for save, send and new-with-variants."
  },
  "use_when": [
    {
      "zh": "存在一个高频默认动作，外加若干同组变体",
      "en": "One frequent default action plus a few variants of it"
    },
    {
      "zh": "希望默认动作一次点击即可执行",
      "en": "The default must fire in a single click"
    },
    {
      "zh": "工具栏或表单操作区空间紧凑",
      "en": "Toolbar or form action rows are tight on space"
    }
  ],
  "avoid_when": [
    {
      "zh": "没有明确默认动作，所有选项同等重要，用 dropdown",
      "en": "No clear default and all options rank equally — use a dropdown"
    },
    {
      "zh": "备选动作与主动作无关，拆成 button 加 menu 更清晰",
      "en": "Related actions are loosely coupled — a separate button and menu reads clearer"
    },
    {
      "zh": "只有一个动作，普通 button 足够",
      "en": "Only one action exists — a plain button is enough"
    }
  ],
  "tags": [
    "action",
    "button",
    "menu"
  ],
  "api": [
    "<button>",
    "aria-haspopup=\"menu\"",
    "aria-expanded"
  ],
  "variants": [
    {
      "id": "horizontal",
      "name": {
        "zh": "水平分体",
        "en": "Horizontal"
      },
      "note": {
        "zh": "主区与箭头左右并排，最常见形态",
        "en": "Main face and arrow side by side — the common form"
      }
    },
    {
      "id": "vertical",
      "name": {
        "zh": "垂直分体",
        "en": "Vertical"
      },
      "note": {
        "zh": "箭头堆叠在主区下方，窄工具栏更稳",
        "en": "Arrow stacks under the main face for narrow toolbars"
      }
    },
    {
      "id": "with-icon",
      "name": {
        "zh": "带图标",
        "en": "With icon"
      },
      "note": {
        "zh": "主区含图标加文案，识别更快",
        "en": "Icon plus label on the main face for faster recognition"
      }
    }
  ],
  "anatomy": [
    "主操作区（Primary）",
    "分隔线（Divider）",
    "附属箭头（Arrow）",
    "备选菜单（Menu）"
  ],
  "framework_names": [
    {
      "framework": "ARIA APG",
      "name": "Menu Button",
      "url": "https://www.w3.org/WAI/ARIA/apg/patterns/menu-button/"
    },
    {
      "framework": "MUI",
      "name": "ButtonGroup",
      "url": "https://mui.com/material-ui/react-button-group/"
    },
    {
      "framework": "Bootstrap",
      "name": "Split button",
      "url": "https://getbootstrap.com/docs/5.3/components/buttons/#split-buttons"
    }
  ],
  "playground": {
    "task": {
      "zh": "分别点击主区与箭头，对比一次执行默认动作与展开备选菜单。",
      "en": "Click the main face and the arrow, comparing a one-shot default with the variant menu."
    },
    "checks": [
      {
        "zh": "主区与箭头是两个独立可聚焦目标",
        "en": "Main face and arrow are two independent focus targets"
      },
      {
        "zh": "菜单打开时箭头呈展开态，Esc 收起并焦点归位",
        "en": "The arrow shows expanded state; Esc closes and restores focus"
      }
    ]
  },
  "applicable_styles": [
    "swiss-style",
    "flat-design",
    "claymorphism",
    "minimalism",
    "neobrutalism",
    "glassmorphism",
    "cyberpunk",
    "neumorphism"
  ],
  "related": [
    {
      "id": "button",
      "relation": "similar_to"
    },
    {
      "id": "dropdown",
      "relation": "used_with"
    },
    {
      "id": "menu",
      "relation": "used_with"
    }
  ],
  "confusable": [
    {
      "id": "dropdown",
      "note": {
        "zh": "dropdown 整键打开菜单；split-button 主区执行动作、只有箭头开菜单",
        "en": "A dropdown opens a menu from the whole face; split-button runs an action on the main face"
      }
    },
    {
      "id": "button",
      "note": {
        "zh": "普通 button 只有一个动作；split-button 把同组变体收进附属菜单",
        "en": "A plain button has one action; split-button folds sibling variants into an attached menu"
      }
    }
  ],
  "disambiguation": {
    "zh": "与 Dropdown 的差别是主区可直接执行默认动作；与「按钮加独立菜单」的差别是箭头在视觉与焦点上都附着于主按钮。",
    "en": "Versus a Dropdown the main face runs the default action; versus a separate button and menu the arrow stays visually and focally attached."
  },
  "demo": {
    "component": "split-button",
    "modes": [
      "default",
      "dark",
      "variants"
    ]
  },
  "sources": [
    {
      "name": "WAI-ARIA Authoring Practices — Menu Button",
      "url": "https://www.w3.org/WAI/ARIA/apg/patterns/menu-button/"
    },
    {
      "name": "Bootstrap — Split buttons",
      "url": "https://getbootstrap.com/docs/5.3/components/buttons/#split-buttons"
    },
    {
      "name": "Material Design — Buttons",
      "url": "https://m3.material.io/components/buttons/overview"
    }
  ],
  "implementation": {
    "css": [
      "display: inline-flex",
      "border-radius: 0",
      "position: relative"
    ],
    "notes": {
      "zh": "两个按钮并排放在 inline-flex 中，接缝处去掉圆角与左边框形成一体外观；箭头用窄热区和 chevron 区分。菜单相对容器绝对定位。主区与箭头各自可聚焦，菜单打开后方向键在菜单项间移动，Esc 归位到箭头。",
      "en": "Seat both halves in an inline-flex row and flatten the seam radius and border so they read as one control; give the arrow a narrow hit area with a chevron. Position the menu absolutely against the container. Each half is its own tab stop; with the menu open, arrows move through items and Esc returns focus to the arrow."
    }
  },
  "prompts": {
    "basic": {
      "zh": "创建一个分体按钮：主区执行默认保存动作，附属箭头展开保存并发布等备选菜单。",
      "en": "Create a split button whose main face saves by default and whose arrow opens alternatives such as save-and-publish."
    },
    "design": {
      "zh": "设计分体按钮。要求：主区与箭头视觉上连为一体，仅以细分隔线区分；主区文案明确动作名称；箭头用 chevron 并在菜单打开时旋转或高亮；菜单项与主区动作同组；深浅色主题一致。",
      "en": "Design a split button. Requirements: the two halves read as one control split by a hairline divider; the main face names its action clearly; the arrow uses a chevron that rotates or lights up when the menu opens; menu items stay in the same action family; consistent light and dark themes."
    },
    "implementation": {
      "zh": "用 React + Tailwind 实现分体按钮：主区为普通 button，箭头为 aria-haspopup=\"menu\" 的 button，共用一套高度与配色；接缝用负 margin 或 border-l-0 拼接；菜单绝对定位在箭头下方，打开时 aria-expanded=\"true\"；支持 Enter 触发主动作、方向键浏览菜单。",
      "en": "React + Tailwind split button: a plain button for the main face and an aria-haspopup=\"menu\" button for the arrow, sharing height and color; join the seam with a negative margin or border-l-0; absolutely position the menu under the arrow with aria-expanded=\"true\" while open; Enter fires the default action and arrows walk the menu."
    },
    "agent": {
      "zh": "在当前项目中实现分体按钮（Split Button）组件。\n先检查现有按钮与菜单组件，优先复用配色、高度与浮层实现。\n用途：保存、发送、新建等带变体的高频动作。\n要求：\n- 主区直接执行默认动作，箭头展开同组备选菜单\n- 两个热区独立可聚焦，菜单打开态有可见反馈\n- Esc 关闭菜单并把焦点还给箭头\n- 尊重 prefers-reduced-motion，深浅色一致\n- 不新增依赖\n完成后运行项目现有检查，并列出修改的文件。",
      "en": "Implement a Split Button component in the current project.\nInspect existing button and menu components first and reuse color, height and overlay primitives.\nUsage: frequent actions with variants — save, send, new.\nRequirements:\n- The main face runs the default action; the arrow opens the sibling menu\n- Two independently focusable targets with visible open state\n- Esc closes the menu and restores focus to the arrow\n- Respect prefers-reduced-motion; consistent light and dark themes\n- No new dependencies\nRun the existing project checks when done and list the modified files."
    }
  }
}