Skip to Content
Diseño

Actualizaciones del contrato de diseño

Registro de cambios en los Tokens de diseño públicos, la API de componentes y el contrato de integración de Qokit.

Actualizaciones del contrato de diseño

2026-10-21 · Acciones fijas en menús desplazables

ActionItem.pinned acepta start o end para mantener las acciones y ActionMenu.dropdownHeader fuera de la lista desplazable. La navegación por teclado y la selección abarcan todas las regiones. Los anfitriones de portales pueden limitar la altura con --qk-menu-available-height, medida en el lado elegido del activador. Sin pinned se conserva la estructura existente.

2026-10-17 · Entrada de personalización de widgets

La personalización de widgets de página utiliza la entrada de encabezado compartida entre Proyectos, Contenido y paneles. CustomizableWidgetLayoutControls añade customizeButtonRef y disabledCustomize opcionales; los controles de colapso son opcionales. CustomizableWidgetLibrary comparte geometría móvil, enfoque inicial, Escape y retorno de enfoque entre hosts. La persistencia de widgets y los comandos siguen siendo propiedad del host. Consulta integración de personalización de widgets.

2026-10-17 · Controles de panel de banco de trabajo gestionados

WorkspaceHeaderPortal acepta startControl y endControl opcionales, con objetivos de host opcionales coincidentes. Las vistas de Archivos gestionados utilizan las mismas ranuras de panel de encabezado y geometría del área de trabajo que la edición y vista previa de un solo activo. Los hosts existentes pueden seguir proporcionando únicamente título, estado y acciones. Consulta integración de EditorHeader.

2026-10-17 · Valores predeterminados medidos del editor

useWorkspaceResponsiveProfile añade onWidthChange(width) opcional para las mediciones disponibles del área de trabajo. useEditorLayout ahora aplica límites de ancho compartido configurados al almacenamiento del host también, y readEditorLayout acepta límites opcionales como su cuarto argumento. Los llamadores existentes mantienen sus valores predeterminados. Consulta Integración de Componentes.

2026-09-26 · Creator · Esquemas de estilo

Espaciado preciso · v3: site.theme.spacingOverrides 按 desktop/tablet/mobile → sectionPadding (0–240px), pageGutter, cardGap (0–96px). --qk-site-custom-{sectionPadding|pageGutter|cardGap}-{desktop|tablet|mobile}. 980px / 720px.

Botones y enlaces: primaryButtonStyle, secondaryButtonStyle (solid/outline), buttonFontSize (12–24px), linkUnderline (always/hover/none), linkHoverStyle (none/tint). --qk-site-{primary|secondary}-button-{background|color|border|shadow}, --qk-site-button-font-size, --qk-site-button-size-{sm|md|lg}, --qk-site-link-decoration, --qk-site-link-hover-decoration, --qk-site-link-hover-background. initial → Automático.

Colores avanzados: mutedColor, borderColor, buttonTextColor, cardSurfaceColor 与对应 dark* 字段 (--qk-site-color-card-rgb).

2026-09-09 · Atajo de navegación global

SidebarNavigation / WorkspaceNavigationMenu: La navegación global usa Command+\ en Mac o Control+\ en Windows/Linux, también de forma independiente dentro de Creator. T y Shift+T conservan el control del diseño del editor. Se ignoran los campos editables, la composición de texto, las repeticiones y los eventos ya procesados.

2026-09-08 · EmptyState

La creación de proyectos y artículos/productos CMS comparte EmptyState, centrado, transparente y con acciones que se ajustan a varias líneas. Admite icon, layout y style opcionales; description también es opcional. El título usa h2: migre los selectores strong al slot de skin title. Las acciones comparten un contenedor; los permisos y la creación siguen a cargo del anfitrión.

2026-09-08 · SidebarNavigation

SidebarNavigation precarga rutas del mismo origen tras 180 ms de pausa del ratón o al recibir foco de teclado. La navegación fija y emergente comparte un límite de 8 destinos cada 30 segundos. No precarga sin conexión, en pestañas ocultas, con Save-Data o 2G; excluye descargas, enlaces desactivados, ventanas nuevas y anclas de la misma página. La navegación y la protección de cambios se mantienen.

2026-09-08 - Primary button foreground

Los botones principales de píldora conservan el azul del Logo #4695D8 y usan texto, iconos e indicadores de carga blancos en ambos temas. Se mantiene el ligero aclarado al pasar el cursor. Los botones secundarios y de peligro conservan sus colores semánticos.

