Skip to Content
Conception

Bouton Button

Spécifications sémantiques, de taille, de forme, d'état et d'accessibilité pour Button et IconButton.

Composant en directBouton / IconButton / AIButton

AIButton réutilise la taille et les sémantiques du bouton tout en ajoutant un état Qokit IA distinct et perceptible.

Sélectionnez le bouton IA pour apercevoir son état de fonctionnement.

Spécifications du composant Button de Qokit

Ce document définit les règles d'utilisation des boutons dans la plateforme Qokit, Builder, CMS, Dashboard, Admin, les pages marketing et les sites générés. L'objectif est d'unifier les composants, la sémantique, la forme, la taille, les icônes, les états et l'accessibilité des boutons, afin d'éviter que chaque route ne redessine les boutons via du CSS local.

1. Modèle fondamental

Les boutons ne sont pas classés uniquement en « ovales » et « ronds », mais sont composés de cinq dimensions indépendantes :

Component type × semantic priority × size × shape × spatial elevation
Button / IconButton × primary / secondary / ghost / danger × sm / md / lg × pill / rounded × flat / raised / floating
  • Le type de composant détermine si le bouton affiche du texte visible et s'il doit conserver une zone de clic carrée.
  • La priorité sémantique détermine la priorité et la couleur du bouton dans la tâche en cours.
  • La taille détermine la hauteur stable, la taille de police du texte et la zone tactile.
  • La forme détermine uniquement le rayon de bordure, sans exprimer de priorité ni de sémantique métier.
  • La couche spatiale indique uniquement si le contrôle s'élève au-dessus du plan courant, sans modifier la sémantique de l'action.

Ne créez pas de nouveaux types de boutons en combinant de nouvelles classes. Commencez par choisir parmi les propriétés existantes des composants partagés.

2. Sélection des composants

Button

Utilisé pour toutes les actions avec du texte visible, notamment :

  • Les boutons texte uniquement ;
  • Les boutons avec icône avant le texte ;
  • Les boutons avec icône après le texte ;
  • Les liens de page ayant l'apparence d'un bouton.

Le Button de la plateforme utilise par défaut le pill entièrement arrondi, ce qui donne visuellement une forme ovale. Tant qu'un bouton contient du texte visible, il ne doit pas être remplacé par un bouton icône circulaire.

variant est découplé de l'ombre : primary utilise par défaut raised, tandis que secondary, danger et ghost utilisent par défaut flat. Les actions à l'intérieur des lignes de liste, des cartes, des barres d'outils et des capsules composées doivent être en flat ; les actions principales indépendantes peuvent utiliser raised ; seules les actions flottant au-dessus du contenu utilisent floating. Les capsules indépendantes ou les contrôles segmentés ne dessinent qu'une seule ombre au niveau le plus externe ; les routes ne doivent pas réécrire les couches partagées via du CSS local.

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

Utilisé pour les actions d'outil compactes ne comportant qu'une icône sans texte visible, par exemple fermer, plus, retour, basculer le menu ou supprimer.

IconButton conserve une largeur, une hauteur et un arrondi complet identiques à chaque taille, ce qui en fait visuellement un bouton circulaire. Il utilise par défaut ghost et impose au niveau du type aria-label.

import { IconButton } from '@qokit/components/ui';

<IconButton aria-label="关闭" tooltip="关闭" type="button">
  <CloseIcon aria-hidden="true" />
</IconButton>

Règles :

  • L'icône elle-même utilise aria-hidden="true" ; le nom du bouton est fourni par aria-label.
  • Les icônes peu familières ou dont la signification peut être ambiguë doivent également utiliser le Tooltip partagé ; un tooltip ne peut pas remplacer aria-label.
  • N'utilisez pas l'attribut DOM title comme indice produit, et ne définissez pas simultanément tooltip tout en enveloppant manuellement un Tooltip.
  • Le Tooltip est une couche d'information en lecture seule, pas un bouton ovale. Il utilise l'arrondi compact partagé des tooltips et ne doit pas réutiliser les visuels pill, hover, pressed ou focus des boutons.
  • N'utilisez pas de Button avec du texte vide, du texte masqué ou une largeur fixe pour simuler un IconButton.
  • Ne définissez pas shape sur IconButton ; la forme circulaire fait partie de son contrat de composant.

