mirror of
https://github.com/snachodog/just-the-docs.git
synced 2025-04-20 10:02:23 -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>
127 lines
4.3 KiB
Markdown
127 lines
4.3 KiB
Markdown
---
|
|
title: Layout
|
|
parent: Utilities
|
|
---
|
|
|
|
# Layout Utilities
|
|
{: .no_toc }
|
|
|
|
## Table of contents
|
|
{: .no_toc .text-delta }
|
|
|
|
1. 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:
|
|
|
|
```markdown
|
|
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:
|
|
|
|
```markdown
|
|
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 }
|
|
```
|