### NPM Installation

Source: https://github.com/rolemodel/optics/blob/main/README.md

Installs the Optics package using npm.

```sh
npm install @rolemodel/optics
```

--------------------------------

### Yarn Installation

Source: https://github.com/rolemodel/optics/blob/main/README.md

Installs the Optics package using Yarn.

```sh
yarn add @rolemodel/optics
```

--------------------------------

### Margin Storybook Examples (JavaScript)

Source: https://github.com/rolemodel/optics/blob/main/src/stories/Utilities/Margin/Margin.mdx

These are examples from Storybook demonstrating the usage of the margin utility classes. They show how to apply different margin sizes to components.

```javascript
import * as MarginStories from './Margin.stories';

// Example for Margin Left Small
<Canvas of={MarginStories.MarginLeftSmall} />

// Example for Margin Left Medium
<Canvas of={MarginStories.MarginLeftMedium} />

// Example for Margin Left Large
<Canvas of={MarginStories.MarginLeftLarge} />

// Example for Margin Left Extra Large
<Canvas of={MarginStories.MarginLeftExtraLarge} />

// Example for Margin Right None
<Canvas of={MarginStories.MarginRightNone} />

// Example for Margin Right Extra Small
<Canvas of={MarginStories.MarginRightExtraSmall} />

// Example for Margin Right Small
<Canvas of={MarginStories.MarginRightSmall} />

// Example for Margin Right Medium
<Canvas of={MarginStories.MarginRightMedium} />

// Example for Margin Right Large
<Canvas of={MarginStories.MarginRightLarge} />

// Example for Margin Right Extra Large
<Canvas of={MarginStories.MarginRightExtraLarge} />
```

--------------------------------

### Detailed Token Naming Examples

Source: https://github.com/rolemodel/optics/blob/main/src/stories/Overview/Tokens.mdx

Provides concrete examples of CSS token names following the defined structure, demonstrating how different components like color, font-size, and shadow are represented.

```css
--op-color-primary-on-plus-one: value
```

```css
--op-font-size-large: value
```

```css
--op-shadow-x-small: value
```

```css
--op-border-bottom: value
```

--------------------------------

### Install Optics via NPM

Source: https://github.com/rolemodel/optics/blob/main/src/stories/Overview/Introduction.mdx

Installs the Optics CSS package using the Node Package Manager (NPM). This is the recommended method for projects using NPM.

```bash
npm install @rolemodel/optics
```

--------------------------------

### Flexbox Playground Example

Source: https://github.com/rolemodel/optics/blob/main/src/stories/Utilities/Flex/Flex.mdx

Demonstrates the 'Flex' component with various configurations using Storybook's Canvas and Controls.

```html
<Canvas of={FlexStories.With} />
<Controls of={FlexStories.With} />
```

--------------------------------

### Shadow Usage Example

Source: https://github.com/rolemodel/optics/blob/main/src/stories/Tokens/Shadow.mdx

Demonstrates how to apply shadow tokens using the CSS box-shadow property. Shows examples for small and large shadow tokens.

```css
box-shadow: var(--op-shadow-x-small);
/* or */
box-shadow: var(--op-shadow-x-large);
```

--------------------------------

### Install Optics via Yarn

Source: https://github.com/rolemodel/optics/blob/main/src/stories/Overview/Introduction.mdx

Installs the Optics CSS package using the Yarn package manager. This is an alternative to NPM for projects using Yarn.

```bash
yarn add @rolemodel/optics
```

--------------------------------

### Gap Utility Usage Example

Source: https://github.com/rolemodel/optics/blob/main/src/stories/Utilities/Gap/Gap.mdx

An HTML example showcasing the application of gap utility classes within a flex container. It illustrates how different gap sizes affect the spacing between child elements.

```html
<div class="flex gap-sm">
  <div>1</div>
  <div>2</div>
  <div class="special-item">
    <div>a</div>
    <div>b</div>
    <div>c</div>
  </div>
  <div>4</div>
</div>
```

--------------------------------

### Storybook Setup for Content Header

Source: https://github.com/rolemodel/optics/blob/main/src/stories/Components/ContentHeader/ContentHeader.mdx

This JavaScript snippet shows the Storybook configuration for the Content Header component, including importing necessary components and stories, and setting up the meta information.

```javascript
import { Meta, Story, Canvas, Controls } from '@storybook/blocks'
import * as ContentHeaderStories from './ContentHeader.stories'
import { createSourceCodeLink } from '../../helpers/sourceCodeLink.js'

import { createAlert } from '../Alert/Alert.js'

<Meta of={ContentHeaderStories} />
```

--------------------------------

### Storybook Configuration and Component Usage

Source: https://github.com/rolemodel/optics/blob/main/tools/templates/component/??name??(pascalCase).mdx

This snippet shows the basic Storybook setup for the Optics component, including importing necessary modules and defining the component's meta information. It also demonstrates how to render the component in different states using Canvas and Controls.

```javascript
import { Meta, Story, Canvas, Controls } from '@storybook/blocks'
import * as ??name??(pascalCase)Stories from './??name??(pascalCase).stories'

import { createAlert } from '../Alert/Alert.js'

<Meta of={??name??(pascalCase)Stories} />

# ??name??(pascalCase)

Brief overview description of how to use ??name??(pascalCase) classes

## Playground

<Canvas of={??name??(pascalCase)Stories.Default} />
<Controls of={??name??(pascalCase)Stories.Default} />
```