Scénarios où Button ne doit pas être utilisé

  • Les onglets utilisent les composants correspondants Tabs/PillTabs/Segmented.
  • Les éléments de menu utilisent les composants correspondants Menu/ActionMenu.
  • Les états, étiquettes et résultats de filtrage utilisent Pill ou les composants d'état.
  • La navigation textuelle ordinaire utilise des liens sémantiques ; un Button avec href n'est utilisé que lorsqu'une emphase visuelle de niveau bouton est nécessaire.

3. Hiérarchie sémantique variant

VariantSignificationScénarios typiquesRestrictions d'utilisation
primaryAction principale de la zone couranteEnregistrer, publier, créer, essayer maintenantUne zone de tâche ne conserve généralement qu'une seule action principale
secondaryAction claire mais secondaireAperçu, annuler, retour, importerNe doit pas rivaliser visuellement avec l'action principale
ghostAction d'outil contextuelle à faible emphaseFermer, plus, actions de barre d'outils, retour légerTransparent par défaut, ne peut pas être le seul CTA critique
dangerAction qui supprime ou cause une destruction notableSupprimer un élément, retirer du contenu, vider des donnéesExprime uniquement la sémantique destructive, pas une couleur d'emphase ordinaire

variant exprime une hiérarchie sémantique et visuelle, pas une forme. Par exemple, ghost peut être un bouton ovale avec du texte ou un IconButton circulaire.

Ordre de sélection :

  1. Identifiez la prochaine étape unique la plus importante de la tâche en cours et définissez-la comme primary.
  2. Les actions secondaires qui doivent rester clairement visibles utilisent secondary.
  3. Les actions à faible emphase dans les barres d'outils ou contextuelles utilisent ghost.
  4. Seules les actions réellement destructrices utilisent danger, en réutilisant le flux de confirmation existant.

Ne choisissez pas un variant en fonction de « quelle couleur est la plus jolie ».

4. Taille size

SizeHauteur/diamètreTaille de policeScénarios recommandés
sm40px14pxNavigation supérieure, barres d'outils compactes, espaces de travail denses
md44px15pxFormulaires par défaut, CMS, boîtes de dialogue et actions courantes
lg48px16pxCTA principal des pages marketing, actions principales nécessitant une meilleure tactilité

La taille par défaut est md.

  • Un même groupe de boutons utilise la même taille.
  • Les contrôles compacts ne doivent pas descendre en dessous de 40px ; les actions principales sur mobile doivent privilégier au moins 44px.
  • La hauteur de Button et le diamètre de IconButton utilisent le même ensemble de tokens de taille, ce qui permet de les aligner dans une même barre d'outils ; la taille visible de l'icône de IconButton est uniformisée à 18px.
  • La taille de police du texte de Button est déterminée par le token partagé correspondant à la taille, et n'hérite pas de la taille de police du Header, du Dialog ou d'un autre conteneur parent.
  • Le CSS des routes peut contrôler l'agencement, l'espacement et la largeur nécessaire des boutons, mais ne doit pas redéfinir la hauteur ou la taille de police des boutons partagés.
  • Lorsque le texte est long, privilégiez l'ajustement de la mise en page ou du conteneur de boutons plutôt que de réduire la hauteur, la police ou l'espacement horizontal.

5. Forme shape

ShapeApparencePortée d'utilisation
pillEntièrement arrondi ; ovale avec du textePar défaut pour la plateforme, adapté aux pages marketing, Dashboard, Builder, CMS et Admin
roundedRayon de bordure de 12pxUtilisé uniquement lorsque le thème du site généré exige explicitement un rayon plus petit

Button est par défaut shape="pill". Le front-end de la plateforme ne doit pas définir explicitement rounded ni écraser le rayon de bordure dans du CSS local.

// 平台默认:省略 shape 即为 pill
<Button type="button" variant="primary">保存</Button>

// 仅生成站点主题有明确视觉要求时使用
<Button shape="rounded" type="button" variant="primary">
  预约咨询
</Button>

IconButton est toujours circulaire et ne participe pas au choix métier pill / rounded.

