Button Component Specification
Semantic, sizing, shape, state, and accessibility guidelines for Buttons and IconButtons.
AIButton reuses Button sizing and semantics while adding a distinct, perceptible Qokit AI state.
Select the AI button to preview its working state.
Qokit Button Component Specification
This document defines button usage rules across the Qokit platform, Builder, CMS, Dashboard, Admin, marketing pages, and generated sites. The goal is to unify component behavior, semantics, shape, size, iconography, states, and accessibility, preventing individual routes from redesigning buttons via local CSS.
1. Core Model
Buttons are not categorized merely by "oval" or "circle." They consist of five independent dimensions:
Component type × semantic priority × size × shape × spatial elevation
Button / IconButton × primary / secondary / ghost / danger × sm / md / lg × pill / rounded × flat / raised / floating- Component Type determines whether visible text is present and if a square click area must be maintained.
- Semantic Priority dictates the priority and color of the button within the current task.
- Size defines stable height, font size, and touch target area.
- Shape only determines border radius and does not convey priority or business semantics.
- Spatial Elevation only describes whether the control leaves its current plane; it does not change action semantics.
Do not create new button types by combining additional class names. Always select from existing properties of shared components first.
2. Component Selection
Button
Used for all actions with visible text, including:
- Text-only buttons;
- Buttons with icons preceding text;
- Buttons with icons following text;
- Page links styled as buttons.
In the platform, Button defaults to fully rounded pill, appearing visually as an oval. As long as the button contains visible text, it should not be replaced with a circular icon button.
variant is independent from shadow. primary defaults to raised; secondary, danger, and ghost default to flat. Actions inside rows, cards, toolbars, and composite pills stay flat; a standalone primary action may use raised; only an action floating above content uses floating. A standalone pill or segmented control draws elevation only on its outer shell, and routes must not rewrite the shared elevation with local CSS.
import { Button } from '@qokit/components/ui';
<Button type="button" variant="primary">
保存
</Button>
<Button
leadingIcon={<SaveIcon aria-hidden="true" />}
type="button"
variant="primary"
>
保存
</Button>
<Button
href="/projects"
trailingIcon={<ArrowRightIcon aria-hidden="true" />}
variant="secondary"
>
查看项目
</Button>IconButton
Used for compact tool actions containing only an icon and no visible text, such as close, more, back, toggle menu, or delete.
IconButton maintains equal width and height with full rounding at every size, resulting in a visually circular button. It defaults to ghost and enforces aria-label at the type level.
import { IconButton } from '@qokit/components/ui';
<IconButton aria-label="关闭" tooltip="关闭" type="button">
<CloseIcon aria-hidden="true" />
</IconButton>Rules:
- The icon itself uses
aria-hidden="true", while the button name is provided byaria-label. - For unfamiliar or ambiguous icons, always use shared
Tooltip; tooltips cannot replacearia-label. - Do not use the DOM
titleattribute as a product hint and do not combinetooltipwith a manually wrapped Tooltip. - A Tooltip is a read-only information layer, not an oval button. It uses the shared compact tooltip radius and must not reuse
pill, button hover, pressed, or focus visuals. - Do not simulate
IconButtonusingButtonwith empty, hidden, or fixed-width text. - Do not set
shapeonIconButton; circularity is part of its component contract.
Scenarios where Button Should Not Be Used
- Tabs should use Tabs/PillTabs/Segmented components.
- Menu items should use Menu/ActionMenu components.
- States, labels, and filter results should use Pill or status components.
- Standard text navigation should use semantic links; only use
Buttonwithhrefwhen button-level visual emphasis is required.
3. Semantic Levels variant
| Variant | Meaning | Typical Scenario | Usage Constraints |
|---|---|---|---|
primary | Primary action for the current area | Save, Publish, Create, Try Now | Usually only one primary action per task area |
secondary | Explicit but secondary action | Preview, Cancel, Back, Import | Should not compete visually with the primary action |
ghost | Low-emphasis, contextual tool action | Close, More, Toolbar actions, Lightweight back | Transparent by default; cannot serve as the sole critical CTA |
danger | Destructive actions causing significant impact | Delete Item, Remove Content, Clear Data | Expresses destructive semantics only; not used as standard emphasis color |
variant expresses semantic and visual hierarchy, not shape. For example, ghost can be an oval button with text or a circular IconButton.
Selection Order:
- Identify the single most important next step for the current task and set it as
primary. - Use
secondaryfor auxiliary actions that still need to be clearly visible. - Use
ghostfor low-emphasis actions in toolbars or contexts. - Use
dangeronly for actual destructive actions, adhering to existing confirmation flows.
Do not choose variants based on "which color looks better."
4. Sizes size
| Size | Height/Diameter | Font Size | Recommended Scenario |
|---|---|---|---|
sm | 40px | 14px | Top navigation, compact toolbars, dense workspaces |
md | 44px | 15px | Default forms, CMS, dialogs, and routine actions |
lg | 48px | 16px | Marketing page primary CTAs, main actions requiring stronger touch targets |
Default size is md.
- Use the same size within a single button group.
- Compact controls must not be lower than 40px; mobile primary actions should prioritize at least 44px.
Buttonheight andIconButtondiameter share the same size tokens, allowing alignment in the same toolbar;IconButtonvisible icons are uniformly 18px.Buttonfont sizes are determined by shared tokens corresponding to the size, not inherited from Header, Dialog, or other parent containers.- Route CSS can control button layout, spacing, and necessary widths, but cannot redefine shared button heights or font sizes.
- When copy is long, prioritize adjusting layout or button containers rather than compressing height, font, or horizontal spacing.
5. Shapes shape
| Shape | Appearance | Scope of Use |
|---|---|---|
pill | Fully rounded; oval when containing text | Platform default; suitable for marketing pages, Dashboard, Builder, CMS, and Admin |
rounded | 12px border radius | Only when generated site themes explicitly require smaller rounding |
Button defaults to shape="pill". Platform frontend should not explicitly set rounded, nor override border radius in local CSS.
// 平台默认:省略 shape 即为 pill
<Button type="button" variant="primary">保存</Button>
// 仅生成站点主题有明确视觉要求时使用
<Button shape="rounded" type="button" variant="primary">
预约咨询
</Button>IconButton is always circular and does not participate in the business selection between pill and rounded.
Tooltips do not participate in button shape selection. Text buttons are oval, icon-only buttons are circular, and Tooltip bubbles remain compact rounded rectangles so the three roles are visually distinct.
6. Icon Rules
- Use
leadingIconfor icons preceding text andtrailingIconfor icons following text. - A button typically uses only one auxiliary icon.
- Familiar actions such as Save, Add, or Back can use icons to reinforce recognition, but icons must not replace the visible text of critical buttons.
- Arrows indicating Continue, Enter, or Expand are usually placed after the text; Back icons are usually placed before the text.
- Do not manually layout icons and text within
children; the component already provides icon and label slots. - Use shared icons and inherit
currentColor; do not hardcode icon colors or sizes in route CSS. - Loading states should maintain the button's original width and height, and provide understandable short copy or existing loading feedback; avoid toolbar jumping caused by text switching.
7. Buttons and Links
Actions and navigation must use correct semantics:
- For current page actions such as Submit, Save, Open Modal, or Toggle State, use
Buttonwithouthref, which renders as<button>. - To navigate to another route or resource, use
Buttonwithhref, which renders as Next.js<Link>. - Non-submit buttons within forms must explicitly set
type="button"; submit buttons must explicitly settype="submit". - Do not use
onClickto simulate normal page navigation.
Disabled links use aria-disabled and exit the Tab order; disabled native buttons use disabled. Disabled states must not rely solely on reduced opacity; business logic must also prevent the action.
8. States and Accessibility
Shared components uniformly handle hover, focus-visible, disabled, and color states. Business code must still satisfy:
- Ordinary unselected buttons use
--control-surface-hoveron hover; pressed, selected, and expanded states use--control-surface-active.focus-visibleretains--focus-ringover the neutral surface, and route styles must not merge hover with persistent states into one blue rule. - Button names must be direct, specific, and describe what will happen, e.g., "Save", "Publish Site", "Delete Project".
IconButtonmust provide localizedaria-label.- Decorative icons use
aria-hidden="true"to avoid screen reader repetition. - Keyboard focus must be visible; route CSS must not remove the shared focus ring.
- Do not rely on hover as the only hint; interactions must support both keyboard and touch.
- Disable buttons only for actions the user cannot perform temporarily; if an explanation is needed, provide adjacent text or a tooltip.
- Keep errors, permission requirements, risk, cost, and other task-critical information visible; Tooltip content is supplementary and cannot be the only way to discover it.
- Asynchronous operations must prevent duplicate submissions and retain understandable in-progress feedback.
- Dangerous actions use
dangerand reuse existing dangerous confirmation patterns; do not rely solely on red to convey risk. - Button copy in Chinese or other languages must not be truncated to the point of incomprehensibility. Verify long copy and mobile widths.
9. Style Responsibility Boundaries
The structure, semantics, and states of shared buttons are handled by Button / IconButton; visual tokens and shared CSS are handled by the component package; routes are responsible only for layout.
Shared Layer Responsibilities
- DOM, link/button semantics, disabled behavior;
- icon/label slots and accessibility type constraints;
- variant, size, shape classes;
- height, border-radius, padding, font-size, font-weight;
- background, text color, shadow, hover, focus-visible, and disabled states.
Route Layer Can Handle
- Button group direction, spacing, alignment, and wrapping;
- Responsive layouts;
width: 100%or container widths required by specific workflows;- Positioning classes that do not alter base visuals.
Route Layer Must Not Handle
- Overriding button height, font-size, border-radius, background, text color, shadow, or focus ring;
- Using hardcoded colors or
border-radius: 999pxto reimplement shared buttons; - Adding local visual variants like
primary-alt,outline-blue,icon-round; - Competing with the shared button contract via
!important; - Directly copying the base styles of
.qk-ui-button.
If a new semantic variant is indeed needed across multiple pages, first establish a unified contract in the shared ButtonVariant, tokens, and primitives.css, rather than adding styles in the route.
10. API Quick Reference
type ButtonVariant = 'primary' | 'secondary' | 'ghost' | 'danger';
type ButtonSize = 'sm' | 'md' | 'lg';
type ButtonShape = 'rounded' | 'pill';Main properties of Button:
| Property | Default | Description |
|---|---|---|
variant | primary | Semantic and visual hierarchy |
size | md | Height, text font-size, and horizontal padding |
shape | pill | Border-radius shape for Button |
leadingIcon | None | Icon preceding text |
trailingIcon | None | Icon following text |
href | None | Renders as a link when provided |
disabled | false | Disables interaction |
tooltip | None | Supplementary shared Tooltip content; never replaces visible critical copy or aria-label |
tooltipPlacement | bottom | Preferred side; the shared Tooltip may flip to stay in the viewport |
tooltipPortal | true | Renders outside clipping containers without adding a layout wrapper |
skin | None | Provides class slot and variable adaptation according to skeleton/skin contract |
IconButton inherits applicable Button properties, but does not provide shape, leadingIcon, or trailingIcon; it requires aria-label, defaulting to variant="ghost".
It is recommended to explicitly write variant and native button type in business code to make action semantics clearly visible during code review.
11. Common Combinations
// 主要操作:椭圆形文字按钮
<Button type="submit" variant="primary">
保存
</Button>
// 次要操作
<Button type="button" variant="secondary" onClick={onPreview}>
预览
</Button>
// 低强调文字操作
<Button type="button" variant="ghost" onClick={onCancel}>
取消
</Button>
// 图标 + 文字,仍然使用 Button
<Button
leadingIcon={<PlusIcon aria-hidden="true" />}
type="button"
variant="primary"
>
新建内容
</Button>
// 纯图标:圆形按钮
<IconButton aria-label="更多操作" tooltip="更多操作" type="button">
<MoreIcon aria-hidden="true" />
</IconButton>
// 危险操作
<Button type="button" variant="danger" onClick={openDeleteConfirm}>
删除项目
</Button>12. Review Checklist
Before submitting UI related to buttons, confirm:
- Have you prioritized reusing
ButtonorIconButton? - Did you select the correct component for buttons with text versus pure icon buttons?
- Is there only one clear
primaryin the current task area? - Are
secondary,ghost,dangerused according to semantics rather than color preference? - Does platform
Buttonkeep the defaultpill, and doesIconButtonremain circular? - Does every Tooltip remain a compact rounded information layer rather than looking like an oval clickable button?
- Are browser-native
title, CSSdata-tooltipbubbles, duplicate hints, and redundant text-button tooltips absent? - Are sizes only using
sm,md,lg, with consistent height and font-size within the same group? - Has the native button explicitly set the correct
type? - Do icons hide redundant screen reader information, and does
IconButtonhave localizedaria-label? - Are focus-visible, disabled, asynchronous, and danger confirmation states complete?
- Does route CSS only handle layout without overriding base button visuals?
- Have you verified long copy, touch targets, and button group arrangements at desktop and mobile widths?
13. Implementation Source
- Component API:
packages/components/src/ui/Button/Button.tsx - Component Export:
packages/components/src/ui/Button/index.ts - Size and Color Tokens:
packages/components/src/styles/foundations.css - Shared Button Styles:
packages/components/src/styles/primitives.css - Public Component Integration Contract:
docs/public/design/component-integration.md
When there is a discrepancy between the documentation and the implementation, synchronize the component, tokens, styles, and this document within the same change.