Improve new Blazor project templates.

[EdCharbeneau]

Summary

File > New templates are the first thing developers see when they try Blazor. The templates shouldn't promote bad practice and poor accessibility. Fixing a few issues would improve the overall optics of Blazor for people onboarding, especially if they're coming from other frameworks that are detail oriented in terms of HTML/CSS/A11y.

Motivation and goals

1. Markup, CSS issues:

The !important keyword in CSS is a code smell. In this case, the template has used the Bootstrap utility px-4 class​ to set the padding in the markup. In the CSS, the class is overridden using a new selector and padding value. This causes confusion when customizing the template.

This is just one simple example, but overall it is a lot of CSS and Bootstrap fighting each other. My recommendation would be to go all in on Boostrap, or remove it completely. I've been working on an example that leans into Boostrap and eliminates redundant CSS like the example above. As much as I personally would like to see Boostrap sunset, it is still one of the easiest ways to onboard new devs.

The structure of the topbar, sidebar and main page are oddly constructed in markup. I feel like this might be related to the Boostrap and CSS duality.

2. A11y:

There is at least one priority item, like turning off a11y features directly through CSS, this focus effect. *:focus is one of the most common a11y criticisms. We should look at color contrast as well, since this is another high priority and easily remedied.

There's also an interesting and creative 💖 use of a checkbox to control the responsive menu. I feel that this was implemented to help with static rendering, so the nav could be hidden and shown on mobile without interactivity (C#/JS), however the a11y aspect of it is questionable. In the short term, this item should have aria-controls​ attributes added to it. In the long term, something needs to address the missing aria-expanded​ attribute (likely requires interactivity to toggle).

Do a full review of the HTML semantics to see if the page is constructed properly. Semantic HTML structure plays a critical role in a11y. The usage of main and article in the template could possibly be an issue.

3. Modernization (both web standards and Blazor features)

Once the aforementioned items are cleaned up, it should be easier to add some modern features like CSS variables that will enable basic customizations that are accessible to Junior level HTML/CSS devs.

Having some examples of the SectionOutlet​ might be nice to see in the sample content, but the state of the current markup makes this difficult to add.

In scope

• Choose to lean into Bootstrap and remove CSS code that overlaps or fights with Bootstrap classes.
• Restructure the markup so the header (topbar), sidebar, and main content have a simpler logical structure. Lean into Bootstrap, and remove custom layout CSS code.
• Review and fix basic HTML/CSS accessibility issues.
• Review HTML semantics and update if needed.
• Add CSS variables for customization of theme color and utilize Bootstrap 5 CSS variables where appropriate. 
• Add SectionOutlet sample where appropriate.

Risks / unknowns

Unsure if there is an accessible alternative to the navbar show/hide feature using a checkbox. Is it an accessibility issue? If so, can it be fixed without introducing JavaScript or C#?

Are there any dependencies outside of Blazor in ASP.NET that will be impacting by the changes? Ex: Identity templates.

Sample repo

The following repo contains a refactored version of the static rendered project template. (No interactivity selected)
https://github.com/EdCharbeneau/BlazorAppTemplateReview

Sample repo Update: The refactored version eliminated roughly 100 lines of CSS code. It utilizes CSS variables built into Bootstrap 5.3, and auto detects and applies light/dark themes (no interactivity required).

Sample repo Update: Rewrote the toggle menu for a11y. It required some inline JavaScript but not enough to warrant a whole script file or tag. The new menu uses proper aria-* attributes and sets focus to the first menu item when shown.

[gragra33]

@EdCharbeneau well said ... when are you posting a pull request with the above changes? 😛 (joking)

[ghost]

Thanks for contacting us.

We're moving this issue to the .NET 9 Planning milestone for future evaluation / consideration. We would like to keep this around to collect more feedback, which can help us with prioritizing this work. We will re-evaluate this issue, during our next planning meeting(s).
If we later determine, that the issue has no community involvement, or it's very rare and low-impact issue, we will close it - so that the team can focus on more important and high impact issues.
To learn more about what to expect next and how this issue will be handled you can read more about our triage process here.

