# Optics Design System

> Optics is a pure-CSS design system by RoleModel Software (npm: `@rolemodel/optics`, v2.4.0). It provides design tokens (CSS custom properties prefixed `--op-`), base styles, utilities, and BEM-style components (`.btn`, `.card`, ...) that are customized per project via token overrides.

Every page below is plain markdown. Component pages include the actual HTML markup for each variant, the component's CSS variable API, and customization patterns. The full documentation in one file: [llms-full.txt](https://docs.optics.rolemodel.design/llms-full.txt). All design tokens as JSON: https://unpkg.com/@rolemodel/optics/dist/tokens/tokens.json

## Introduction

- [Introduction](https://docs.optics.rolemodel.design/llms/introduction.md): Optics embodies the RoleModel ethos of deep collaboration, uniting our team's diverse expertise with the shared goal of crafting excellent design solutions a...

## Overview

- [Overview/Addons](https://docs.optics.rolemodel.design/llms/overview-addons.md): Optics provides a few addons for integrating Third-Party tools with your application.
- [Overview/Base Reset](https://docs.optics.rolemodel.design/llms/overview-base-reset.md): All browsers ship with some default styles. These styles are inconsistent across browsers and can cause issues when building a UI. To ensure consistency acro...
- [Overview/File Organization](https://docs.optics.rolemodel.design/llms/overview-file-organization.md): As you use Optics, you will likely want to organize your Optics configuration into multiple files.
- [Overview/Scale Overriding](https://docs.optics.rolemodel.design/llms/overview-scale-overriding.md): There are multiple scales in Optics. Unit Scales exist to allow adjusting font and spacing values. Color Scales exist to provide semantically named color var...
- [Overview/Selective Imports](https://docs.optics.rolemodel.design/llms/overview-selective-imports.md): By default, when you import the design system, it will include the basics. CSS reset, All Tokens, Base styles, Utilities, and all Components.
- [Overview/Themes](https://docs.optics.rolemodel.design/llms/overview-themes.md): Optics defines a default theme along with it's dark mode. If you import the design system, it will be used automatically.
- [Overview/Tokens](https://docs.optics.rolemodel.design/llms/overview-tokens.md): Tokens are defined in `src/core/tokens`

## Tokens

- [Tokens/Animation](https://docs.optics.rolemodel.design/llms/tokens-animation.md): Animation and Transition tokens can be used for element transitions or animations.
- [Tokens/Border/Border Radius](https://docs.optics.rolemodel.design/llms/tokens-border-border-radius.md): Border radius tokens can be used to round corners on various elements.
- [Tokens/Border/Border Stroke](https://docs.optics.rolemodel.design/llms/tokens-border-border-stroke.md): Border tokens can be used as box shadows to add borders to various elements. Box Shadows are used in order to provide border styling without affecting the si...
- [Tokens/Border/Border Width](https://docs.optics.rolemodel.design/llms/tokens-border-border-width.md): Border width tokens can be used to define a border width or a box shadow width.
- [Tokens/Breakpoint](https://docs.optics.rolemodel.design/llms/tokens-breakpoint.md): Breakpoint tokens are used to define common device sizes for use within media queries or max widths.
- [Tokens/Color/Basic Color](https://docs.optics.rolemodel.design/llms/tokens-color-basic-color.md): Basic color tokens can be used to define exact colors.
- [Tokens/Color/Border Color](https://docs.optics.rolemodel.design/llms/tokens-color-border-color.md): Border color tokens can be used to define the color of borders and box shadows.
- [Tokens/Color/Color Scale](https://docs.optics.rolemodel.design/llms/tokens-color-color-scale.md): Optics has five main color scales that provide all the color your application may need. These Consist of the `Primary` scale, the `Neutral` scale, and four A...
- [Tokens/Color/Color with Alpha](https://docs.optics.rolemodel.design/llms/tokens-color-color-with-alpha.md): There may be a case where you need to use the alpha channel in a color. This can be useful for creating more opaque or transparent looks built directly into ...
- [Tokens/Encoded Image](https://docs.optics.rolemodel.design/llms/tokens-encoded-image.md): Encoded Image tokens are primarily used to create the dropdown arrow on `<select>` elements using the `.form-control` class.
- [Tokens/Input/Input Focus](https://docs.optics.rolemodel.design/llms/tokens-input-input-focus.md): Input Focus tokens are used to define a button or form controls focus state.
- [Tokens/Input/Input Height](https://docs.optics.rolemodel.design/llms/tokens-input-input-height.md): Input Height tokens are used to define a button or form controls height.
- [Tokens/Opacity](https://docs.optics.rolemodel.design/llms/tokens-opacity.md): Opacity tokens can be used to create a faded or disabled effect on any element.
- [Tokens/Shadow](https://docs.optics.rolemodel.design/llms/tokens-shadow.md): Shadow tokens can be used to create an elevation effect on any element. There are also [Card classes](components-card.md#shadow) to create an elevated card e...
- [Tokens/Sizing](https://docs.optics.rolemodel.design/llms/tokens-sizing.md): The Size token enables creating scalable widths (inline-size) and heights (block-size) for your application. It is meant to be used in a `calc` expression wi...
- [Tokens/Spacing](https://docs.optics.rolemodel.design/llms/tokens-spacing.md): The Spacing Size tokens enable creating scalable spaces for your application. They can be used for margin, padding, gap, and anything else that is intended f...
- [Tokens/Typography/Font Family](https://docs.optics.rolemodel.design/llms/tokens-typography-font-family.md): Font Family tokens can be used to change the font used when displaying text.
- [Tokens/Typography/Font Size](https://docs.optics.rolemodel.design/llms/tokens-typography-font-size.md): Font Size tokens can be used to change the size of text.
- [Tokens/Typography/Font Weight](https://docs.optics.rolemodel.design/llms/tokens-typography-font-weight.md): Font Weight tokens can be used to change the font weight of text.
- [Tokens/Typography/Letter Spacing](https://docs.optics.rolemodel.design/llms/tokens-typography-letter-spacing.md): Letter Spacing tokens can be used to change the space between letters of text.
- [Tokens/Typography/Line Height](https://docs.optics.rolemodel.design/llms/tokens-typography-line-height.md): Line height tokens can be used to change the line height of text.
- [Tokens/Z-Index](https://docs.optics.rolemodel.design/llms/tokens-z-index.md): Z-Index tokens can be used to define the page z-index of an element.

## Utilities

- [Utilities/Advanced/Cluster](https://docs.optics.rolemodel.design/llms/utilities-advanced-cluster.md): The cluster utility provides a simple way to create a wrapping, group of spaced items. It works with all of the gap and other flex utilities. It is effective...
- [Utilities/Advanced/Flank](https://docs.optics.rolemodel.design/llms/utilities-advanced-flank.md): The flank utility provides a simple way to create a horizontal row with an item flanked by another large item. It works with all of the gap and other flex ut...
- [Utilities/Advanced/Frame](https://docs.optics.rolemodel.design/llms/utilities-advanced-frame.md): The frame utility provides a simple way to constrain content to a consistent aspect ratio. It centers its content and clips any overflow, so whatever it wrap...
- [Utilities/Advanced/Grid](https://docs.optics.rolemodel.design/llms/utilities-advanced-grid.md): The grid utility provides a simple way to create a dynamic grid layout. It is primarily intended for simple layouts with a minimum column size, or evenly div...
- [Utilities/Advanced/Split](https://docs.optics.rolemodel.design/llms/utilities-advanced-split.md): The split utility provides a simple way to push two items apart from each other. It is effectively equivalent to using `.flex .flex-wrap .items-center .justi...
- [Utilities/Advanced/Stack](https://docs.optics.rolemodel.design/llms/utilities-advanced-stack.md): The stack utility provides a simple way to create a vertical stack of spaced items. It works with all of the gap and other flex utilities. It is effectively ...
- [Utilities/Container](https://docs.optics.rolemodel.design/llms/utilities-container.md): Container utility classes are used to create a centered content area for your application.
- [Utilities/Flex](https://docs.optics.rolemodel.design/llms/utilities-flex.md): Flex utility classes are used to quickly lay out a page using the flex engine.
- [Utilities/Gap](https://docs.optics.rolemodel.design/llms/utilities-gap.md): Gap utility classes can be used to set the spacing between items within a flex or grid container.
- [Utilities/Introduction](https://docs.optics.rolemodel.design/llms/utilities-introduction.md): Utility classes are CSS classes scoped to a simple style property like flex or gap or a collection of related properties. They can be combined together to qu...
- [Utilities/Item Width](https://docs.optics.rolemodel.design/llms/utilities-item-width.md): Item Width utility classes can be used to set an element's width relative to its parent.
- [Utilities/Margin](https://docs.optics.rolemodel.design/llms/utilities-margin.md): Margin utility classes are used to add margin to an element.
- [Utilities/Text Alignment](https://docs.optics.rolemodel.design/llms/utilities-text-alignment.md): Text Alignment utility classes can be used to align text in an element.
- [Utilities/Visibility](https://docs.optics.rolemodel.design/llms/utilities-visibility.md): Use the '.sr-only' class to hide accessibility text that is needed for screenreaders but needs to be hidden from regular users. [Read more here.](https://sno...

## Components

- [Components/Accordion](https://docs.optics.rolemodel.design/llms/components-accordion.md): Accordion classes are built on the `details` and `summary` html elements. They provide consistent and composable styling for disclosure widgets.
- [Components/Alert](https://docs.optics.rolemodel.design/llms/components-alert.md): Alert classes can be used to create a highlighted message or callout in your application. These could be as banners for global application messages, or an er...
- [Components/Avatar](https://docs.optics.rolemodel.design/llms/components-avatar.md): Avatar classes can be used on `a` or `div` html elements with an `img` within it. They provide consistent and composable styling for application avatars or p...
- [Components/Badge](https://docs.optics.rolemodel.design/llms/components-badge.md): The Badge component is similar to the Tag component, however it has a different semantic purpose. Badge is intended to be used for notification and informati...
- [Components/Breadcrumbs](https://docs.optics.rolemodel.design/llms/components-breadcrumbs.md): The breadcrumbs component is used to show the user's current location in a hierarchy of pages.
- [Components/Button](https://docs.optics.rolemodel.design/llms/components-button.md): Button classes can be used on `button` or `a` html elements. They provide consistent and composable styling that should address most applications basic needs.
- [Components/ButtonGroup](https://docs.optics.rolemodel.design/llms/components-buttongroup.md): Button Group is similar to the Segmented Control component, however it has a different semantic purpose. Button Group is intended to be used for grouping rel...
- [Components/Card](https://docs.optics.rolemodel.design/llms/components-card.md): Card classes can be used to denote bordered sections of an application. They provide simple styles to create sections or "cards" for your interface. They can...
- [Components/Confirm Dialog](https://docs.optics.rolemodel.design/llms/components-confirm-dialog.md): The Confirm Dialog classes can be used for styling a custom alert or confirm dialog. This can be used alongside [Turbo Confirm](https://github.com/RoleModel/...
- [Components/Content Header](https://docs.optics.rolemodel.design/llms/components-content-header.md): Content Header classes can be used to denote a page or content section header of an application. They provide simple styles to provide context and actions fo...
- [Components/Divider](https://docs.optics.rolemodel.design/llms/components-divider.md): Divider classes can be used to create horizontal or vertical visual divides between content.
- [Components/Form](https://docs.optics.rolemodel.design/llms/components-form.md): Form classes can be used on a variety of `inputs` or `select` HTML elements. They provide consistent and composable styling that should address most applicat...
- [Components/Icon](https://docs.optics.rolemodel.design/llms/components-icon.md): Icon classes are built on top of [Google's Material Symbols Icon Font](https://fonts.google.com/icons). They provide a way to integrate iconography into your...
- [Components/Modal](https://docs.optics.rolemodel.design/llms/components-modal.md): The Modal classes can be used for styling a custom modal. This can be used alongside the Rails configuration and Javascript implemented by [RoleModel Rails M...
- [Components/Navbar](https://docs.optics.rolemodel.design/llms/components-navbar.md): Navbar classes provide simple styling for a navigation header.
- [Components/Pagination](https://docs.optics.rolemodel.design/llms/components-pagination.md): Pagination is used to navigate through a series of pages, typically when dealing with tabular data. A few classes are used in combination with the button com...
- [Components/Segmented Control](https://docs.optics.rolemodel.design/llms/components-segmented-control.md): Segmented Control classes can be used to create a stylized radio select group.
- [Components/Sidebar](https://docs.optics.rolemodel.design/llms/components-sidebar.md): Sidebar classes provide simple styling for a navigation sidebar drawer, compact, or rail.
- [Components/SidePanel](https://docs.optics.rolemodel.design/llms/components-sidepanel.md): Side Panel classes provide simple styling for a panel of sections with a scrollable body.
- [Components/Spinner](https://docs.optics.rolemodel.design/llms/components-spinner.md): Spinners are CSS loading indicators that should be shown when retrieving data or performing slow computations.
- [Components/Switch](https://docs.optics.rolemodel.design/llms/components-switch.md): Switch classes can be used to create a stylized checkbox or boolean input.
- [Components/Tab](https://docs.optics.rolemodel.design/llms/components-tab.md): Tab classes provide simple styling for a tab group navigation.
- [Components/Table](https://docs.optics.rolemodel.design/llms/components-table.md): Table classes provide simple styling for tables and their content.
- [Components/Tag](https://docs.optics.rolemodel.design/llms/components-tag.md): The tag component can be applied to an element with a button within it. The Tag component is similar to the Badge component, however it has a different seman...
- [Components/Text Pair](https://docs.optics.rolemodel.design/llms/components-text-pair.md): The Text Pair component is used to display a title and subtitle together. It can also be used to group other elements within it, though should generally be r...
- [Components/Tooltip](https://docs.optics.rolemodel.design/llms/components-tooltip.md): Tooltips are build using data attributes on any element. Setting these will show text on hover.

## Recipes

- [Recipes/Aligned Header](https://docs.optics.rolemodel.design/llms/recipes-aligned-header.md): There are cases when you want to vertically center something on a line of text that wraps. Like a badge or edit button at the end of a text header. Achieving...
- [Recipes/Custom Sidebar](https://docs.optics.rolemodel.design/llms/recipes-custom-sidebar.md): Your app may want to customize the sidebar to change the look and feel. Here are a few examples to help you get started:
- [Recipes/Layout](https://docs.optics.rolemodel.design/llms/recipes-layout.md): Optics provides two patterns for application layout. The basic (legacy) version is maintained for backwards compatibility, but all new projects should use th...