Atualizações do Contrato de Design
Registros de alterações nas Tokens de Design públicas, APIs de componentes e contratos de integração do Qokit.
Atualizações do Contrato de Design
2026-10-21 · Ações fixas em menus com rolagem
ActionItem.pinned aceita start ou end para manter ações e ActionMenu.dropdownHeader fora da lista com rolagem. A navegação por teclado e a seleção abrangem todas as regiões. Hospedeiros de portais podem limitar a altura com --qk-menu-available-height, medida no lado escolhido do acionador. Sem pinned, a estrutura existente é mantida.
17/10/2026 · Entrada de personalização de widget
A personalização do widget de página usa a entrada de cabeçalho compartilhada entre Projetos, Conteúdo e painéis. CustomizableWidgetLayoutControls adiciona customizeButtonRef e disabledCustomize opcionais; os controles de colapso são opcionais. CustomizableWidgetLibrary compartilha geometria móvel, foco inicial, Escape e retorno de foco entre hosts. A persistência de widgets e comandos permanecem sob propriedade do host. Veja integração de personalização de widget.
17/10/2026 · Controles de painel da bancada gerenciada
WorkspaceHeaderPortal aceita startControl e endControl opcionais, com destinos de host correspondentes opcionais. As visualizações de Arquivos Gerenciados usam os mesmos slots de painel de cabeçalho e geometria da área de trabalho que a edição e visualização de ativo único. Hosts existentes podem continuar fornecendo apenas título, status e ações. Veja integração do EditorHeader.
17/10/2026 · Padrões medidos do editor
useWorkspaceResponsiveProfile adiciona onWidthChange(width) opcional para medições disponíveis da área de trabalho. useEditorLayout agora aplica limites de largura configurados compartilhados ao armazenamento do host também, e readEditorLayout aceita limites opcionais como seu quarto argumento. Chamadores existentes mantêm seus padrões. Veja Integração de Componentes.
2026-09-26 · Creator · Esquemas de estilo
Espaçamento detalhado · 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.
Botões e links: 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.
Cores avançadas: mutedColor, borderColor, buttonTextColor, cardSurfaceColor 与对应 dark* 字段 (--qk-site-color-card-rgb).
2026-09-09 · Atalho de navegação global
SidebarNavigation / WorkspaceNavigationMenu: A navegação global usa Command+\ no Mac ou Control+\ no Windows/Linux, inclusive de forma independente no Creator. T e Shift+T continuam controlando o layout do editor. Campos editáveis, composição de texto, repetições e eventos já tratados são ignorados.
2026-09-08 · EmptyState
A criação de projetos e artigos/produtos CMS compartilha EmptyState: centralizado, transparente, compacto e com ações que quebram linha. icon, layout, style e description são opcionais. O título usa h2; migre seletores strong para o slot de skin title. As ações usam um contêiner compartilhado. Permissões e criação continuam no aplicativo hospedeiro.
2026-09-08 · SidebarNavigation
SidebarNavigation pré-carrega rotas da mesma origem após 180 ms de permanência do mouse ou ao receber foco do teclado. A navegação fixa e a flutuante compartilham o limite de 8 destinos por 30 segundos. O pré-carregamento pausa offline, em abas ocultas, com Save-Data ou 2G; exclui downloads, links desativados, novas janelas e âncoras da mesma página. A navegação e a proteção de alterações permanecem.
2026-09-08 - Primary button foreground
Os botões principais em pílula mantêm o azul do Logo #4695D8 e usam texto, ícones e indicadores brancos nos dois temas. O cursor mantém o leve clareamento. Botões secundários e de perigo conservam suas cores semânticas.
2026-09-07 - AccountDropdown / SidebarProfile
AccountDropdown aceita compact e preferences opcionais: o modo compacto oculta identificadores e histórico de criação; o padrão mantém o conteúdo existente. Appearance e Language aceitam triggerRole="menuitem" no menu da conta. A navegação pelo teclado restaura o foco, e diálogos de idioma aninhados tratam Escape. SidebarNavigation.searchEnabled é true por padrão; use false para navegação curta e fixa. SidebarProfile com href, sem menu, abre o mesmo destino nos modos expandido e de ícones.
2026-09-07 - FormField / AdminEntityDialog / EditorWorkspace
Formulários compartilham escala tipográfica e quebram textos longos, mantendo formas de pílula e cores da marca. FormField nomeia grupos: controlId e a id interna vinculam o rótulo. SearchField devolve o foco após limpar. Segmented e ControlMenu aceitam opções desativadas; itens desativados de ActionMenu não têm link. Botões ocupados mantêm tamanho e indicador. AdminEntityDialog valida campos obrigatórios, e-mail e JSON, foca erros, impede salvamentos duplicados e preserva entradas após falhas. EditorWorkspace oferece ref.focusControl(element) para revelar painéis ocultos antes de focar. Movimento reduzido desativa transições dos controles. WorkspaceDialog rola conteúdo longo mantendo cabeçalho e ações visíveis; diálogos móveis curtos se ajustam ao conteúdo.
2026-09-07 · WorkspaceLocationSync / ProjectSwitcher
Após a mudança de rota, WorkspaceLocationSync fecha o seletor temporário de espaços e mostra as ferramentas do destino. As preferências de busca e seções são mantidas. O nome do escopo e seu contexto ficam em linhas separadas; nomes longos no cabeçalho são truncados dentro do botão.
2026-09-07 · Navegação unificada e superfícies arredondadas Qokit
WorkspaceNavigationDock reutiliza navegação e permissões do host com items, fallback, className e onClickCapture, sem carregar outra sessão. A preferência existente define expansão, ícones ou ocultação; até 860px permanece o menu lateral. PlatformHeader.leadingContext também aparece em EditorHeader. Botões em cápsula e superfícies arredondadas são preservados; bordas repetidas são removidas.
No desktop, clicar no menu oculta a barra lateral ou restaura seu último modo visível. Arrastar o menu ou a borda da barra alterna entre oculta, apenas ícones e expandida. As setas esquerda/direita seguem a direção de leitura. Cancelar o arraste preserva a preferência salva; no celular, permanece o painel de navegação.
Monte WorkspaceLocationSync uma vez sob Suspense no layout Next. useWorkspaceQueryState(key, defaultValue, validate) retorna [value, setValue, ready]; useWorkspaceQueryRecord(key, defaults, validators) restaura apenas filtros planos declarados. Não coloque credenciais nem rascunhos em URLs. WorkspacePage restaura posições limitadas de rolagem da sessão; áreas internas usam data-workspace-scroll-region e WorkspaceScrollRestoration. A navegação nativa cancelável reutiliza a proteção de saída sem adicionar histórico. AdminEntityDialog mantém entradas após falhas e novas renderizações; versões e resultados continuam sob responsabilidade do host.
A gestão usa papéis tipográficos fixos: título da página 20px/650, seção 16px/600, texto e navegação 14px, rótulos 13px, notas 12px. --qk-workspace-body-ink e --qk-workspace-active-ink derivam das cores existentes.
Os botões principais em pílula usam diretamente o azul do Logo #4695D8 via --accent-action, sem gradiente escurecido. Ao passar o cursor, adicionam 8% de branco; os rótulos usam tinta da marca com 10% de preto para legibilidade. A navegação mantém o mesmo azul e texto adaptado ao tema.
Menus suspensos e seletores de espaço compartilham --menu-option-font-size (14px) e --menu-option-font-weight (500), com altura de linha 1.45; opções selecionadas usam 600 e metadados 12px/400. WorkspaceNavigationDock pré-carrega destinos da mesma origem ao passar o mouse ou receber foco do teclado, com deduplicação limitada. As proteções de saída e as rotas do host continuam ativas.
2026-09-07 - ColumnLayout
ColumnLayout preenche a janela de gestão com navegação ancorada, rolagem independente e barra de página fixa. WorkspacePage usa seções planas e Tokens de raio compartilhados. Até 860px, a navegação continua em um painel, inativo quando fechado. Propriedades e comportamento de negócio não mudam. Remova margens externas duplicadas e limite a largura dentro dos formulários.
2026-09-05 · WorkspaceNavigationMenu / WorkspacePageHeader
Os espaços autenticados usam PlatformHeader.workspaceActions para compartilhar conta e navegação em todas as larguras. WorkspacePageHeader padroniza títulos e ações. WorkspaceNavigationMenu mostra a barra lateral atual com permissões e contexto; EditorNavigationMenu continua como alias compatível. O Studio mantém sua barra de ferramentas. Os cabeçalhos públicos preservam sua apresentação.
WorkspaceNavigationGuard protege a navegação global com dirty, busy, error e onSave opcional. Só um salvamento confirmado que retorna true permite sair; falhas preservam o rascunho. Language.onBeforeChange(apply) permite a mesma proteção antes de mudar o idioma. Desative os campos durante o salvamento.
2026-09-05 · EditorNavigationMenu
EditorNavigationMenu reutiliza toda a SidebarNavigation do aplicativo em um painel sobreposto, mantendo permissões e contexto do projeto sem deslocar a área de edição. Idioma e tema ficam na parte inferior; os submenus tratam Escape primeiro. Até 1120px, o cabeçalho usa duas linhas e o menu mostra a visualização atual. Foco e tela cheia do navegador são independentes. A navegação aguarda os salvamentos em andamento e protege os rascunhos.
2026-09-05 · EditorHeader
EditorHeader mantém o logo, a conta e o menu global do host no editor ativo. startControl e endControl controlam os painéis laterais, center as visualizações e actions o salvamento. PlatformHeader.editorActions reutiliza a navegação responsiva, o idioma e o tema. onNavigate deve tratar alterações não salvas antes de executar o callback. Em telas estreitas, o cabeçalho usa duas linhas; os submenus processam Escape primeiro.
2026-09-05 · SidebarToggleSlot
SidebarToggleSlot coloca o controle da barra lateral no cabeçalho. Use um único slot com uma barra lateral esquerda. SidebarNavigation mantém o estado, os atalhos e o painel móvel; sem slot, os controles ficam no lugar original. O botão do cabeçalho também fecha o painel móvel; ao fechar, o foco volta para esse mesmo botão.
2026-09-05 · EditorWorkspace / Dialog / Segmented
view / onViewChange alternam entre edit, focus e preview sem substituir o editor. preview fornece a prévia; previewPanel reutiliza um painel. layout aceita writing, structure e canvas. storageKey lembra larguras e painéis recolhidos, nunca o documento.
onSaveAndClose retorna true após confirmar o salvamento, false em caso de falha, handled se o aplicativo já navegou ou pending se a validação exige uma decisão. A falha mantém o editor aberto. Use closeBehavior="collapse" somente quando o aplicativo preserva o rascunho. EditorSaveStatus mostra estados confirmados. EditorViewControls, EditorLeaveDialog e useEditorLayout também podem ser combinados em espaços existentes.
Migração de teclado: Segmented tem uma parada de Tab e usa setas / Home / End. Dialog respeita Escape tratado por uma sobreposição filha; depois o editor sai do foco ou da prévia antes de fechar. LivePreviewToolbar.exitControl aceita os controles de visualização compartilhados. Salvamento, publicação e permissões continuam sob responsabilidade do aplicativo.
2026-09 · EditorWorkspace
EditorWorkspace reúne um diálogo em tela cheia, gerenciamento de foco e painéis responsivos. dirty confirma o descarte de alterações, busy impede o fechamento durante o salvamento e onSave atende a Ctrl/Cmd+S. A aplicação cuida de permissões, dados, salvamento e publicação.
2026-08 · Densidade Compacta de Métricas
- Adicionada API opcional
density="compact"paraMetricCard, destinada a workspaces operacionais de alta densidade; - Mantidos inalterados a densidade padrão atual e a semântica do DOM;
- Unificadas as configurações de preenchimento compacto, escala numérica e altura mínima nos estilos compartilhados dos componentes, eliminando a necessidade de substituições visuais nas rotas.
2026-07 · Controles de Formulário Unificados
- Adicionados
FormField,Input,Textarea,Checkbox,RadioGroupeSwitcha@qokit/components/ui; - Associados rótulos, descrições, erros, estados obrigatórios e referências ARIA pelo esqueleto compartilhado
FormField; - Unificados
Input,Textarea,SelecteSearchFieldaos tamanhos de 40px, 44px e 48px e aos Tokens de interação compartilhados; - Adicionadas receitas de Skin para plataforma, Admin e sites gerados aos novos componentes base de formulário;
- Mantidos os estilos existentes de
.qk-fieldcomo caminho de migração com compatibilidade retroativa.
2026-07 · Tipografia de Tamanhos de Botão
- Adicionados três Tokens semânticos
--button-font-size-sm,--button-font-size-mde--button-font-size-lg; - O
Buttonagora usa fixamente tamanhos de texto de 14px, 15px e 16px para seussm,mdelg, não herdando mais o tamanho da fonte do Header, Dialog ou contêiner da página; - Se o Skin do site precisar ajustar a tipografia dos botões, deve sobrescrever o Token semântico correspondente, em vez de reescrever o
font-sizevia classe de rota.
2026-07 · Estrutura de Navegação Pública da Plataforma
- Adicionado
PlatformHeadersem dependência de login, com a plataforma e o site de documentação usando a mesma estrutura semântica; - Adicionados
PublicPlatformHeaderebuildPublicHeaderNavItems, permitindo que o estado anônimo da plataforma e a reutilização da documentação compartilhem a mesma combinação de Header público e configuração de navegação; - O
HeaderNavItemadiciona o tipomenu: o Header de desktop usa menus suspensos fecháveis, enquanto o Header móvel expande automaticamente para grupos de links; - O
SiteFooteradiciona opções debrandHrefecontrols, suportando diferentes cenários de integração como documentos públicos; - Adicionado
PublicPlatformFooter, onde a plataforma e o site de documentação compartilham o mesmo Footer Shell, permitindo a resolução de links da plataforma entre domínios; - Todos estes são APIs opcionais compatíveis com versões anteriores; a lógica de estado do Header da plataforma original e os controles padrão do Footer permanecem inalterados.
2026-07 · Guia de Design Público
- Separação do contrato de design público das especificações internas de implementação de IA;
- Divulgação de Tokens visuais, importação de componentes, limites de Skeleton/Skin, Button, Card e requisitos de acessibilidade;
- Esclarecimento de que mudanças destrutivas em componentes devem fornecer instruções de migração;
- A pesquisa pública, Sitemap e saída de LLM incluem apenas conteúdo que pode ser dependência externa.
Notas de Compatibilidade
-
Novas propriedades opcionais, slots de Skin e Tokens semânticos geralmente mantêm a compatibilidade com versões anteriores;
-
Exclusão ou renomeação de propriedades, alteração do comportamento padrão de DOM/semântica/teclado são consideradas mudanças destrutivas;
-
Mudanças destrutivas serão explicadas nesta página, incluindo escopo de impacto, APIs alternativas e etapas de migração.
-
2026-09-06: A navegação no computador mantém a barra expandida e os ícones e adiciona ocultação automática. SidebarNavigation / WorkspaceNavigationMenu / Dialog
-
2026-09-06: EditorViewControls separa Edição/Foco da tela cheia nativa. EditorViewControls
-
2026-09-06:
LanguageeAppearance variant="menu"aceitamlayout="row"para mostrar rótulo, valor atual e seta. O layout compacto padrão e a proteção na troca de idioma permanecem inalterados.SiteHeaderCopy.helpResourcesecontactSupportnomeiam opcionalmente os links de ajuda do espaço de trabalho. Language / Appearance -
2026-09-06: Páginas com barra lateral removem o botão de menu duplicado; o controle existente e a API de navegação continuam disponíveis. WorkspaceNavigation
-
2026-09-06: A navegação global usa um ícone de menu; as ferramentas usam ícones direcionais de painel. WorkspacePanelReveal / EditorViewControls
-
2026-09-06: Modo de exibição ·
E/T/V/F·Segment.shortcut. EditorViewControls -
2026-09-06:
PlatformHeader.workspaceNavigationposiciona a navegação global antes do logotipo PlatformHeader.workspaceNavigation
2026-09-06 - EditorHeader.preview / EditorViewControls.returnView
EditorHeader.preview mostra apenas center como barra de prévia compacta e sem bordas; logotipo, conta, salvar e painéis continuam montados, mas ocultos. Com uma LivePreviewToolbar separada, o cabeçalho do editor pode ser ocultado e EditorViewControls.returnView (edit ou focus) restaura o modo anterior. Mantenha retorno acessível e tela cheia independente; o cabeçalho do site continua visível.
2026-09-06 · Builder / CMS
Builder e CMS compartilham BuilderWorkspace, EditorCatalog e EditorComponentSettings para painéis, ilustrações de inserção e ajustes visuais. As predefinições aplicam os ajustes relacionados juntos e preservam o conteúdo; cada aplicativo gerencia salvar e desfazer. Os controles seguem o tema da plataforma, e o conteúdo segue o tema do site.
2026-09-06 - EditorViewControls
Um botão alterna nos dois sentidos: durante a edição mostra Foco; no foco mostra Editar. Clique ou pressione T; E volta diretamente à edição. Em cabeçalhos estreitos, o botão fica visível; prévia, tela cheia e ações adicionais ficam em Mais. EditorViewControls
2026-09 · Áreas de administração
Tabelas estreitas (WorkspaceDataTable, AdminDataTable) exibem registros rotulados com seleção, cabeçalhos personalizados e ações. Use mobileLayout="scroll" para matrizes comparativas. WorkspaceFilterToolbar posiciona busca e filtros antes da ordenação e visualização. A barra lateral usa h2; a página usa h1.
2026-09-08 · Task focus
useSidebarTaskFocus(active) oculta temporariamente a navegação durante uma tarefa de concentração. Ao sair, restaura a exibição anterior, salvo alteração explícita do usuário. A ocultação automática não substitui a preferência salva.
Novas referências de API (inglês; tradução pendente)
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.
Novas referências de API (inglês; tradução pendente) · 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.