2026-09-07 - AccountDropdown / SidebarProfile

AccountDropdown admite compact y preferences opcionales: el modo compacto oculta identificadores e historial de creación; el contenido anterior se conserva por defecto. Appearance y Language aceptan triggerRole="menuitem" en el menú de cuenta. La navegación por teclado restaura el foco y los diálogos de idioma anidados gestionan Escape. SidebarNavigation.searchEnabled vale true por defecto; use false para una navegación breve y fija. SidebarProfile con href y sin menú abre el mismo destino en ambos modos.

2026-09-07 - FormField / AdminEntityDialog / EditorWorkspace

Los formularios comparten escala tipográfica y ajustan textos largos; conservan formas de píldora y colores de marca. FormField nombra grupos: controlId y la id interior conectan la etiqueta. SearchField devuelve el foco tras borrar. Segmented y ControlMenu admiten opciones desactivadas; los elementos desactivados de ActionMenu no tienen enlace. Los botones ocupados conservan tamaño e indicador. AdminEntityDialog valida campos obligatorios, correo y JSON, enfoca errores, evita guardados duplicados y conserva datos ante fallos. EditorWorkspace ofrece ref.focusControl(element) para revelar paneles ocultos antes de enfocar. El movimiento reducido desactiva transiciones de controles. WorkspaceDialog desplaza el contenido largo manteniendo visibles cabecera y acciones; los diálogos móviles cortos se ajustan al contenido.

2026-09-07 · WorkspaceLocationSync / ProjectSwitcher

Al completar un cambio de ruta, WorkspaceLocationSync cierra el selector temporal de espacios y muestra las herramientas del destino. Se conservan las preferencias de búsqueda y secciones. El nombre del ámbito y su contexto aparecen en líneas separadas; los nombres largos de la cabecera se truncan dentro del botón.

2026-09-07 · Navegación unificada y superficies redondeadas Qokit

WorkspaceNavigationDock reutiliza la navegación y los permisos del anfitrión con items, fallback, className y onClickCapture, sin cargar otra sesión. Conserva la preferencia de vista expandida, iconos u oculta; hasta 860px utiliza el panel de navegación. PlatformHeader.leadingContext también aparece en EditorHeader. Se mantienen los botones de cápsula y las superficies redondeadas, eliminando bordes repetidos.

En escritorio, pulsar el menú oculta la barra lateral o restaura su último modo visible. Arrastrar el menú o el borde de la barra alterna entre oculta, solo iconos y expandida. Las flechas izquierda/derecha siguen la dirección de lectura. Cancelar el arrastre conserva la preferencia guardada; en móvil se mantiene el panel de navegación.

Montar WorkspaceLocationSync una vez bajo Suspense en el layout Next. useWorkspaceQueryState(key, defaultValue, validate) devuelve [value, setValue, ready]; useWorkspaceQueryRecord(key, defaults, validators) solo restaura filtros planos declarados. No guardar credenciales ni borradores en URL. WorkspacePage recupera posiciones de desplazamiento de sesión limitadas; las zonas internas usan data-workspace-scroll-region y WorkspaceScrollRestoration. La navegación nativa atrás/adelante cancelable reutiliza la protección de salida sin añadir historial. AdminEntityDialog conserva entradas tras errores y nuevos renderizados; el anfitrión controla versiones y resultados.

La gestión usa tamaños fijos: título de página 20px/650, sección 16px/600, texto y navegación 14px, etiquetas 13px y notas 12px. --qk-workspace-body-ink y --qk-workspace-active-ink derivan de los colores existentes.

Los botones principales de píldora usan directamente el azul del Logo #4695D8 mediante --accent-action, sin degradado oscuro. Al pasar el cursor se añade un 8% de blanco; el texto usa tinta de marca con un 10% de negro para facilitar la lectura. La navegación mantiene el mismo azul y texto adaptado al tema.

Los desplegables y selectores de espacio comparten --menu-option-font-size (14px) y --menu-option-font-weight (500), con interlineado 1.45; la selección usa 600 y los metadatos 12px/400. WorkspaceNavigationDock precarga destinos del mismo origen al pasar el ratón o recibir foco de teclado, con deduplicación limitada. Se mantienen las protecciones al salir y las rutas del host.

2026-09-07 - ColumnLayout

ColumnLayout ocupa la ventana de gestión con navegación anclada, desplazamiento independiente y una barra de página fija. WorkspacePage usa secciones planas y Tokens de radio compartidos. Hasta 860px, la navegación sigue siendo un panel lateral, inactivo al cerrarse. Las propiedades y el comportamiento de negocio no cambian. Elimine márgenes exteriores duplicados y limite el ancho dentro de los formularios.

2026-09-05 · WorkspaceNavigationMenu / WorkspacePageHeader

Los espacios con sesión iniciada usan PlatformHeader.workspaceActions para compartir cuenta y navegación en cualquier ancho. WorkspacePageHeader unifica títulos y acciones. WorkspaceNavigationMenu muestra la barra lateral actual con sus permisos y contexto; EditorNavigationMenu sigue como alias compatible. Studio conserva su barra de herramientas. Las cabeceras públicas mantienen su presentación.

WorkspaceNavigationGuard protege la navegación global con dirty, busy, error y onSave opcional. Solo un guardado confirmado que devuelve true permite salir; los errores conservan el borrador. Language.onBeforeChange(apply) permite aplicar la misma protección al cambiar de idioma. Desactiva los campos mientras se guarda.

2026-09-05 · EditorNavigationMenu

EditorNavigationMenu reutiliza toda la SidebarNavigation del anfitrión en un panel superpuesto, conservando permisos y contexto del proyecto sin desplazar el lienzo. Idioma y tema quedan abajo; los submenús procesan Escape primero. Hasta 1120px, la cabecera ocupa dos filas y el menú muestra la vista actual. Concentración y pantalla completa del navegador son independientes. La navegación espera los guardados en curso y protege los borradores.

2026-09-05 · EditorHeader

EditorHeader conserva el logo, la cuenta y el menú global del anfitrión en el editor activo. startControl y endControl controlan los paneles laterales; center, las vistas; y actions, el guardado. PlatformHeader.editorActions reutiliza la navegación adaptable, el idioma y el tema. onNavigate debe resolver los cambios sin guardar antes de ejecutar su callback. En pantallas estrechas, la cabecera usa dos filas; los submenús procesan Escape primero.

2026-09-05 · SidebarToggleSlot

SidebarToggleSlot sitúa el control de la barra lateral en la cabecera. Usa un único espacio con una barra lateral izquierda. SidebarNavigation conserva el estado, los atajos y el panel móvil; sin este espacio mantiene los controles originales. El botón de la cabecera también cierra el panel móvil; al cerrarlo, el foco vuelve a ese mismo botón.

2026-09-05 · EditorWorkspace / Dialog / Segmented

view / onViewChange alternan entre edit, focus y preview sin sustituir el editor. preview aporta la vista previa; previewPanel reutiliza un panel. layout admite writing, structure y canvas. storageKey recuerda anchos y paneles contraídos, nunca el documento.

onSaveAndClose devuelve true tras confirmar el guardado, false si falla, handled si el anfitrión ya navegó o pending si la validación necesita una decisión. Un fallo mantiene abierto el editor. Usa closeBehavior="collapse" solo si el anfitrión conserva el borrador. EditorSaveStatus refleja estados confirmados. También pueden componerse EditorViewControls, EditorLeaveDialog y useEditorLayout.

Migración del teclado: Segmented ocupa una sola parada de Tab y cambia con flechas / Home / End. Dialog respeta Escape consumido por una capa secundaria; después el editor sale del enfoque o la vista previa antes de cerrarse. LivePreviewToolbar.exitControl acepta los controles compartidos. El guardado, la publicación y los permisos siguen a cargo del anfitrión.

2026-09 · EditorWorkspace

EditorWorkspace reúne un diálogo a pantalla completa, gestión del foco y paneles adaptables. dirty confirma si se descartan los cambios, busy impide cerrar durante el guardado y onSave responde a Ctrl/Cmd+S. La aplicación gestiona permisos, datos, guardado y publicación.

2026-08 · Densidad de métricas compacta

  • Se añadió una API opcional density="compact" para MetricCard, destinada a espacios de trabajo operativos de alta densidad;
  • Se mantienen sin cambios la densidad predeterminada actual y la semántica del DOM;
  • Los rellenos compactos, las escalas numéricas y las alturas mínimas se unificaron en los estilos de componentes compartidos, por lo que las rutas ya no requieren anulaciones visuales.