[mkArtakMSFT]

Thanks for bringing this up, @EdCharbeneau.

Feel free to send us a PR (in main) and we will try to merge it for .NET 9.
Unfortunately, it's too late for template styling related issues in .NET 8.

[EdCharbeneau]

@mkArtakMSFT Will the template shipping in .NET 8 be backwards compatible with .NET 7, or will it only apply to 8+?

[EdCharbeneau]

Before submitting a PR, it would help to gather some feedback. There is a sample repo linked above, the refactored version eliminated roughly 100 lines of CSS code. It utilizes CSS variables built into Bootstrap 5.3, and auto detects and applies light/dark themes (no interactivity required).

If anyone would like to give it a quick review, I'll start working on a PR.

gragra33 Care to give it a look?

[gragra33]

@EdCharbeneau Happy to...

[gragra33]

@EdCharbeneau I had a look and looks great!

4 minor things:

1. Recommendation: Add a CSS-only light./dark toggle. Here is an example: HTML and CSS Only Dark Mode Toggle (no javascript) - CodePen
2. Header meta viewport tag has warnings and errors (chromium) - initial-scale and maximum-scale
3. Light & Dark mode: About button text fails AAA contrast
4. The checkbox toggle is missing an id property

[EdCharbeneau]

@EdCharbeneau I had a look and looks great!

4 minor things:

1. Recommendation: Add a CSS-only light./dark toggle. Here is an example: HTML and CSS Only Dark Mode Toggle (no javascript) - CodePen
2. Header meta viewport tag has warnings and errors (chromium) - initial-scale and maximum-scale
3. Light & Dark mode: About button text fails AAA contrast
4. The checkbox toggle is missing an id property

This is awesome, thanks. I'll fix these before submitting a PR.

Note: The checkbox UI toggles need to be replaced by something accessible.

https://ux.stackexchange.com/questions/81122/what-are-the-accessibility-concerns-of-a-checkbox-based-navigation

[EdCharbeneau]

Fixed:

• Header meta viewport tag has warnings and errors (chromium) - initial-scale and maximum-scale
• The checkbox toggle is missing an id property

Not Fixing:

Recommendation: Add a CSS-only light./dark toggle. Here is an example: HTML and CSS Only Dark Mode Toggle (no javascript) - CodePen

Doing this properly with a11y in mind will require JavaScript. I feel like it's a nice-have feature but adds unnecessary complexity.

Light & Dark mode: About button text fails AAA contrast

This is already an issue in the Bootstrap repo. It's better to let them handle it there and benefit from it in the next version of Bootstrap. twbs/bootstrap#29422

[gragra33]

@EdCharbeneau as a thought, it might be advisable to add a comment line in the header to indicate how to turn off auto-dark mode.

[EdCharbeneau]

@EdCharbeneau as a thought, it might be advisable to add a comment line in the header to indicate how to turn off auto-dark mode.

Great minds think alike. It's already there. 😀

[gragra33]

@EdCharbeneau Great work as usual. Hope to see the PR accepted for the final release of 8.0.

[EdCharbeneau]

@EdCharbeneau Great work as usual. Hope to see the PR accepted for the final release of 8.0.

Thanks. It looks like (if accepted) it will come in an SDK update later on. .NET 8 is locked, got to respect the existing plans.

[ghost]

Thanks for contacting us.

We're moving this issue to the .NET 9 Planning milestone for future evaluation / consideration. We would like to keep this around to collect more feedback, which can help us with prioritizing this work. We will re-evaluate this issue, during our next planning meeting(s).
If we later determine, that the issue has no community involvement, or it's very rare and low-impact issue, we will close it - so that the team can focus on more important and high impact issues.
To learn more about what to expect next and how this issue will be handled you can read more about our triage process here.

[mkArtakMSFT]

Thanks for your feedback. We've decided that we will be modernizing the template during .NET 9 and we will incorporate your feedback as part of that work, that we track using #53142