Description
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
- 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.
- 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.
- 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
SectionOutletsample 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.