--------------------------------

### Usage Example

Source: https://github.com/rolemodel/optics/blob/main/src/stories/Tokens/Color/BorderColor.mdx

Demonstrates how to apply border color tokens using CSS.

```css
border-color: var(--op-color-border);
/* or */
box-shadow: var(--op-border-top) var(--op-color-border);
```

--------------------------------

### Basic Div Example

Source: https://github.com/rolemodel/optics/blob/main/src/stories/Utilities/Flex/Flex.mdx

Illustrates a standard 'div' element without any flex utility classes applied.

```html
A normal `div` without the flex utility

<Canvas of={FlexStories.Without} />
```

--------------------------------

### Text Pair Customization Example

Source: https://github.com/rolemodel/optics/blob/main/src/stories/Components/TextPair/TextPair.mdx

Provides an example of how to override the default styles of the Text Pair component by targeting the `.text-pair` selector.

```css
.text-pair {
  gap: var(--op-space-x-large);
}
```

--------------------------------

### Usage Example

Source: https://github.com/rolemodel/optics/blob/main/src/stories/Tokens/Border/BorderWidth.mdx

Demonstrates how to apply border width tokens using CSS for borders or box shadows.

```css
border-width: 0 0 0 var(--op-border-width);
/* or */
box-shadow: 0 0 0 var(--op-border-width);
```

--------------------------------

### Text Alignment Utility Classes

Source: https://github.com/rolemodel/optics/blob/main/src/stories/Utilities/TextAlignment/TextAlignment.mdx

Demonstrates the usage of text alignment utility classes for aligning text within elements. Includes examples for left, center, right, and justify alignments.

```html
<div
  dangerouslySetInnerHTML={{ __html: createSourceCodeLink({ link: 'core/utilities.css' }).outerHTML }}>
</div>
```

```html
<!-- Playground -->
<Canvas of={TextAlignmentStories.Left} />
<Controls of={TextAlignmentStories.Left} />

<!-- Left Alignment -->
<Canvas of={TextAlignmentStories.Left} />

<!-- Center Alignment -->
<Canvas of={TextAlignmentStories.Center} />

<!-- Right Alignment -->
<Canvas of={TextAlignmentStories.Right} />

<!-- Justify Alignment -->
<Canvas of={TextAlignmentStories.Justify} />
```

--------------------------------

### Token Naming Structure Example

Source: https://github.com/rolemodel/optics/blob/main/src/stories/Overview/Tokens.mdx

Illustrates the standard naming structure for CSS tokens in the Optics project, showing the breakdown of prefix, category, sub-category, qualifiers, and variants.

```css
--prefix-category-sub-category-variant-qualifier-variant: value
```

--------------------------------

### Fullscreen Spinner Layout

Source: https://github.com/rolemodel/optics/blob/main/src/stories/Recipes/Layout/Layout.mdx

Provides an example of how to implement a fullscreen loading spinner within the application layout. It uses the `.app-body` class along with utility classes for centering content and styling the spinner itself.

```html
<!doctype html>
<html>
  <head>
    <title>Sample Layout</title>
    <meta content="width=device-width, initial-scale=1" name="viewport" />
  </head>
  <body class="app-body items-center justify-center">
    <div class="spinner spinner--large">
      <span class="sr-only">Loading</span>
    </div>
  </body>
</html>
```

--------------------------------

### CSS Component Structure Example

Source: https://github.com/rolemodel/optics/blob/main/NEW_COMPONENT.md

Demonstrates the recommended structure for CSS components, including base styles, hover states, variant modifiers (e.g., `--large`), and disabled states. It follows a BEM-like naming convention for modifiers and variants.

```css
.btn {
  /* Base styles for the button */

  /* Hover state */
  &:hover {
    /*
      Styles for the hovered button modifier
      ...
    */
  }

  /* Modifier: Large button */
  &.btn--large {
    /* Styles for the large button modifier */
  }

  /* Modifier: Disabled button */
  &.btn--disabled,
  &:disabled {
    /* Styles for the disabled button modifier */
  }
}

/* Variant: Primary button */
.btn.btn--primary {
  /*
    Specific styles for the primary button variant
    ...
  */
}
```

--------------------------------

### Usage Example

Source: https://github.com/rolemodel/optics/blob/main/src/stories/Tokens/Opacity.mdx

Demonstrates how to apply opacity tokens using CSS variables to achieve faded or disabled effects on elements.

```css
opacity: var(--op-opacity-disabled);
/* or */
opacity: var(--op-opacity-full);
```

--------------------------------

### Storybook Setup for Encoded Image Tokens

Source: https://github.com/rolemodel/optics/blob/main/src/stories/Tokens/EncodedImage.mdx

Imports necessary components from Storybook and local helpers to set up the documentation page for Encoded Image tokens. It defines the meta information and includes a link to the source CSS file.

```javascript
import { Canvas, Meta } from '@storybook/blocks'
import * as SelectStories from '../Components/Form/Select.stories'
import { DesignTokenDocBlock } from 'storybook-design-token'
import { createSourceCodeLink } from '../helpers/sourceCodeLink.js'

<Meta title="Tokens/Encoded Image" />

# Encoded Image

<div
  dangerouslySetInnerHTML={{
    __html: createSourceCodeLink({ link: 'core/tokens/base_tokens.css' }).outerHTML,
  }}
></div>
```

--------------------------------

