{
  "id": "button",
  "type": "components",
  "status": "published",
  "name": {
    "zh": "按钮",
    "en": "Button"
  },
  "aliases": [
    "按钮",
    "按键",
    "点击按钮",
    "主按钮",
    "提交按钮",
    "CTA 按钮"
  ],
  "category": [
    "Action",
    "Form"
  ],
  "description": {
    "zh": "用可点击的色块触发一个明确的动作，是界面中最基础的操作入口。 通过填充、描边、幽灵等视觉层级区分主次操作，按压时有即时的下沉反馈， 繁忙时进入加载态并禁用点击，防止重复提交。",
    "en": "A clickable block that triggers one clear action — the most basic interactive element of any interface. Fill, outline and ghost styles rank primary against secondary actions; presses give instant sink-in feedback, and a busy state disables further clicks to prevent double submission."
  },
  "use_when": [
    {
      "zh": "需要用户主动触发一个明确动作（提交、创建、确认）",
      "en": "A user-initiated action such as submit, create or confirm"
    },
    {
      "zh": "同一区域存在主次多个操作，需要视觉分层",
      "en": "Multiple actions coexist and need visual hierarchy"
    },
    {
      "zh": "操作会改变数据或状态，需要防止误触与重复提交",
      "en": "The action mutates data and must guard against double submits"
    }
  ],
  "avoid_when": [
    {
      "zh": "动作只是导航到另一页，用链接更符合预期",
      "en": "Pure navigation — a link matches expectations better"
    },
    {
      "zh": "操作可逆且频繁切换，用开关或复选框更合适",
      "en": "Frequently toggled reversible state — use a switch or checkbox"
    },
    {
      "zh": "一屏内大量重复的次要操作，弱化为文字按钮避免视觉噪音",
      "en": "Many repeated secondary actions — demote to text buttons to cut noise"
    }
  ],
  "tags": [
    "action",
    "form",
    "interaction"
  ],
  "api": [
    "<button>",
    "type",
    "role=\"button\""
  ],
  "framework_names": [
    {
      "framework": "HTML",
      "name": "<button>",
      "url": "https://developer.mozilla.org/en-US/docs/Web/HTML/Element/button"
    },
    {
      "framework": "shadcn/ui",
      "name": "Button",
      "url": "https://ui.shadcn.com/docs/components/button"
    },
    {
      "framework": "MUI",
      "name": "Button",
      "url": "https://mui.com/material-ui/react-button/"
    },
    {
      "framework": "AntD",
      "name": "Button",
      "url": "https://ant.design/components/button"
    }
  ],
  "variants": [
    {
      "id": "primary",
      "name": {
        "zh": "主要",
        "en": "Primary"
      },
      "note": {
        "zh": "实心填充，一屏内主操作唯一",
        "en": "Solid fill — the single primary action per view"
      }
    },
    {
      "id": "secondary",
      "name": {
        "zh": "次要",
        "en": "Secondary"
      },
      "note": {
        "zh": "描边样式，与主操作并列",
        "en": "Outlined style, paired with the primary"
      }
    },
    {
      "id": "ghost",
      "name": {
        "zh": "幽灵",
        "en": "Ghost"
      },
      "note": {
        "zh": "无边框纯文字，弱化视觉重量",
        "en": "Borderless text-only, minimal visual weight"
      }
    },
    {
      "id": "danger",
      "name": {
        "zh": "危险",
        "en": "Danger"
      },
      "note": {
        "zh": "不可逆操作的警示色",
        "en": "Warning color for irreversible actions"
      }
    }
  ],
  "anatomy": [
    "容器（Container）",
    "标签文字（Label）",
    "前置 / 后置图标（Icon）",
    "加载指示（Spinner）"
  ],
  "applicable_styles": [
    "minimalism",
    "neobrutalism",
    "glassmorphism",
    "swiss-style",
    "cyberpunk",
    "neumorphism",
    "flat-design",
    "pixel-art",
    "brutalism",
    "corporate-memphis",
    "aurora",
    "liquid-glass",
    "claymorphism",
    "y2k",
    "retro-futurism",
    "skeuomorphism",
    "organic",
    "editorial",
    "art-deco",
    "hand-drawn",
    "bauhaus"
  ],
  "applicable_components": [],
  "applicable_pages": [
    "login",
    "checkout",
    "settings"
  ],
  "related": [
    {
      "id": "press-feedback",
      "relation": "alternative_to"
    },
    {
      "id": "ripple",
      "relation": "used_with"
    },
    {
      "id": "magnetic-button",
      "relation": "used_with"
    },
    {
      "id": "hover-lift",
      "relation": "used_with"
    },
    {
      "id": "loading-spinner",
      "relation": "used_with"
    }
  ],
  "demo": {
    "component": "button",
    "modes": [
      "default",
      "dark",
      "variants"
    ]
  },
  "compare": {
    "group": "click-feedback",
    "dimensions": {
      "强度": {
        "zh": "低～中，轻微下沉即可",
        "en": "Low to medium — a subtle sink is enough"
      },
      "移动端友好": {
        "zh": "好，触控目标不小于 44px",
        "en": "Good — keep touch targets ≥ 44px"
      },
      "适合元素": {
        "zh": "按钮 / 小尺寸可点块",
        "en": "Buttons / small clickable blocks"
      }
    }
  },
  "implementation": {
    "css": [
      "transition",
      "transform: scale(0.97)",
      "background",
      "box-shadow"
    ],
    "notes": {
      "zh": "用 transition 让颜色与阴影平滑变化，按压瞬间加 scale(0.97) 下沉； focus-visible 描边保证键盘可达；加载态将文字替换为 spinner 并 disabled， 保留按钮宽度避免布局跳动。触控目标高度不小于 44px。",
      "en": "Transition colors and shadows smoothly; add scale(0.97) on the press frame. Keep a focus-visible ring for keyboard access. In the busy state swap the label for a spinner while disabled, preserving width to avoid layout shift. Touch targets should be at least 44px tall."
    }
  },
  "sources": [
    {
      "name": "Material Design — Common buttons",
      "url": "https://m3.material.io/components/buttons/overview"
    },
    {
      "name": "Apple HIG — Buttons",
      "url": "https://developer.apple.com/design/human-interface-guidelines/buttons"
    }
  ],
  "prompts": {
    "basic": {
      "zh": "创建一个按钮组件，支持主要、次要、幽灵、危险四种样式和加载状态。",
      "en": "Create a button component with primary, secondary, ghost and danger styles plus a loading state."
    },
    "design": {
      "zh": "创建按钮组件。要求：四种层级（实心主按钮、描边次按钮、幽灵文字按钮、危险按钮）， 按压有轻微下沉反馈，加载时显示 spinner 并禁用点击且保持宽度不变， 支持 icon 前置位，深浅色主题一致。",
      "en": "Create a button component. Requirements: four levels (solid primary, outlined secondary, ghost text, danger), a subtle press-down feedback, a loading state with spinner that disables clicks and preserves width, optional leading icon, consistent in light/dark themes."
    },
    "implementation": {
      "zh": "用 React + Tailwind 实现 Button：variant 与 size 走映射表；disabled 与 loading 合并控制 pointer-events；点击反馈用 active:scale-[0.97] + transition；加载态渲染 spinner 并保留 min-width；支持 asChild 或 as=\"a\" 复用到链接场景。 尊重 prefers-reduced-motion（去掉位移类动画）。",
      "en": "React + Tailwind Button: variant and size via lookup maps; disabled and loading merged into pointer control; press feedback with active:scale-[0.97] and transition; busy state renders a spinner and keeps min-width; support an anchor variant for link use. Respect prefers-reduced-motion."
    },
    "agent": {
      "zh": "在当前项目中实现按钮组件。\n\n先检查现有的 Design Token 与按钮类样式，优先复用现有颜色与圆角变量。\n要求：\n- 主要 / 次要 / 幽灵 / 危险四种样式\n- 按压反馈与 focus-visible 键盘焦点样式\n- 加载态：spinner + disabled + 宽度不变\n- 深浅色主题一致，尊重 prefers-reduced-motion\n- 不新增依赖\n完成后运行项目现有检查，并列出修改的文件。",
      "en": "Implement a button component in the current project.\n\nInspect the existing design tokens and button-like styles first; reuse existing color and radius variables.\nRequirements:\n- Primary / secondary / ghost / danger variants\n- Press feedback and a focus-visible keyboard focus style\n- Loading state: spinner + disabled + unchanged width\n- Consistent light/dark themes, respect prefers-reduced-motion\n- No new dependencies\nRun existing project checks when done and list the modified files."
    }
  },
  "playground": {
    "task": {
      "zh": "在本地模拟中点击保存，处理中取消，再用键盘重试；比较 21 种风格和四种按钮层级。",
      "en": "Save in the local simulation, cancel while pending, then retry with the keyboard. Compare 21 styles and four button levels."
    },
    "checks": [
      {
        "zh": "同一区域通常只有一个最突出的主操作。",
        "en": "Usually give one action the strongest emphasis in a region."
      },
      {
        "zh": "处理中的操作应防止重复触发并保留结果反馈。",
        "en": "Prevent duplicate activation while processing and show the result."
      },
      {
        "zh": "取消处理中操作后，旧完成回调不能再显示成功；仍可重新尝试。",
        "en": "Cancelling a pending action must suppress late success callbacks and allow retry."
      },
      {
        "zh": "Enter / Space 与点击触发相同的行为，焦点可见，触控目标不小于 44px。",
        "en": "Enter / Space and pointer activation trigger the same behavior, with visible focus and touch targets at least 44px tall."
      }
    ]
  }
}