Improve Flutter Web accessibility: update flt meta viewport tag to align with WCAG 2 guidelines

[jlemanski1]

This PR updates the parameters in the flutter viewport meta tag to align with the WCAG 2 rule concerning restricting user scaling and increases the light house accessibility score of a brand new Flutter Web project. Using the hello_world example project, the lighthouse accessibility score jumps from 87 to 95.

The reason for this change is the failure of Flutter Web in automated accessibility check the values of the user-scalable and maximum-scale properties. When evaluating Flutter Web against other frameworks, this restriction can be a blocker for many organizations.

Before	After

One workaround for this issue is to use the CustomElementEmbeddingStrategy and set up the viewport tag and container element yourself, though this is not a welcoming workflow for developers that are new to Flutter Web.

Fixes:

• #97305
• #122127

Pre-launch Checklist

• I read the [Contributor Guide] and followed the process outlined there for submitting PRs.
• I read the [Tree Hygiene] wiki page, which explains my responsibilities.
• I read and followed the [Flutter Style Guide], including [Features we expect every widget to implement].
• I signed the [CLA].
• I listed at least one issue that this PR fixes in the description above.
• I updated/added relevant documentation (doc comments with ///).
• I added new tests to check the change I am making, or this PR is [test-exempt].
• I followed the [breaking change policy] and added [Data Driven Fixes] where supported.
• All existing and new tests are passing.

[gemini-code-assist]

Code Review

This pull request updates the viewport meta tag for Flutter Web applications to improve accessibility. Specifically, it removes the user-scalable=no attribute and increases maximum-scale from 1.0 to 5.0, aligning with WCAG guidelines that recommend allowing users to zoom. The corresponding test in window_test.dart has also been updated to reflect these changes.

[mdebbar]

Thanks for looking into this!

I haven't tested this patch yet, but I'm curious what happens when you scale a Flutter app? Does it continue to work correctly? What does the browser do when the user scales the page, does it change the devicePixelRatio?

[jlemanski1]

Hi @mdebbar,

No worries!

I did some basic testing with a Flutter web app that measured pointer events, had text, sliders, and some gesture detection and I found no regressions on desktop web or mobile web when compared to the latest stable Flutter release. Running the web app on my local Flutter Engine from this branch, the devicePixelRatio changes with the browser zoom. With a browser zoom of 75%, MediaQuery.devicePixelRatioOf(context) will return 0.75, 100% will return 1.0, 150% will return 1.5, and so on. This same behaviour is observed when running the same example against the latest Flutter release.

The browser scales as expected in on either this branch or the latest stable release, the main difference is that automated accessibility checks don't flag this version as it doesn't have the user-scalable=no & maximum-scale=1.0 viewport properties that has existed in Flutter Web.

[flutter-zl]

Confirmed locally by deploying both branches to Firebase:

• Before the PR change: https://flutter-demo-15-before.web.app
• After the PR change: https://flutter-demo-15-after.web.app

The audit fix works as advertised: Lighthouse / ACT b4f0c3 passes, Cmd +/- and devicePixelRatio behave the same as on stable, matching @mdebbar's question above.

One thing worth flagging though: this PR doesn't actually unblock pinch-zoom on mobile. _setHostStyles at full_page_embedding_strategy.dart#L183 sets touch-action: none on the body, so pinching the canvas still does nothing on Chrome. So this fixes #122127 (the audit), but #97305's original ask, "support scaling page content using two-finger pinch gesture", is still inert.

[jlemanski1]

One thing worth flagging though: this PR doesn't actually unblock pinch-zoom on mobile. _setHostStyles at full_page_embedding_strategy.dart#L183 sets touch-action: none on the body, so pinching the canvas still does nothing on Chrome. So this fixes #122127 (the audit), but #97305's original ask, "support scaling page content using two-finger pinch gesture", is still inert.

Thank you for validating @flutter-zl

The initial issue I had opened, 97305 was for the audit only, but was renamed by someone on the Flutter team in 2022. For context on the initial issue, the primary goal at the time was to resolve the audit as that web app had implemented pinch to zoom at the widget level. The web app was for a large American university that required a certain level of accessibility to receive approval/funding, and unfortunately that viewport tag was the piece that preventing that audit from passing.

Personally, I would like to see this change brought into Flutter so that a fresh flutter web app (with the lang attribute added to the index.html), hits 100 on Lighthouse scores. Implementing pinch-to-zoom within Flutter is a larger task that can be handled separately.

I'm happy to update the PR to tag it to only 122127, the audit issue if that helps to get this merged. Just let me know!

Thanks

[flutter-zl]

One thing worth flagging though: this PR doesn't actually unblock pinch-zoom on mobile. _setHostStyles at full_page_embedding_strategy.dart#L183 sets touch-action: none on the body, so pinching the canvas still does nothing on Chrome. So this fixes #122127 (the audit), but #97305's original ask, "support scaling page content using two-finger pinch gesture", is still inert.

Thank you for validating @flutter-zl

The initial issue I had opened, 97305 was for the audit only, but was renamed by someone on the Flutter team in 2022. For context on the initial issue, the primary goal at the time was to resolve the audit as that web app had implemented pinch to zoom at the widget level. The web app was for a large American university that required a certain level of accessibility to receive approval/funding, and unfortunately that viewport tag was the piece that preventing that audit from passing.

Personally, I would like to see this change brought into Flutter so that a fresh flutter web app (with the lang attribute added to the index.html), hits 100 on Lighthouse scores. Implementing pinch-to-zoom within Flutter is a larger task that can be handled separately.

I'm happy to update the PR to tag it to only 122127, the audit issue if that helps to get this merged. Just let me know!

Thanks

Agreed the audit fix is worth landing on its own. LGTM.

[flutter-zl]

LGTM

[chunhtai]

I am not sure this really brings value besides makes muted the warning in lighthouse or audit tool. For those who is chasing VPAT or WCAG compliance, they would still need to make sure the pinch zoom works before checking off the checkbox

[jlemanski1]

Hi @chunhtai,

From my perspective, the value-add for this change is the resolved warning in lighthouse. It doesn't implement pinch to zoom Flutter web-wide, but if you implement it at the application-level, the viewport tag will no longer plague you in lighthouse scores.

Optics-wise, it also vastly improves the lighthouse accessibility score on a fresh flutter web project. When teams are evaluating Flutter web, it can be disconcerting to read the accessibility page in the docs, then spin up a fresh project and see warnings.

[chunhtai]

yeah.. i guess sooner or later we need to add the attr. LGTM then