Accessibility enhancement on styles

[evnchn]

Motivation

As mentioned in #5794, we can do better in accessibility.

This PR focuses on the styles.

Implementation

Manually-written because I cannot trust an AI on human accessibility.

The PR comments should be descriptive of the changes.

The policy is: Implement the change in library-level if possible, if not then at documentation-website-level.

Progress

• I chose a meaningful title that completes the sentence: "If applied, this PR will..."
• The implementation is complete.
• If this PR addresses a security issue, it has been coordinated via the security advisory process.
• Pytests are not necessary.
• We need a new documentation section for the new accessibility stuff, such as ui.colors(..., at_rule='@media (prefers-contrast: more)'), and general guidance, especially the forced-colors: variant.
  • Ref: ui.skip_to_main: skip to main content button #5790 as well

Final notes

Happy Lunar New Year everyone!

[falkoschindler]

Thanks for working on accessibility improvements, @evnchn -- this is a valuable area that deserves attention.

However, this PR has a few structural issues that make it hard to review and merge as-is:

Merge conflicts after website redesign (#5910)

The website was completely redesigned and merged in #5910. This PR touches 9 website files (header.py, main_page.py, star.py, style.css, style.py, windows.py, demo.py, overview.py, main.py) that were rewritten or restructured in the redesign. The PR is currently in a conflicting state, and resolving these conflicts would essentially mean redoing the website-level changes from scratch against the new markup.

Too many concerns in a single PR

This PR bundles at least 5 independent changes:

1. A new at_rule parameter on ui.colors() (public API addition)
2. prefers-reduced-motion: reduce support in nicegui.css
3. prefers-reduced-transparency handling for the header
4. forced-colors: active support across website components
5. Replacing hardcoded #5898d4 with var(--q-primary)
6. Removing smooth-scroll behavior from sub_pages

Each of these deserves its own review and discussion. Mixing a public API change with website styling tweaks makes it hard to evaluate the trade-offs individually.

PR description lacks detail

The description says "This PR focuses on the styles" and "The PR comments should be descriptive of the changes," but there is no explanation of what the changes are, why each one is needed, or what accessibility standards they address (WCAG level, specific success criteria, etc.). For a public API addition like at_rule, we'd want to understand the use cases and design rationale up front.

"Help wanted" tag is unclear

The PR is tagged as "help wanted" but doesn't specify what kind of help is needed -- code review? Testing with assistive technology? Completing the documentation mentioned in the checklist? This makes it hard for contributors to know how to pitch in.

Suggestion

Given the conflicts and the breadth of changes, it would probably make sense to split this into focused follow-ups:

• PR 1: ui.colors(at_rule=...) API addition + test -- this is the core library feature and needs the most design discussion
• PR 2: prefers-reduced-motion in nicegui.css + sub_pages smooth-scroll change -- small, self-contained
• PR 3: Re-apply forced-colors, prefers-reduced-transparency, and other website-level accessibility to the current website markup (post-redesign)

This way each change can be reviewed on its own merits and merged independently.

[evnchn]

@falkoschindler I guess we're familiar with the situation as it's appearing several times:

• This PR represents the best I can do functionality wise (highly conformant with the accessibility spec)
• But as a library the codebase have requirements on API, code quality, etc

And somewhere we'd meet in between. So that's kinda expected.

However the twist comes when we realize that for the documentation page that accessibility is evolving backwards.

And I don't blame the website design. It's a good one. It's just that IMHO modern design is somehow against accessibility without us realizing it, such as:

• Visual language decisions
• Visual decorative flares
• Visual de-emphasis (contrast with emphasized content)

And that, hot take, "modern" = "average in the modern era", where let's be honest, = "poor accessibility". It compounds with the use of AI, which is the ultimate average-finding machine.

Anyways, since the web design is out only a while, I'd think we can wait a while before shipping big changes, both to keep 3.10 sane, and to observe community feedback. Hence I would do PR 1 first, and PR 2 and 3 later.

P.S.: If you have accessibility needs and the new documentation webpage is not good, then please comment below. I'll iterate with you, and keep the branch up to date so that you can view the documentation nicely 😉

[falkoschindler]

Thanks for the thoughtful reply, @evnchn. You're right that modern design and accessibility often pull in opposite directions - that's a tension worth addressing.

But I want to pick up on something you said: "I guess we're familiar with the situation as it's appearing several times." That's exactly the pattern I'd like us to break. What keeps happening is:

1. A PR is created alongside many others
2. It bundles multiple independent changes, making it hard to review
3. The description stays vague, so reviewers have to reverse-engineer the intent
4. Due to too many open ends, the PR gets postponed to a later milestone
5. Meanwhile other work (like the website redesign) lands and creates conflicts
6. Eventually the PR has to be closed and the work starts from scratch

This is frustrating for everyone - you put in real effort and it goes stale before we can act on it.

The lesson I take from this is that we need to keep the number of open PRs small and focused. Fewer concurrent PRs means shorter response times on our side, fewer topics to juggle in parallel, and a much lower chance of conflicts making work obsolete. A single-purpose PR with a clear description ("adds X because Y") is far easier to review quickly than a broad one that touches multiple concerns.

So yes - let's start with the ui.colors(at_rule=...) idea. But before jumping into implementation, it might be worth discussing the API design first. For example, the same effect can already be achieved with ui.add_css(), so we should clarify what value a dedicated parameter adds and what the API should look like. A short discussion thread or issue would help align on that before writing code. In the meantime, the website-level accessibility improvements aren't blocked by this -- they can simply use ui.add_css() today.

[evnchn]

@falkoschindler I'm sleeping soon, but few points:

1. Some workflow enhancements have already been done on my side, where https://github.com/evnchn/nicegui/pulls now has 25 decently-triaged PRs which track changes similar to this PR (big, meets goals, needs division for upstreaming). Fixes your point (1) and (4) in the long term, and with work we can address (2)
2. I don't think PRs like this one is "wasted work" since (a) labour is cheap nowadays with AI to thank, (b) without this we don't discover what NiceGUI can do and then work towards meeting there.
3. I'm commited to enhancing the PR description because it's something I keep forgetting with these PRs as they represent projects not individual changes sometimes, fixing (3)

I think we'd meet in the middle for how we work as well, because I (and possibly others, and maybe the AI I use after following me so long) prefers to work top-down instead of bottom up. I like to answer "How might we XXX" more than "What fundamental building blocks are required to do XXX". Though both solve XXX I think you get the difference.

For now I'd suggest:

• Separate project stretches from individualized PRs. It can be fancy like a label, or as simple as redefining the definition of draft to include project stretches.
• Maybe you can look at https://github.com/evnchn/nicegui/pulls when you have the bandwidth.

Bottom line being, Yes to "breaking the pattern", sorry but no to eliminating project stretch PRs altogether, as no projects = no innovation = no upstream-ready PRs, because downstream's where the party's at. They need to exist but we need to make it work nicely.