2026-07 · Controles de formulario unificados

  • Se añadieron FormField, Input, Textarea, Checkbox, RadioGroup y Switch a @qokit/components/ui;
  • El esqueleto compartido FormField vincula etiquetas, descripciones, errores, estados obligatorios y referencias ARIA;
  • Se unificaron Input, Textarea, Select y SearchField en tamaños de 40px, 44px y 48px con tokens de interacción compartidos;
  • Se añadieron recetas de Skin para plataforma, Admin y sitios generados para los nuevos componentes base de formularios;
  • Se conservan los estilos .qk-field existentes como ruta de migración compatible con versiones anteriores.

2026-07 · Tipografía de tamaños de botón

  • Se añaden tres semánticas Token --button-font-size-sm, --button-font-size-md y --button-font-size-lg;
  • El Button utiliza ahora fijos sm, md y lg de 14px, 15px y 16px respectivamente, dejando de heredar el tamaño de fuente del Header, Dialog o contenedor de página;
  • Si el Skin del sitio necesita ajustar la tipografía del botón, debe sobrescribir el Token semántico correspondiente, ya no se debe reescribir font-size mediante la clase de ruta.

2026-07 · Esqueleto de navegación pública de la plataforma

  • Se añade PlatformHeader sin dependencia de inicio de sesión, utilizando el mismo esqueleto semántico para la plataforma y el sitio de documentación;
  • Se añaden PublicPlatformHeader y buildPublicHeaderNavItems, permitiendo que el estado anónimo de la plataforma y el sitio de documentación reutilicen la misma combinación de Header público y configuración de navegación;
  • HeaderNavItem añade el tipo menu, donde el Header de escritorio utiliza menús desplegables cerrables y el Header móvil se expande automáticamente en grupos de enlaces;
  • SiteFooter añade brandHref y controls opcionales, soportando diferentes escenarios de integración como documentos públicos;
  • Se añade PublicPlatformFooter, permitiendo que la plataforma y el sitio de documentación reutilicen el mismo Footer Shell y resuelvan enlaces de la plataforma entre dominios;
  • Todo lo anterior son APIs opcionales compatibles con versiones anteriores; la lógica de estado del Header de la plataforma original y los controles predeterminados del Footer permanecen sin cambios.

2026-07 · Guía de diseño pública

  • Separar el contrato de diseño público de las especificaciones internas de implementación de IA;
  • Publicar Tokens visuales, importación de componentes, límites de Skeleton/Skin, Button, Card y requisitos de accesibilidad;
  • Establecer que los cambios destructivos en componentes deben proporcionar instrucciones de migración;
  • La búsqueda pública, Sitemap y la salida de LLM solo incluyen contenido que puede depender externamente.

Notas de compatibilidad

  • Las propiedades opcionales, ranuras Skin y Tokens semánticos nuevos suelen mantener la compatibilidad hacia atrás;

  • Eliminar o renombrar propiedades, cambiar el comportamiento predeterminado de DOM/semántica/teclado constituye un cambio destructivo;

  • Los cambios destructivos explicarán el alcance del impacto, la API alternativa y los pasos de migración en esta página.

  • 2026-09-06: La navegación de escritorio conserva la barra expandida y los iconos, y añade ocultación automática. SidebarNavigation / WorkspaceNavigationMenu / Dialog

  • 2026-09-06: EditorViewControls separa Edición/Concentración de la pantalla completa nativa. EditorViewControls

  • 2026-09-06: Language y Appearance variant="menu" admiten layout="row" para mostrar etiqueta, valor actual y flecha. Se mantienen el diseño compacto predeterminado y la protección al cambiar de idioma. SiteHeaderCopy.helpResources y contactSupport permiten nombrar los enlaces de ayuda del espacio de trabajo. Language / Appearance

  • 2026-09-06: Las páginas con barra lateral eliminan el botón de menú duplicado; se mantienen el control existente y la API de navegación. WorkspaceNavigation

  • 2026-09-06: La navegación global usa un icono de menú y las herramientas iconos de panel direccionales. WorkspacePanelReveal / EditorViewControls

  • 2026-09-06: Modo de visualización · E / T / V / F · Segment.shortcut. EditorViewControls

  • 2026-09-06: PlatformHeader.workspaceNavigation sitúa la navegación global antes del logotipo PlatformHeader.workspaceNavigation

2026-09-06 - EditorHeader.preview / EditorViewControls.returnView

EditorHeader.preview muestra solo center como barra de vista previa compacta sin bordes; logotipo, cuenta, guardado y paneles siguen montados pero ocultos. Con una LivePreviewToolbar independiente se puede ocultar la cabecera del editor y usar EditorViewControls.returnView (edit o focus) para recuperar el modo anterior. Mantenga accesibles el regreso y la pantalla completa independiente; la cabecera del sitio sigue visible.

