Atualizações do Contrato de Design
Registo das alterações nas Tokens de Design, APIs de Componentes e Contratos de Integração publicados pela Qokit.
Atualizações do Contrato de Design
2026-10-21 · Ações fixas em menus com deslocamento
ActionItem.pinned aceita start ou end para manter ações e ActionMenu.dropdownHeader fora da lista com deslocamento. A navegação por teclado e a seleção abrangem todas as regiões. Anfitriões de portais podem limitar a altura com --qk-menu-available-height, medida no lado escolhido do acionador. Sem pinned, mantém-se a estrutura existente.
2026-10-17 · Entrada de personalização de widgets
A personalização do widget de página utiliza a entrada de cabeçalho partilhada entre Projetos, Conteúdo e painéis. CustomizableWidgetLayoutControls adiciona customizeButtonRef e disabledCustomize opcionais; os controlos de recolha são opcionais. CustomizableWidgetLibrary partilha a geometria móvel, o foco inicial, Escape e o retorno do foco entre anfitriões. A persistência dos widgets e os comandos permanecem da responsabilidade do anfitrião. Consulte integração de personalização de widgets.
2026-10-17 · Controlos do painel da bancada de trabalho gerida
WorkspaceHeaderPortal aceita startControl e endControl opcionais, com destinos de anfitrião correspondentes opcionais. As vistas de Ficheiros geridos utilizam os mesmos slots do painel de cabeçalho e a mesma geometria da área de trabalho que a edição e pré-visualização de um único ativo. Os anfitriões existentes podem continuar a fornecer apenas título, estado e ações. Consulte integração EditorHeader.
2026-10-17 · Valores padrão do editor medido
useWorkspaceResponsiveProfile adiciona onWidthChange(width) opcional para as medições da área de trabalho disponível. useEditorLayout aplica agora os limites de largura partilhados configurados também ao armazenamento do anfitrião, e readEditorLayout aceita limites opcionais como o seu quarto argumento. Os chamadores existentes mantêm os seus valores padrão. Consulte 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 ligações: 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, também de forma independente no Creator. T e Shift+T mantêm as funções de disposição 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 partilha EmptyState: centrado, transparente, compacto e com ações que mudam de 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 contentor comum. Permissões e criação continuam a cargo da aplicação anfitriã.
2026-09-08 · SidebarNavigation
SidebarNavigation pré-carrega rotas da mesma origem após 180 ms de permanência do rato ou ao receber foco do teclado. A navegação fixa e a flutuante partilham o limite de 8 destinos por 30 segundos. O pré-carregamento pausa sem ligação, em separadores ocultos, com Save-Data ou 2G; exclui transferências, ligações desativadas, novas janelas e âncoras da mesma página. A navegação e a proteção de alterações mantêm-se.
2026-09-08 - Primary button foreground
Os botões principais arredondados mantêm o azul do Logo #4695D8 e usam texto, ícones e indicadores brancos nos dois temas. A passagem do cursor mantém o ligeiro aclaramento. Botões secundários e de perigo conservam as 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; por omissão, mantém o conteúdo existente. Appearance e Language aceitam triggerRole="menuitem" no menu da conta. A navegação por teclado repõe o foco, e os diálogos de idioma aninhados tratam Escape. SidebarNavigation.searchEnabled é true por omissão; utilize 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 partilham a escala tipográfica e adaptam textos longos, mantendo formas arredondadas e cores da marca. FormField nomeia grupos: controlId e a id interna associam a etiqueta. SearchField devolve o foco após limpar. Segmented e ControlMenu aceitam opções desativadas; itens desativados de ActionMenu não têm ligação. Botões ocupados mantêm tamanho e indicador. AdminEntityDialog valida campos obrigatórios, e-mail e JSON, foca erros, impede gravações repetidas e preserva dados após falhas. EditorWorkspace fornece ref.focusControl(element) para revelar painéis ocultos antes de focar. Movimento reduzido desativa transições dos controlos. WorkspaceDialog desloca conteúdo longo mantendo cabeçalho e ações visíveis; diálogos móveis curtos adaptam-se 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 pesquisa e secções são mantidas. O nome do âmbito e o 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 a navegação e permissões do anfitrião com items, fallback, className e onClickCapture, sem carregar outra sessão. A preferência existente define expansão, ícones ou ocultação; até 860px mantém-se o menu lateral. PlatformHeader.leadingContext surge também em EditorHeader. Preservam-se os botões em cápsula e superfícies arredondadas, removendo contornos repetidos.
No computador, clicar no menu oculta a barra lateral ou repõe o último modo visível. Arrastar o menu ou a margem da barra alterna entre oculta, apenas ícones e expandida. As setas esquerda/direita seguem a direção de leitura. Cancelar o arrastamento mantém a preferência guardada; no telemóvel, mantém-se o painel de navegação.
Monte WorkspaceLocationSync uma vez sob Suspense no layout Next. useWorkspaceQueryState(key, defaultValue, validate) devolve [value, setValue, ready]; useWorkspaceQueryRecord(key, defaults, validators) restaura apenas filtros planos declarados. Não coloque credenciais nem rascunhos nos URL. WorkspacePage restaura posições limitadas de deslocamento 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 acrescentar histórico. AdminEntityDialog mantém os dados após falhas e novas renderizações; versões e resultados continuam a cargo do anfitrião.
A gestão usa funções tipográficas fixas: título da página 20px/650, secção 16px/600, texto e navegação 14px, etiquetas 13px, notas 12px. --qk-workspace-body-ink e --qk-workspace-active-ink derivam das cores existentes.
Os botões principais arredondados usam diretamente o azul do Logo #4695D8 através de --accent-action, sem gradiente escurecido. Ao passar o cursor, adicionam 8% de branco; as etiquetas usam tinta da marca com 10% de preto para legibilidade. A navegação mantém o mesmo azul e texto adaptado ao tema.
Menus pendentes e seletores de espaço partilham --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 rato ou receber foco do teclado, com deduplicação limitada. As proteções de saída e as rotas do anfitrião mantêm-se ativas.
2026-09-07 - ColumnLayout
ColumnLayout preenche a janela de gestão com navegação ancorada, deslocamento independente e barra de página fixa. WorkspacePage usa secções planas e Tokens de raio partilhados. Até 860px, a navegação mantém-se num painel, inativo quando fechado. Propriedades e comportamento de negócio não mudam. Remova margens exteriores duplicadas e limite a largura dentro dos formulários.
2026-09-05 · WorkspaceNavigationMenu / WorkspacePageHeader
Os espaços autenticados usam PlatformHeader.workspaceActions para partilhar conta e navegação em todas as larguras. WorkspacePageHeader uniformiza títulos e ações. WorkspaceNavigationMenu apresenta a barra lateral atual com permissões e contexto; EditorNavigationMenu mantém-se como alias compatível. O Studio conserva a sua barra de ferramentas. Os cabeçalhos públicos mantêm a apresentação.
WorkspaceNavigationGuard protege a navegação global com dirty, busy, error e onSave opcional. Só uma gravação confirmada que devolve true permite sair; as falhas preservam o rascunho. Language.onBeforeChange(apply) permite a mesma proteção antes de mudar o idioma. Desative os campos durante a gravação.
2026-09-05 · EditorNavigationMenu
EditorNavigationMenu reutiliza toda a SidebarNavigation da aplicação num painel sobreposto, mantendo permissões e contexto do projeto sem deslocar a área de edição. Idioma e tema ficam em baixo; os submenus tratam Escape primeiro. Até 1120px, o cabeçalho utiliza duas linhas e o menu indica a vista atual. Foco e ecrã inteiro do navegador são independentes. A navegação aguarda as gravações em curso e protege os rascunhos.
2026-09-05 · EditorHeader
EditorHeader mantém o logótipo, a conta e o menu global do anfitrião no editor ativo. startControl e endControl controlam os painéis laterais, center as vistas e actions a gravação. PlatformHeader.editorActions reutiliza a navegação responsiva, o idioma e o tema. onNavigate deve tratar alterações não guardadas antes de executar o callback. Em ecrãs estreitos, o cabeçalho usa duas linhas; os submenus processam Escape primeiro.
2026-09-05 · SidebarToggleSlot
SidebarToggleSlot coloca o controlo da barra lateral no cabeçalho. Use um único espaço com uma barra lateral esquerda. SidebarNavigation mantém o estado, os atalhos e o painel móvel; sem esse espaço, os controlos ficam na posição original. O botão do cabeçalho também fecha o painel móvel; ao fechar, o foco regressa a 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é-visualização; previewPanel reutiliza um painel. layout aceita writing, structure e canvas. storageKey memoriza larguras e painéis recolhidos, nunca o documento.
onSaveAndClose devolve true após confirmar a gravação, false em caso de falha, handled se a aplicação já navegou ou pending se a validação exige uma decisão. A falha mantém o editor aberto. Use closeBehavior="collapse" apenas quando a aplicação mantém o rascunho. EditorSaveStatus apresenta estados confirmados. EditorViewControls, EditorLeaveDialog e useEditorLayout também podem ser combinados em espaços existentes.
Migração do teclado: Segmented tem uma paragem de Tab e usa setas / Home / End. Dialog respeita Escape tratado por uma sobreposição secundária; depois o editor sai do foco ou da pré-visualização antes de fechar. LivePreviewToolbar.exitControl aceita os controlos de vista partilhados. Gravação, publicação e permissões continuam a cargo da aplicação.
2026-09 · EditorWorkspace
EditorWorkspace combina um diálogo em ecrã inteiro, gestão do foco e painéis adaptáveis. dirty confirma se as alterações devem ser descartadas, busy impede o fecho durante a gravação e onSave responde a Ctrl/Cmd+S. A aplicação gere permissões, dados, gravação e publicação.
2026-08 · Densidade Compacta de Indicadores
- Adicionar uma API opcional
density="compact"aoMetricCard, destinada a espaços de trabalho operacionais de alta densidade; - Manter a densidade padrão atual e a semântica DOM inalteradas;
- Unificar o espaçamento interno compacto, a escala numérica e a altura mínima nos estilos partilhados dos componentes, eliminando a necessidade de sobreposições visuais nas rotas.
2026-07 · Controlos de Formulário Unificados
- Adicionar ao
@qokit/components/uios seguintes elementos:FormField,Input,Textarea,Checkbox,RadioGroupeSwitch; - Associar etiquetas, descrições, erros, estado obrigatório e referências ARIA através da estrutura partilhada
FormField; - Unificar as dimensões de 40px, 44px e 48px, bem como as Tokens de interação partilhadas, para
Input,Textarea,SelecteSearchField; - Adicionar receitas de Skin para plataforma, Admin e sites gerados aos novos componentes base de formulários;
- Manter os estilos existentes de
.qk-fieldcomo caminho de migração compatível com versões anteriores.
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; - Os valores de
sm,mdelgparaButtonestão agora fixados em 14px, 15px e 16px respetivamente, deixando de herdar o tamanho da fonte do Header, Dialog ou do contêiner da página; - Se o Skin do site necessitar de ajustar a tipografia dos botões, deve sobrescrever o Token semântico correspondente, em vez de reescrever
font-sizeatravés de classes de rota.
2026-07 · Estrutura de Navegação Pública da Plataforma
- Adicionado
PlatformHeadersem dependência de login, partilhando a mesma estrutura semântica entre a plataforma e o site de documentação; - Adicionados
PublicPlatformHeaderebuildPublicHeaderNavItems, permitindo que o estado anónimo da plataforma e o site de documentação reutilizem a mesma combinação de Header público e configuração de navegação; HeaderNavItemadiciona o tipomenu: o Header de desktop utiliza menus pendentes fecháveis, enquanto o Header móvel expande automaticamente para grupos de links;SiteFooteradicionabrandHrefecontrolsopcionais, suportando cenários de integração como documentação pública;- Adicionado
PublicPlatformFooter, permitindo que a plataforma e o site de documentação reutilizem o mesmo Footer Shell, com resolução de links da plataforma entre domínios; - Todas estas 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;
- Publicação de Tokens visuais, importação de componentes, limites de Skeleton/Skin, Button, Card e requisitos de acessibilidade;
- Estabelecido que alterações destrutivas nos componentes devem incluir instruções de migração;
- A pesquisa, Sitemap e saídas de LLM incluem apenas conteúdos passíveis de dependência externa.
Notas de Compatibilidade
-
A adição de propriedades opcionais, slots de Skin opcionais e Tokens semânticos mantém geralmente a compatibilidade com versões anteriores;
-
A eliminação ou renomeação de propriedades, bem como a alteração do comportamento padrão do DOM, semântica ou teclado, constitui uma alteração destrutiva;
-
As alterações destrutivas serão explicadas nesta página, incluindo o alcance do impacto, a API alternativa e os passos de migração.
-
2026-09-06: A navegação no computador mantém a barra expandida e os ícones e acrescenta ocultação automática. SidebarNavigation / WorkspaceNavigationMenu / Dialog
-
2026-09-06: EditorViewControls separa Edição/Foco do ecrã inteiro nativo. EditorViewControls
-
2026-09-06:
LanguageeAppearance variant="menu"aceitamlayout="row"para mostrar rótulo, valor atual e seta. O esquema compacto predefinido e a proteção na mudança de idioma mantêm-se.SiteHeaderCopy.helpResourcesecontactSupportdefinem opcionalmente os nomes das ligações de ajuda do espaço de trabalho. Language / Appearance -
2026-09-06: As páginas com barra lateral removem o botão de menu duplicado; o controlo 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 visualização ·
E/T/V/F·Segment.shortcut. EditorViewControls -
2026-09-06:
PlatformHeader.workspaceNavigationcoloca a navegação global antes do logótipo PlatformHeader.workspaceNavigation
2026-09-06 - EditorHeader.preview / EditorViewControls.returnView
EditorHeader.preview mostra apenas center como barra de pré-visualização compacta e sem contornos; logótipo, conta, guardar e painéis permanecem montados, mas ocultos. Com uma LivePreviewToolbar separada, pode ocultar o cabeçalho do editor e usar EditorViewControls.returnView (edit ou focus) para restaurar o modo anterior. Mantenha o regresso acessível e o ecrã inteiro independente; o cabeçalho do site continua visível.
2026-09-06 · Builder / CMS
Builder e CMS partilham BuilderWorkspace, EditorCatalog e EditorComponentSettings para painéis, ilustrações de inserção e definições visuais. As predefinições aplicam as opções relacionadas em conjunto e preservam o conteúdo; cada aplicação gere guardar e anular. Os controlos 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 prima T; E regressa diretamente à edição. Em cabeçalhos estreitos, o botão permanece visível; pré-visualização, ecrã inteiro e ações adicionais ficam em Mais. EditorViewControls
2026-09 · Áreas de administração
Tabelas estreitas (WorkspaceDataTable, AdminDataTable) apresentam registos identificados com seleção, cabeçalhos personalizados e ações. Use mobileLayout="scroll" para matrizes comparativas. WorkspaceFilterToolbar coloca pesquisa 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, repõe a apresentação anterior, salvo alteração explícita do utilizador. A ocultação automática não substitui a preferência guardada.
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.