### Confirm Dialog CSS Customization Example

Source: https://github.com/rolemodel/optics/blob/main/src/stories/Components/ConfirmDialog/ConfirmDialog.mdx

Provides an example of how to customize the Confirm Dialog's appearance by overriding its default CSS properties. This demonstrates modifying the z-index and background color.

```css
.confirm-dialog-wrapper {
  z-index: 200;
}

.confirm-dialog {
  background-color: red;
}
```

--------------------------------

### Custom Variable Font Configuration (Roboto Flex Example)

Source: https://github.com/rolemodel/optics/blob/main/src/stories/Tokens/Typography/FontFamily.mdx

Provides a template for configuring custom variable fonts, using Roboto Flex as an example, and defining various axes like weight, slant, and width.

```css
/*
  {uniquifier}: Use a unique and descriptive class name
  {weight}: Use a value from 100 to 1000
  {grade}: Use a value from -200 to 150
  {slant}: Use a value from -10 to 0
  {width}: Use a value from 25 to 151
  {thick stroke}: Use a value from 27 to 175
  {thin stroke}: Use a value from 25 to 135
  {counter width}: Use a value from 323 to 603
  {uppercase height}: Use a value from 528 to 760
  {lowercase height}: Use a value from 416 to 570
  {ascender height}: Use a value from 649 to 854
  {descender depth}: Use a value from -305 to -98
  {figure height}: Use a value from 560 to 788
*/

.roboto-flex-{uniquifier} {
  font-family: 'Roboto Flex', sans-serif;
  font-optical-sizing: auto;
  font-weight: {weight};
  font-style: normal;
  font-variation-settings:
    'slnt' {slant},
    'wdth' {width},
    'GRAD' {grade},
    'XOPQ' {thick stroke},
    'XTRA' {counter width},
    'YOPQ' {thin stroke},
    'YTAS' {ascender height},
    'YTDE' {descender depth},
    'YTFI' {figure height},
    'YTLC' {lowercase height},
    'YTUC' {uppercase height};
}
```

--------------------------------

### CSS Usage for Animation and Transition

Source: https://github.com/rolemodel/optics/blob/main/src/stories/Tokens/Animation/Animation.mdx

Examples of how to apply animation and transition tokens using CSS variables for element transitions and animations.

```css
transition: var(--op-transition-input);
/* or */
animation: var(--op-animation-flash);
```

--------------------------------

### Size Token Usage Example

Source: https://github.com/rolemodel/optics/blob/main/src/stories/Tokens/Sizing.mdx

Demonstrates how to use the Size token in CSS `calc` expressions to create scalable dimensions that are multiples of 4px.

```css
height: calc(11 * var(--op-size-unit)); /* 44px */
/* Or */
width: calc(54 * var(--op-size-unit)); /* 216px */
```

--------------------------------

### Cascade Example

Source: https://github.com/rolemodel/optics/blob/main/src/stories/Utilities/Gap/Gap.mdx

Demonstrates how to use the --op-gap CSS variable to match container spacing in nested elements. This ensures consistent visual spacing.

```css
.special-item {
  display: flex;
  gap: var(--op-gap, var(--op-space-sm)); /* Include a fallback in case the wrapping gap is missing. */
}
```

--------------------------------

### Customizing Dynamic Themes (CSS)

Source: https://github.com/rolemodel/optics/blob/main/src/stories/Overview/Themes.mdx

Shows how to define styles for a specific dynamic theme (e.g., 'example') by targeting the `data-theme` attribute. This includes overriding colors, color scales, and fonts, with conditional styling for dark mode.

```css
@import url('https://fonts.googleapis.com/css2?family=Coming+Soon&display=swap');
@import url('https://fonts.googleapis.com/css2?family=Grandstander:ital,wght@0,100;0,200;0,300;0,400;0,500;0,600;0,700;0,800;0,900;1,100;1,200;1,300;1,400;1,500;1,600;1,700;1,800;1,900&display=swap');

:root[data-theme='example'] {
  /* Colors */
  --op-color-primary-h: my-new-value;
  --op-color-primary-s: my-new-value;
  --op-color-primary-l: my-new-value;

  /* Color Scale */
  --op-color-primary-plus-two: light-dark(
    hsl(var(--op-color-primary-h) var(--op-color-primary-s) 64%),
    hsl(var(--op-color-primary-h) var(--op-color-primary-s) 32%)
  );

  /* Fonts */
  --op-font-family: 'Coming Soon', sans-serif;
}

@media (prefers-color-scheme: dark) {
  :root[data-theme='example']:not([data-theme-mode='light']) {
    /* Fonts */
    --op-font-family: 'Grandstander', sans-serif;
  }
}

:root[data-theme='example'][data-theme-mode='dark'] {
  /* Fonts */
  --op-font-family: 'Grandstander', sans-serif;
}
```

--------------------------------

### Basic Layout Structure

Source: https://github.com/rolemodel/optics/blob/main/src/stories/Recipes/Layout/Layout.mdx

Demonstrates the fundamental HTML structure for a typical application layout, including the body, header, content, and footer elements. It highlights the use of classes like `.app-body`, `.app__header`, `.app__content`, and `.app__footer` for styling and functionality.

