This paragraph uses the light theme on brand background.
\n \n\n```\n\n### Color Schemes\n\nSpirit **color schemes** are **semantic surfaces** built from design tokens. They are not the same as the CSS [`color-scheme`][mdn-color-scheme] property\nor OS light/dark mode (`prefers-color-scheme`); they are Spiritโs own pattern for pairing foreground, background, and border colors on a subtree.\nIn practice, this means you choose one surface class and Spirit keeps text, background, and border colors in sync for that part of the UI.\n\n#### How It Works\n\n1. **Surface class** โ Put `color-scheme-on-` on a container (for example `color-scheme-on-neutral-basic`, `color-scheme-on-emotion-success-basic`,\n `color-scheme-on-accent-01-subtle`, or `color-scheme-on-disabled`). Each one sets **local** custom properties for content, border, and background (with the\n Spirit CSS variable prefix), for example `--spirit-local-color` and `--spirit-local-background-color`.\n\n โน๏ธ Every surface class also exposes both intensities of the background and content colors regardless of which variant you picked\n (`--spirit-local-background-color-basic`, `--spirit-local-background-color-subtle`, `--spirit-local-color-basic`, and `--spirit-local-color-subtle`), so a\n single surface class can color a component that combines them, for example a subtle surface carrying a basic-colored indicator. For\n `color-scheme-on-disabled`, the basic background is the disabled foreground โ the color of a filled element sitting on a disabled surface โ and its single\n content color serves as both content intensities.\n\n2. **Utilities or Components** โ On the same element (or an ancestor that already has a surface class), use utilities that read those locals: `bg-color-scheme`,\n `text-color-scheme`, and `border-color-scheme` so backgrounds, text, and borders stay on-palette without listing every token. See the [dynamic color helper demo][dynamic-color-demo] for examples.\n Or read the color scheme directly in the component CSS classes (for example `Pill`).\n\n3. **Tokens** โ Accent and emotion schemes follow the accent and emotion keys in [`spirit-design-tokens`][design-tokens-pkg]. New accents or emotions\n in tokens translate into additional `color-scheme-on-*` classes when themes are built. Fixed keys such as `neutral-*`, `selected-*`, and `disabled` are defined alongside them in the same generator.\n\n### Advanced Implementation in Product with Sass\n\nโ **Important:** Make sure you have the `sass` dependency installed in your project (`sass` is marked as optional peer dependency since you can use the pre-built distribution CSS).\nAlso [configure Sass load path][design-tokens-load-path] for `@tokens`, `@themes`, and `node_modules` so all dependencies are resolved correctly by Sass.\n\nHaving the Sass load path configured, you can import just the components you need in your Sass stylesheet:\n\n```scss\n// my-product-styles.scss\n\n// Spirit themes and foundation are mandatory\n@use 'node_modules/@alma-oss/spirit-web/scss/themes';\n@use 'node_modules/@alma-oss/spirit-web/scss/foundation';\n\n// Spirit components can be hand-picked\n@use 'node_modules/@alma-oss/spirit-web/scss/components/Button';\n\n// Spirit helpers and utilities are optional\n@use 'node_modules/@alma-oss/spirit-web/scss/helpers';\n@use 'node_modules/@alma-oss/spirit-web/scss/utilities';\n```\n\n### Usage of Mixins and Functions\n\nThe mixins and functions provided in this package are intended for internal use only.\nTheir stability is not guaranteed under semantic versioning.\nIf you choose to use them, consider copying them into your own codebase to avoid potential issues.\n\n### Custom Themes\n\n#### Automatically: Using Figma and Supernova\n\nThe recommended way to create custom themes is using Figma and Supernova to define and export your design tokens, including their themed variants.\nOnce you have your design tokens, you can [use them in your Sass project][design-tokens-usage].\n\nTo generate actual themes based on provided design tokens, just include our `themes` file in your Sass project:\n\n```scss\n@use 'node_modules/@alma-oss/spirit-web/scss/themes';\n```\n\n#### Manual Theme Creation\n\nIf you don't use Figma and Supernova or you need to theme just a small piece of your UI, you can create your own themes manually.\nJust define your theme variables so they match the structure outlined in the\n[`scss/themes/_color-tokens.scss`][design-tokens-color-tokens] file in the design tokens package.\n\nFor example:\n\n```scss\n@use '@tokens' as tokens;\n\n:root,\n.my-theme-light {\n --#{tokens.$token-prefix}color-text-primary: #007bff;\n}\n\n.my-theme-dark {\n --#{tokens.$token-prefix}color-text-primary: #beddff;\n}\n```\n\n### Prefixing CSS Class Names\n\nYou can add prefixes to CSS class names to better separate Spirit from other CSS\nin your project. The recommended way is using PostCSS with the\n[`postcss-prefix-selector`][postcss-prefix-selector] plugin:\n\n```js\n// postcss.config.js\n\nconst postcssPrefixSelector = require('postcss-prefix-selector');\n\nmodule.exports = {\n plugins: [\n postcssPrefixSelector({\n prefix: 'spirit-',\n transform(prefix, selector) {\n // Ignore interaction state classes controlled by JS: .is-* | .has-*\n const regex = /\\.(?!is-|has-)/gi;\n return selector.replaceAll(regex, `.${prefix}`);\n },\n }),\n ],\n};\n```\n\n### JavaScript\n\nSome components require JavaScript plugins for their full functionality. You can use individual modules or compiled bundle.\n\n#### Individual or Compiled\n\nPlugins can be included individually as an ECMAScript module (using `import { } from '@alma-oss/spirit-web'`, see [Using Spirit Web as a module](#using-spirit-web-as-a-module-in-browser)), or all at once using `js/{cjs|esm|bundle}/spirit-web.js` or the minified `js/{cjs|esm|bundle}/spirit-web.min.js` (do not include both), all files are UMD ready.\n\n```html\n\n```\n\nIf you use a bundler (Webpack, Rollup, โฆ), you can use `/js/*.js` files which are ECMAScript modules.\n\n#### Using Spirit Web as a Module in Browser\n\nWe provide a version of Spirit Web as `ESM` (`spirit-web.esm.js` and `spirit-web.esm.min.js`) which allows you to use Spirit Web as a module in your browser.\n\n```html\n\n```\n\n#### Data Attributes\n\nNearly all Spirit-Web plugins can be enabled and configured through HTML alone with data attributes (our preferred way of using JavaScript functionality).\nBe sure to only use one set of data attributes on a single element (e.g., you cannot trigger a tooltip and modal from the same button.).\n\nโน๏ธ For turning off this functionality just do not set the `data-spirit-toggle` attribute and use the Programmatic API.\n\n> #### Selectors\n>\n> Currently, to query DOM elements we use the native methods `querySelector` and `querySelectorAll` for performance reasons, so you have to use valid selectors.\n> If you use special selectors, for example: `collapse:Example` be sure to escape them.\n\n#### Events\n\nSpirit-Web provides custom events for most plugins' unique actions.\nGenerally, these come in an infinitive and past participle form - where the infinitive (ex. `show`) is triggered at the start of an event, and its past participle form (ex. `shown`) is triggered on the completion of an action.\n\nAll infinitive events provide [`preventDefault()`](https://developer.mozilla.org/en-US/docs/Web/API/Event/preventDefault) functionality.\nThis provides the ability to stop the execution of an action before it starts.\nReturning false from an event handler will also automatically call `preventDefault()`.\n\n```javascript\nvar myModal = document.getElementById('my-modal');\n\nmyModal.addEventListener('show.modal', function (event) {\n if (!data) {\n return event.preventDefault(); // stops modal from being shown\n }\n});\n```\n\n#### Programmatic API\n\n```javascript\nvar myModalEl = document.getElementById('my-modal');\n\nvar modal = new Modal(myModalEl); // initialized with defaults\n```\n\nIf youโd like to get a particular plugin instance, each plugin exposes a `getInstance` method.\n\n#### CSS Selectors in Constructors\n\nYou can also use a CSS selector as the first argument instead of a DOM element to initialize the plugin.\nCurrently, the element for the plugin is found by the `querySelector` method since our plugins support a single element only.\n\n```javascript\nvar modal = new Modal('#myModal');\nvar dropdown = new Dropdown('[data-spirit-toggle=\"dropdown\"]');\n```\n\n### CDN\n\nSpirit Design System is also available on CDN:\n\n| Description | URL |\n| --------------- | ------------------------------------------------------------------------------------------- |\n| CSS: Foundation | https://cdn.jsdelivr.net/npm/@alma-oss/spirit-web@latest/css/foundation.min.css |\n| CSS: Components | https://cdn.jsdelivr.net/npm/@alma-oss/spirit-web@latest/css/components.min.css |\n| CSS: Helpers | https://cdn.jsdelivr.net/npm/@alma-oss/spirit-web@latest/css/helpers.min.css |\n| CSS: Themes | https://cdn.jsdelivr.net/npm/@alma-oss/spirit-web@latest/css/themes.min.css |\n| CSS: Utilities | https://cdn.jsdelivr.net/npm/@alma-oss/spirit-web@latest/css/utilities.min.css |\n| JavaScript | https://cdn.jsdelivr.net/npm/@alma-oss/spirit-web@latest/js/bundle/spirit-web.bundle.min.js |\n\n๐ Consider using a specific version instead of `latest` in production.\n\n## Units โ `rem`\n\nSpirit primarily uses `rem` for layout-related sizing โ spacing, typography, radii, and shadows\nare expressed in `rem` relative to a **16 px** root font size. Intentional `px` exceptions exist\nfor values that must not scale with the root font size, such as border widths and\nvisually-hidden utility techniques.\n\n๐ See the [units guide][units-guide] for full details, including the SCSS\n`px-to-rem()` function available internally and how the base font size relates to design tokens.\n\n## Rebranding\n\nDesign tokens enable quick and easy rebranding of Spirit Sass components and styles.\nOnce you have created your own design tokens, just provide them to your Sass compiler and you are ready to go!\nLearn more in the [`spirit-design-tokens` docs][design-tokens-rebranding].\n\n## Development\n\nStart local development server with `yarn start` to get started. You will get the live preview of all components and plugins in your browser. Just get dirty and change something and you will see the changes live.\n\nThe dev-stack is based on [Vite][vite].\n\n## Deprecations\n\nThis package uses the deprecation warnings for props, functions and components that will be removed or replaced in the next major release.\nCheck your browser console to see if you are using any of the deprecated functionality.\n\n![Deprecations in the Browser's console][deprecations]\n\n๐ [See a DEPRECATIONS file][all-deprecations] for a list of all deprecations.\n\n## Feature Flags\n\n๐ See [Feature Flags documentation][feature-flags-docs] for how to use them.\n\n## Examples\n\n๐ See [examples][examples] for a live demo.\n\n## License\n\nSee the [LICENSE][license] file for information.\n\n[all-deprecations]: https://github.com/alma-oss/spirit-design-system/tree/main/packages/web/DEPRECATIONS.md\n[deprecations]: https://github.com/alma-oss/spirit-design-system/blob/main/static/deprecations-browser-console.png?raw=true\n[design-tokens-usage]: https://github.com/alma-oss/spirit-design-system/tree/main/packages/design-tokens#basic-usage\n[design-tokens-load-path]: https://github.com/alma-oss/spirit-design-system/tree/main/packages/design-tokens#in-sass\n[design-tokens-color-tokens]: https://github.com/alma-oss/spirit-design-system/blob/main/packages/design-tokens/src/scss/themes/_color-tokens.scss\n[design-tokens-rebranding]: https://github.com/alma-oss/spirit-design-system/tree/main/packages/design-tokens#rebranding-spirit\n[design-tokens-pkg]: https://github.com/alma-oss/spirit-design-system/tree/main/packages/design-tokens\n[dynamic-color-demo]: https://github.com/alma-oss/spirit-design-system/blob/main/packages/web/src/scss/helpers/dynamic-color/index.html\n[examples]: https://spirit-design-system.netlify.app/packages/web/\n[feature-flags-docs]: https://github.com/alma-oss/spirit-design-system/blob/main/docs/contribution/feature-flags.md\n[license]: https://github.com/alma-oss/spirit-design-system/blob/main/packages/web/LICENSE.md\n[mdn-color-scheme]: https://developer.mozilla.org/en-US/docs/Web/CSS/color-scheme\n[postcss-prefix-selector]: https://www.npmjs.com/package/postcss-prefix-selector\n[units-guide]: https://github.com/alma-oss/spirit-design-system/tree/main/docs/contribution/units.md\n[vite]: https://vitejs.dev\n","readmeFilename":"README.md"}