Bouton Button
Spécifications sémantiques, de taille, de forme, d'état et d'accessibilité pour Button et IconButton.
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 pararia-label. - Les icônes peu familières ou dont la signification peut être ambiguë doivent également utiliser le
Tooltippartagé ; un tooltip ne peut pas remplaceraria-label. - N'utilisez pas l'attribut DOM
titlecomme indice produit, et ne définissez pas simultanémenttooltiptout 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
Buttonavec du texte vide, du texte masqué ou une largeur fixe pour simuler unIconButton. - Ne définissez pas
shapesurIconButton; 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
Buttonavechrefn'est utilisé que lorsqu'une emphase visuelle de niveau bouton est nécessaire.
3. Hiérarchie sémantique variant
| Variant | Signification | Scénarios typiques | Restrictions d'utilisation |
|---|---|---|---|
primary | Action principale de la zone courante | Enregistrer, publier, créer, essayer maintenant | Une zone de tâche ne conserve généralement qu'une seule action principale |
secondary | Action claire mais secondaire | Aperçu, annuler, retour, importer | Ne doit pas rivaliser visuellement avec l'action principale |
ghost | Action d'outil contextuelle à faible emphase | Fermer, plus, actions de barre d'outils, retour léger | Transparent par défaut, ne peut pas être le seul CTA critique |
danger | Action qui supprime ou cause une destruction notable | Supprimer un élément, retirer du contenu, vider des données | Exprime 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 :
- Identifiez la prochaine étape unique la plus importante de la tâche en cours et définissez-la comme
primary. - Les actions secondaires qui doivent rester clairement visibles utilisent
secondary. - Les actions à faible emphase dans les barres d'outils ou contextuelles utilisent
ghost. - 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
| Size | Hauteur/diamètre | Taille de police | Scénarios recommandés |
|---|---|---|---|
sm | 40px | 14px | Navigation supérieure, barres d'outils compactes, espaces de travail denses |
md | 44px | 15px | Formulaires par défaut, CMS, boîtes de dialogue et actions courantes |
lg | 48px | 16px | CTA 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
Buttonet le diamètre deIconButtonutilisent 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 deIconButtonest uniformisée à 18px. - La taille de police du texte de
Buttonest 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
| Shape | Apparence | Portée d'utilisation |
|---|---|---|
pill | Entièrement arrondi ; ovale avec du texte | Par défaut pour la plateforme, adapté aux pages marketing, Dashboard, Builder, CMS et Admin |
rounded | Rayon de bordure de 12px | Utilisé 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 utilisenttrailingIcon. - 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
Buttonsanshref, qui sera finalement rendu en<button>. - La navigation vers une autre route ou ressource utilise un
Buttonavechref, 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 explicitementtype="submit". - N'utilisez pas
onClickpour 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-visibleconserve--focus-ringsur 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 ».
IconButtondoit fournir unaria-labellocalisé.- 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
dangeret 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éfaut | Description |
|---|---|---|
variant | primary | Hiérarchie sémantique et visuelle |
size | md | Hauteur, taille de police du texte et padding horizontal |
shape | pill | Forme de rayon de bordure de Button |
leadingIcon | Aucun | Icône avant le texte |
trailingIcon | Aucun | Icône après le texte |
href | Aucun | Rendu en lien lorsqu'il est fourni |
disabled | false | Désactive l'interaction |
tooltip | Aucun | Contenu supplémentaire du Tooltip partagé ; ne peut pas remplacer les informations clés visibles ou aria-label |
tooltipPlacement | bottom | Direction préférée ; le Tooltip partagé peut se retourner pour rester dans le viewport |
tooltipPortal | true | Rendu en dehors du conteneur de découpage sans ajouter de couche d'enveloppement de mise en page |
skin | Aucun | Fournit 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
ButtonouIconButton? - 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
primaryclair ? secondary,ghost,dangersont-ils utilisés selon la sémantique et non selon la préférence de couleur ?- Le
Buttonde la plateforme conserve-t-il lepillpar défaut, etIconButtonreste-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
titlenatifs du navigateur, les bulles CSSdata-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
typedéfini ? - Les icônes masquent-elles les informations de lecture d'écran dupliquées, et
IconButtona-t-il unaria-labellocalisé ? - 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.