```html
<!doctype html>
<html>
  <head>
    <title>Sample Layout</title>
    <meta content="width=device-width, initial-scale=1" name="viewport" />
  </head>
  <body class="app-body">
    <!-- Alert Flash message here -->
    <!-- Confirm here -->
    <!-- Modal here -->
    <!-- Panel here -->
    <!--
      If your app has a top header, use
      <div class='app__header'></div>
    -->
    <div class="app__content"></div>
    <!--
      If your app has a bottom footer, use
      <div class='app__footer'></div>
    -->
  </body>
</html>
```

--------------------------------

### Accordion New Variation Example

Source: https://github.com/rolemodel/optics/blob/main/src/stories/Components/Accordion/Accordion.mdx

Illustrates how to create a new Accordion variation using a BEM modifier. This example shows how to set a specific CSS variable for a new style.

```css
.accordion--{
  --_op-accordion-summary-min-height: var(--op-font-small);
}
```

--------------------------------

### Applying Dynamic Themes with Data Attributes (HTML)

Source: https://github.com/rolemodel/optics/blob/main/src/stories/Overview/Themes.mdx

Demonstrates how to activate a specific dynamic theme by setting the `data-theme` attribute on the root HTML element. This allows for multiple predefined themes to be switched between.

```html
<!doctype html>
<html data-theme="example">
  ...
</html>
```

--------------------------------

### Avatar New Variation Example

Source: https://github.com/rolemodel/optics/blob/main/src/stories/Components/Avatar/Avatar.mdx

Provides a template for creating new Avatar variations using BEM modifiers. This example shows how to set a custom border radius for a new variation.

```css
.avatar--{name} {
  --_op-avatar-border-radius: var(--op-radius-2x-large);
}
```

--------------------------------

### Layout with Sidebar

Source: https://github.com/rolemodel/optics/blob/main/src/stories/Recipes/Layout/Layout.mdx

Illustrates the HTML structure for an application that includes a sidebar. It shows how to use the `.app-with-sidebar` class on the body and nest the sidebar and main content within the `.app-body`.

```html
<!doctype html>
<html>
  <head>
    <title>Sample Layout</title>
    <meta content="width=device-width, initial-scale=1" name="viewport" />
  </head>
  <body class="app-with-sidebar">
    <!-- Alert Flash message here -->
    <!-- Confirm here -->
    <!-- Modal here -->
    <!-- Panel here -->
    <div class="sidebar sidebar--{rail or drawer}">...</div>
    <div class="app-body">
      <!--
        If your app has a top header, use
        <div class='app__header'></div>
      -->
      <div class="app__content"></div>
      <!--
        If your app has a bottom footer, use
        <div class='app__footer'></div>
      -->
    </div>
    <!-- You could put the sidebar or some other drawer here as well -->
  </body>
</html>
```

--------------------------------

### CSS Purple Alert Example

Source: https://github.com/rolemodel/optics/blob/main/src/stories/Components/Alert/Alert.mdx

An example of a specific CSS alert variation for a purple alert. It showcases the implementation of base styles and the '--muted' and '--filled' states with concrete color values.

```css
.alert--purple {
  background-color: verylightpurple;
  box-shadow: var(--op-border-all) purple;
  color: purple;

  .alert__title {
    color: darkpurple;
  }

  &.alert--muted {
    background-color: lightpurple;
    box-shadow: none;
    color: white;

    .alert__title {
      color: purple;
    }
  }

  &.alert--filled {
    background-color: purple;
    box-shadow: none;
    color: white;

    .alert__title {
      color: darkpurple;
    }
  }
}
```

--------------------------------

### CSS Import with Compiler

Source: https://github.com/rolemodel/optics/blob/main/README.md

Demonstrates how to import Optics CSS using a compiler like webpack.

```css
@import '@rolemodel/optics'; /* Using webpack to compile */
/* Or */
@import '@rolemodel/optics/dist/css/optics'; /* Using a different compiler */
/* Or */
@import '@rolemodel/optics/dist/css/optics.min.css'; /* If you want a single file with all the styles in it. */
```

--------------------------------

### Storybook Meta Configuration

Source: https://github.com/rolemodel/optics/blob/main/tools/templates/overview/??name??(pascalCase).mdx

Configures Storybook documentation for a component, setting its title and potentially other metadata. The title is dynamically generated using Storybook's templating.

```javascript
import { Meta } from '@storybook/addon-docs'

<Meta title="Overview/??name??(pascalCase)" />
```

--------------------------------

### Design Token Documentation

Source: https://github.com/rolemodel/optics/blob/main/src/stories/Tokens/Opacity.mdx

Renders the documentation for Opacity design tokens using a card view.

```javascript
import { DesignTokenDocBlock } from 'storybook-design-token'

<DesignTokenDocBlock categoryName="Opacities" viewType="card" />
```

--------------------------------

### Helper for Source Code Link

Source: https://github.com/rolemodel/optics/blob/main/src/stories/Components/ConfirmDialog/ConfirmDialog.mdx

This code snippet demonstrates the usage of a helper function to create a link to the source code for the Confirm Dialog's CSS file.

```html
<div
  dangerouslySetInnerHTML={{ 
    __html: createSourceCodeLink({ link: 'components/confirm-dialog.css' }).outerHTML,
  }}
></div>
```

--------------------------------

### Align Self Start

Source: https://github.com/rolemodel/optics/blob/main/src/stories/Utilities/Flex/Flex.mdx

Applies `.self-start` to a flex item, aligning it to the beginning of the cross axis.

```html
`.self-start` places a specific flex item at the start of the cross axis.

<Canvas of={FlexStories.AlignSelfStart} />
```

--------------------------------

### Align Items Start

Source: https://github.com/rolemodel/optics/blob/main/src/stories/Utilities/Flex/Flex.mdx

Applies `.items-start` to align flex items to the beginning of the cross axis.

```html
`.items-start` places each flex item at the start of the cross axis.

<Canvas withToolbar>
  <Canvas of={FlexStories.AlignStart} />
</Canvas>
```

--------------------------------

### Storybook Design Token Categorization

Source: https://github.com/rolemodel/optics/blob/main/README.md

Example of how to categorize design tokens in Storybook using a CSS comment.

```css
/**
* @tokens Basic Colors
* @presenter Color
*/
```

--------------------------------

### Basic Lucide Icon Usage

Source: https://github.com/rolemodel/optics/blob/main/src/stories/Components/Icon/Icon.mdx

Demonstrates how to render a Lucide icon using an `<i>` tag with the appropriate classes. The `.li` prefix followed by the icon name (`li-banana`) specifies the icon.

```html
<i class="icon li li-banana"></i>
```

--------------------------------

### Customizing Sidebar Widths

Source: https://github.com/rolemodel/optics/blob/main/src/stories/Components/Sidebar/Sidebar.mdx

Example of overriding CSS variables to customize the width of the sidebar, rail, and drawer components.

```css
.sidebar {
  --_op-sidebar-rail-width: 10rem;
  --_op-sidebar-compact-width: 20rem;
  --_op-sidebar-drawer-width: 30rem;
}
```

--------------------------------

### Applying Optics and Custom Theme Overrides (CSS)

Source: https://github.com/rolemodel/optics/blob/main/src/stories/Overview/Themes.mdx

Illustrates the standard method for applying the Optics design system and then overriding its default tokens with custom theme files in your main CSS.

```css
@import '@rolemodel/optics';

@import 'stylesheets/theme/my_app_theme';
```

--------------------------------

### Justify Content Start

Source: https://github.com/rolemodel/optics/blob/main/src/stories/Utilities/Flex/Flex.mdx

Applies `.justify-start` to align flex items to the beginning of the main axis. This is the default alignment.

```html
`.justify-start` justifies the contents to the start of the flex axis. This is the default justification of a flex container and doesn't need to be applied unless you are overriding something set differently.

<Canvas of={FlexStories.JustifyStart} />
```

--------------------------------

### CSS Font Weight Usage

Source: https://github.com/rolemodel/optics/blob/main/src/stories/Tokens/Typography/FontWeight.mdx

Demonstrates how to apply font weight tokens using CSS variables. It highlights the use of '--op-font-weight-bold' as an example.

```css
font-weight: var(--op-font-weight-bold);
```

--------------------------------

### Phosphor Icons Usage

Source: https://github.com/rolemodel/optics/blob/main/src/stories/Components/Icon/Icon.mdx

Demonstrates the HTML structure for using Phosphor Icons, including standard icons and the duotone variation. It also highlights class modifiers for weight and fill, noting limitations.

```html
<i class="icon ph ph-smiley"></i>
```

```html
<i class="icon ph-duotone ph-smiley"></i>
```

--------------------------------

### Accordion CSS Customization

Source: https://github.com/rolemodel/optics/blob/main/src/stories/Components/Accordion/Accordion.mdx

Provides an example of how to customize Accordion styles by overriding the base '.accordion' selector. This allows for project-specific styling adjustments.

```css
.accordion {
}
```

--------------------------------

### Dynamic Themes with Manual Light/Dark Mode Control (HTML)

Source: https://github.com/rolemodel/optics/blob/main/src/stories/Overview/Themes.mdx

Shows how to combine dynamic theme activation with manual control over light or dark mode by setting both `data-theme` and `data-theme-mode` attributes on the root HTML element.

```html
<!doctype html>
<html data-theme="example" data-theme-mode="light">
  ...
</html>
```

--------------------------------

### HTML Import via CDN

Source: https://github.com/rolemodel/optics/blob/main/README.md

Shows how to include Optics CSS in an HTML file using a CDN link.

```html
<link
  rel="stylesheet"
  href="https://cdn.jsdelivr.net/npm/@rolemodel/optics@[desired version]/dist/css/optics.min.css"
/>
```

--------------------------------

### Usage Example

Source: https://github.com/rolemodel/optics/blob/main/src/stories/Tokens/Border/BorderRadius.mdx

Demonstrates how to apply border radius tokens to an element using CSS variables. This is a common way to achieve consistent rounded corners across the application.

```css
border-radius: var(--op-radius-small);
```

--------------------------------

### Pagination Base Structure and Styling

Source: https://github.com/rolemodel/optics/blob/main/src/stories/Components/Pagination/Pagination.mdx

Demonstrates the basic HTML structure for the Pagination component using the `.pagination` class on a `nav` element. It also outlines the recommended button classes (`.btn`, `.btn--no-border`, `.btn--small`) for a default look, and modifiers for icon buttons (`.btn--icon`) and active pages (`.btn--active`). The use of `.pagination__divider` for page breaks is also explained.

```css
/* Base class for pagination */
.pagination {
}

/* Button classes for pagination items */
.btn {
}
.btn--no-border {
}
.btn--small {
}

/* Modifier for icon-only buttons */
.btn--icon {
}

/* Modifier for the currently active page */
.btn--active {
}

/* Divider to indicate page breaks */
.pagination__divider {
}
```