6. Règles des icônes

  • Les icônes avant le texte utilisent leadingIcon ; les icônes après le texte utilisent trailingIcon.
  • Un bouton n'utilise généralement qu'une seule icône auxiliaire.
  • Les actions courantes comme enregistrer, ajouter ou retourner peuvent utiliser une icône pour renforcer la reconnaissance, mais l'icône ne peut pas remplacer le texte visible des boutons critiques.
  • Les flèches indiquant la poursuite, l'entrée ou le développement sont généralement placées après le texte ; les icônes de retour sont généralement placées avant le texte.
  • Ne codez pas manuellement la disposition de l'icône et du texte dans children ; le composant fournit déjà les emplacements icon et label.
  • Utilisez les icônes partagées et héritez de currentColor ; ne codez pas en dur la couleur ou la taille des icônes dans le CSS des routes.
  • L'état de chargement doit conserver les dimensions d'origine du bouton et fournir un texte court compréhensible ou un retour de chargement existant ; ne laissez pas le changement de texte provoquer des sauts dans la barre d'outils.

7. Boutons et liens

Les actions et la navigation doivent utiliser la sémantique correcte :

  • Les actions sur la page courante telles que soumettre, enregistrer, ouvrir un overlay, basculer un état utilisent un Button sans href, qui sera finalement rendu en <button>.
  • La navigation vers une autre route ou ressource utilise un Button avec href, qui sera finalement rendu en Next.js <Link>.
  • Les boutons non-submit dans un formulaire doivent explicitement écrire type="button" ; les boutons de soumission écrivent explicitement type="submit".
  • N'utilisez pas onClick pour simuler une navigation de page normale.

Les liens désactivés utilisent aria-disabled et sortent de l'ordre de tabulation ; les boutons natifs désactivés utilisent disabled. L'état désactivé ne peut pas être exprimé uniquement par une réduction de l'opacité ; la logique métier doit également bloquer l'action.

8. États et accessibilité

Les composants partagés gèrent de manière uniforme les états hover, focus-visible, disabled et les états de couleur. Le code métier doit néanmoins satisfaire :

  • Le hover des boutons ordinaires non sélectionnés utilise --control-surface-hover ; les états pressed, selected et expanded utilisent --control-surface-active. focus-visible conserve --focus-ring sur les surfaces neutres ; les styles des routes ne doivent pas fusionner le hover et l'état persistant en une seule règle bleu clair.
  • Les noms des boutons doivent être directs, spécifiques et décrire ce qui va se produire, par exemple « Enregistrer », « Publier le site », « Supprimer l'élément ».
  • IconButton doit fournir un aria-label localisé.
  • Les icônes décoratives utilisent aria-hidden="true" pour éviter une lecture répétée par le lecteur d'écran.
  • Le focus clavier doit être visible ; le CSS des routes ne doit pas supprimer le focus ring partagé.
  • Ne faites pas du hover le seul indice ; l'interaction doit prendre en charge à la fois le clavier et le tactile.
  • Les boutons désactivés ne sont utilisés que pour les actions que l'utilisateur ne peut pas exécuter temporairement ; si une explication est nécessaire, fournissez une indication à proximité ou un tooltip.
  • Les erreurs, les exigences de permissions, les risques, les coûts et autres informations critiques pour la tâche doivent rester visibles ; le Tooltip ne peut que compléter les informations et ne doit pas être le seul moyen de les découvrir.
  • Les opérations asynchrones doivent empêcher les soumissions multiples et conserver un retour compréhensible en cours.
  • Les actions dangereuses utilisent danger et réutilisent le pattern de confirmation dangereuse existant ; ne vous fiez pas uniquement au rouge pour transmettre le risque.
  • Le texte des boutons en chinois ou dans d'autres langues ne doit pas être tronqué au point de devenir incompréhensible. Les textes longs et les largeurs mobiles doivent être vérifiés.

9. Périmètres de responsabilité des styles

La structure, la sémantique et les états des boutons partagés sont gérés par Button / IconButton ; les tokens visuels et le CSS partagé sont gérés par le package de composants ; les routes ne gèrent que la mise en page.

Responsabilités de la couche partagée

  • DOM, sémantique lien/bouton, comportement disabled ;
  • Emplacements icon/label et contraintes de type d'accessibilité ;
  • Classes variant, size, shape ;
  • Hauteur, rayon de bordure, padding, taille de police, poids de police ;
  • Arrière-plan, couleur du texte, ombre, états hover, focus-visible et disabled.

Responsabilités de la couche route

  • Direction, espacement, alignement et retour à la ligne des groupes de boutons ;
  • Agencement responsive ;
  • width: 100% ou largeur de conteneur nécessaire pour des workflows spécifiques ;
  • Classes de positionnement qui ne modifient pas le visuel de base.

