Skip to Content
Design

Button Component Specification

Semantic, sizing, shape, state, and accessibility guidelines for Buttons and IconButtons.

Live componentButton / IconButton / AIButton

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 by aria-label.
  • For unfamiliar or ambiguous icons, always use shared Tooltip; tooltips cannot replace aria-label.
  • Do not use the DOM title attribute as a product hint and do not combine tooltip with 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 IconButton using Button with empty, hidden, or fixed-width text.
  • Do not set shape on IconButton; 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 Button with href when button-level visual emphasis is required.

3. Semantic Levels variant

VariantMeaningTypical ScenarioUsage Constraints
primaryPrimary action for the current areaSave, Publish, Create, Try NowUsually only one primary action per task area
secondaryExplicit but secondary actionPreview, Cancel, Back, ImportShould not compete visually with the primary action
ghostLow-emphasis, contextual tool actionClose, More, Toolbar actions, Lightweight backTransparent by default; cannot serve as the sole critical CTA
dangerDestructive actions causing significant impactDelete Item, Remove Content, Clear DataExpresses 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:

  1. Identify the single most important next step for the current task and set it as primary.
  2. Use secondary for auxiliary actions that still need to be clearly visible.
  3. Use ghost for low-emphasis actions in toolbars or contexts.
  4. Use danger only for actual destructive actions, adhering to existing confirmation flows.

Do not choose variants based on "which color looks better."

4. Sizes size

SizeHeight/DiameterFont SizeRecommended Scenario
sm40px14pxTop navigation, compact toolbars, dense workspaces
md44px15pxDefault forms, CMS, dialogs, and routine actions
lg48px16pxMarketing 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.
  • Button height and IconButton diameter share the same size tokens, allowing alignment in the same toolbar; IconButton visible icons are uniformly 18px.
  • Button font 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

ShapeAppearanceScope of Use
pillFully rounded; oval when containing textPlatform default; suitable for marketing pages, Dashboard, Builder, CMS, and Admin
rounded12px border radiusOnly 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 leadingIcon for icons preceding text and trailingIcon for 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.

Actions and navigation must use correct semantics:

  • For current page actions such as Submit, Save, Open Modal, or Toggle State, use Button without href, which renders as <button>.
  • To navigate to another route or resource, use Button with href, which renders as Next.js <Link>.
  • Non-submit buttons within forms must explicitly set type="button"; submit buttons must explicitly set type="submit".
  • Do not use onClick to 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-hover on hover; pressed, selected, and expanded states use --control-surface-active. focus-visible retains --focus-ring over 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".
  • IconButton must provide localized aria-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 danger and 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: 999px to 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:

PropertyDefaultDescription
variantprimarySemantic and visual hierarchy
sizemdHeight, text font-size, and horizontal padding
shapepillBorder-radius shape for Button
leadingIconNoneIcon preceding text
trailingIconNoneIcon following text
hrefNoneRenders as a link when provided
disabledfalseDisables interaction
tooltipNoneSupplementary shared Tooltip content; never replaces visible critical copy or aria-label
tooltipPlacementbottomPreferred side; the shared Tooltip may flip to stay in the viewport
tooltipPortaltrueRenders outside clipping containers without adding a layout wrapper
skinNoneProvides 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 Button or IconButton?
  • Did you select the correct component for buttons with text versus pure icon buttons?
  • Is there only one clear primary in the current task area?
  • Are secondary, ghost, danger used according to semantics rather than color preference?
  • Does platform Button keep the default pill, and does IconButton remain circular?
  • Does every Tooltip remain a compact rounded information layer rather than looking like an oval clickable button?
  • Are browser-native title, CSS data-tooltip bubbles, 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 IconButton have localized aria-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.

On this page