--------------------------------

### Design Token Documentation

Source: https://github.com/rolemodel/optics/blob/main/src/stories/Tokens/Animation/Animation.mdx

Renders documentation for Transition and Animation design tokens in a card view.

```storybook
<DesignTokenDocBlock categoryName="Transition" viewType="card" />

<DesignTokenDocBlock categoryName="Animation" viewType="card" />
```

--------------------------------

### Customizing Sidebar Content Styles

Source: https://github.com/rolemodel/optics/blob/main/src/stories/Components/Sidebar/Sidebar.mdx

Examples of overriding CSS for sidebar content elements using BEM selectors to modify alignment and font weight.

```css
.sidebar {
  .sidebar__content {
    align-items: flex-end;
  }
}

.sidebar {
  .sidebar__content {
    > * {
      font-weight: var(--op-font-weight-black);
    }
  }
}
```

--------------------------------

### Source Code Link Helper

Source: https://github.com/rolemodel/optics/blob/main/src/stories/Tokens/Sizing.mdx

Generates an HTML element containing a link to the source code for the base tokens CSS file.

```javascript
import { createSourceCodeLink } from '../helpers/sourceCodeLink.js'

<div
  dangerouslySetInnerHTML={{ __html: createSourceCodeLink({ link: 'core/tokens/base_tokens.css' }).outerHTML }}
></div>
```

--------------------------------

### Import Google Fonts

Source: https://github.com/rolemodel/optics/blob/main/src/stories/Tokens/Typography/FontFamily.mdx

Imports Noto Sans and Noto Serif fonts from Google Fonts CDN. This is the default font setup for Optics.

```css
@import 'https://fonts.googleapis.com/css2?family=Noto+Sans:ital,wdth,wght@0,62.5..100,100..900;1,62.5..100,100..900&family=Noto+Serif:ital,wdth,wght@0,62.5..100,100..900;1,62.5..100,100..900&display=swap';
```

--------------------------------

### Override Color Scale

Source: https://github.com/rolemodel/optics/blob/main/src/stories/Overview/ScaleOverriding.mdx

Provides an example of overriding the primary color scale, including base HSL values and derived 'on' colors, using CSS variables.

```css
:root {
  --op-color-primary-h: 164;
  --op-color-primary-s: 100%;
  --op-color-primary-l: 50%;

  /* Main Scale */
  --op-color-primary-plus-two: light-dark(
    hsl(var(--op-color-primary-h) var(--op-color-primary-s) 64%),
    hsl(var(--op-color-primary-h) var(--op-color-primary-s) 32%)
  );
  --op-color-primary-plus-one: light-dark(
    hsl(var(--op-color-primary-h) var(--op-color-primary-s) 45%),
    hsl(var(--op-color-primary-h) var(--op-color-primary-s) 35%)
  );

  /* On Scale */
  --op-color-primary-on-plus-two: light-dark(
    hsl(var(--op-color-primary-h) var(--op-color-primary-s) 16%),
    hsl(var(--op-color-primary-h) var(--op-color-primary-s) 80%)
  );
  --op-color-primary-on-plus-two-alt: light-dark(
    hsl(var(--op-color-primary-h) var(--op-color-primary-s) 6%),
    hsl(var(--op-color-primary-h) var(--op-color-primary-s) 92%)
  );
  --op-color-primary-on-plus-one: light-dark(
    hsl(var(--op-color-primary-h) var(--op-color-primary-s) 100%),
    hsl(var(--op-color-primary-h) var(--op-color-primary-s) 80%)
  );
  --op-color-primary-on-plus-one-alt: light-dark(
    hsl(var(--op-color-primary-h) var(--op-color-primary-s) 95%),
    hsl(var(--op-color-primary-h) var(--op-color-primary-s) 98%)
  );
}
```

--------------------------------

### Usage Example for Encoded Image Tokens

Source: https://github.com/rolemodel/optics/blob/main/src/stories/Tokens/EncodedImage.mdx

Demonstrates how to apply the Encoded Image tokens as a background image for elements, specifically showing the CSS required to set a dropdown arrow background.

```css
background: var(--op-encoded-images-dropdown-arrow) center right no-repeat;
```

--------------------------------

### Confirm Dialog CSS Imports

Source: https://github.com/rolemodel/optics/blob/main/src/stories/Components/ConfirmDialog/ConfirmDialog.mdx

Demonstrates the necessary CSS imports for the Confirm Dialog component, including core styles and component-specific styles. These imports ensure the dialog is styled correctly.

```css
/* Depends on */
@import '@rolemodel/optics/dist/css/core/fonts';
@import '@rolemodel/optics/dist/css/core/tokens';
@import '@rolemodel/optics/dist/css/core/base';

/* Component */
@import '@rolemodel/optics/dist/css/components/confirm-dialog';
```

--------------------------------

### Storybook Canvas and Controls

Source: https://github.com/rolemodel/optics/blob/main/src/stories/Components/Switch/Switch.mdx

Example of how to integrate Storybook's Canvas and Controls components to display and interact with the Switch component's stories. This is used for development and documentation purposes.

```javascript
import { Meta, Story, Canvas, Controls } from '@storybook/blocks'
import * as SwitchStories from './Switch.stories'

<Meta of={SwitchStories} />

<Canvas of={SwitchStories.Default} />
<Controls of={SwitchStories.Default} />
```

--------------------------------

### CSS Import via CDN

Source: https://github.com/rolemodel/optics/blob/main/README.md

Demonstrates importing Optics CSS directly into a CSS file using a CDN link.

```css
@import 'https://cdn.jsdelivr.net/npm/@rolemodel/optics@[desired version]/dist/css/optics.min.css';
```

--------------------------------

### Alert Component Usage

Source: https://github.com/rolemodel/optics/blob/main/src/stories/Components/Icon/Icon.mdx

Demonstrates the usage of an alert component, likely for displaying important messages or notifications. It takes a title and description as parameters.

```javascript
createAlert({
  title: 'Important!',
  description: 'These patterns represent how to customize the style of the icon for your project.'
})
```

--------------------------------

### Tabler Icons Usage

Source: https://github.com/rolemodel/optics/blob/main/src/stories/Components/Icon/Icon.mdx

Provides examples of using Tabler Icons, showcasing standard icons, size modifiers, and the filled variant. It explains how to apply these classes to the `<i>` tag.

```html
<i class="icon ti ti-settings"></i>
```

```html
<i class="icon ti ti-settings icon--x-large"></i>
```

```html
<i class="icon ti ti-settings-filled"></i>
```

--------------------------------

### Customizing Tab Styles

Source: https://github.com/rolemodel/optics/blob/main/src/stories/Components/Tab/Tab.mdx

Demonstrates how to customize the Tab component's styles by overriding CSS variables. It shows an example of modifying the small tab's font and padding.

```css
.tab {
  --_op-tab-font-small: var(--op-font-2x-small);
  --_op-tab-padding-small: var(--op-space-3x-small) var(--op-space-small);
}
```

--------------------------------

### Flex Utility Classes Overview

Source: https://github.com/rolemodel/optics/blob/main/src/stories/Utilities/Flex/Flex.mdx

Provides an overview of Flex utility classes for implementing flexbox layouts. Includes links to external resources for deeper understanding of flexbox.

```javascript
import { Meta, Story, Canvas, Controls } from '@storybook/blocks'
import * as FlexStories from './Flex.stories'
import { createSourceCodeLink } from '../../helpers/sourceCodeLink.js'

<Meta of={FlexStories} />

# Flex

<div
  dangerouslySetInnerHTML={{
    __html: createSourceCodeLink({ link: 'core/utilities.css' }).outerHTML,
  }}
></div>

Flex utility classes are used to quickly lay out a page using the flex engine.

[CSS Tricks: A Guide to Flexbox](https://css-tricks.com/snippets/css/a-guide-to-flexbox/) is an excellent resource in understanding how the flexbox layout engine works

[Flexbox Froggy](https://codepip.com/games/flexbox-froggy/) is another excellent resource for practicing your Flexbox knowledge

Note: the `gap-xxs` utility in these examples is not necessary for the flex utilities to work. It is here to distinguish each item.
```

--------------------------------

### Customizing Specific Sidebar Color Styles

Source: https://github.com/rolemodel/optics/blob/main/src/stories/Components/Sidebar/Sidebar.mdx

Example of overriding CSS variables for a specific sidebar variation (e.g., '.sidebar--primary') to change background and text colors.

```css
/* This will only affect the primary sidebar, but not default */
.sidebar--primary {
  --_op-sidebar-background-color: purple;
  --_op-sidebar-text-color: purple;
}
```

--------------------------------

### Storybook Configuration

Source: https://github.com/rolemodel/optics/blob/main/src/stories/Recipes/Layout/Layout.mdx

This snippet shows the Storybook configuration for the Layout component, importing necessary modules and stories. It also includes a helper function to create links to source code.

```javascript
import { Meta, Story, Canvas, Controls } from '@storybook/blocks'
import * as LayoutStories from './Layout.stories'
import { createSourceCodeLink } from '../../helpers/sourceCodeLink.js'

<Meta of={LayoutStories} />

# Layout

<div
  dangerouslySetInnerHTML={{ __html: createSourceCodeLink({ link: 'core/layout.css' }).outerHTML }}
></div>
```

--------------------------------

### Customizing Navbar Styles

Source: https://github.com/rolemodel/optics/blob/main/src/stories/Components/Navbar/Navbar.mdx

Demonstrates how to customize Navbar styles using CSS by overriding the `--_op-navbar-*` variables. It shows examples of changing the overall navbar appearance and specific modifier styles.

```css
.navbar {
  --_op-navbar-background-color: pink;
  --_op-navbar-text-color: blue;
}

.navbar--modifier {
  --_op-navbar-brand-height: 5.4rem;
  --_op-navbar-horizontal-spacing: var(--op-space-small);
  --_op-navbar-content-item-spacing: var(--op-space-x-small);
}
```

--------------------------------

### Responsive Sidebar Implementation

Source: https://github.com/rolemodel/optics/blob/main/src/stories/Components/Sidebar/Sidebar.mdx

JavaScript code to dynamically apply sidebar styles (drawer, compact, rail) based on window width. It handles initial load and window resize events.

```javascript
const sidebarStyleOptions = {
  drawer: 'sidebar--drawer',
  compact: 'sidebar--compact',
  rail: 'sidebar--rail',
}

const getSidebarStyle = (width) => {
  let newStyle = sidebarStyleOptions['drawer']

  if (window.innerWidth <= 1024) {
    newStyle = sidebarStyleOptions['compact']
  }

  if (window.innerWidth <= 768) {
    newStyle = sidebarStyleOptions['rail']
  }

  return newStyle
}

const applySidebarStyle = (newStyle) => {
  const sidebar = document.getElementById('sidebar')
  sidebar.classList.remove(sidebarStyleOptions['drawer'])
  sidebar.classList.remove(sidebarStyleOptions['compact'])
  sidebar.classList.remove(sidebarStyleOptions['rail'])
  sidebar.classList.add(newStyle)
}

// Initial Page Load
applySidebarStyle(getSidebarStyle(window.innerWidth))

// Window Resize
window.addEventListener('resize', (event) => {
  applySidebarStyle(getSidebarStyle(window.innerWidth))
})
```

--------------------------------

### Storybook Meta Configuration

Source: https://github.com/rolemodel/optics/blob/main/src/stories/Tokens/Color/BasicColor.mdx

Configures Storybook metadata for the 'Basic Color' token documentation, specifying the title and importing necessary helper functions and components.

```javascript
import { Meta } from '@storybook/blocks'
import { createSourceCodeLink } from '../../helpers/sourceCodeLink.js'
import { DesignTokenDocBlock } from 'storybook-design-token'

<Meta title="Tokens/Color/Basic Color" />
```

--------------------------------

### Storybook Configuration for Item Width

Source: https://github.com/rolemodel/optics/blob/main/src/stories/Utilities/ItemWidth/ItemWidth.mdx

This snippet shows the Storybook configuration for the Item Width component, importing necessary modules and defining stories for different width variations. It also includes a helper function to link to the source code.

```javascript
import { Meta, Story, Canvas, Controls } from '@storybook/blocks'
import * as ItemWidthStories from './ItemWidth.stories'
import { createSourceCodeLink } from '../../helpers/sourceCodeLink.js'

<Meta of={ItemWidthStories} />

# Item Width

<div
  dangerouslySetInnerHTML={{
    __html: createSourceCodeLink({ link: 'core/utilities.css' }).outerHTML,
  }}
></div>

Item Width utility classes can be used to set an element's width relative to its parent.

## Playground

<Canvas of={ItemWidthStories.Half} />
<Controls of={ItemWidthStories.Half} />

## Half

`.half-width` This item will be half the width of its parent.

<Canvas of={ItemWidthStories.Half} />

## Full

`.full-width` This item will be the entire width of its parent.

<Canvas of={ItemWidthStories.Full} />

## One-Fifth

`.one-fifth-width` This item will be one-fifth's width of its parent.

<Canvas of={ItemWidthStories.OneFifth} />

## Two-Fifths

`.two-fifths-width` This item will be two-fifths' width of its parent.

<Canvas of={ItemWidthStories.TwoFifths} />

## Three-Fifths

`.three-fifths-width` This item will be three-fifths' width of its parent.

<Canvas of={ItemWidthStories.ThreeFifths} />

## Four-Fifths

`.four-fifths-width` This item will be four-fifths' width of its parent.

<Canvas of={ItemWidthStories.FourFifths} />

## One-Quarter

`.one-quarter-width` This item will be one-quarter's width of its parent.

<Canvas of={ItemWidthStories.OneQuarter} />

## Three-Quarters

`.three-quarters-width` This item will be three-quarters' width of its parent.

<Canvas of={ItemWidthStories.ThreeQuarters} />

## One-Third

`.one-third-width` This item will be one-third's width of its parent.

<Canvas of={ItemWidthStories.OneThird} />

## Two-Thirds

`.two-thirds-width` This item will be two-thirds' width of its parent.

<Canvas of={ItemWidthStories.TwoThirds} />
```

--------------------------------

### Storybook Meta Configuration

Source: https://github.com/rolemodel/optics/blob/main/src/stories/Tokens/Opacity.mdx

Configures Storybook metadata for the Opacity token documentation page.

```javascript
import { Meta } from '@storybook/blocks'

<Meta title="Tokens/Opacity" />
```

--------------------------------

### Switch Modifier Styling

Source: https://github.com/rolemodel/optics/blob/main/src/stories/Components/Switch/Switch.mdx

Illustrates how to apply modifier classes to alter the behavior or appearance of the Switch component. This example shows a general modifier class `.switch--modifier` for custom overrides.

```css
.switch--modifier {
}
```

--------------------------------

### Tooltip CSS Dependencies

Source: https://github.com/rolemodel/optics/blob/main/src/stories/Components/Tooltip/Tooltip.mdx

Imports necessary CSS files for the Tooltip component, including core styles and component-specific styles.

```css
@import '@rolemodel/optics/dist/css/core/fonts';
@import '@rolemodel/optics/dist/css/core/tokens';
@import '@rolemodel/optics/dist/css/core/base';

/* Component */
@import '@rolemodel/optics/dist/css/components/tooltip';
```

--------------------------------

### Storybook Canvas and Controls

Source: https://github.com/rolemodel/optics/blob/main/src/stories/Tokens/Color/ColorScale.mdx

This JSX code demonstrates how to integrate Storybook's Canvas and Controls components to create interactive examples of the color scales. It links to specific stories defined in `ColorScaleStories` for rendering and control.

```jsx
import { Canvas, Controls } from '@storybook/blocks'
import * as ColorScaleStories from './ColorScale.stories'

<Canvas of={ColorScaleStories.Primary} />
<Controls of={ColorScaleStories.Primary} />
```