{
  "id": "fab",
  "type": "components",
  "status": "published",
  "name": {
    "zh": "悬浮按钮",
    "en": "Floating Action Button"
  },
  "aliases": [
    "悬浮按钮",
    "浮动按钮",
    "悬浮球",
    "右下角那个圆按钮",
    "FAB",
    "floating action button"
  ],
  "category": [
    "Action"
  ],
  "description": {
    "zh": "锚在视口角落、悬浮于内容之上的圆形按钮，承载当前页面唯一的主操作（新建、撰写、扫码）。 用阴影和位置宣告「我在所有内容之上」，比行内主按钮更醒目，但一屏只应有一个。点击后可展开 为带标签的扩展形态，或扇出一组快捷动作。",
    "en": "A circular button anchored to a corner of the viewport, floating above the content and carrying the one primary action of the current view (create, compose, scan). Shadow and placement declare \"I sit above everything\" — louder than an inline primary button, but there should be only one per screen. On click it may expand into a labeled bar or fan out into a set of quick actions."
  },
  "disambiguation": {
    "zh": "悬浮按钮不是「更显眼的主按钮」：主按钮嵌在页面布局里、随内容滚动；悬浮按钮脱离文档流、 常驻视口角落并覆盖在内容之上。判断标准是它是否悬浮在滚动内容之上，而不是颜色有多亮。",
    "en": "A FAB is not \"a louder primary button\": a primary button lives inside the layout and scrolls with content; a FAB detaches from the flow, stays pinned to a corner and overlays content. The test is whether it floats above scrolling content — not how bright its color is."
  },
  "use_when": [
    {
      "zh": "页面有唯一、高频、正向的主操作（新建、撰写）",
      "en": "The view has one frequent, constructive primary action (create, compose)"
    },
    {
      "zh": "底部拇指热区需要常驻入口",
      "en": "A persistent entry point in the bottom thumb zone"
    },
    {
      "zh": "工具型界面需要比行内按钮更强的操作召唤",
      "en": "A tool-like surface needs a stronger call to action than an inline button"
    }
  ],
  "avoid_when": [
    {
      "zh": "有多个并列主操作（并列会互相削弱，用底部操作条）",
      "en": "Several co-equal primary actions — they cancel out; use a bottom action bar"
    },
    {
      "zh": "操作是破坏性的（删除、清空）",
      "en": "Destructive actions (delete, wipe)"
    },
    {
      "zh": "会遮挡关键内容或底部导航",
      "en": "It would cover key content or the bottom navigation"
    }
  ],
  "tags": [
    "action",
    "floating",
    "mobile",
    "material"
  ],
  "variants": [
    {
      "id": "single",
      "name": {
        "zh": "单一圆形",
        "en": "Single"
      },
      "note": {
        "zh": "纯图标圆形按钮，最常见形态",
        "en": "Icon-only circle — the classic form"
      }
    },
    {
      "id": "extended",
      "name": {
        "zh": "扩展标签",
        "en": "Extended"
      },
      "note": {
        "zh": "图标 + 文字标签，行动意图更明确",
        "en": "Icon plus label — a clearer call to action"
      }
    },
    {
      "id": "speed-dial",
      "name": {
        "zh": "快捷扇出",
        "en": "Speed dial"
      },
      "note": {
        "zh": "点击扇出多个子动作，再点收起",
        "en": "Fans out several sub-actions on click, retracts on second click"
      }
    }
  ],
  "anatomy": [
    "按钮主体（Button body）",
    "图标（Icon）",
    "扩展标签 / 子动作（Label / Speed dial actions）"
  ],
  "api": [
    "<button>",
    "position",
    "box-shadow",
    "aria-expanded"
  ],
  "framework_names": [
    {
      "framework": "MUI",
      "name": "Fab",
      "url": "https://mui.com/material-ui/react-fab/"
    },
    {
      "framework": "Ionic",
      "name": "Fab",
      "url": "https://ionicframework.com/docs/api/fab"
    },
    {
      "framework": "Material Design",
      "name": "FAB",
      "url": "https://m3.material.io/components/floating-action-button/overview"
    }
  ],
  "playground": {
    "task": {
      "zh": "点击右下角悬浮按钮，展开子动作后再收起，观察它与内容的层级关系。",
      "en": "Tap the corner FAB, fan out the sub-actions and retract; watch how it layers over content."
    },
    "checks": [
      {
        "zh": "按钮悬浮于滚动内容之上且不被遮挡",
        "en": "The button floats above scrolling content and stays unoccluded"
      },
      {
        "zh": "扇出的子动作均可键盘到达",
        "en": "Every fanned-out sub-action is keyboard reachable"
      }
    ]
  },
  "applicable_styles": [
    "neobrutalism",
    "liquid-glass",
    "claymorphism",
    "minimalism",
    "flat-design",
    "swiss-style",
    "glassmorphism",
    "cyberpunk"
  ],
  "related": [
    {
      "id": "button",
      "relation": "alternative_to"
    },
    {
      "id": "press-feedback",
      "relation": "used_with"
    },
    {
      "id": "ripple",
      "relation": "used_with"
    }
  ],
  "demo": {
    "component": "fab",
    "modes": [
      "default",
      "dark",
      "variants"
    ]
  },
  "sources": [
    {
      "name": "Material Design — Floating action button",
      "url": "https://m3.material.io/components/floating-action-button/overview"
    },
    {
      "name": "Apple HIG — Buttons",
      "url": "https://developer.apple.com/design/human-interface-guidelines/buttons"
    }
  ],
  "implementation": {
    "css": [
      "position: fixed",
      "border-radius",
      "box-shadow",
      "transform",
      "transition"
    ],
    "notes": {
      "zh": "position: fixed（或 absolute 于滚动容器外）锚定角落，圆形用 border-radius: 9999px； 抬升靠 box-shadow 多层阴影而非描边。扇出的子动作用 scale + opacity 依次错开出现， 主按钮旋转 45° 变关闭。按压 scale(0.94) 反馈；触控目标不小于 48px；尊重 prefers-reduced-motion。",
      "en": "Anchor the corner with position: fixed (or absolute outside the scroller); make it circular with border-radius: 9999px; elevation comes from layered box-shadows, not outlines. Speed-dial actions stagger in with scale + opacity while the main button rotates 45° into a close affordance. Press feedback is scale(0.94); keep the touch target ≥ 48px; respect prefers-reduced-motion."
    }
  },
  "prompts": {
    "basic": {
      "zh": "创建一个悬浮按钮（FAB）组件：圆形图标按钮固定在右下角，点击扇出多个子动作。",
      "en": "Create a Floating Action Button: a circular icon button pinned to the bottom-right corner that fans out several sub-actions on click."
    },
    "design": {
      "zh": "创建 FAB：56px 圆形、主色填充、白色图标、多层柔和阴影；右下角距边 16px； 扩展形态为图标 + 标签胶囊；扇出子动作为 40px 小圆钮，从下往上错开浮现； 按压轻微缩小；深浅色主题一致。",
      "en": "Create a FAB: a 56px circle, accent fill, white icon, layered soft shadow; 16px from the bottom-right edge; the extended form is an icon-plus-label pill; speed-dial actions are 40px mini circles staggering upward; subtle press scale; consistent light/dark themes."
    },
    "implementation": {
      "zh": "用 React + Tailwind 实现 FAB：variant 映射 single / extended / speed-dial；open 受控， 子动作用 CSS transition 交错 delay 呈现；role=\"menu\" 或 group 语义，aria-expanded 标在主按钮上；主按钮点击切换 open，Esc 收起并归还焦点；active:scale-[0.94] 按压反馈； 尊重 prefers-reduced-motion。无新增依赖。",
      "en": "React + Tailwind FAB: a variant map for single / extended / speed-dial; controlled open state with staggered CSS transition delays on sub-actions; role=\"menu\" or group semantics with aria-expanded on the main button; clicking toggles open, Esc retracts and restores focus; active:scale-[0.94] press feedback; respect prefers-reduced-motion. No new dependencies."
    },
    "agent": {
      "zh": "在当前项目中实现一个 FAB 悬浮按钮组件。\n先检查现有组件体系和 Design Token，优先复用当前按钮与阴影变量。\n与行内主按钮区分：悬浮、常驻、一屏一个。\n保持现有项目视觉风格。不要新增不必要依赖。\n尊重 prefers-reduced-motion，支持键盘操作。\n完成后运行项目现有检查，并列出修改的文件。",
      "en": "Implement a Floating Action Button in the current project.\nInspect the existing component system and design tokens first; reuse button and shadow\nvariables.\nKeep it distinct from an inline primary button: floating, persistent, one per screen.\nKeep the project's visual style. Add no unnecessary dependencies.\nRespect prefers-reduced-motion and support keyboard operation.\nRun the project's existing checks when done and list the modified files."
    }
  }
}