docs(design): tag examples with @example

libs/design/button/src/button/basic/button.component.ts

@@ -13,7 +13,7 @@ import { DaffButtonBaseDirective } from '../button-base.directive';
 /**
  * DaffButtonComponent is a rectangular contained button with background color.
  *
- * ## Usage
+ * @example Basic button
  * ```html
  * <button daff-button>
  *  <div daffPrefix></div>

libs/design/button/src/button/flat/flat.component.ts

@@ -13,7 +13,7 @@ import { DaffButtonBaseDirective } from '../button-base.directive';
 /**
  * DaffFlatButtonComponent is a rectangular contained button no background.
  *
- * ## Usage
+ * @example Flat button
  * ```html
  * <button daff-flat-button>
  *  <div daffPrefix></div>

libs/design/button/src/button/icon/icon.component.ts

@@ -13,7 +13,7 @@ import { DaffButtonBaseDirective } from '../button-base.directive';
 /**
  * DaffIconButtonComponent is an icon button used with icon fonts.
  *
- * ## Usage
+ * @example Icon button
  * ```html
  * <button daff-icon-button>
  *  <fa-icon [icon]="faPlus"></fa-icon>

libs/design/button/src/button/raised/raised.component.ts

@@ -13,7 +13,7 @@ import { DaffButtonBaseDirective } from '../button-base.directive';
 /**
  * DaffRaisedButtonComponent is a rectangular contained button with background color and elevation.
  *
- * ## Usage
+ * @example Raised button
  * ```html
  * <button daff-raised-button>
  *  <div daffPrefix></div>

libs/design/button/src/button/stroked/stroked.component.ts

@@ -14,7 +14,7 @@ import { DaffButtonBaseDirective } from '../button-base.directive';
 /**
  * DaffStrokedButtonComponent is a rectangular outlined button with no background color.
  *
- * ## Usage
+ * @example Stroked button
  * ```html
  * <button daff-stroked-button>
  *  <div daffPrefix></div>

libs/design/button/src/button/underline/underline.component.ts

@@ -14,7 +14,7 @@ import { DaffButtonBaseDirective } from '../button-base.directive';
 /**
  * DaffUnderlineButtonComponent is a borderless button with a custom underline style.
  *
- * ## Usage
+ * @example Underline button
  * ```html
  * <button daff-underline-button>
  *  <div daffPrefix></div>

libs/design/sidebar/src/sidebar-viewport/sidebar-viewport.component.ts

@@ -46,23 +46,25 @@ import { DaffSidebarComponent } from '../sidebar/sidebar.component';
 import { DaffSidebarViewportBackdropComponent } from '../sidebar-viewport-backdrop/sidebar-viewport-backdrop.component';
 
 /**
- * The DaffSidebarViewport is the "holder" of sidebars throughout an entire application.
- * It's generally only used once, like
+ * The DaffSidebarViewportComponent is the "holder" of sidebars throughout an entire application.
  *
- * ```html
- * <daff-sidebar-viewport>
- *    <daff-sidebar></daff-sidebar>
- *    <p>Some Content</p>
- * </daff-sidebar-viewport>
- * ```
- *
- * Importantly, its possible for there to be multiple sidebars of many modes
- * at the same time. @see {@link DaffSidebarMode }
+ * `<daff-sidebar-viewport>` should only ever be used once in an application,
+ * but it's possible for there to be multiple sidebars of many modes
+ * at the same time. See {@link DaffSidebarMode}.
  *
  * Since this is a functional component, it's possible to have multiple "open" sidebars
  * at the same time. As a result, this component attempts to gracefully handle these situations.
  * However, importantly, there can only be one sidebar of each mode, on each side, at any given time.
+ *
  * If this is violated, this component will throw an exception.
+ *
+ * @example Using the sidebar viewport
+ * ```html
+ * <daff-sidebar-viewport>
+ *    <daff-sidebar></daff-sidebar>
+ *    <p>Site content</p>
+ * </daff-sidebar-viewport>
+ * ```
  */
 @Component({
   selector: 'daff-sidebar-viewport',

libs/design/src/core/article-encapsulated/article-encapsulated.directive.ts

@@ -7,15 +7,15 @@ import {
  * `DaffArticleEncapsulatedDirective` is used to encapsulate custom components within an article,
  * preventing {@link DaffArticleComponent } styles from bleeding into the component.
  *
- * ## Usage
+ * @example
  *
- * ### Implementing it as an attribute directive
+ * Implementing it as an attribute directive
  *
  * ```html
  * <my-custom-component daffArticleEncapsulated></my-custom-component>
  * ```
  *
- * ### Implementing it as an Angular host directive
+ * Implementing it as an Angular host directive
  *
  * ```ts
  * @Component({
@@ -25,6 +25,7 @@ import {
  *  hostDirectives: [{ directive: DaffArticleEncapsulatedDirective }],
  * })
  * export class CustomComponent { }
+ * ```
  *
  * This directive will apply the `daff-ae` class to your component, ensuring that it is encapsulated from the article's styles.
  */

libs/design/src/core/colorable/colorable.directive.ts

@@ -26,15 +26,15 @@ const validateColor = (color: string) => {
  * styles by setting CSS classes based on the specified color. This directive is useful
  * for applying different color palettes to a component in an Angular application.
  *
- * ## Usage
+ * @example
  *
- * ### Implementing it as an attribute directive
+ * Implementing it as an attribute directive
  *
  * ```html
  * <div daffColorable [color]="componentColor">Colored content</div>
  * ```
  *
- * ### Implementing it as an Angular host directive
+ * Implementing it as an Angular host directive
  *
  * ```ts
  * @Component({
@@ -51,6 +51,7 @@ const validateColor = (color: string) => {
  * export class CustomComponent { }
  * ```
  *
+ * Setting custom styles
  * ```scss
  * .custom-component {
  *
@@ -61,8 +62,6 @@ const validateColor = (color: string) => {
  * }
  * ```
  *
- * ## Styles
- *
  * The directive applies the following CSS classes based on the color:
  *
  * - `daff-primary`: Applied when the color is `primary`.

libs/design/src/core/compactable/compactable.directive.ts

@@ -9,18 +9,18 @@ import {
  * style by toggling a CSS class. This is useful for creating components that can
  * switch between regular and compact styles based on the `compact` property.
  *
- * ## Usage
+ * @example
  *
- * ### Implementing it as an attribute directive
+ * Implementing it as an attribute directive
+ *
+ * In this example, the `daff-compact` class is applied to the `div` element when
+ * `isCompact` is `true`, making the `div` display its compact state.
  *
  * ```html
  * <div daffCompactable [compact]="isCompact">Content goes here</div>
  * ```
  *
- * In this example, the `daff-compact` class is applied to the `div` element when
- * `isCompact` is `true`, making the `div` display its compact state.
- *
- * ### Implementing it as an Angular host directive
+ * Implementing it as an Angular host directive
  *
  * ```ts
  * @Component({
@@ -37,6 +37,9 @@ import {
  * export class CustomComponent { }
  * ```
  *
+ * The `daff-compact` class should be defined in your styles to display the compact
+ * state as desired.
+ *
  * ```scss
  * .custom-component {
  *  padding: 8px 16px;
@@ -46,11 +49,6 @@ import {
  *  }
  * }
  * ```
- *
- * ## Styles
- *
- * The `daff-compact` class should be defined in your styles to display the compact
- * state as desired.
  */
 @Directive({
   selector: '[daffCompactable]',

libs/design/src/core/focus/stack.service.ts

@@ -25,6 +25,7 @@ export class DaffFocusStackService {
    * Generally, you will probably want to call this before you transition focus
    * onto a new element.
    *
+   * @example Using the push function
    * ```ts
    * this._focusStack.push(this._doc.activeElement);
    * ```
@@ -37,8 +38,9 @@ export class DaffFocusStackService {
   /**
    * Focuses on the HTML element at the top of a stack.
    *
+   * @example Using the focus function
    * ```ts
-   * this._focusStack.push(this._doc.activeElement);
+   * this._focusStack.focus(this._doc.activeElement);
    * ```
    */
   focus() {

libs/design/src/core/manage-container-layout/manage-container-layout.directive.ts

@@ -26,9 +26,9 @@ import {
  * while the latter (without `DaffManageContainerLayoutDirective`) may unexpectedly
  * interfere in the layout features of its parent element (i.e. display: grid, display: flex).
  *
- * ## Usage
+ * @example
  *
- * ### Implementing it as an attribute directive
+ * Implementing it as an attribute directive
  *
  * ```html
  * <my-custom-component daffManageContainerLayout>
@@ -43,7 +43,7 @@ import {
  * }
  * ```
  *
- * ### Implementing it as an Angular host directive
+ * Implementing it as an Angular host directive
  *
  * ```ts
  * @Component({

libs/design/src/core/openable/openable.directive.ts

@@ -16,7 +16,7 @@ import { DaffOpenableStateError } from './utils/state-error';
  * A directive that opens or closes a component. It should only be used as an [Angular Host Directive](https://angular.dev/guide/directives/directive-composition-api).
  * This directive is stateless by default, but it supports both a state and stateless implementation. Only one version should be used within a component.
  *
- * ## Example
+ * @example Using the DaffOpenableDirective
  * ```ts
  * import {
  *  Component,
@@ -74,6 +74,7 @@ export class DaffOpenableDirective implements DaffOpenable, OnChanges {
 
   /** Whether or not a component should handle state
    *
+   * @example Setting the `stateless` property on a component
    * ```ts
    * constructor(private openDirective: DaffOpenableDirective) {
    *  this.openDirective.stateless = false;

libs/design/src/core/sizable/sizable.directive.ts

@@ -17,17 +17,17 @@ import {
  * `DaffSizableDirective` allows for dynamic sizing of a component by setting
  * CSS classes based on the specified size.
  *
- * ## Usage
+ * @example
  *
- * ### Implementing it as an attribute directive
+ * Implementing it as an attribute directive
  *
  * ```html
  * <div daffSizable [size]="small">Sized content</div>
  * ```
  * In this example, the `daff-small` class is applied to the `div` element, allowing you to
  * use the class to style the `div`.
  *
- * ### Implementing it as an Angular host directive
+ * Implementing it as an Angular host directive
  *
  * ```ts
  * @Component({
@@ -56,8 +56,6 @@ import {
  * }
  * ```
  *
- * ## Styles
- *
  * The directive applies the following CSS classes based on the size:
  *
  * - `daff-xs`: Applied when the size is `xs`.

libs/design/src/core/skeletonable/skeletonable.directive.ts

@@ -12,15 +12,15 @@ import {
  * input property. When `skeleton` is `true`, the `daff-skeleton` CSS class
  * is applied, which should style the component to look like a loading placeholder.
  *
- * ## Usage
+ * @example
  *
- * ### Implementing it as an attribute directive
+ * Implementing it as an attribute directive
  *
  * ```html
  * <div daffSkeletonable [skeleton]="isLoading">Content</div>
  * ```
  *
- * ### Implementing it as an Angular host directive
+ * Implementing it as an Angular host directive
  *
  * ```ts
  * @Component({
@@ -43,8 +43,6 @@ import {
  * }
  * ```
  *
- * ## Styles
- *
  * The `daff-skeleton` class should be defined in your styles to display the loading
  * state as desired. It can be used in conjuction with the `skeleton-screen` mixin, which provides predefined loading styles.
  */

libs/design/src/core/statusable/statusable.directive.ts

@@ -15,15 +15,15 @@ import {
  * styles by setting CSS classes based on the specified status. This directive is useful
  * for indicating different statuses such as info, warning, critical, or success states.
  *
- * ## Usage
+ * @example
  *
- * ### Implementing it as an attribute directive
+ * Implementing it as an attribute directive
  *
  * ```html
  * <div daffStatusable [status]="componentStatus">Status content</div>
  * ```
  *
- * ### Implementing it as an Angular host directive
+ * Implementing it as an Angular host directive
  *
  * ```ts
  * @Component({
@@ -48,7 +48,6 @@ import {
  *  }
  * }
  * ```
- * ## Styles
  *
  * The directive applies the following CSS classes based on the status:
  *

libs/design/src/core/text-alignable/text-alignable.directive.ts

@@ -17,19 +17,25 @@ import {
  * setting CSS classes based on the specified text alignment. This directive is
  * useful when text alignment needs to be managed dynamically in an Angular component.
  *
- * ## Usage
+ * ## Why not just use CSS?
+ *
+ * While the native CSS `text-align` property can be used for static text alignment,
+ * the `DaffTextAlignableDirective` provides a structured and consistent way to handle
+ * dynamic text alignment within Angular components in more complex use cases where the
+ * application of `text-align: center;` would cause unexpected side effects.
  *
- * ### Implementing it as an attribute directive
+ * @example
+ *
+ * Implementing it as an attribute directive
  *
  * ```html
  * <div daffTextAlignable textAlignment="center">Aligned text</div>
+ * ```
  *
  * In this example, the `daff-center` class is added to the `div` element, allowing
  * you to style the `div` as you wish using the class.
  *
- * ```
- *
- * ### Implementing it as an Angular host directive
+ * Implementing it as an Angular host directive
  *
  * ```ts
  * @Component({
@@ -53,13 +59,6 @@ import {
  *  }
  * }
  * ```
- *
- * ## Why not just use CSS?
- *
- * While the native CSS `text-align` property can be used for static text alignment,
- * the `DaffTextAlignableDirective` provides a structured and consistent way to handle
- * dynamic text alignment within Angular components in more complex use-cases where the
- * application of `text-align:center` would cause unexpected side effects.
  */
 @Directive({
   selector: '[daffTextAlignable]',