Skip to Content
Diseño

Botón Button

Especificaciones de semántica, tamaño, forma, estados y accesibilidad para Button e IconButton.

Componente en vivoBotón / IconButton / AIButton

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 proporciona aria-label.
  • Los iconos poco conocidos o de significado potencialmente ambiguo deben usar también el Tooltip compartido; el tooltip no puede sustituir al aria-label.
  • No uses el atributo DOM title como pista de producto, ni establezcas tooltip y 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 Button con texto vacío, texto oculto o ancho fijo para simular IconButton.
  • No establezcas shape en IconButton; 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 Button con href cuando se necesita énfasis visual de nivel de botón.

3. Niveles semánticos variant

VarianteSignificadoEscenario típicoRestricciones de uso
primaryAcción principal del área actualGuardar, publicar, crear, probar ahoraUn área de tarea normalmente solo conserva una acción principal
secondaryAcción clara pero secundariaVista previa, cancelar, atrás, importarNo debe competir por atención visual con la acción principal
ghostAcción de herramienta contextual de baja énfasisCerrar, más, acciones de barra de herramientas, atrás ligeroTransparente por defecto, no puede ser el único CTA clave
dangerAcción que elimina o causa daño significativoEliminar elemento, quitar contenido, vaciar datosSolo 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:

  1. Identifica el único siguiente paso más importante de la tarea actual y establécelo como primary.
  2. Las acciones auxiliares que aún deben ser claramente visibles usan secondary.
  3. Las acciones de baja énfasis en barras de herramientas o contextos usan ghost.
  4. 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ñoAltura/diámetroTamaño de fuenteEscenario recomendado
sm40px14pxNavegación superior, barras de herramientas compactas, áreas de trabajo densas
md44px15pxFormularios por defecto, CMS, diálogos y acciones normales
lg48px16pxCTA 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 Button y el diámetro de IconButton usan 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 de IconButton es uniformemente 18px.
  • El tamaño de fuente de Button lo 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

FormaAparienciaAlcance de uso
pillRadio completo; ovalado cuando tiene textoPor defecto en la plataforma, aplicable a páginas de marketing, Dashboard, Builder, CMS y Admin
roundedRadio de borde de 12pxSolo 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 usan trailingIcon.
  • 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 Button sin href, que se renderiza finalmente como <button>.
  • Para ir a otra ruta o recurso, usa Button con href, 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ícitamente type="submit".
  • No uses onClick para 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-visible conserva --focus-ring en 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".
  • IconButton debe proporcionar aria-label localizado.
  • 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 danger y 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:

PropiedadValor por defectoDescripción
variantprimaryNivel semántico y visual
sizemdAltura, tamaño de fuente y relleno horizontal
shapepillForma de radio de borde de Button
leadingIconNingunoIcono antes del texto
trailingIconNingunoIcono después del texto
hrefNingunoSe renderiza como enlace cuando se proporciona
disabledfalseDeshabilita la interacción
tooltipNingunoContenido complementario del Tooltip compartido; no puede sustituir información clave visible o aria-label
tooltipPlacementbottomDirección preferida; el Tooltip compartido puede invertirse para permanecer en el viewport
tooltipPortaltrueSe renderiza fuera del contenedor de recorte sin añadir capas de diseño envolventes
skinNingunoProporciona 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 Button o IconButton?
  • ¿Los botones con texto y de solo icono han elegido el componente correcto?
  • ¿El área de tarea actual tiene solo un primary claro?
  • ¿secondary, ghost, danger se usan por semántica y no por preferencia de color?
  • ¿La plataforma Button mantiene el pill por defecto y IconButton mantiene 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 title nativos del navegador, burbujas CSS data-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 type correcto?
  • ¿Los iconos han ocultado la información duplicada del lector de pantalla y IconButton tiene aria-label localizado?
  • ¿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.

En esta página