mirror of
https://github.com/snachodog/just-the-docs.git
synced 2025-04-10 14:01:22 -06:00
8292f46be9
This PR fixes some accessibility issues in our theme docs (i.e. not generated code) flagged by #1513. Here, I target changes that I say are not "systemic", i.e. issues that are easily resolvable by changing our copy and page structure (rather than issues that are created by how kramdown/rouge generates HTML, or reworking our color themes). Here's a quick summary of the manual changes I made: - ~~writing some JS to set `tabindex="0"` on all code blocks; I'd prefer a ruby-native solution, but that involves writing Ruby code, which is incompatible with the pages gem~~ I've moved this to #1533 - rewriting many headings named "Example" which were almost always h4s into more descriptive headings + the appropriate heading level, adding .text-delta to maintain the previous style when necessary - removing some old heading ID hacks in `index-test` that are no longer necessary, since Jekyll does this automatically now - fixing the table headings in `docs/utilities/layout.md` - adding accessible titles + descriptions to the mermaid examples - occasionally, slightly moving around copy to make it align with new headings If you test with #1513 with the following rules disabled: ```rb skipped_rules = [ 'color-contrast', # requires theme auditing # issues w/ autogenerated footnotes 'aria-allowed-role', 'landmark-no-duplicate-contentinfo', 'landmark-unique', 'aria-deprecated-role', # issues w/ markdown checkboxes 'label' ] ``` You should get passing tests :) which is awesome! ## next steps 1. we need to do a pass over our docs copy - very inconsistent. This has been a pain point for me for a while now, just need to find time to sit down and do it. In particular, I'd love to standardize how we display example code (perhaps even hiding it with `<details>` and `<summary>`?), our headings language, what goes into the ToC, our overall writing style, etc. 2. ~~I don't love the JS hack for adding `tabindex="0"` to code blocks (so that they are keyboard-focusable). Ideally, we'd add a custom formatter to rouge to do this, but we can't execute arbitrary Ruby code when users use `github-pages`. I'll look into this some more - maybe rouge would be open to adding this as a feature.~~ see: #1533 4. There are some systemic issues that need a deeper look: 1. The most common issue is still color-contrast. Fixing this involves: - looking at our whites/blacks/grays for core text and highlighting - reevaluating our syntax highlighting themes - fixing dark mode, once and for all :) - also, picking accessible callout colours! 2. kramdown's autogenerated footnotes feature creates a bunch of errors that aXe flags: it seems like a deprecated aria role is being used, and perhaps some misuse of markup. Need to look into this more before I can make a solid attempt at resolving this issue. 3. We demonstrate the use of `- [ ]`, but this generates `<input type="checkbox">` values with no label. I'm not entirely sure what the best way to fix this problem is (without writing custom Ruby code). I'll have to think about this some more. --------- Co-authored-by: Michael Ball <michael@mball.co>
4.3 KiB
4.3 KiB
| title | parent |
|---|---|
| Layout | Utilities |
Layout Utilities
{: .no_toc }
Table of contents
{: .no_toc .text-delta }
- TOC {:toc}
Spacing
These spacers are available to use for margins and padding with responsive utility classes. Combine these prefixes with a screen size and spacing scale to use them responsively.
| Classname prefix | Related CSS Property |
|---|---|
.m- |
margin |
.mx- |
margin-left, margin-right |
.my- |
margin top, margin bottom |
.mt- |
margin-top |
.mr- |
margin-right |
.mb- |
margin-bottom |
.ml- |
margin-left |
| Classname prefix | Related CSS Property |
|---|---|
.p- |
padding |
.px- |
padding-left, padding-right |
.py- |
padding top, padding bottom |
.pt- |
padding-top |
.pr- |
padding-right |
.pb- |
padding-bottom |
.pl- |
padding-left |
Spacing values are based on a 1rem = 16px spacing scale, broken down into these units:
| Spacer/suffix | Size in rems | Rem converted to px |
|---|---|---|
1 |
0.25rem | 4px |
2 |
0.5rem | 8px |
3 |
0.75rem | 12px |
4 |
1rem | 16px |
5 |
1.5rem | 24px |
6 |
2rem | 32px |
7 |
2.5rem | 40px |
8 |
3rem | 48px |
auto |
auto | auto |
Use mx-auto to horizontally center elements.
Applying Spacing Utilities with {: }
{: .no_toc .text-delta }
In Markdown, use the {: } wrapper to apply custom classes:
This paragraph will have a margin bottom of 1rem/16px on large screens.
{: .mb-lg-4 }
This paragraph will have 2rem/32px of padding on the right and left at all screen sizes.
{: .px-6 }
Horizontal Alignment
| CSS Class | Applied CSS Declaration |
|---|---|
.float-left |
float: left |
.float-right |
float: right |
.flex-justify-start |
justify-content: flex-start |
.flex-justify-end |
justify-content: flex-end |
.flex-justify-between |
justify-content: space-between |
.flex-justify-around |
justify-content: space-around |
Note: any of the flex- classes must be used on a parent element that has d-flex applied to it.
Vertical Alignment
| CSS Class | Applied CSS Declaration |
|---|---|
.v-align-baseline |
vertical-align: baseline |
.v-align-bottom |
vertical-align: bottom |
.v-align-middle |
vertical-align: middle |
.v-align-text-bottom |
vertical-align: text-bottom |
.v-align-text-top |
vertical-align: text-top |
.v-align-top |
vertical-align: top |
Display
Display classes aid in adapting the layout of the elements on a page:
| CSS Class | Applied CSS Declaration |
|---|---|
.d-block |
display: block |
.d-flex |
display: flex |
.d-inline |
display: inline |
.d-inline-block |
display: inline-block |
.d-none |
display: none |
Use these classes in conjunction with the responsive modifiers.
Applying Display Utilities with {: }
{: .no_toc .text-delta }
In Markdown, use the {: } wrapper to apply custom classes:
This button will be hidden until medium screen sizes:
[ A button ](#url)
{: .d-none .d-md-inline-block }
These headings will be `inline-block`:
### heading 3
{: .d-inline-block }
### heading 3
{: .d-inline-block }