Group 4: Banner and Image audit on the website (#2907)

Co-authored-by: Majed <[email protected]>

Author: andgen404

website/docs/components/button/partials/code/how-to-use.md

@@ -138,14 +138,14 @@ If the route is external to your current engine, you have to pass `@isRouteExter
 
 ### Loading state
 
-If the button needs to toggle between an "idle" and a "loading" state, we suggest applying a width to it (via inline style or CSS class) to prevent the button from resizing on click (and potentially causing layout shifts):
-
 !!! Info
 
 While applying an explicit width to the button is possible in general, we suggest limiting the application of this override **only** to this specific use case and letting the button resize accordingly to its content.
 
 !!!
 
+If the button needs to toggle between an "idle" and a "loading" state, we suggest applying a width to it (via inline style or CSS class) to prevent the button from resizing on click (and potentially causing layout shifts):
+
 ```handlebars
 <Hds::Button
   {{style width="7.5rem"}}
@@ -157,13 +157,13 @@ While applying an explicit width to the button is possible in general, we sugges
 
 ### Disabled Buttons
 
-To disable a Button, manually add the native `disabled` attribute:
-
 !!! Info
 
 Links cannot use the `disabled` attribute (per HTML specification); even if you were to intercept the event, they are still subject to color-contrast conformance requirements.
 !!!
 
+To disable a Button, manually add the native `disabled` attribute:
+
 ```handlebars
 <Hds::Button @text="Alert me" disabled {{on "click" this.alertOnClick}} />
 ```

website/docs/components/button/partials/guidelines/guidelines.md

@@ -63,15 +63,15 @@ For example:
 
 ## Icon position
 
-Buttons are provided with flexible icon use; allowing for leading, trailing, or icon only buttons. Use icons intentionally and only when they provide the user with extra value. Do not create buttons with both leading and trailing icons. Tertiary buttons are required to have either a leading or trailing icon layout to be accessible.
-
 !!! Info
 
 **Looking for Dropdowns?**
 
 Buttons used for a Dropdown (with the chevron icon) can be found in [Dropdown](/components/dropdown).
 !!!
 
+Buttons are provided with flexible icon use; allowing for leading, trailing, or icon only buttons. Use icons intentionally and only when they provide the user with extra value. Do not create buttons with both leading and trailing icons. Tertiary buttons are required to have either a leading or trailing icon layout to be accessible.
+
 <Hds::ButtonSet>
   <Hds::Button @color="secondary" @text="No icon" />
   <Hds::Button @color="secondary" @text="Leading Icon" @icon="plus" @iconPosition="leading" />

website/docs/components/code-editor/partials/code/how-to-use.md

@@ -34,6 +34,12 @@ Optionally, you can pass a title and/or a description using the `[CE].Title` and
 
 ### Title tag
 
+!!! Insight
+
+The default `@tag` is `"h2"`, however, the correct value is dependent on the individual page. We strongly encourage consumers to update the `@tag` to meet WCAG Success Criterion [1.3.1 Info and Relationships](https://www.w3.org/WAI/WCAG22/Understanding/info-and-relationships.html) as the visual experience should match what is presented to the user with assistive technology.
+
+!!!
+
 The `@tag` argument changes the HTML element that wraps the `[CE].Title` content. When organizing the content on a webpage, the heading levels should reflect the structure of the page. For example, if a Code Editor is within a subsection of the page below a heading level 2, the value should be `"h3"`. 
 
 ```handlebars
@@ -51,12 +57,6 @@ The `@tag` argument changes the HTML element that wraps the `[CE].Title` content
 </Hds::CodeEditor>
 ```
 
-!!! Insight
-
-The default `@tag` is `"h2"`, however, the correct value is dependent on the individual page. We strongly encourage consumers to update the `@tag` to meet WCAG Success Criterion [1.3.1 Info and Relationships](https://www.w3.org/WAI/WCAG22/Understanding/info-and-relationships.html) as the visual experience should match what is presented to the user with assistive technology.
-
-!!!
-
 ### Language
 
 The `language` argument sets the syntax highlighting used. We support the following languages: `rego`, `ruby`, `sentinel`, `shell`, `go`, `hcl`, `javascript`, `json`, `markdown`, `sql`, and `yaml`. If you need additional languages, <LinkTo class="doc-link-generic" @route="show" @model="about/support">contact the Design Systems Team</LinkTo>.

website/docs/components/code-editor/partials/guidelines/guidelines.md

@@ -54,21 +54,18 @@ The secondary actions section supports two optional buttons: the [Copy Button](/
 
 ## Custom actions
 
-Custom primary actions can be added to the header. Primary actions include those necessary for the user to complete their work.
-
-![The Code Editor with the title “CodeEditor title”. The custom yielded element section shows a placeholder and is between the title and the editor.](/assets/components/code-editor/code-editor-primary-yielded-elements.png)
-
-Here is an example of a custom action to reveal secrets.
-
-![The Code Editor with the title “CodeEditor title”. The custom yielded section has a “Reveal secrets” toggle.](/assets/components/code-editor/code-editor-primary-yielded-actions.png)
-
-
 !!! Warning
 
 The Code Editor has limited support for dark mode styles. Buttons have pre-defined dark mode styles, but all other components require manual color adjustments until a dark mode theme is released. Please [contact the Design Systems Team](/about/support) for help translating components into dark mode.
 
 !!!
 
+Custom primary actions can be added to the header. Primary actions include those necessary for the user to complete their work.
+
+Here is an example of a custom action to reveal secrets.
+
+![The Code Editor with the title “CodeEditor title”. The custom yielded section has a “Reveal secrets” toggle.](/assets/components/code-editor/code-editor-primary-yielded-elements.png)
+
 ## External elements
 
 Some elements or functions outside the Code Editor may affect the content within the Code Editor. In this case, we recommend turning off the header to visually couple the editor with the nearby controlling elements.
@@ -106,12 +103,13 @@ If you wish to create custom examples using the Code Editor, we publish all of t
 For more details around syntax, visit the [specifications](/components/code-editor?tab=specifications).
 
 ## Linting
-The Code Editor supports linting for JSON using [CodeMirror6](https://codemirror.net/examples/lint/). This feature highlights all errors with an underline and an icon next to the line number. Each icon has a tooltip explaining the error on the associated line.
 
 !!! Info 
 Linting is only available in the Ember component and is not supported in Figma.
 !!!
 
+The Code Editor supports linting for JSON using [CodeMirror6](https://codemirror.net/examples/lint/). This feature highlights all errors with an underline and an icon next to the line number. Each icon has a tooltip explaining the error on the associated line.
+
 ![Code editor with linting errors. On hover of an icon indicating an error on a line, a tooltip displays details on the linting error.](/assets/components/code-editor/codeeditor-linting-preview-tooltip.png)
 
 When linting is enabled, the Code Editor will have a minimum height set by default to avoid the alert dialog covering all the content within the editor when opened. The minimum height for the Code Editor with linting is 160px. The linting alert dialog is always 80px in height.

website/docs/components/flyout/partials/code/how-to-use.md

@@ -24,6 +24,12 @@ When the Flyout has been closed, the browser automatically returns the focus to
 
 ## How to use this component
 
+!!! Info
+
+When a Flyout is opened with the keyboard, the focus is automatically set to the first focusable element inside the Flyout, which is the “Dismiss” button.
+
+!!!
+
 ```handlebars
 <Hds::Button
   @text="Open Flyout"
@@ -50,10 +56,4 @@ When the Flyout has been closed, the browser automatically returns the focus to
     </M.Body>
   </Hds::Flyout>
 {{/if}}
-```
-
-!!! Info
-
-When a Flyout is opened with the keyboard, the focus is automatically set to the first focusable element inside the Flyout, which is the “Dismiss” button.
-
-!!!
+```

website/docs/components/flyout/partials/guidelines/guidelines.md

@@ -17,14 +17,14 @@ While similar in functionality and interaction, the Flyout and [Modal](/componen
 
 #### Complexity
 
-A Flyout is useful for more complex content, given the space it occupies in the viewport, while Modals are useful for less complex content that can be interacted with quickly.
-
 !!! Info
 
 Complexity of content is relative, use your own judgment to determine if the content or function is overly complex and consider moving it to its own page.
 
 !!!
 
+A Flyout is useful for more complex content, given the space it occupies in the viewport, while Modals are useful for less complex content that can be interacted with quickly.
+
 #### Status and messaging
 
 Flyouts are useful when displaying detailed content that relates to the page, while Modals are useful for messaging status, e.g., confirming a destructive action or warning about the effects of a change.
@@ -113,6 +113,11 @@ The purpose and function of the Flyout should not rely solely on an icon, instea
 
 ### Tagline
 
+!!! Warning
+
+Even though adding a title icon and tagline can help the user better understand the content, both elements add visual weight which might not be suitable or necessary for all Flyouts.
+!!!
+
 **With tagline**
 
 ![Flyout header tagline, title, and dismiss button](/assets/components/dialog-primitives/dialog-primitives-header-tagline-and-title.jpg)
@@ -125,11 +130,6 @@ A **tagline** helps the user maintain the context of the main page the Flyout wa
 
 The **tagline** should directly reference the page, feature title, or object to reinforce the purpose of the Flyout.
 
-!!! Warning
-
-Even though adding a title icon and tagline can help the user better understand the content, both elements add visual weight which might not be suitable or necessary for all Flyouts.
-!!!
-
 ### Description
 
 A **description** provides additional information about the Flyout.
@@ -148,18 +148,18 @@ The body of the Flyout supports any generic content, local components, or Helios
 
 ## Flyout footer
 
+!!! Info
+
+The footer is **optional** and should be used sparingly as it increases the complexity of the Flyout.
+!!!
+
 The Flyout footer is a persistent content area at the bottom of the Flyout, and supports additional descriptive content, links, actions, and any other generic content or Helios components.
 
 The Ember and Figma components account for the footer in slightly different ways, though both can achieve the same results:
 
 - The Ember component is a generic container that yields elements passed to it.
 - The Figma component consists of a variant for the number of actions, as well as support for generic content via an instance swap property.
 
-!!! Info
-
-The footer is **optional** and should be used sparingly as it increases the complexity of the Flyout.
-!!!
-
 **With one action**
 
 ![Flyout footer with one action](/assets/components/dialog-primitives/dialog-primitives-footer-actions-one.png)
@@ -212,20 +212,20 @@ Multiple dismissal options are available that can be customized in production wi
 
 ## Positioning and responsive sizing
 
-A Flyout should slide out from the right side of the viewport on top of the main page content and occupy 100% of the viewport height.
-
-- This is true regardless of whether there is a sidebar or navigational element that persists on the page.
-- A Flyout should overlay all content and block/disable interaction on the main page.
-
-![Flyout in a desktop viewport](/assets/components/flyout/flyout-sizing.png)
-
 !!! Info
 
 In Figma, the Flyout should be paired with the [Overlay](https://www.figma.com/design/iweq3r2Pi8xiJfD9e6lOhF/HDS-Components-v2.0?node-id=67216-32335&t=gWdKy44MzTP4cTRo-1) component which obscures the main page content the Flyout sits on top of. Using the Flyout without the overlay is currently not supported and helps to communicate visually the `inert` nature of the main page.
 
 We publish a [[Template] Flyout](https://www.figma.com/design/iweq3r2Pi8xiJfD9e6lOhF/HDS-Components-v2.0?node-id=67212-27152&t=gWdKy44MzTP4cTRo-1) component coupling these two components together that can be imported into your design file and detached.
 !!!
 
+A Flyout should slide out from the right side of the viewport on top of the main page content and occupy 100% of the viewport height.
+
+- This is true regardless of whether there is a sidebar or navigational element that persists on the page.
+- A Flyout should overlay all content and block/disable interaction on the main page.
+
+![Flyout in a desktop viewport](/assets/components/flyout/flyout-sizing.png)
+
 On smaller viewports, the Flyout should occupy 100% of the viewport width minus half the size of the minimized SideNav width from the viewport edge.
 
 - If the body content of the Flyout exceeds the maximum height of the viewport, a scroll will be introduced.

website/docs/components/form/file-input/partials/code/how-to-use.md

@@ -88,14 +88,14 @@ Add more than one error message using the more specific `Message` contextual com
 
 #### Custom control ID
 
-To use a custom ID value instead of the one automatically generated by the component, pass the `@id` argument to the Field component.
-
 !!! Info
 
 In this case, all the internal references (`id/for/aria-describedby`) between the different parts of the field will still be automatically generated but will use the custom ID provided.
 
 !!!
 
+To use a custom ID value instead of the one automatically generated by the component, pass the `@id` argument to the Field component.
+
 ```handlebars
 <Hds::Form::FileInput::Field @id="my-control" name="demo-profile-photo" as |F|>
   <F.Label>Upload a file</F.Label>

website/docs/components/form/file-input/partials/guidelines/guidelines.md

@@ -10,15 +10,15 @@ Because the File Input is based on the native HTML input, the content and visual
 
 ## Truncation
 
-Truncation is built into the native component and uses the width of the container to determine when the text gets truncated. It is not based on a character limit. 
-
 !!! Info
 
 Due to limitations in Figma, truncation will occur at the end of the text, while in the browser, truncation occurs in the middle. 
 
 ![visual difference in truncation between figma and browser](/assets/components/form/file-input/file-input-truncation.png)
 !!!
 
+Truncation is built into the native component and uses the width of the container to determine when the text gets truncated. It is not based on a character limit. 
+
 ## Multiple files
 
 Multiple files can be added at once when the `multiple` attribute is enabled in code. When more than one file is selected, the text will change to show the number of files you’ve selected, e.g., “2 files”. *The exact language used may differ between browsers.*

website/docs/components/form/masked-input/partials/code/how-to-use.md

@@ -51,6 +51,18 @@ If you need to make the content visible by default or control the masking from o
 
 #### Multiline
 
+!!! Info
+
+**Important to know**
+
+When the multiline input is masked, the browser converts newline characters to masked characters: this means that the multiline text will appear as a single long string of characters, even if it’s inside a `<textarea>` element.
+
+When the text is not masked, the newline characters will be respected. This means it may occupy more lines than when it’s masked (see the example above).
+
+Something to keep in mind when designing and implementing functionality that makes use of this component.
+
+!!!
+
 Set `@isMultiline` argument to `true` to render a `<textarea>`
 
 ```handlebars
@@ -72,18 +84,6 @@ v/Ow5T0q5gIJAiEAyS4RaI9YG8EWx/2w0T67ZUVAw8eOMB6BIUg0Xcu+3okCIBOs
 </Hds::Form::MaskedInput::Field>
 ```
 
-!!! Info
-
-**Important to know**
-
-When the multiline input is masked, the browser converts newline characters to masked characters: this means that the multiline text will appear as a single long string of characters, even if it’s inside a `<textarea>` element.
-
-When the text is not masked, the newline characters will be respected. This means it may occupy more lines than when it’s masked (see the example above).
-
-Something to keep in mind when designing and implementing functionality that makes use of this component.
-
-!!!
-
 #### Copy button
 
 To allow users to copy the input value to their clipboard, set the `@hasCopyButton` argument to `true`.
@@ -322,13 +322,13 @@ Pass a custom width for the control using the `@width` argument.
 
 ### Form::MaskedInput::Base
 
-The Base component is intended for rare cases where the Field component can’t be used and a custom implementation is needed. Most of the details for the Field component also apply to the Base component, but see the [Component API](#component-api) for more details.
-
 !!! Warning
 
 `Form::MaskedInput::Base` does not come with built-in accessibility functionality. It is the responsibility of the product team to ensure the implementation is conformant.
 !!!
 
+The Base component is intended for rare cases where the Field component can’t be used and a custom implementation is needed. Most of the details for the Field component also apply to the Base component, but see the [Component API](#component-api) for more details.
+
 The default invocation creates a `<input type="text">` or a `<textarea>` control with an automatically generated `ID` attribute.
 
 ```handlebars
@@ -338,6 +338,17 @@ The default invocation creates a `<input type="text">` or a `<textarea>` control
   name="demo-team-token"
 />
 ```
+!!! Info
+
+**Important to know**
+
+When the multiline input is masked, the browser converts newline characters to masked characters: this means that the multiline text will appear as a single long string of characters, even though it’s inside a `<textarea>` element.
+
+Instead, when the text is not masked it will respect the newline characters: this means it may occupy more lines that when it’s masked (try the example above).
+
+Something to keep in mind when designing and implementing functionality that requires this component.
+
+!!!
 
 When the `@isMultiline` argument is set to `true`, it creates a `<textarea>` control with an automatically generated `ID` attribute. You can also adjust the height of `<textarea>` either by using the `rows` attribute or by setting a custom `@height` value.
 
@@ -357,16 +368,4 @@ v/Ow5T0q5gIJAiEAyS4RaI9YG8EWx/2w0T67ZUVAw8eOMB6BIUg0Xcu+3okCIBOs
   aria-label="Private key"
   name="demo-team-token"
 />
-```
-
-!!! Info
-
-**Important to know**
-
-When the multiline input is masked, the browser converts newline characters to masked characters: this means that the multiline text will appear as a single long string of characters, even though it’s inside a `<textarea>` element.
-
-Instead, when the text is not masked it will respect the newline characters: this means it may occupy more lines that when it’s masked (try the example above).
-
-Something to keep in mind when designing and implementing functionality that requires this component.
-
-!!!
+```

website/docs/components/form/masked-input/partials/guidelines/overview.md

@@ -1,10 +1,8 @@
-A Masked Input field is a special input that visually obfuscates characters to protect sensitive information by masking them with a circular shape.
-
 !!! Warning
 
 **Important to know**
 
 This component is meant for **visual obfuscation** only. Consumers should be aware that the hidden text value could still be obtained through other means (e.g., copying it from the input, via JavaScript, via the developer tools, etc.).
+!!!
 
-
-!!!
+A Masked Input field is a special input that visually obfuscates characters to protect sensitive information by masking them with a circular shape.