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"paraMetricCard, 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,RadioGroupySwitcha@qokit/components/ui; - El esqueleto compartido
FormFieldvincula etiquetas, descripciones, errores, estados obligatorios y referencias ARIA; - Se unificaron
Input,Textarea,SelectySearchFielden 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-fieldexistentes 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-mdy--button-font-size-lg; - El
Buttonutiliza ahora fijossm,mdylgde 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-sizemediante la clase de ruta.
2026-07 · Esqueleto de navegación pública de la plataforma
- Se añade
PlatformHeadersin dependencia de inicio de sesión, utilizando el mismo esqueleto semántico para la plataforma y el sitio de documentación; - Se añaden
PublicPlatformHeaderybuildPublicHeaderNavItems, 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; HeaderNavItemañade el tipomenu, donde el Header de escritorio utiliza menús desplegables cerrables y el Header móvil se expande automáticamente en grupos de enlaces;SiteFooterañadebrandHrefycontrolsopcionales, 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:
LanguageyAppearance variant="menu"admitenlayout="row"para mostrar etiqueta, valor actual y flecha. Se mantienen el diseño compacto predeterminado y la protección al cambiar de idioma.SiteHeaderCopy.helpResourcesycontactSupportpermiten 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.workspaceNavigationsitú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.