Merge branch 'ouds/main' into ouds/main-jd-helpers-stacks

site/content/docs/0.0/getting-started/accessibility.md

@@ -8,4 +8,100 @@ aliases:
 toc: true
 ---
 
-{{< callout-soon "page" >}}
+OUDS Web provides an easy-to-use framework of ready-made styles, layout tools, and interactive components, allowing developers to create websites and applications that are visually appealing, functionally rich, and accessible out of the box.
+
+## Overview and limitations
+
+The overall accessibility of any project built with OUDS Web depends in large part on the author's markup, additional styling, and scripting they've included. However, provided that these have been implemented correctly, it should be perfectly possible to create websites and applications with OUDS Web that fulfill [<abbr title="Web Content Accessibility Guidelines">WCAG</abbr> 2.1](https://www.w3.org/TR/WCAG/) (A/AA/AAA), [Section 508](https://www.section508.gov/), and similar accessibility standards and requirements.
+
+### Structural markup
+
+OUDS Web's styling and layout can be applied to a wide range of markup structures. This documentation aims to provide developers with best practice examples to demonstrate the use of OUDS Web itself and illustrate appropriate semantic markup, including ways in which potential accessibility concerns can be addressed.
+
+### Interactive components
+
+OUDS Web's interactive components<!--—such as modal dialogs, dropdown menus, and custom tooltips—--> are designed to work for touch, mouse, and keyboard users. Through the use of relevant [<abbr title="Web Accessibility Initiative">WAI</abbr>-<abbr title="Accessible Rich Internet Applications">ARIA</abbr>](https://www.w3.org/WAI/standards-guidelines/aria/) roles and attributes, these components should also be understandable and operable using assistive technologies (such as screen readers).
+
+Because OUDS Web's components are purposely designed to be fairly generic, authors may need to include further <abbr title="Accessible Rich Internet Applications">ARIA</abbr> roles and attributes, as well as JavaScript behavior, to more accurately convey the precise nature and functionality of their component. This is usually noted in the documentation.
+
+<!--### Color contrast
+
+Some combinations of colors that currently make up OUDS Web's default palette—used throughout the framework for things such as button variations, alert variations, form validation indicators—may lead to *insufficient* color contrast (below the recommended [WCAG 2.1 text color contrast ratio of 4.5:1](https://www.w3.org/TR/WCAG/#contrast-minimum) and the [WCAG 2.1 non-text color contrast ratio of 3:1](https://www.w3.org/TR/WCAG21/#non-text-contrast)), particularly when used against a light background.
+
+Unlike Bootstrap, in OUDS Web **contrasts are locked to ensure they meet [WCAG 2.1 accessibility standards for color contrast](https://www.w3.org/TR/WCAG21/#contrast-minimum)** when using [`.text-*`]({{< docsref "/utilities/colors" >}}) and [`.bg-*` utilities]({{< docsref "/utilities/background" >}}), by defining `color` and `background-color` altogether. Please refer to [our theme colors]({{< docsref "/customize/color-palette" >}}) to have a full preview of OUDS Web color palette’s reached WCAG level.-->
+
+### Visually hidden content
+
+Content which should be visually hidden, but remain accessible to assistive technologies such as screen readers, can be styled using the `.visually-hidden` class. This can be useful in situations where additional visual information or cues (such as meaning denoted through the use of color) need to also be conveyed to non-visual users.
+
+<!--```html
+<p class="text-danger">
+  <span class="visually-hidden">Danger: </span>
+  This action is not reversible
+</p>
+```-->
+
+For visually hidden interactive controls, such as traditional "skip" links, use the `.visually-hidden-focusable` class. This will ensure that the control becomes visible once focused (for sighted keyboard users). **Watch out, `.visually-hidden-focusable` is a standalone class, and must not be used in combination with the `.visually-hidden` class.**
+
+```html
+<a class="visually-hidden-focusable" href="#content">Skip to main content</a>
+```
+
+### Reduced motion
+
+OUDS Web includes support for the [`prefers-reduced-motion` media feature](https://www.w3.org/TR/mediaqueries-5/#prefers-reduced-motion). In browsers/environments that allow the user to specify their preference for reduced motion, most CSS transition effects in OUDS Web<!-- (for instance, when a modal dialog is opened or closed, or the sliding animation in carousels)--> will be disabled, and meaningful animations <!--(such as spinners) -->will be slowed down.
+
+On browsers that support `prefers-reduced-motion`, and where the user has *not* explicitly signaled that they'd prefer reduced motion (i.e. where `prefers-reduced-motion: no-preference`), OUDS Web enables smooth scrolling using the `scroll-behavior` property.
+
+### Focus visibility
+
+OUDS Web includes [WICG's `:focus-visible` polyfill](https://github.com/WICG/focus-visible) to ensure an enhanced focus visibility for keyboard users while shutting down focus styles on active state.
+
+{{< scss-docs name="focus-visibility" file="scss/_reboot.scss" >}}
+
+OUDS Web provides `focus-visible()` mixin to ensure a proper visible focus state:
+
+{{< scss-docs name="focus-visible" file="scss/mixins/_focus.scss" >}}
+
+This visible focus state is defined by an outer outline and an inner box shadow. Colors are switched in a dark context. Here are the basic variables that define this visible focus:
+
+{{< scss-docs name="focus-visible-variables" file="scss/_variables.scss" >}}
+
+<!--Each component then specifies its own visible focus style when needed, for example [carousels]({{< docsref "/components/carousel#with-indicators" >}}).
+
+{{< scss-docs name="focus-visible-carousel" file="scss/_carousel.scss" >}}-->
+
+<!--#### Under a fixed header
+
+When using a fixed (or sticky) header, tabbing backward often hides focused element under the header. OUDS Web sets `scroll-padding-top` property for such case. This feature is configurable in two ways:
+
+1. `$scroll-offset-top` variable defines the offset,
+2. and [`$enable-fixed-header` allows to drop this rule]({{< docsref "/customize/options" >}}) if you don't use a fixed header.
+
+{{< scss-docs name="scroll-offset" file="scss/_reboot.scss" >}}-->
+
+### Minimum target size
+
+OUDS Web provides `target-size()` mixin to ensure a minimum target size, adding a centered pseudo-element with a minimum size —defaulting to `44px` to pass [WCAG 2.1 "Target Size" Success Criterion (2.5.5)](https://www.w3.org/WAI/WCAG21/Understanding/target-size.html)— alongside a few arguments to fit specific needs (e.g. different width and height, using `::after` instead of `::before`, etc.).
+
+{{< scss-docs name="target-size" file="scss/mixins/_target-size.scss" >}}
+
+### Maximum line length
+
+When writing a paragraph, it is commonly admitted that a line should have 80 characters as a maximum. This phenomenon is carefully explained in the [C20 technique: Using relative measurements to set column widths](https://www.w3.org/TR/2016/NOTE-WCAG20-TECHS-20161007/C20).
+
+<!--For more information, please [read text utilities]({{< docsref "/utilities/text#line-length" >}}).-->
+
+## Additional resources
+
+- [Web Content Accessibility Guidelines (WCAG) 2.1](https://www.w3.org/TR/WCAG/)
+- [The A11Y Project](https://www.a11yproject.com/)
+- [MDN accessibility documentation](https://developer.mozilla.org/en-US/docs/Web/Accessibility)
+- [Tenon.io Accessibility Checker](https://tenon.io/)
+- [Color Contrast Analyser (CCA)](https://www.tpgi.com/color-contrast-checker/)
+- ["HTML Codesniffer" bookmarklet for identifying accessibility issues](https://github.com/squizlabs/HTML_CodeSniffer)
+- [Microsoft Accessibility Insights](https://accessibilityinsights.io/)
+- [Deque Axe testing tools](https://www.deque.com/axe/)
+- [Orange accessibility guidelines](http://a11y-guidelines.orange.com/)
+- [Introduction to Web Accessibility](https://www.w3.org/WAI/fundamentals/accessibility-intro/)
+- [`:focus-visible` on MDN](https://developer.mozilla.org/en-US/docs/Web/CSS/:focus-visible)

site/content/docs/0.0/getting-started/introduction.md

@@ -11,4 +11,206 @@ aliases:
 toc: true
 ---
 
-{{< callout-soon "page" >}}
+<!--## About Orange Brand
+
+As OUDS Web is based on Bootstrap, you'll find in OUDS Web **all** the Bootstrap's components and their variants, but with an Orange branded look.
+
+Among those inherited components and variants, some exist in Orange Unified Design System and fully respect its design specifications and some don't. Those ones should not be used in your projects to ensure a consistent user experience throughout our Orange web services.
+
+As for maintainability reasons we have to keep them in this documentation, we tagged them under a `<details><summary>` with incompatibility design callouts. They inform you of what should not be used from an Orange design point of view. They suggest, when available, a replacement solution and/or a link to the Orange Unified Design System website to see other possibilities. We tried to hide them as much as possible while keeping the variants in our documentation.
+Thanks for taking this information into account.
+
+Design incompatibility callouts message example:
+
+{{< design-callout-alert >}}
+This checkbox variant should not be used because it does not respect the Orange Unified Design System specifications.
+
+From the Orange Unified Design System point of view, checkboxes should be represented like in our [Checks component]({{< docsref "/forms/checks-radios" >}}). You can also refer to the [Checkbox guidelines](https://system.design.orange.com/0c1af118d/p/88ab5b-forms/b/599459/i/48901789) on on the Orange Unified Design System website.
+{{< /design-callout-alert >}}
+
+In the same spirit, some recommendation design callouts will inform you of specific Orange Unified Design System recommendations.
+
+Design recommendation callouts message example:
+
+{{< design-callout-alert info >}}
+To display basic tables, Orange Unified Design System recommends using these compact tables.
+{{< /design-callout-alert >}}-->
+
+## Quick start
+
+Get started by including OUDS Web's production-ready CSS and JavaScript via CDN without the need for any build steps. See it in practice with this [OUDS Web CodePen demo](https://codepen.io/louismaximepiton/pen/NWZdZJm).
+
+<br>
+
+1. **Create a new `index.html` file in your project root.** Include the `<meta name="viewport">` tag as well for [proper responsive behavior](https://developer.mozilla.org/en-US/docs/Web/HTML/Viewport_meta_tag) in mobile devices.
+
+   ```html
+   <!doctype html>
+   <html lang="en">
+     <head>
+       <meta charset="utf-8">
+       <meta name="viewport" content="width=device-width, initial-scale=1">
+       <title>OUDS Web demo</title>
+     </head>
+     <body>
+       <h1>Hello, world!</h1>
+     </body>
+   </html>
+   ```
+
+2. **Include OUDS Web's CSS and JS.** Place the `<link>` tag in the `<head>` for our CSS, and the `<script>` tag for our JavaScript bundle (including Popper for positioning dropdowns, popovers, and tooltips) before the closing `</body>`. Learn more about our [CDN links](#cdn-links).
+
+   ```html
+   <!doctype html>
+   <html lang="en">
+     <head>
+       <meta charset="utf-8">
+       <meta name="viewport" content="width=device-width, initial-scale=1">
+       <title>OUDS Web demo</title>
+       <link href="{{< param "cdn.css" >}}" rel="stylesheet" integrity="{{< param "cdn.css_hash" >}}" crossorigin="anonymous">
+     </head>
+     <body>
+       <h1>Hello, world!</h1>
+       <script src="{{< param "cdn.js_bundle" >}}" integrity="{{< param "cdn.js_bundle_hash" >}}" crossorigin="anonymous"></script>
+     </body>
+   </html>
+   ```
+
+   You can also include [Popper](https://popper.js.org/docs/v2/) and our JS separately. If you don't plan to use dropdowns, popovers, or tooltips, save some kilobytes by not including Popper.
+
+   ```html
+   <script src="{{< param "cdn.popper" >}}" integrity="{{< param "cdn.popper_hash" >}}" crossorigin="anonymous"></script>
+   <script src="{{< param "cdn.js" >}}" integrity="{{< param "cdn.js_hash" >}}" crossorigin="anonymous"></script>
+   ```
+
+3. **Hello, world!** Open the page in your browser of choice to see your OUDS Web page. <!--Now you can start building with OUDS Web by creating your own [layout]({{< docsref "/layout/grid" >}}), adding dozens of [components]({{< docsref "/components/buttons" >}}), and utilizing [our official examples]({{< docsref "/examples" >}}).-->
+
+## CDN links
+
+As reference, here are our primary CDN links.
+
+{{< bs-table >}}
+| Description | URL |
+| --- | --- |
+| CSS | `{{< param "cdn.css" >}}` |
+| JS | `{{< param "cdn.js_bundle" >}}` |
+{{< /bs-table >}}
+
+<!--You can also use the CDN to fetch any of our [additional builds listed in the Contents page]({{< docsref "/getting-started/contents" >}}).-->
+
+## Next steps
+
+- Read a bit more about some [important global environment settings](#important-globals) that OUDS Web utilizes.
+- Read about what's included in OUDS Web<!-- in our [contents section]({{< docsref "/getting-started/contents/" >}}) and the list of [components that require JavaScript](#js-components) below-->.
+<!--- Need a little more power? Consider building with OUDS Web by [including the source files via package manager]({{< docsref "/getting-started/download#package-managers" >}}).-->
+<!--- Looking to use Boosted as a module with `<script type="module">`? Please refer to our [using Boosted as a module]({{< docsref "/getting-started/javascript#using-boosted-as-a-module" >}}) section.-->
+
+<!--## JS components
+
+Curious which components explicitly require our JavaScript and Popper? If you're at all unsure about the general page structure, keep reading for an example page template.
+
+- Accordions for extending our Collapse plugin
+- Alerts for dismissing and Close button tooltip
+- Buttons for toggling states and checkbox/radio functionality
+- Carousel for all slide behaviors, controls, and indicators
+- Close button for displaying and positioning tooltip
+- Collapse for toggling visibility of content
+- Dropdowns for displaying and positioning (also requires [Popper](https://popper.js.org/docs/v2/))
+- Footer for extending our Collapse plugin to implement responsive behavior
+- Modals for displaying, positioning, scroll behavior, and Close button tooltip
+- Navbar for extending our Collapse and Offcanvas plugins to implement responsive behaviors, and Close button tooltip (Offcanvas only)
+- Navs with the Tab plugin for toggling content panes
+- Offcanvases for displaying, positioning, scroll behavior, and Close button tooltip
+- Orange navbar for minimizing the header
+- Quantity selector for incrementing/decrementing number value
+- Scrollspy for scroll behavior and navigation updates
+- Toasts for displaying, dismissing, and Close button tooltip
+- Tooltips and popovers for displaying and positioning (also requires [Popper](https://popper.js.org/docs/v2/))-->
+
+## Required script
+
+OUDS Web includes [WICG's `:focus-visible` polyfill](https://github.com/WICG/focus-visible) to ensure an enhanced focus visibility for keyboard users while shutting down focus styles on active state.
+
+{{< callout warning >}}
+However, if you don't need or want to use OUDS Web's JavaScript files, you'll still need to use the polyfill.
+{{< /callout >}}
+
+```html
+<script src="{{< param "cdn.focus_visible" >}}" integrity="{{< param "cdn.focus_visible_hash" >}}" crossorigin="anonymous"></script>
+```
+
+## Important globals
+
+OUDS Web employs a handful of important global styles and settings, all of which are almost exclusively geared towards the *normalization* of cross browser styles. Let's dive in.
+
+### HTML5 doctype
+
+OUDS Web requires the use of the HTML5 doctype. Without it, you'll see some funky and incomplete styling.
+
+```html
+<!doctype html>
+<html lang="en">
+  ...
+</html>
+```
+
+### Viewport meta
+
+OUDS Web is developed *mobile first*, a strategy in which we optimize code for mobile devices first and then scale up components as necessary using CSS media queries. To ensure proper rendering and touch zooming for all devices, add the responsive viewport meta tag to your `<head>`.
+
+```html
+<meta name="viewport" content="width=device-width, initial-scale=1">
+```
+
+You can see an example of this in action in the [quick start](#quick-start).
+
+### Box-sizing
+
+For more straightforward sizing in CSS, we switch the global `box-sizing` value from `content-box` to `border-box`. This ensures `padding` does not affect the final computed width of an element, but it can cause problems with some third-party software like Google Maps and Google Custom Search Engine.
+
+On the rare occasion you need to override it, use something like the following:
+
+```css
+.selector-for-some-widget {
+  box-sizing: content-box;
+}
+```
+
+With the above snippet, nested elements—including generated content via `::before` and `::after`—will all inherit the specified `box-sizing` for that `.selector-for-some-widget`.
+
+Learn more about [box model and sizing at CSS Tricks](https://css-tricks.com/box-sizing/).
+
+### Resource Hints
+
+[Resource hints](https://html.spec.whatwg.org/#linkTypes) are meant to optimize browser loading strategy, by either preloading assets, prefetching DNS or preconnecting to domains — but please use them carefully and **only to hint resources you'll really be using soon**.
+It should be used for critical resources only.
+
+#### `preconnect` to CDNs
+
+```html
+<link rel="preconnect" href="https://cdn.jsdelivr.net" crossorigin="anonymous">
+```
+
+### Reboot
+
+For improved cross-browser rendering, we <!--use [Reboot]({{< docsref "/content/reboot" >}}) to -->correct inconsistencies across browsers and devices while providing slightly more opinionated resets to common HTML elements.
+
+## OUDS Web community
+
+Stay up-to-date on the development of OUDS Web and reach out to the community with these helpful resources.
+
+- Ask questions and explore [our GitHub Discussions](https://github.com/Orange-OpenSource/Orange-Boosted-Bootstrap/discussions).
+- Chat with the core team and fellow OUDS Web users on internal Orange communication tools.
+
+## Bootstrap Community
+
+Stay up-to-date on the development of Bootstrap and reach out to the community with these helpful resources.
+
+- Read and subscribe to [The Official Bootstrap Blog]({{< param blog >}}).
+- Ask questions and explore [Bootstrap GitHub Discussions](https://github.com/twbs/bootstrap/discussions).
+- Discuss, ask questions, and more on [the Bootstrap community Discord](https://discord.gg/bZUvakRU3M) or [Bootstrap subreddit](https://www.reddit.com/r/bootstrap/).
+- Chat with fellow Bootstrappers in IRC. On the `irc.libera.chat` server, in the `#bootstrap` channel.
+- Implementation help may be found at Stack Overflow (tagged [`bootstrap-5`](https://stackoverflow.com/questions/tagged/bootstrap-5)).
+- Developers should use the keyword `bootstrap` on packages that modify or add to the functionality of Bootstrap when distributing through [npm](https://www.npmjs.com/search?q=keywords:bootstrap) or similar delivery mechanisms for maximum discoverability.
+
+You can also follow [@getbootstrap on Twitter](https://twitter.com/{{< param twitter >}}) for the latest gossip and awesome music videos.

site/data/sidebar.yml

@@ -6,7 +6,6 @@
   icon_color: body-color
   pages:
     - title: Introduction
-      draft: true
     - title: Download
       draft: true
     - title: Contents
@@ -22,7 +21,6 @@
     - title: Vite
       draft: true
     - title: Accessibility
-      draft: true
     - title: RFS
       draft: true
     - title: RTL