2026-09-06 · Builder / CMS

Builder y CMS comparten BuilderWorkspace, EditorCatalog y EditorComponentSettings para paneles, gráficos de inserción y ajustes visuales. Los preajustes aplican juntos los ajustes relacionados y conservan el contenido; cada aplicación gestiona el guardado y el deshacer. Los controles usan el tema de la plataforma y el contenido usa el del sitio.

2026-09-06 - EditorViewControls

Un botón cambia en ambos sentidos: al editar muestra Concentración y al concentrarse muestra Editar. Haz clic o pulsa T; E vuelve directamente a editar. En cabeceras estrechas, el botón sigue visible y la vista previa, pantalla completa y acciones adicionales están en Más. EditorViewControls

2026-09 · Espacios de administración

Las tablas estrechas (WorkspaceDataTable, AdminDataTable) muestran registros etiquetados con selección, cabeceras personalizadas y acciones. Use mobileLayout="scroll" para matrices comparativas. WorkspaceFilterToolbar coloca búsqueda y filtros antes de orden y vista. La barra lateral usa h2; la página usa h1.

2026-09-08 · Task focus

useSidebarTaskFocus(active) oculta temporalmente la navegación durante una tarea de concentración. Al salir restaura la vista anterior, salvo que el usuario cambie el modo. La ocultación automática no modifica la preferencia guardada.

Nueva referencia de API (inglés; traducción pendiente)

Optional FloatingToolPanel.viewKey animates tool changes without remounting the body. Shared opening, closing, unfolding and pin feedback respect reduced motion; pointer geometry updates run at most once per animation frame. Closed Dialog keepMounted surfaces become inert and hidden from assistive technology immediately, including during an exit transition. Existing props and document state ownership are unchanged.

The opt-in useWorkspacePanelEdgeDrag hook connects existing workspace borders to expanded, icon and hidden states in one mouse or touch gesture, with keyboard resizing, RTL and cancellation. ResizablePanels now marks its separators with data-workspace-panel-edge; existing hosts retain their behavior until they enable the hook. Hosts own widths, state, focus and visual skins. See the integration contract.

Nueva referencia de API (inglés; traducción pendiente) · 2026-10

2026-10-08 · Workspace title navigation

WorkspaceLayout and WorkspacePageHeader accept optional backControl before the title. Use WorkspaceBackButton with a localized label and the existing href or onClick; it supplies an icon, accessible name, Tooltip and RTL mirroring. Hosts retain return destinations, list state and navigation guards. Existing headers without this slot keep their layout.

En esta página

Actualizaciones del contrato de diseño2026-10-21 · Acciones fijas en menús desplazables2026-10-17 · Entrada de personalización de widgets2026-10-17 · Controles de panel de banco de trabajo gestionados2026-10-17 · Valores predeterminados medidos del editor2026-09-26 · Creator · Esquemas de estilo2026-09-09 · Atajo de navegación global2026-09-08 · EmptyState2026-09-08 · SidebarNavigation2026-09-08 - Primary button foreground2026-09-07 - AccountDropdown / SidebarProfile2026-09-07 - FormField / AdminEntityDialog / EditorWorkspace2026-09-07 · WorkspaceLocationSync / ProjectSwitcher2026-09-07 · Navegación unificada y superficies redondeadas Qokit2026-09-07 - ColumnLayout2026-09-05 · WorkspaceNavigationMenu / WorkspacePageHeader2026-09-05 · EditorNavigationMenu2026-09-05 · EditorHeader2026-09-05 · SidebarToggleSlot2026-09-05 · EditorWorkspace / Dialog / Segmented2026-09 · EditorWorkspace2026-08 · Densidad de métricas compacta2026-07 · Controles de formulario unificados2026-07 · Tipografía de tamaños de botón2026-07 · Esqueleto de navegación pública de la plataforma2026-07 · Guía de diseño públicaNotas de compatibilidad2026-09-06 - EditorHeader.preview / EditorViewControls.returnView2026-09-06 · Builder / CMS2026-09-06 - EditorViewControls2026-09 · Espacios de administración2026-09-08 · Task focusNueva referencia de API (inglés; traducción pendiente)Nueva referencia de API (inglés; traducción pendiente) · 2026-102026-10-08 · Workspace title navigation