import { Meta } from '@storybook/blocks';

<Meta title="Introduction/Styling" />

# Styling

This page describes how styling works in Spirit Web React, including how to customize spacing, sizing, and positioning,
and how to create your own custom components using Spirit styles.

## Introduction

Spirit components are designed to be consistent across all LMC applications. They include built-in styling that has been
considered carefully, and extensively tested. In general, customizing Spirit design is discouraged, but most components
do offer control over layout and other aspects. In addition, you can use Spirit defined design tokens to ensure your
application conforms to design requirements, and is adaptive across platform scales and color schemes.

## Style props

**Will be implemented soon**

All Spirit Web React components support a limited set of styling options, including layout, spacing, sizing, and
positioning options. While internal component styles such as padding, colors, borders and text styles are included
in Spirit and not available to override, external styles like margins and sizes can be set on all components.

Supported styling options are available as props on every Spirit Web React component.

**Will be implemented soon**

## Escape hatches

While we encourage teams to utilize Spirit design as it is, we do realize that sometimes product specific customizations
may be needed. In these cases, we encourage you or your designers to **talk to us**. We may be able to suggest
an alternative implementation strategy, or perhaps your design can help inform future Spirit additions.

While the traditional className and style props are not supported in Spirit Web React components, there are two escape
hatches that you can **use at your own risk**. These are UNSAFE_className and UNSAFE_style. Use of these props should be
considered **a last resort**. They can be used to work around bugs or limitations in Spirit Web React, but should
not be used in the long term.

The reasoning behind this is that future updates to Spirit design may cause unintended breaking changes in products.
If the internal DOM structure or CSS properties of a Spirit Web React component change, this may lead to conflicts
with CSS overrides in products. For this reason, className and style are unsafe, and if you use them know that you
are doing so at your own risk.
