Skip to Content
Design

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" ao MetricCard, 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/ui os seguintes elementos: FormField, Input, Textarea, Checkbox, RadioGroup e Switch;
  • 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, Select e SearchField;
  • Adicionar receitas de Skin para plataforma, Admin e sites gerados aos novos componentes base de formulários;
  • Manter os estilos existentes de .qk-field como 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-md e --button-font-size-lg;
  • Os valores de sm, md e lg para Button estã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-size através de classes de rota.

2026-07 · Estrutura de Navegação Pública da Plataforma

  • Adicionado PlatformHeader sem dependência de login, partilhando a mesma estrutura semântica entre a plataforma e o site de documentação;
  • Adicionados PublicPlatformHeader e buildPublicHeaderNavItems, 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;
  • HeaderNavItem adiciona o tipo menu: o Header de desktop utiliza menus pendentes fecháveis, enquanto o Header móvel expande automaticamente para grupos de links;
  • SiteFooter adiciona brandHref e controls opcionais, 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: Language e Appearance variant="menu" aceitam layout="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.helpResources e contactSupport definem 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.workspaceNavigation coloca 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.

Nesta página

Atualizações do Contrato de Design2026-10-21 · Ações fixas em menus com deslocamento2026-10-17 · Entrada de personalização de widgets2026-10-17 · Controlos do painel da bancada de trabalho gerida2026-10-17 · Valores padrão do editor medido2026-09-26 · Creator · Esquemas de estilo2026-09-09 · Atalho de navegação 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 · Navegação unificada e superfícies arredondadas 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 · Densidade Compacta de Indicadores2026-07 · Controlos de Formulário Unificados2026-07 · Tipografia de Tamanhos de Botão2026-07 · Estrutura de Navegação Pública da Plataforma2026-07 · Guia de Design PúblicoNotas de Compatibilidade2026-09-06 - EditorHeader.preview / EditorViewControls.returnView2026-09-06 · Builder / CMS2026-09-06 - EditorViewControls2026-09 · Áreas de administração2026-09-08 · Task focusNovas referências de API (inglês; tradução pendente)Novas referências de API (inglês; tradução pendente) · 2026-102026-10-08 · Workspace title navigation