Ce que la couche route ne doit pas faire

  • Réécrire la hauteur, la taille de police, le rayon de bordure, l'arrière-plan, la couleur du texte, l'ombre ou le focus ring des boutons ;
  • Réimplémenter les boutons partagés avec des couleurs codées en dur ou border-radius: 999px ;
  • Ajouter des variants visuels locaux tels que primary-alt, outline-blue, icon-round ;
  • Rivaliser avec le contrat des boutons partagés via !important ;
  • Copier directement les styles de base de .qk-ui-button.

Si un nouveau variant sémantique nécessaire apparaît sur plusieurs pages, il faut d'abord établir un contrat unifié dans le ButtonVariant partagé, les tokens et primitives.css, plutôt que d'ajouter des styles dans les routes.

10. Référence rapide API

type ButtonVariant = 'primary' | 'secondary' | 'ghost' | 'danger';
type ButtonSize = 'sm' | 'md' | 'lg';
type ButtonShape = 'rounded' | 'pill';

Principales propriétés de Button :

PropriétéValeur par défautDescription
variantprimaryHiérarchie sémantique et visuelle
sizemdHauteur, taille de police du texte et padding horizontal
shapepillForme de rayon de bordure de Button
leadingIconAucunIcône avant le texte
trailingIconAucunIcône après le texte
hrefAucunRendu en lien lorsqu'il est fourni
disabledfalseDésactive l'interaction
tooltipAucunContenu supplémentaire du Tooltip partagé ; ne peut pas remplacer les informations clés visibles ou aria-label
tooltipPlacementbottomDirection préférée ; le Tooltip partagé peut se retourner pour rester dans le viewport
tooltipPortaltrueRendu en dehors du conteneur de découpage sans ajouter de couche d'enveloppement de mise en page
skinAucunFournit des emplacements de classe et une adaptation de variables selon le contrat skeleton/skin

IconButton hérite des propriétés applicables de Button, mais ne fournit pas shape, leadingIcon ni trailingIcon ; il requiert aria-label, par défaut variant="ghost".

Il est recommandé d'écrire explicitement variant et le type de bouton natif dans le code métier, afin que la sémantique de l'action soit clairement visible lors des revues de code.

11. Combinaisons courantes

// 主要操作:椭圆形文字按钮
<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. Liste de vérification de revue

Avant de soumettre une UI liée aux boutons, vérifiez :

  • A-t-on priorisé la réutilisation de Button ou IconButton ?
  • Les boutons avec texte et les boutons icône uniquement ont-ils choisi le bon composant ?
  • La zone de tâche courante n'a-t-elle qu'un seul primary clair ?
  • secondary, ghost, danger sont-ils utilisés selon la sémantique et non selon la préférence de couleur ?
  • Le Button de la plateforme conserve-t-il le pill par défaut, et IconButton reste-t-il circulaire ?
  • Chaque Tooltip est-il toujours une couche d'information à arrondi compact, et non un bouton ovale cliquable ?
  • A-t-on éliminé les title natifs du navigateur, les bulles CSS data-tooltip, les indices dupliqués et les tooltips synonymes des boutons texte ?
  • Les tailles utilisent-elles uniquement sm, md, lg, avec une hauteur et une taille de police cohérentes au sein d'un même groupe ?
  • Les boutons natifs ont-ils explicitement le bon type défini ?
  • Les icônes masquent-elles les informations de lecture d'écran dupliquées, et IconButton a-t-il un aria-label localisé ?
  • Les états focus-visible, disabled, asynchrone et de confirmation dangereuse sont-ils complets ?
  • Le CSS des routes ne gère-t-il que la mise en page sans écraser le visuel de base des boutons ?
  • Les textes longs, les tailles tactiles et l'agencement des groupes de boutons ont-ils été vérifiés sur les largeurs desktop et mobile ?

13. Sources d'implémentation

  • API du composant : packages/components/src/ui/Button/Button.tsx
  • Exports du composant : packages/components/src/ui/Button/index.ts
  • Tokens de taille et de couleur : packages/components/src/styles/foundations.css
  • Styles de boutons partagés : packages/components/src/styles/primitives.css
  • Contrat d'intégration des composants publics : docs/public/design/component-integration.md

Lorsque des divergences apparaissent entre la documentation et l'implémentation, le composant, les tokens, les styles et ce document doivent être synchronisés dans le même changement.

Sur cette page