Docs frontend UI kit (premium surfaces and interactions)
Overview
This page defines the visual system for premium docs frontend surfaces: command palette, page actions, hotkey tip, continue-reading card, and page feedback card. The goal is consistent quality in both light and dark themes.
- Scope: interactive docs chrome provided by
docs/assets/docs-nav.jsand styled indocs/assets/docs.css. - Audience: maintainers of docs frontend UI and contributors updating docs experience components.
- Design intent: compact, modern, low-noise premium UI with strong keyboard and accessibility support.
Required page contract
Pages that rely on this UI kit must keep the shared docs frontend mounts and scripts.
| Contract element | Required markup | Purpose |
|---|---|---|
| Top navigation and quick actions | <div id="docs-top-nav"></div> |
Mount for top nav and page actions toolbar with command palette launcher. |
| Page editors metadata | <div id="docs-page-meta-mount" hidden></div> + data-maintainer-ids |
Maintainer avatars and editors panel. |
| Auto in-page TOC | <div class="docs-inpage-toc-mount" data-inpage-toc="auto"></div> near end of <main> |
Stable insertion point for “Page feedback” card and TOC layout. |
Script dependencies: docs/assets/docs-nav.js, docs/assets/docs-portal-data.js, and
docs/assets/docs-internal-meta.js.
Component inventory
| Component | Main selectors | Behavior owner |
|---|---|---|
| Page actions toolbar | .docs-page-actions, .docs-page-actions__button, .docs-page-actions__link |
injectDocsPageActions() |
| Command palette | .docs-quick-actions* |
installDocsQuickActionsUi() |
| Hotkey hint tip | .docs-hotkey-tip* |
injectDocsHotkeyHint() |
| Continue reading card | .docs-continue-reading* |
injectDocsContinueReading() |
| Page feedback card | .docs-feedback-card* |
injectDocsFeedbackCard() |
Visual principles
- Premium surface: layered gradient plus subtle inner highlight, never flat gray blocks.
- Low-noise density: compact spacing and restrained shadows to keep focus on content.
- Modern corners: soft rounded rectangles (not old pill-heavy controls by default).
- Predictable states: hover, focus, and active use one coherent accent language.
- Theme parity: dark mode uses dedicated tokens, not naive inversion.
Design tokens
Premium UI surfaces must use shared token variables from :root and :root[data-theme="dark"],
not hard-coded per-component colors.
| Token | Use |
|---|---|
--docs-premium-surface-border | Main panel/card border for command palette and premium cards. |
--docs-premium-surface-bg | Primary layered surface background. |
--docs-premium-surface-shadow | Depth model for primary panels. |
--docs-premium-chip-bg | Buttons/chips background in toolbars and floating cards. |
--docs-premium-chip-border | Buttons/chips border color. |
--docs-premium-item-border | Command palette item border. |
--docs-premium-item-bg | Default item background. |
--docs-premium-item-hover-bg | Hover item background. |
--docs-premium-item-active-bg | Active/focused item background. |
--docs-premium-focus-glow-soft | Outer soft glow layer for focus-visible. |
--docs-premium-focus-glow-strong | Inner strong glow ring for focus-visible. |
Interaction model
- Open/close: command palette supports hotkeys and launcher button; repeated trigger toggles panel.
- Keyboard navigation: arrow keys move active item, Enter executes, Esc closes panel.
- New tab behavior: Cmd/Ctrl + Enter opens active navigation target in new tab.
- Motion profile: short premium easing and reduced-motion fallback are mandatory.
- Viewport policy: quick actions + page actions are desktop/tablet only; mobile widths disable them.
Accessibility requirements
- Palette panel must preserve dialog semantics:
role="dialog",aria-modal, and labeled title. - Interactive controls must have visible
:focus-visiblestates and sufficient contrast in both themes. - Feedback and toast surfaces must use live-region semantics where status updates are dynamic.
- Keyboard shortcuts should not hijack typing behavior in form fields.
- Reduced-motion mode must suppress non-essential transforms and animations.
Implementation map
docs/assets/docs-nav.js— lifecycle, rendering, keyboard handling, and runtime composition.docs/assets/docs.css— token definitions, theme overrides, component visuals, state styling.docs/internal/front/docs-frontend-hotkeys.html— end-user shortcut reference.docs/internal/front/docs-frontend-menu-and-theme-controls.html— broader docs frontend UX requirements.
QA checklist
- Verify all premium surfaces in both light and dark themes (toolbar, palette, tip, continue-reading, feedback).
- Run keyboard-only pass: open, navigate, execute, close, and return focus correctly.
- Validate focus-visible rings and glow contrast on interactive controls.
- Check reduced-motion mode to ensure animations are disabled or near-instant.
- Check responsive behavior at desktop, tablet, and phone breakpoints.
- Run
make docs-html-checkafter UI changes.
Change management rules
- When adding a new premium docs component, define tokens first, then implement styles.
- Avoid introducing one-off colors/shadows in component rules without token coverage.
- Any visual update in one theme must be reviewed for parity in the other theme.
- Update this page and hotkeys page whenever interaction model or shortcuts change.
Page history
| Date | Change | Author |
|---|---|---|
| Initial UI kit spec for docs premium surfaces, tokens, interaction model, accessibility, and QA baseline. | Ivan Boyarkin |