Design Contract Updates
Records of changes to Qokit's public design Tokens, component APIs, and integration contracts.
Design Contract Updates
2026-10-21 · Fixed actions in scrolling menus
ActionItem.pinned accepts start or end to keep actions, along with ActionMenu.dropdownHeader, outside the scrolling list. Menu keyboard navigation and selection semantics span all regions. Portal hosts can cap menu height using --qk-menu-available-height, measured on the chosen side of the trigger. Items without pinned retain the existing menu structure.
2026-10-17 · Widget customization entry
Page widget customization uses the shared header entry across Projects, Content and dashboards. CustomizableWidgetLayoutControls adds optional customizeButtonRef and disabledCustomize; collapse controls are optional. CustomizableWidgetLibrary shares mobile geometry, initial focus, Escape and focus return across hosts. Widget persistence and commands remain host-owned. See widget customization integration.
2026-10-17 · Managed workbench panel controls
WorkspaceHeaderPortal accepts optional startControl and endControl, with matching optional host targets. Managed Files views use the same header panel slots and work-area geometry as single-asset editing and preview. Existing hosts can continue supplying title, status and actions only. See EditorHeader integration.
2026-10-17 · Measured editor defaults
useWorkspaceResponsiveProfile adds optional onWidthChange(width) for available work-area measurements. useEditorLayout now applies configured shared width limits to host storage too, and readEditorLayout accepts optional limits as its fourth argument. Existing callers keep their defaults. See Component Integration.
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.
2026-09-26 · Creator · Style schemes
Site theme contract v3 adds optional refinements; unset values retain recipe defaults. site.theme.spacingOverrides stores sectionPadding (0–240px), pageGutter and cardGap (0–96px) per desktop/tablet/mobile. Container breakpoints are 980px and 720px; missing device values inherit from wider devices. Explicit block rhythm and local element styles keep precedence.
primaryButtonStyle and secondaryButtonStyle accept solid/outline; buttonFontSize accepts 12–24px; linkUnderline accepts always/hover/none; linkHoverStyle accepts none/tint. mutedColor, borderColor, buttonTextColor, cardSurfaceColor (--qk-site-color-card-rgb) and their dark* counterparts isolate light and dark colors. Editing, preview and publishing share the resolver.
Added tokens: --qk-site-custom-{sectionPadding|pageGutter|cardGap}-{desktop|tablet|mobile}, --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. Their initial defaults preserve recipe fallbacks.
2026-09-09 · Global navigation shortcut
SidebarNavigation and WorkspaceNavigationMenu now use Command+\ / Control+\, with matching trigger hints and accessible shortcut metadata. Global navigation works independently inside Creator; T and Shift+T retain their editor layout behavior. Input and composition protection is preserved.
2026-09-09 · FloatingToolPanel motion
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.
2026-09-09 · WorkspacePanelEdgeDrag
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.
2026-09-08 · EmptyState
Project and CMS article/product creation guidance now share EmptyState: centered, transparent, compact type hierarchy and wrapping actions. Optional icon, layout and style are supported, and description is optional. The title now uses h2; migrate custom strong selectors to the title skin slot. Multiple actions use the shared action wrapper. Existing permissions and create handlers remain host-owned.
2026-09-08 · SidebarNavigation
SidebarNavigation prefetches same-origin routes after a 180 ms mouse hover or keyboard focus, sharing a limit of 8 destinations per 30 seconds across docked and popup navigation. Prefetching pauses offline, in hidden tabs, with Save-Data or on 2G; downloads, disabled links, new-window targets and same-page anchors are excluded. Navigation and unsaved-change guards are unchanged.
2026-09-08 - Primary button foreground
Primary pill buttons retain the Logo-blue fill #4695D8 and use white text, icons and loading indicators in both themes. Hover keeps the existing slight brightening. Secondary and danger buttons retain their own semantic colors.
2026-09-07 - AccountDropdown / SidebarProfile
AccountDropdown accepts optional compact and preferences: compact mode hides identifiers and creation history; the default retains existing content. Appearance and Language accept triggerRole="menuitem" inside account menus. Menu keyboard navigation restores focus and lets nested language dialogs handle Escape. SidebarNavigation.searchEnabled defaults to true; set it to false for short, fixed navigation. A SidebarProfile with href and no menu links to the same destination in expanded and icon modes.
2026-09-07 - FormField / AdminEntityDialog / EditorWorkspace
Shared form typography wraps long labels and metadata while keeping pill shapes and brand colors. FormField names composite groups; pair controlId with the nested input id for label focus. SearchField restores focus after clearing. Segmented and ControlMenu support disabled options; disabled ActionMenu items have no link. Busy buttons keep their size and visible indicator. AdminEntityDialog validates required fields, email and JSON, focuses errors, prevents duplicate saves and retains failed input. EditorWorkspace exposes ref.focusControl(element) to reveal hidden panels before focusing. Reduced motion disables control transitions. WorkspaceDialog scrolls long content while keeping its header and actions visible; short mobile dialogs fit their content.
2026-09-07 · WorkspaceLocationSync / ProjectSwitcher
After a route commits, WorkspaceLocationSync closes the transient space chooser so the destination immediately shows its tools. Search and section preferences remain. Sidebar scope labels and context badges occupy separate lines; long header switcher names truncate within the button.
2026-09-07 · Unified workbench navigation and rounded Qokit surfaces
WorkspaceNavigationDock reuses the host sidebar and its permissions on desktop; items, fallback, className and onClickCapture adapt its contents without loading another session. Expanded, icon and hidden states share the existing preference. At 860px and below, navigation uses the shared drawer. PlatformHeader.leadingContext also appears in EditorHeader, preserving workspace and project switching. Pill buttons and rounded content surfaces remain; repeated outlines are removed.
On desktop, clicking the menu hides the sidebar or restores its last visible mode. Dragging the menu or sidebar edge snaps between hidden, icons and expanded states. Left/right keys follow the reading direction. Cancelled drags keep the saved preference; mobile keeps the navigation drawer.
Mount WorkspaceLocationSync once under Suspense in a Next layout. useWorkspaceQueryState(key, defaultValue, validate) returns [value, setValue, ready]; useWorkspaceQueryRecord(key, defaults, validators) restores only declared flat filters. Keep credentials and drafts out of URLs. WorkspacePage restores bounded session scroll positions; nested scrollers use data-workspace-scroll-region with WorkspaceScrollRestoration. Native cancellable Back/Forward transitions reuse leave protection without adding history entries; other browsers retain their existing fallback. AdminEntityDialog retains input after failed saves and parent rerenders; hosts still own versions and save results.
Management typography uses stable roles: page title 20px/650, section title 16px/600, body and navigation 14px, labels 13px, captions 12px. --qk-workspace-body-ink and --qk-workspace-active-ink derive from existing platform colors.
Primary pill buttons use the Logo blue #4695D8 directly through --accent-action, with no darkened gradient. Hover adds 8% white; labels use brand ink mixed with 10% black for readability. Navigation highlights retain the same brand-blue tint and theme-aware text.
Dropdowns and workspace switchers share --menu-option-font-size (14px) and --menu-option-font-weight (500), with a 1.45 line height; selected options use weight 600 and metadata uses 12px/400. WorkspaceNavigationDock prefetches same-origin destinations on mouse hover or keyboard focus, with bounded deduplication. Navigation still uses the existing leave guards and host routes.
2026-09-07 - ColumnLayout
Desktop management hosts using ColumnLayout fill the viewport with docked navigation, independent content scrolling and a sticky page toolbar. WorkspacePage uses flat sections and shared control-radius Tokens. Navigation remains a drawer at 860px and below; closed drawers are inert. Props and business behavior are unchanged. Remove duplicate outer gutters and limit reading width within forms.
2026-09-05 · WorkspaceNavigationMenu / WorkspacePageHeader
Signed-in workspaces use PlatformHeader.workspaceActions for one account and navigation area at every width. WorkspacePageHeader shares titles and actions. WorkspaceNavigationMenu displays the current sidebar, preserving permissions and context; EditorNavigationMenu remains a compatible alias. Studio keeps its task toolbar. Public headers retain their existing presentation.
WorkspaceNavigationGuard protects global navigation with dirty, busy, error and optional onSave. Saving must resolve to true before leaving; failure retains the draft. Language.onBeforeChange(apply) lets the host defer a language change through the same guard. Keep form fields disabled while saving.
2026-09-05 · EditorNavigationMenu
EditorNavigationMenu reuses the host’s full SidebarNavigation in an overlay, preserving permissions and project context without resizing the canvas. Language and theme stay at the bottom; nested menus handle Escape first. At 1120px and below, the header uses two rows and a menu naming the current view. Focus and native browser fullscreen are independent; navigation waits for pending saves and protects drafts.
2026-09-05 · EditorHeader
EditorHeader keeps the host logo, account and global menu inside the active editor. startControl and endControl toggle the corresponding side panels; center holds view commands and actions holds save commands. PlatformHeader.editorActions reuses the responsive navigation, language and appearance controls. onNavigate must resolve unsaved changes before running its callback. On narrow screens the header uses two rows, and nested menus consume Escape before the editor does.
2026-09-05 · SidebarToggleSlot
SidebarToggleSlot places the existing sidebar toggle in a workspace header. Render one slot alongside one left sidebar. SidebarNavigation keeps ownership of collapse state, shortcuts and the mobile drawer; without a slot it keeps its original controls. The header button also closes the mobile drawer; closing restores focus to that same button.
2026-09-05 · EditorWorkspace / Dialog / Segmented
view / onViewChange select edit, focus, or preview without replacing the document editor. preview supplies a preview; previewPanel reuses an existing panel. layout supports writing, structure, and canvas. storageKey remembers panel widths and collapse preferences, never document data.
onSaveAndClose returns true only after a confirmed save, false on failure, handled when the host navigated, or pending when domain validation needs a decision. Failures keep the editor open. Use closeBehavior="collapse" only when the host retains the draft. EditorSaveStatus displays host-confirmed state; EditorViewControls, EditorLeaveDialog, and useEditorLayout can also be composed in existing workspaces.
Keyboard migration: Segmented has one Tab stop and uses arrows / Home / End to switch choices. Dialog respects a child overlay consuming Escape; the editor then exits focus or preview before closing. LivePreviewToolbar.exitControl accepts the shared view controls. Save shortcuts call the host; publishing and permissions remain host-owned.
2026-09 · EditorWorkspace
EditorWorkspace combines a full-screen dialog, focus management and responsive panels. Use dirty to confirm discarding changes, busy to block closing during saves, and onSave for Ctrl/Cmd+S. Hosts own permissions, data, saving and publishing.
2026-08 · Compact Metric Density
- Added the optional
density="compact"API toMetricCardfor dense operational workspaces; - Kept the existing default density and DOM semantics unchanged;
- Centralized compact padding, value scale, and minimum height in the shared component styles so routes do not need visual overrides.
2026-07 · Unified Form Controls
- Added
FormField,Input,Textarea,Checkbox,RadioGroup, andSwitchto@qokit/components/ui; - Connected labels, descriptions, errors, required state, and ARIA references through the shared
FormFieldskeleton; - Unified
Input,Textarea,Select, andSearchFieldaround 40px, 44px, and 48px control sizes and shared interaction Tokens; - Added platform, Admin, and generated-site Skin recipes for the new form primitives;
- Kept the existing
.qk-fieldstyles as a backward-compatible migration path.
2026-07 · Button Size Typography
- Added three semantic Tokens:
--button-font-size-sm,--button-font-size-md,--button-font-size-lg; - The
sm,md, andlgofButtonnow fix text sizes to 14px, 15px, and 16px respectively, no longer inheriting font sizes from Header, Dialog, or page containers; - Site Skins needing to adjust button typography should override the corresponding semantic Token, rather than rewriting
font-sizevia route classes.
2026-07 · Platform Public Navigation Skeleton
- Added
PlatformHeaderwithout login dependency, allowing the platform and documentation site to share the same semantic skeleton; - Added
PublicPlatformHeaderandbuildPublicHeaderNavItems, enabling the platform's anonymous state and the documentation site to reuse the same public Header composition and navigation configuration; HeaderNavItemaddedmenutype; desktop Headers use closable dropdown menus, while mobile Headers automatically expand into link groups;SiteFooteradded optionalbrandHrefandcontrols, supporting different integration scenarios such as public documentation;- Added
PublicPlatformFooter, allowing the platform and documentation site to reuse the same Footer Shell, with support for cross-domain resolution of platform links; - All of the above are backward-compatible optional APIs; existing platform Header state logic and Footer default controls remain unchanged.
2026-07 · Public Design Guidelines
- Separated public design contracts from internal AI implementation specifications;
- Published visual Tokens, component imports, Skeleton/Skin boundaries, Button, Card, and accessibility requirements;
- Clarified that breaking component changes must include migration instructions;
- Ensured public search, Sitemap, and LLM outputs contain only externally dependant content.
Compatibility Notes
-
Added optional properties, optional Skin slots, and semantic Tokens generally maintain backward compatibility;
-
Deleting or renaming properties, or changing default DOM/semantic/keyboard behavior constitutes a breaking change;
-
Breaking changes will detail the impact scope, alternative APIs, and migration steps on this page.
-
2026-09-06: Desktop navigation retains expanded and icon modes and adds auto-hide. SidebarNavigation / WorkspaceNavigationMenu / Dialog
-
2026-09-06: EditorViewControls separates Edit/Focus from native screen fullscreen. EditorViewControls
-
2026-09-06:
LanguageandAppearance variant="menu"accept optionallayout="row"to display a label, current value and chevron. The default compact layout and language-change guard remain unchanged.SiteHeaderCopy.helpResourcesandcontactSupportoptionally label workspace help links. Language / Appearance -
2026-09-06: Sidebar pages remove the duplicate header menu button; the existing toggle and navigation API remain available. WorkspaceNavigation
-
2026-09-06: Global navigation uses a menu icon; editor tools use directional panel icons. WorkspacePanelReveal / EditorViewControls
-
2026-09-06: Display mode ·
E/T/V/F·Segment.shortcut. EditorViewControls -
2026-09-06:
PlatformHeader.workspaceNavigationplaces global navigation before the logo PlatformHeader.workspaceNavigation
2026-09-06 - EditorHeader.preview / EditorViewControls.returnView
EditorHeader.preview keeps only center as a compact borderless preview toolbar; logo, account, save and panel controls remain mounted but hidden. Hosts with a separate LivePreviewToolbar may hide the editor header and pass EditorViewControls.returnView (edit or focus) to restore the preceding mode. Keep accessible return and independent fullscreen controls; the website's own header remains in the preview.
2026-09-06 · Builder / CMS
Builder and CMS content editing share BuilderWorkspace, EditorCatalog and EditorComponentSettings for panels, insertion graphics and presentation controls. Preset changes apply their linked settings together and preserve authored content; each host owns persistence and undo. Workspace controls follow the platform theme, while rendered content follows the site theme.
2026-09-06 - EditorViewControls
One button switches both ways: Edit shows Focus, and Focus shows Edit. Click it or press T; E still returns directly to Edit. On narrow headers, the switch stays visible and Preview, Fullscreen and extra actions appear in More. EditorViewControls
2026-09 · Management workspaces
Narrow WorkspaceDataTable and AdminDataTable layouts now default to labeled records, preserving selection, custom headers and actions. Set mobileLayout="scroll" for comparison matrices that must retain aligned columns. WorkspaceFilterToolbar places search before filters, then sort and view controls. Sidebar titles use h2; the page owns h1.
2026-09-08 · Task focus
useSidebarTaskFocus(active) temporarily hides navigation during a focused task. It restores the prior display on exit unless the user explicitly changes the navigation mode; automatic hiding does not overwrite the saved preference.