Botón Button
Especificaciones de semántica, tamaño, forma, estados y accesibilidad para Button e IconButton.
AIButton reutiliza el tamaño y los significados del botón, añadiendo un estado de Qokit AI distintivo y perceptible.
Selecciona el botón de IA para ver su estado de trabajo.
Especificaciones del componente Button de Qokit
Este documento define las reglas de uso de botones en la plataforma Qokit, Builder, CMS, Dashboard, Admin, páginas de marketing y sitios generados. El objetivo es unificar los componentes, la semántica, la forma, el tamaño, los iconos, los estados y la accesibilidad de los botones, evitando que cada ruta rediseñe los botones con CSS local.
1. Modelo central
Los botones no se clasifican simplemente como "ovalados o circulares", sino que se componen de cinco dimensiones independientes entre sí:
Component type × semantic priority × size × shape × spatial elevation
Button / IconButton × primary / secondary / ghost / danger × sm / md / lg × pill / rounded × flat / raised / floating- Tipo de componente determina si el botón tiene texto visible y si debe mantener un área de clic cuadrada.
- Prioridad semántica determina la prioridad y el color del botón en la tarea actual.
- Tamaño determina la altura fija, el tamaño de fuente del texto y el área táctil.
- Forma solo determina el radio de borde, no expresa prioridad ni semántica de negocio.
- Nivel espacial solo indica si el control se eleva del plano actual, sin cambiar la semántica de la acción.
No crees nuevos tipos de botón combinando nombres de clase. Primero selecciona entre las propiedades existentes del componente compartido.
2. Selección de componentes
Button
Se utiliza para todas las acciones con texto visible, incluyendo:
- Botones de solo texto;
- Botones con icono antes del texto;
- Botones con icono después del texto;
- Enlaces de página con apariencia de botón.
El Button en la plataforma usa por defecto pill con radio completo, presentándose visualmente como ovalado. Siempre que el botón contenga texto visible, no debe reemplazarse por un botón de icono circular.
variant está desacoplado de las sombras: primary usa por defecto raised, mientras que secondary, danger, ghost usan por defecto flat. Las acciones dentro de filas de lista, tarjetas, barras de herramientas y cápsulas compuestas deben ser flat; las acciones principales independientes pueden usar raised; solo las acciones que flotan sobre el contenido usan floating. Las cápsulas independientes o los controles segmentados solo dibujan una sombra en la capa más externa; las rutas no deben sobrescribir los niveles compartidos con 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
Se utiliza para acciones de herramientas compactas con un solo icono y sin texto visible, como cerrar, más, atrás, alternar menú o eliminar.
IconButton mantiene el mismo ancho, altura y radio completo en cada tamaño, por lo que visualmente es un botón circular. Usa por defecto ghost y exige a nivel de tipo aria-label.
import { IconButton } from '@qokit/components/ui';
<IconButton aria-label="关闭" tooltip="关闭" type="button">
<CloseIcon aria-hidden="true" />
</IconButton>Reglas:
- El icono en sí usa
aria-hidden="true"; el nombre del botón lo proporcionaaria-label. - Los iconos poco conocidos o de significado potencialmente ambiguo deben usar también el
Tooltipcompartido; el tooltip no puede sustituir alaria-label. - No uses el atributo DOM
titlecomo pista de producto, ni establezcastooltipy envuelvas manualmente con Tooltip al mismo tiempo. - El Tooltip es una capa de información de solo lectura, no un botón ovalado. Usa el radio de Tooltip compacto compartido y no debe reutilizar la apariencia visual de
pill, hover, pressed o focus del botón. - No uses
Buttoncon texto vacío, texto oculto o ancho fijo para simularIconButton. - No establezcas
shapeenIconButton; la forma circular es su contrato de componente.
Escenarios donde no se debe usar Button
- Las pestañas usan los componentes correspondientes Tabs/PillTabs/Segmented.
- Los elementos de menú usan los componentes correspondientes Menu/ActionMenu.
- Los estados, etiquetas y resultados de filtro usan Pill o componentes de estado.
- La navegación de texto normal usa enlaces semánticos; solo se usa
Buttonconhrefcuando se necesita énfasis visual de nivel de botón.
3. Niveles semánticos variant
| Variante | Significado | Escenario típico | Restricciones de uso |
|---|---|---|---|
primary | Acción principal del área actual | Guardar, publicar, crear, probar ahora | Un área de tarea normalmente solo conserva una acción principal |
secondary | Acción clara pero secundaria | Vista previa, cancelar, atrás, importar | No debe competir por atención visual con la acción principal |
ghost | Acción de herramienta contextual de baja énfasis | Cerrar, más, acciones de barra de herramientas, atrás ligero | Transparente por defecto, no puede ser el único CTA clave |
danger | Acción que elimina o causa daño significativo | Eliminar elemento, quitar contenido, vaciar datos | Solo expresa semántica destructiva, no como color de énfasis normal |
variant expresa niveles semánticos y visuales, no formas. Por ejemplo, ghost puede ser un botón ovalado con texto o un IconButton circular.
Orden de selección:
- Identifica el único siguiente paso más importante de la tarea actual y establécelo como
primary. - Las acciones auxiliares que aún deben ser claramente visibles usan
secondary. - Las acciones de baja énfasis en barras de herramientas o contextos usan
ghost. - Solo las acciones realmente destructivas usan
danger, manteniendo el flujo de confirmación existente.
No elijas la variante según "qué color se ve mejor".
4. Tamaños size
| Tamaño | Altura/diámetro | Tamaño de fuente | Escenario recomendado |
|---|---|---|---|
sm | 40px | 14px | Navegación superior, barras de herramientas compactas, áreas de trabajo densas |
md | 44px | 15px | Formularios por defecto, CMS, diálogos y acciones normales |
lg | 48px | 16px | CTA principal de páginas de marketing, acciones principales que requieren mayor capacidad táctil |
El tamaño por defecto es md.
- Un mismo grupo de botones usa el mismo tamaño.
- Los controles compactos no deben ser menores de 40px; las acciones principales en móvil deben usar al menos 44px.
- La altura de
Buttony el diámetro deIconButtonusan el mismo conjunto de tokens de tamaño, por lo que pueden alinearse en una misma barra de herramientas; el tamaño visible del icono deIconButtones uniformemente 18px. - El tamaño de fuente de
Buttonlo determina el token compartido correspondiente al tamaño, no hereda el tamaño de fuente de Header, Dialog u otros contenedores padre. - El CSS de ruta puede controlar la disposición, espaciado y ancho necesario de los botones, pero no puede redefinir la altura ni el tamaño de fuente de los botones compartidos.
- Cuando el texto es largo, prioriza ajustar el diseño o el contenedor del botón; no lo resuelvas comprimiendo altura, fuente o espaciado lateral.
5. Forma shape
| Forma | Apariencia | Alcance de uso |
|---|---|---|
pill | Radio completo; ovalado cuando tiene texto | Por defecto en la plataforma, aplicable a páginas de marketing, Dashboard, Builder, CMS y Admin |
rounded | Radio de borde de 12px | Solo cuando el tema del sitio generado requiere explícitamente un radio menor |
Button usa por defecto shape="pill". El frontend de la plataforma no debe establecer explícitamente rounded, ni sobrescribir el radio de borde en CSS local.
// 平台默认:省略 shape 即为 pill
<Button type="button" variant="primary">保存</Button>
// 仅生成站点主题有明确视觉要求时使用
<Button shape="rounded" type="button" variant="primary">
预约咨询
</Button>IconButton siempre es circular y no participa en la selección de negocio de pill / rounded.
6. Reglas de iconos
- Los iconos antes del texto usan
leadingIcon; los iconos después del texto usantrailingIcon. - Un botón normalmente usa solo un icono auxiliar.
- Acciones conocidas como guardar, añadir o atrás pueden reforzar el reconocimiento con iconos, pero el icono no puede sustituir el texto visible de los botones clave.
- Las flechas que indican continuar, entrar o expandir normalmente van después del texto; los iconos de atrás normalmente van antes del texto.
- No escribas a mano la disposición de icono y texto en
children; el componente ya proporciona las ranuras de icono y etiqueta. - Usa iconos compartidos y hereda
currentColor; no codifiques a mano el color o tamaño de los iconos en el CSS de ruta. - El estado de carga debe mantener las dimensiones originales del botón y proporcionar un texto corto comprensible o retroalimentación de carga existente; no permitas que el cambio de texto cause saltos en la barra de herramientas.
7. Botones y enlaces
Las acciones y la navegación deben usar la semántica correcta:
- Para acciones en la página actual como enviar, guardar, abrir capa o cambiar estado, usa
Buttonsinhref, que se renderiza finalmente como<button>. - Para ir a otra ruta o recurso, usa
Buttonconhref, que se renderiza finalmente como Next.js<Link>. - Los botones no submit dentro de formularios deben escribir explícitamente
type="button"; los botones de envío deben escribir explícitamentetype="submit". - No uses
onClickpara simular navegación normal de página.
Los enlaces deshabilitados usan aria-disabled y salen del orden de Tab; los botones nativos deshabilitados usan disabled. El estado deshabilitado no puede expresarse solo reduciendo la opacidad; la lógica de negocio también debe bloquear la acción.
8. Estados y accesibilidad
Los componentes compartidos se encargan uniformemente de los estados hover, focus-visible, disabled y de color. El código de negocio aún debe cumplir:
- Los botones normales no seleccionados en hover usan
--control-surface-hover; los estados pressed, selected y expanded usan--control-surface-active.focus-visibleconserva--focus-ringen superficies neutras; los estilos de ruta no deben fusionar hover y estado persistente en una misma regla azul claro. - Los nombres de los botones deben ser directos, específicos e indicar qué va a ocurrir, como "Guardar", "Publicar sitio", "Eliminar proyecto".
IconButtondebe proporcionararia-labellocalizado.- Los iconos decorativos usan
aria-hidden="true"para evitar que el lector de pantalla los lea repetidamente. - El foco de teclado debe ser visible; el CSS de ruta no debe eliminar el focus ring compartido.
- No uses hover como única pista; la interacción debe soportar tanto teclado como táctil.
- Los botones deshabilitados solo se usan para acciones que el usuario no puede ejecutar temporalmente; si se necesita explicar la razón, proporciona una explicación cercana o un tooltip.
- Los errores, requisitos de permisos, riesgos, costes y otra información crítica de la tarea deben permanecer visibles; el Tooltip solo puede complementar información, no ser la única forma de descubrir esta información.
- Las operaciones asíncronas deben prevenir envíos duplicados y mantener retroalimentación comprensible de progreso.
- Las acciones peligrosas usan
dangery reutilizan el patrón de confirmación peligrosa existente; no dependas solo del rojo para comunicar riesgo. - El texto de botones en chino u otros idiomas no debe truncarse hasta ser incomprensible. Debes validar textos largos y anchos en móvil.
9. Límites de responsabilidad de estilos
La estructura, semántica y estados de los botones compartidos son responsabilidad de Button / IconButton; los tokens visuales y CSS compartido son responsabilidad del paquete de componentes; las rutas solo son responsables del diseño.
Responsabilidades de la capa compartida
- DOM, semántica de enlace/botón, comportamiento disabled;
- Ranuras de icono/etiqueta y restricciones de tipo de accesibilidad;
- Clases de variante, tamaño y forma;
- Altura, radio de borde, relleno, tamaño de fuente, peso de fuente;
- Fondo, color de texto, sombra, estados hover, focus-visible y disabled.
Responsabilidades de la capa de ruta
- Dirección, espaciado, alineación y ajuste de grupos de botones;
- Disposición responsiva;
width: 100%o ancho de contenedor necesario para flujos de trabajo específicos;- Clases de posicionamiento que no cambian la apariencia base.
La capa de ruta no debe
- Reescribir altura, tamaño de fuente, radio de borde, fondo, color de texto, sombra o focus ring del botón;
- Reimplementar botones compartidos con colores codificados o
border-radius: 999px; - Añadir variantes visuales locales como
primary-alt,outline-blue,icon-round; - Competir con el contrato de botón compartido usando
!important; - Copiar directamente los estilos base de
.qk-ui-button.
Si realmente aparecen nuevas variantes semánticas necesarias en múltiples páginas, primero se debe establecer un contrato unificado en ButtonVariant, tokens y primitives.css compartidos, en lugar de añadir estilos en las rutas.
10. Consulta rápida de API
type ButtonVariant = 'primary' | 'secondary' | 'ghost' | 'danger';
type ButtonSize = 'sm' | 'md' | 'lg';
type ButtonShape = 'rounded' | 'pill';Propiedades principales de Button:
| Propiedad | Valor por defecto | Descripción |
|---|---|---|
variant | primary | Nivel semántico y visual |
size | md | Altura, tamaño de fuente y relleno horizontal |
shape | pill | Forma de radio de borde de Button |
leadingIcon | Ninguno | Icono antes del texto |
trailingIcon | Ninguno | Icono después del texto |
href | Ninguno | Se renderiza como enlace cuando se proporciona |
disabled | false | Deshabilita la interacción |
tooltip | Ninguno | Contenido complementario del Tooltip compartido; no puede sustituir información clave visible o aria-label |
tooltipPlacement | bottom | Dirección preferida; el Tooltip compartido puede invertirse para permanecer en el viewport |
tooltipPortal | true | Se renderiza fuera del contenedor de recorte sin añadir capas de diseño envolventes |
skin | Ninguno | Proporciona ranuras de clase y adaptación de variables según el contrato skeleton/skin |
IconButton hereda las propiedades aplicables de Button, pero no proporciona shape, leadingIcon ni trailingIcon; requiere aria-label, por defecto variant="ghost".
Se recomienda escribir explícitamente variant y type de botón nativo en el código de negocio para que la semántica de la acción sea claramente visible en la revisión de código.
11. Combinaciones comunes
// 主要操作:椭圆形文字按钮
<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. Lista de verificación de revisión
Antes de enviar UI relacionada con botones, confirma:
- ¿Se ha priorizado la reutilización de
ButtonoIconButton? - ¿Los botones con texto y de solo icono han elegido el componente correcto?
- ¿El área de tarea actual tiene solo un
primaryclaro? - ¿
secondary,ghost,dangerse usan por semántica y no por preferencia de color? - ¿La plataforma
Buttonmantiene elpillpor defecto yIconButtonmantiene la forma circular? - ¿Cada Tooltip sigue siendo una capa de información de radio compacto y no parece un botón ovalado clicable?
- ¿Se han eliminado los
titlenativos del navegador, burbujas CSSdata-tooltip, pistas duplicadas y Tooltips sinónimos de botones de texto? - ¿Los tamaños usan solo
sm,md,lg, y la altura y tamaño de fuente son consistentes dentro del mismo grupo? - ¿Los botones nativos tienen establecido explícitamente el
typecorrecto? - ¿Los iconos han ocultado la información duplicada del lector de pantalla y
IconButtontienearia-labellocalizado? - ¿Los estados focus-visible, disabled, asíncrono y confirmación peligrosa están completos?
- ¿El CSS de ruta solo maneja el diseño sin sobrescribir la apariencia base del botón?
- ¿Se han validado textos largos, tamaños táctiles y disposición de grupos de botones en anchos de escritorio y móvil?
13. Fuentes de implementación
- API del componente:
packages/components/src/ui/Button/Button.tsx - Exportaciones del componente:
packages/components/src/ui/Button/index.ts - Tokens de tamaño y color:
packages/components/src/styles/foundations.css - Estilos de botón compartidos:
packages/components/src/styles/primitives.css - Contrato de integración de componentes públicos:
docs/public/design/component-integration.md
Cuando haya diferencias entre la documentación y la implementación, se deben sincronizar componente, tokens, estilos y este documento en el mismo cambio.