Skip to content

Document the [bar] size keys - #13137

Open
cristian-fleischer wants to merge 2 commits into
omacom:quattrofrom
cristian-fleischer:bar/1-numeric-keys
Open

cristian-fleischer wants to merge 2 commits into
omacom:quattrofrom
cristian-fleischer:bar/1-numeric-keys

Conversation

@cristian-fleischer

@cristian-fleischer cristian-fleischer commented Sep 24, 2026 •

Copy link
Copy Markdown

201de1c already lets the [bar] size keys through the Style.qml parser, so this PR no longer changes code. What is left is the docs.

  • docs/omarchy-shell.md, the theme template and the Style.qml header list icon-slot, icon-canvas, icon-size, icon-font and status-slot next to the two bar sizes.
  • icon-font is described as what it does: the font size an icon button renders its glyph and label at. The drawn glyph is still rescaled to fit icon-size.

The parser test is gone: it passed on quattro without this PR.

Part 1 of #11359 (thanks @fk1blow for the analysis). #6587 by @tmn73 made the same parser fix first; I missed it when I searched for duplicates.

#13138 and #13139 no longer depend on this PR.


Part of a set of opt-in bar changes described in #13136: #13137 [bar] size keys, #13138 floating, #13139 pills, #13140 bar options. Nothing changes unless you turn it on.

Claude (Anthropic) wrote most of this under my supervision; I reviewed it and run it on my own Omarchy install.

@llstrk

llstrk commented Sep 24, 2026

Copy link
Copy Markdown

Automated AI review

Community review: Independent automated community review, unaffiliated with the Omarchy team, intended to help prepare PRs for their review.

Verified: The parser change fixes the reported gap. [bar] icon-slot, icon-canvas, icon-font and status-slot set in a theme or user shell.toml now reach Style.bar.*. They follow the same parsing, fallback, [font] base-size scaling, scale-with-font and user-over-theme rules as size-horizontal and size-vertical. Configs that set none of these keys (no file, the stock template, size-only overrides) produce identical bar token values on base and head. barOverrides is read only by barToken(), which is called only with its six declared keys, so extra keys such as background-alpha are stored but unused.

Bar tokens with a synthetic user shell.toml (defaults at base-size 12: iconSlot 27, iconCanvas 16, iconFont 13, statusSlot 21):

[bar] input Base (iconSlot/iconCanvas/iconFont/statusSlot) PR
icon-slot = 34, icon-canvas = 22, icon-font = 24, status-slot = 26 27/16/13/21 (ignored) 34/22/24/26
same, plus [font] base-size = 18 41/24/20/32 51/33/36/39
theme icon-font = 20, user icon-font = 15 iconFont 13 iconFont 15
keys removed again defaults defaults
icon-font = 0, -4, "big" 13 13 (fallback, same rules as the size keys)

Added test matches source text, not parser behavior

The new assertion in test/shell.d/bar-test.sh requires the literal key === "size-horizontal" to be absent and an exact two-line parseInt/barOut[key] statement to be present. It fails on the base and passes on the head, but it does not check that any key reaches barToken(). Diagnostic in-memory variants of Style.qml:

Variant New assertion All six keys applied
PR as submitted pass yes
Explicit six-key allowlist (the fix suggested in #11359) fail yes
PR with const b instead of var b fail yes
Allowlist of size-vertical only pass no
PR parser, but barToken() ignores overrides pass no

Impact: Test-only. A regression of this bug written differently would still pass, and an equivalent refactor would fail.

Suggested change: Evaluate the real functions instead of matching text: extract barToken, boolToken and applyShellValues from Style.qml into a vm context (the pattern plugin-auth-boundary-test.sh already uses), apply all six bar.* keys, and assert each barToken() result. A candidate of this shape failed on the base at icon-slot (expected 30, got 1), passed on the head, and classified all four variants above correctly.

Candidate assertion (replaces the new block in the run_node_test section)
const vm = require('vm')
const styleSource = fs.readFileSync(root + '/shell/Commons/Style.qml', 'utf8')
function qmlFunction(source, name) {
  const start = source.indexOf(`function ${name}(`)
  let depth = 0
  for (let i = source.indexOf('{', start); start >= 0 && i < source.length; i++) {
    if (source[i] === '{') depth++
    else if (source[i] === '}' && --depth === 0) return source.slice(start, i + 1)
  }
  throw new Error(`Style.qml has no function ${name}`)
}
const style = vm.createContext({})
vm.runInContext(
  ['barToken', 'boolToken', 'applyShellValues'].map(name => qmlFunction(styleSource, name)).join('\n') +
  '\nvar fontScale = 1, barScaleWithFont = true, barOverrides = {}',
  style
)
style.applyShellValues({
  'bar.size-horizontal': '32', 'bar.size-vertical': '34', 'bar.icon-slot': '30',
  'bar.icon-canvas': '20', 'bar.icon-font': '17', 'bar.status-slot': '25'
})
for (const [key, value] of [['size-horizontal', 32], ['size-vertical', 34], ['icon-slot', 30],
                            ['icon-canvas', 20], ['icon-font', 17], ['status-slot', 25]]) {
  assertEqual(style.barToken(key, 1), value, `[bar] ${key} in shell.toml reaches barToken()`)
}

Optional documentation note: The four keys that now take effect are not described anywhere users look: the "Bar size" section of docs/omarchy-shell.md, the [bar] comments in default/themed/shell.toml.tpl and the Style.qml header cover only size-horizontal and size-vertical. A short entry for each (slot width, icon canvas, glyph size, status indicator slot; defaults 27/16/13/21 at base-size 12, scaled with the font unless scale-with-font = false) would make the fix discoverable without reading the source.


Review information

Test scope: Source review of head d6fa34d against quattro at 28ceaae. The parser, token and shell.toml loading functions were copied verbatim from both snapshots into a synthetic harness object and run in an isolated Qt 6.11.2 QML engine (offscreen), with a V8 cross-check that agreed on every scenario. The JavaScript block of bar-test.sh ran under Deno on both snapshots. The real Quickshell singletons, the full test suite, the shell portions of bar-test.sh and live bar rendering at larger sizes were not exercised.

AI process: Opus 5.5 Medium coordination and synthesis, independent Opus 5.5 Xhigh and GPT 6 Sol Xhigh technical assessments, Opus 5.5 Medium editorial check.

Opt out: To stop receiving these reviews, reply to this comment saying so.

@cristian-fleischer

Copy link
Copy Markdown
Author

Thanks @llstrk, useful review. I took your harness almost as is: bar-test.sh now runs the real parser and barToken() and checks all six keys, and it fails on the base at icon-slot. The four keys are documented in docs/omarchy-shell.md, the theme template and the Style.qml header.

@llstrk

llstrk commented Sep 27, 2026

Copy link
Copy Markdown

Automated AI review

Community review: Independent automated community review, unaffiliated with the Omarchy team, intended to help prepare PRs for their review.

Follow-up to the earlier review and the author's reply, checked at head ab3fa9e. Both earlier points are resolved. No new defects were found.

Earlier point Status at ab3fa9e
Added test matched source text, not parser behavior Resolved
Four newly effective keys undocumented Resolved (one wording note below)

Verified (test): test/shell.d/bar-test.sh now extracts barToken, boolToken and applyShellValues from Style.qml into a vm context, applies all six bar.* keys and checks each barToken() result. On the base Style.qml it fails at icon-slot (expected 30, actual 1), and test/shell reports the file as failed. The full file passes on the head. Diagnostic Style.qml variants:

Style.qml variant Real regression? New test Earlier text-matching test
Base parser (size keys only) yes fail fail
Allowlist of size-vertical only yes fail pass
Five-key allowlist without icon-font yes fail at icon-font fail
barToken() ignores overrides yes fail pass
barOverrides = barOut removed yes fail pass
Explicit six-key allowlist, const b, parseFloat no pass fail

The test fixes fontScale at 1 and calls barToken() directly, so base-size scaling, scale-with-font parsing and the Style.bar property wiring are not covered. None of these paths is changed by this PR.

Verified (docs): The four keys are now in the "Bar size" block of docs/omarchy-shell.md, the [bar] comments of default/themed/shell.toml.tpl and the Style.qml header. The documented defaults 27/16/13/21 match the barToken() fallbacks, and the scaling statements match barToken(). Uncommenting the new template lines parses correctly and leaves every token at its default.

Verified (production): Since the earlier reviewed head d6fa34d, the commit changes only comments, docs and the test. The parser behavior from the earlier review still holds: the four keys reach Style.bar.* (34/22/24/26, or 51/33/36/39 at base-size 18), user values win over theme values, invalid values fall back, and configs without these keys give the same tokens as the base.

Optional documentation note: "width of one widget slot" (icon-slot) and "width of a status indicator slot" (status-slot) hold only for top/bottom bars. On left/right bars, icon buttons and status indicators use these values as the slot's height (shell/Ui/BarIconButton.qml:20-21, shell/Ui/BarIndicator.qml:49-50). The earlier review's "slot width" wording contributed to this. Wording such as "length of one icon slot along the bar" would fit both orientations. Also, icon-font does not reach status indicators, which use Style.font.caption (shell/Ui/BarIndicator.qml:46); the PR description already leaves glyph sizing out of scope.


Review information

Test scope: Source review of head ab3fa9e against the earlier reviewed head d6fa34d and the merge-base 28ceaae. bar-test.sh ran in an isolated sandbox under Node on the head, and the head test also ran against the base and earlier-head Style.qml and 13 diagnostic variants. The earlier review's token scenarios, other than the reload after removing the keys, were rerun with the real shell.toml parsing and merging functions and the Style.qml token functions under Node, with fontScale modeled from base-size. Not exercised: Quickshell's QML engine, the full test suite and live bar rendering.

AI process: Opus 5.5 Medium coordination and synthesis, Opus 5.5 Xhigh technical review and final fact check, GPT 6 Sol Xhigh search for related issues, Opus 5.5 Medium editorial check.

Opt out: To stop receiving these reviews, reply to this comment saying so.

@cristian-fleischer

Copy link
Copy Markdown
Author

Thanks @llstrk. Fixed the wording: icon-slot and status-slot now say "length along the bar", and icon-font says it applies to icon buttons.

@omarchybot omarchybot added verified Omarchy Triage has verified that this issue is ready for final review ready Good to merge labels Oct 3, 2026
@omarchybot

Copy link
Copy Markdown
Collaborator

Reviewed and reproduced on an Omarchy worker VM. The bug is real on current quattro and this fixes it. Nothing found that needs changing.

Reproduction. I wrote my own check rather than relying on the PR's test: a shell.toml with [font] base-size = 18 and all six [bar] size keys, run through the real Color.parseShell and Style.applyShellValues, then read through barToken() the way Style.bar does. On quattro (821ae589), icon-slot, icon-canvas, icon-font and status-slot stay at their defaults (41/24/20/32 at that font size). On this head they take the configured values (51/33/36/39). With only the parser hunk reverted, they fall back to the defaults again. In the live shell on the worker, setting icon-slot = 60 and status-slot = 60 in ~/.config/omarchy/shell.toml visibly widens the bar's icon and indicator slots.

Tests. I merged this head onto quattro and ran it on the worker. test/shell.d/bar-test.sh passed 94 of 94 and theme-staging-test.sh passed 8 of 8. ./test/cli had one failure, vscode generated theme references current theme file, which fails the same way on quattro without this change. The new bar-test.sh assertions fail on quattro's Style.qml at icon-slot (expected 30), so they test the behaviour rather than the text.

Side effects. Other numeric [bar] values, such as background-alpha, now land in barOverrides too. barToken() is the only reader of barOverrides, and it only asks for its six size keys, so those extra values are never read. Colours and alpha still come from shellValues. Configs that set none of the four keys produce the same tokens as before.

Second opinion. Codex Medium reviewed the same diff and found no defects. It agreed on the side effects and on the test failing on the base. It also checked the documented defaults (27/16/13/21) and the "along the bar" wording against BarIconButton.qml and BarIndicator.qml, and both match. It could read this review's working notes, so its agreement is not guaranteed to be independent.

Related. #6587 makes the same parser change and came first. This PR adds a behavioural test and documentation for the four keys, and both reviews prefer it for that. Which one lands is the maintainer's call. This covers part 1 of #11359. The glyph-sizing half is still open, so this PR is not linked to close that issue.

Waiting on the maintainer.

@omarchybot omarchybot removed ready Good to merge verified Omarchy Triage has verified that this issue is ready for final review labels Oct 10, 2026
@omarchybot

Copy link
Copy Markdown
Collaborator

This now conflicts with quattro, and on a second look it competes with #6587, which makes the same parser change and came first. Under how competing fixes are settled here — the older one lands unless the newer fixes something it misses — #6587 is the one to bring forward, and what this pull request adds goes into it with credit to you.

Same fix. Against current quattro (04b374a9), both replace the [bar] allowlist in shell/Commons/Style.qml with an else that keeps every numeric value, and the two applyShellValues bodies match apart from comments. The conflict here is only that quattro added notch-height to the allowlist this pull request replaces; keeping this side covers it, since notchHeight reads barOverrides["notch-height"] directly. Neither change breaks it, and #6587 already merges cleanly.

What this one adds. Your bar-test.sh block runs the real applyShellValues and barToken() and checks all six keys, while #6587's test only looks for quoted key names in the parser's text: it still passes if the assignment that stores the value is deleted, or if the allowlist comes back written with single quotes. The documentation in docs/omarchy-shell.md, the theme template and the Style.qml header is also only here. Those are improvements to the same fix rather than a defect in the older one, so they are being handed to #6587 to fold in, with a Co-Authored-By trailer for you.

What was checked. Both diffs read against current quattro, and a trial merge of this head onto it. Nothing was run on a worker this time, since this one is not the fix being brought forward; the earlier reproduction on this pull request still describes its behaviour.

Second opinion. Codex Medium was given both pull requests without my answer and came to the same choice. It added the two mutations above that #6587's test misses, and noted that the comment in the folded test should not claim every bar token goes through barToken(), since notch-height does not. It could read this session's working notes, so its agreement is not guaranteed to be independent.

Waiting on the maintainer.

@cristian-fleischer cristian-fleischer changed the title Read every numeric [bar] key from shell.toml Document and test the [bar] size keys Oct 16, 2026
@cristian-fleischer

Copy link
Copy Markdown
Author

Rebased on quattro. 201de1c already lets these keys through the parser, so I dropped the code change and kept the docs and the parser test. I think the widget sizes are still worth documenting, but if you'd rather not take docs on their own, feel free to close this. #13138 and #13139 don't depend on it anymore.

@greptile-apps

greptile-apps Bot commented Oct 16, 2026 •

Copy link
Copy Markdown
Contributor

RetriggerView in GreptileConfidence Score: 5/5

[Low impact] This documentation-only PR appears safe to merge.

Summary

Documents the five existing [bar] widget-size keys without changing behavior.

  • Theme guides now explain five bar widget size keys.

Reviews (5) · Last reviewed commit: "Merge remote-tracking branch 'origin/qua..." · Reviewed by Greptile

@omarchybot omarchybot removed the bug Something isn't working label Oct 16, 2026
@omarchybot

Copy link
Copy Markdown
Collaborator

Re-read at 318dd22f after the rebase. quattro now lets all seven [bar] size keys through the parser in shell/Commons/Style.qml (since 201de1c), so this pull request no longer fixes a bug, and I have taken the bug label off. What remains is documentation of those keys in docs/omarchy-shell.md, the theme template and the Style.qml header, plus the bar-test.sh block that runs the real applyShellValues() and barToken().

Classification is unsettled. I read it as documentation. Codex Medium, asked separately without my answer, read it as enhancement. The test block is code that runs, so it does not fit documentation cleanly either. Two models disagreeing means it gets no class label, and it was not verified or run on a worker this time.

What was read. I checked the documented keys and defaults against quattro and found nothing wrong. icon-slot 27, icon-canvas 16, icon-size 12 (capped at icon-canvas), icon-font 13 and status-slot 21 match the barToken() fallbacks in Style.bar. All of them scale with base-size unless scale-with-font = false. "Length along the bar" holds in both orientations (WidgetButton.qml, BarIndicator.qml). This was one model reading the code, with no second review of the content.

Related. #6587 makes the parser change that quattro now already has, so the earlier plan to fold this pull request's test and docs into it no longer applies as written. #11359 still has its glyph-sizing half open, so this is not linked to close it.

Waiting on the maintainer, who decides whether docs and a test for existing keys are worth taking on their own.

@cristian-fleischer
cristian-fleischer force-pushed the bar/1-numeric-keys branch 2 times, most recently from d04554d to 0b1af62 Compare October 29, 2026 14:55
Comment thread test/shell.d/bar-test.sh Resolved
@omarchybot

Copy link
Copy Markdown
Collaborator

Re-read at 0b1af623. The only difference from 318dd22f is the rebase onto newer quattro, and it still merges cleanly. Since the last comment, two models have reviewed the content, and they found two things worth changing.

icon-font is described wrongly. docs/omarchy-shell.md and default/themed/shell.toml.tpl say it is the "glyph size of a font icon on an icon button". In shell/Ui/BarIconButton.qml, icon-font becomes the button's fontSize (line 32), but the glyph is then drawn by OpticalGlyph with paintedSize: root.visualIconSize (line 78). That rescales it to fit icon-size (OpticalGlyph.qml, paintedScale). Raising icon-font does not make the visible icon bigger. It changes the font size the glyph is rendered at before that rescaling, and the size of a button's text label. Wording along the lines of "font size icon buttons render glyphs and labels at; the drawn icon still fits icon-size" would match the code.

The test does not fail without this pull request. quattro's applyShellValues has had all seven keys in its allowlist since 201de1c (shell/Commons/Style.qml:432-434), so the new bar-test.sh block passes on quattro as it is. The repository's AGENTS.md asks that "a test must fail without your change" and that a test earn its place by catching a regression nothing else would. The block does run the real parser, and it would catch a key being dropped from that allowlist again, which has happened once. Whether that is worth 29 lines with no code change beside it is the maintainer's call. Codex suggested keeping the documentation and dropping the test.

What checks out. The defaults (27/16/12/13/21) match the barToken() fallbacks, icon-size is capped at icon-canvas, and every key scales with base-size unless scale-with-font = false. "Length along the bar" for icon-slot and status-slot holds in both orientations (BarIconButton.qml, BarIndicator.qml:51-52, WidgetButton.qml:95-98).

Classification is still unsettled. I read this as documentation. Codex Medium, asked separately without my answer, read it as enhancement again. So it gets no class label, and nothing was run on a worker.

Who checked it. I (Claude Opus 5.5) read the diff against the code at this head. Codex Medium reviewed the same and raised both points above. I confirmed each one in the source. Codex could read this session's working notes, so its review is not guaranteed to be independent.

Waiting on the maintainer, who decides whether to take documentation for existing keys on its own, and whether to take the test. The icon-font wording is for @cristian-fleischer.

201de1c lets icon-slot, icon-canvas, icon-size, icon-font and
status-slot through the [bar] parser, which fixes part 1 of omacom#11359. The
keys are still missing from docs/omarchy-shell.md and the theme template.

docs/omarchy-shell.md and shell.toml.tpl list the keys with their
defaults; the Style.qml header names them. icon-font is the font size an
icon button renders its glyph and label at; the drawn glyph is rescaled
to fit icon-size, so it does not make the icon bigger.

Co-Authored-By: Claude <noreply@anthropic.com>
@cristian-fleischer cristian-fleischer changed the title Document and test the [bar] size keys Document the [bar] size keys Nov 2, 2026
@cristian-fleischer

Copy link
Copy Markdown
Author

Thanks, both fixed in f52df76. icon-font now reads as the font size an icon button renders its glyph and label at, with the glyph still fitting icon-size. The test is dropped, so this is docs only.

@omarchybot omarchybot added documentation Improvements or additions to documentation verified Omarchy Triage has verified that this issue is ready for final review ready Good to merge labels Nov 18, 2026
@omarchybot

Copy link
Copy Markdown
Collaborator

Checked at eb9aee581203914bfcbdbfe0b0906ba58b1faa06. The icon-font wording now matches the glyph and label rendering, and the redundant parser test is gone. I checked all five defaults, font scaling and scale-with-font = false, slot sizing in both orientations, and the icon-size cap against the parser and widget code. Nothing found that needs changing.

./test/all passed on a disposable Omarchy ISO worker: 7,805 checks passed, zero failed, across the CLI suite and all 427 shell test files. Six files included optional skipped checks. The run used the worker's installed Node with UTF-8 enabled; the QML object body and active template content are unchanged by this diff.

I reviewed this as GPT-6 in Codex (effort setting not exposed). Opus 5.5 High and muse-wonder via pi, thinking high, reviewed the same change and found no actionable defects. Their agreement is not guaranteed to be independent.

Waiting on the maintainer.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

documentation Improvements or additions to documentation ready Good to merge verified Omarchy Triage has verified that this issue is ready for final review

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants