Skip to content

feat(theme): rest the header tool buttons in a quiet tone - #237

Merged
capjan merged 5 commits into
mainfrom
feat/quiet-controls
Nov 15, 2026
Merged

capjan merged 5 commits into
mainfrom
feat/quiet-controls

Conversation

@capjan

@capjan capjan commented Nov 15, 2026

Copy link
Copy Markdown
Owner

Adopts "quiet controls" (from the TenFingers UX concept, adapted for the web): tool buttons are not the content, so they rest in the secondary tone like the navigation already does, and only light up when they are the topic.

  • New tokens in main.css: --control-rest (= --text-secondary), --control-current (= --text-primary), --control-current-fill (10 % primary over the page) and --control-disabled (30 % primary). Aliases, so dark mode and custom palettes follow on their own.
  • Header tool buttons rest quietly: menu, sidebar/TOC panel toggles, search as an icon, theme, media settings, repository link. Hover is unchanged (--link for the round buttons; the square panel toggles get --hover-background plus the primary tone). The open mobile menu (aria-expanded="true") shows the primary tone.
  • prefers-contrast: more keeps tool buttons in the primary tone.
  • Gallery buttons that cannot move further use --control-disabled instead of secondary at 60 % opacity.
  • The site title, the current tab and page, content, cards, open menus and dialog buttons stay bright.
  • AGENTS.md gets a "Quiet controls" section next to the focus rule; the MDU design system documents the rule, the tokens and the contrast values.

Contrast: rest 5.20:1 (light) / 5.64:1 (dark) on the page, above AA for text; disabled 1.97:1 / 2.51:1, clearly below the rest tone.

Checked in a served page (design system docs) in light and dark mode at 1440 px and 390 px: header tool buttons quiet, title and current tab bright, the open mobile menu bright, keyboard focus ring unchanged. Markdown.Renderer.Test green (788).

Adds the control tokens --control-rest, --control-current, --control-current-fill and --control-disabled. The menu, panel, search, theme, media and repository buttons rest in the secondary tone and turn bright on hover or when the mobile menu is open; with prefers-contrast: more they keep the primary tone. Gallery buttons that cannot move further use the disabled tone.
… throughout

Sets the control tokens again in the header over the beach hero, where the text turns white. Only the open overlay menu brightens the menu button; on wide screens it toggles a panel and stays quiet. The menu button hovers to --link like the other round buttons, the code copy button and gallery controls use --control-rest, and the header buttons get their color from one shared rule.
The sidebar of a tab section now always starts with the section's own page, flush with the tabs and in normal case, so readers reach it from the sidebar and not only from the tab. Before, it was a small uppercase label that was hidden whenever pages outside the tabs followed.
The bar behind the header and tabs fades its background over 300 ms for the hero, so on a theme switch it lagged behind the page and flashed grey. theme.js now turns transitions off for two frames whenever the color scheme changes, by the toggle or by the system.
@capjan
capjan merged commit 12c3bd7 into main Nov 15, 2026
7 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant