### Install Atomium Tokens

Source: https://github.com/juntossomosmais/atomium/blob/main/packages/tokens/README.md

Install the Atomium tokens package using npm.

```bash
npm i @juntossomosmais/atomium-tokens
```

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

### Install Dependencies and Build

Source: https://github.com/juntossomosmais/atomium/blob/main/README.md

Install project dependencies using npm and then build the project. If dependency resolution issues arise, try the `--legacy-peer-deps` flag.

```sh
npm i
npm run build
```

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

### Install Atomium NPM Packages

Source: https://context7.com/juntossomosmais/atomium/llms.txt

Install the core Atomium Web Components and optionally the design tokens package using npm.

```bash
npm i @juntossomosmais/atomium
npm i @juntossomosmais/atomium-tokens   # optional, for design tokens
```

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

### Run React Stories Locally

Source: https://github.com/juntossomosmais/atomium/blob/main/README.md

Before running `npm start`, execute this command to set up and run React Stories locally. This is necessary for developing React-specific components.

```sh
npm run docs-react:start
```

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

### Install Atomium Package

Source: https://github.com/juntossomosmais/atomium/blob/main/packages/react/README.md

Install the Atomium package using npm. This command adds the necessary libraries to your project for using Atomium components.

```bash
npm i @juntossomosmais/atomium
```

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

### Implement a Multi-Step Wizard with atom-steps-modal

Source: https://context7.com/juntossomosmais/atomium/llms.txt

This example shows how to set up a wizard-style modal with multiple steps, custom titles, and navigation button texts. It also demonstrates listening for step navigation and completion events.

```html
<atom-button id="wizard-trigger" color="primary">Start Wizard</atom-button>

<atom-steps-modal
  id="wizard"
  trigger="wizard-trigger"
  steps="3"
  steps-titles="Personal Info,Address,Review"
  primary-button-texts-by-step="Next,Next,Finish"
  secondary-button-texts-by-step="Cancel,Back,Back"
  close-on-finish="true"
>
  <div slot="step-1">
    <atom-input label="Full Name" placeholder="John Doe"></atom-input>
    <atom-input label="Email" type="email"></atom-input>
  </div>
  <div slot="step-2">
    <atom-input label="Street" placeholder="123 Main St"></atom-input>
    <atom-input label="City"></atom-input>
  </div>
  <div slot="step-3">
    <p>Please review your details before submitting.</p>
  </div>
</atom-steps-modal>

<script>
  const wizard = document.getElementById('wizard')

  wizard.addEventListener('atomNextStep', (e) => console.log('Moved to step:', e.detail))
  wizard.addEventListener('atomPreviousStep', (e) => console.log('Back to step:', e.detail))
  wizard.addEventListener('atomFinish', () => console.log('Wizard completed!'))
  wizard.addEventListener('atomCancel', () => console.log('Wizard cancelled'))
</script>
```

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

### Run Vue Stories Locally

Source: https://github.com/juntossomosmais/atomium/blob/main/README.md

Before running `npm start`, execute this command to set up and run Vue Stories locally. This is necessary for developing Vue-specific components.

```sh
npm run docs-vue:start
```

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

### Run Storybook and Stencil

Source: https://github.com/juntossomosmais/atomium/blob/main/README.md

Start the development server for Storybook and Stencil. This command allows for interactive component development and testing.

```sh
npm start
```

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

### Atom Input Component Examples

Source: https://context7.com/juntossomosmais/atomium/llms.txt

Illustrates the usage of the atom-input component with various configurations like labels, helper text, error states, icons, password toggles, and counters. Event listeners for 'atomChange' and 'atomInput' are shown, along with programmatic control via methods like setFocus().

```html
<atom-input
  id="email-input"
  label="Email address"
  type="email"
  placeholder="user@example.com"
  helper-text="We'll never share your email."
  error-text="Invalid email format"
  icon="mail-outline"
  required="true"
  maxlength="100"
  counter="true"
></atom-input>

<atom-input
  id="pwd-input"
  label="Password"
  type="password"
  password-toggle="true"
  label-placement="floating"
></atom-input>

```

```javascript
<script>
  const emailInput = document.getElementById('email-input')

  // Listen to value changes (fires on commit / blur)
  emailInput.addEventListener('atomChange', (e) => {
    console.log('New value:', e.detail) // string
  })

  // Listen to every keystroke
  emailInput.addEventListener('atomInput', (e) => {
    console.log('Input event:', e.detail)
  })

  // Show error state programmatically
  emailInput.hasError = true

  // Programmatically focus the input
  emailInput.setFocus()

  // Get the underlying <input> element
  emailInput.getInputElement().then(el => el.select())
</script>

```

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

### Atom Button Component Examples

Source: https://context7.com/juntossomosmais/atomium/llms.txt

Demonstrates various configurations for the atom-button component, including solid, outline, loading states, icon buttons, link behavior, and custom colors. Listen to click events using addEventListener.

```html
<!-- Solid primary button (default) -->
<atom-button color="primary" fill="solid" size="default">Submit</atom-button>

<!-- Outline secondary button, full-width -->
<atom-button color="secondary" fill="outline" expand="block">Cancel</atom-button>

<!-- Loading state (shows spinner, disables interaction) -->
<atom-button color="primary" loading="true">Saving...</atom-button>

<!-- Circle icon button -->
<atom-button color="secondary" fill="clear" shape="circle" aria-label="Close">
  <atom-icon icon="close"></atom-icon>
</atom-button>

<!-- Link button (renders as <a>) -->
<atom-button color="primary" href="https://example.com" target="_blank">
  Open Link
</atom-button>

<!-- Custom color via CSS variables -->
<style>
  atom-button.custom-btn {
    --atom-button-color: #9b59b6;
    --atom-button-color-contrast: #ffffff;
  }
</style>
<atom-button color="custom" class="custom-btn">Custom Color</atom-button>

```

```javascript
<script>
  // Listen to click events
  document.querySelector('atom-button').addEventListener('click', (e) => {
    console.log('Button clicked', e.detail)
  })
</script>

```

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

### Vue Setup with Atomium

Source: https://context7.com/juntossomosmais/atomium/llms.txt

Register Atomium as a Vue plugin in your main.js or main.ts file. The ComponentLibrary.install() call registers all custom elements with proper event name kebab-casing for Vue's event system.

```javascript
// main.js
import { createApp } from 'vue'
import { ComponentLibrary } from '@juntossomosmais/atomium/vue'
import '@juntossomosmais/atomium/core.css'
import App from './App.vue'

const app = createApp(App)
app.use(ComponentLibrary)
app.mount('#app')

```

```html
<!-- MyComponent.vue -->
<template>
  <atom-input
    label="Search"
    placeholder="Type to search..."
    :value="query"
    @atom-change="query = $event.detail"
  />
  <atom-button color="secondary" fill="outline" @click="search">
    Search
  </atom-button>
  <atom-badge type="primary">{{ resultCount }}</atom-badge>
</template>

<script setup>
import { ref } from 'vue'
const query = ref('')
const resultCount = ref(0)
function search() { /* ... */ }
</script>

```

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

### Configure NPM for GitHub Packages

Source: https://context7.com/juntossomosmais/atomium/llms.txt

Configure your .npmrc file to authenticate with GitHub Packages for private package installation.

```bash
@juntossomosmais:registry=https://npm.pkg.github.com
//npm.pkg.github.com/:_authToken=<your-github-token>
```

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

### Register ComponentLibrary Globally (main.js)

Source: https://github.com/juntossomosmais/atomium/blob/main/packages/vue/README.md

Import and install the ComponentLibrary globally in your Vue application's main.js file. Ensure core CSS is also imported.

```javascript
import { ComponentLibrary } from '@juntossomosmais/atomium/vue'

import '@juntossomosmais/atomium/core.css'

ComponentLibrary.install()
```

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

### atom-steps-modal Component

Source: https://context7.com/juntossomosmais/atomium/llms.txt

A wizard-style multi-step modal that wraps `atom-modal`, featuring navigation buttons and a progress bar for a guided user experience.

```APIDOC
## atom-steps-modal Component

A wizard-style multi-step modal that wraps `atom-modal`. Steps are controlled by navigation buttons (Next/Previous/Cancel/Finish), with a built-in progress bar. Content for each step is placed in named slots (`step-1`, `step-2`, …).

### Props:
`steps`, `stepsTitles` (comma-separated), `currentStep`, `trigger`, `isOpen`, `primaryButtonTextsByStep` (comma-separated), `secondaryButtonTextsByStep` (comma-separated), `closeOnFinish`, `lockedInitialStep`, `disablePrimaryButton`, `disableSecondaryButton`, `metaData`.

### Events:
`atomNextStep`, `atomPreviousStep`, `atomFinish`, `atomCancel`, `atomCloseClick`, `atomDidPresent`, `atomDidDismiss`, `atomIsOpenChange`.

### Example Usage:
```html
<atom-button id="wizard-trigger" color="primary">Start Wizard</atom-button>

<atom-steps-modal
  id="wizard"
  trigger="wizard-trigger"
  steps="3"
  steps-titles="Personal Info,Address,Review"
  primary-button-texts-by-step="Next,Next,Finish"
  secondary-button-texts-by-step="Cancel,Back,Back"
  close-on-finish="true"
>
  <div slot="step-1">
    <atom-input label="Full Name" placeholder="John Doe"></atom-input>
    <atom-input label="Email" type="email"></atom-input>
  </div>
  <div slot="step-2">
    <atom-input label="Street" placeholder="123 Main St"></atom-input>
    <atom-input label="City"></atom-input>
  </div>
  <div slot="step-3">
    <p>Please review your details before submitting.</p>
  </div>
</atom-steps-modal>

<script>
  const wizard = document.getElementById('wizard')

  wizard.addEventListener('atomNextStep', (e) => console.log('Moved to step:', e.detail))
  wizard.addEventListener('atomPreviousStep', (e) => console.log('Back to step:', e.detail))
  wizard.addEventListener('atomFinish', () => console.log('Wizard completed!'))
  wizard.addEventListener('atomCancel', () => console.log('Wizard cancelled'))
</script>
```
```

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

### Atom Datetime Component Examples

Source: https://context7.com/juntossomosmais/atomium/llms.txt

The atom-datetime component is a versatile date/time picker. Examples demonstrate inline date selection, button-triggered date range selection, and time-only selection. Event listeners are included for capturing user selections.

```html
<!-- Inline date picker -->
<atom-datetime
  id="event-date"
  label="Event Date"
  presentation="date"
  locale="en-US"
  min="2024-01-01"
  max="2025-12-31"
></atom-datetime>
```

```html
<!-- Date range picker (button-triggered popover) -->
<atom-datetime
  id="date-range"
  label="Travel Dates"
  presentation="date"
  range-mode="true"
  use-button="true"
  show-clear-button="true"
  show-default-buttons="true"
></atom-datetime>
```

```html
<!-- Time-only picker -->
<atom-datetime
  id="meeting-time"
  presentation="time"
  use-button="true"
  hour-cycle="h23"
  value="14:30"
></atom-datetime>
```

```javascript
document.getElementById('event-date').addEventListener('atomChange', (e) => {
  // Single mode: string like "2024-06-15"
  // Range mode: string[] with all dates in range
  // Multiple mode: string[]
  console.log('Selected date:', e.detail)
})
```

```javascript
document.getElementById('date-range').addEventListener('atomChange', (e) => {
  console.log('Date range:', e.detail) // ["2024-06-01", "2024-06-02", ..., "2024-06-07"]
})
```

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

### Atom Grid and Column Layout System

Source: https://context7.com/juntossomosmais/atomium/llms.txt

The atom-grid and atom-col components provide a responsive 16-column grid system. Examples show a two-column desktop layout and a three-column layout with an offset.

```html
<atom-grid fixed="true">
  <!-- Two-column layout on desktop, full-width on mobile -->
  <ion-row>
    <atom-col size="16" size-md="8">
      <div class="card">Main Content</div>
    </atom-col>
    <atom-col size="16" size-md="8">
      <div class="card">Sidebar</div>
    </atom-col>
  </ion-row>

  <!-- Three-column layout with offset -->
  <ion-row>
    <atom-col size="4">Col 1</atom-col>
    <atom-col size="4" offset="4">Col 2 (offset by 4)</atom-col>
    <atom-col size="4">Col 3</atom-col>
  </ion-row>
</atom-grid>
```

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

### JSX Boolean Prop Example

Source: https://github.com/juntossomosmais/atomium/blob/main/apps/docs/stories/architecture-decision-records/0010-why-do-we-need-react-fix.mdx

Illustrates how React renders a boolean prop as an attribute, deviating from the HTML spec.

```jsx
<AtomButton disabled={false} />
```

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

### Atom Link Component Examples

Source: https://context7.com/juntossomosmais/atomium/llms.txt

The atom-link component provides styled hyperlinks or button-style links. It supports loading states and size variants. An event listener is shown for a button-style link.

```html
<!-- Anchor-style link -->
<atom-link color="secondary" size="medium">Read the documentation</atom-link>
```

```html
<!-- Button-style link (rendered as <button>) with click handler -->
<atom-link id="go-back" type="button" color="primary" size="large">
  Go back
</atom-link>
```

```html
<!-- Loading state -->
<atom-link type="button" loading="true" size="small">Processing...</atom-link>
```

```javascript
document.getElementById('go-back').addEventListener('click', () => {
  history.back()
})
```

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

### Build Libraries and Storybook

Source: https://github.com/juntossomosmais/atomium/blob/main/README.md

Build the project libraries and the Storybook documentation. Use `npm run build` for libraries and `npm run docs:build` for Storybook.

```sh
## Build Libs
npm run build

## Build Storybook
npm run docs:build
```

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

### Build Atomium Libraries for Alpha Release

Source: https://github.com/juntossomosmais/atomium/blob/main/README.md

Run this command in the root directory to build Atomium libraries for publishing alpha versions.

```bash
npx nx run @juntossomosmais/atomium:publish-library-alpha
```

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

### Build Atomium Libraries for NPM Link

Source: https://github.com/juntossomosmais/atomium/blob/main/README.md

Execute this command in the root directory to build Atomium libraries before linking them.

```bash
npm run build
```

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

### Letter Spacing Variable Usage

Source: https://github.com/juntossomosmais/atomium/blob/main/packages/tokens/stories/3_Typography.mdx

Explains how to use letter spacing variables, which are combined with the font size. For example, `--title-giant-letter` includes both font and letter spacing.

```html
#### !important

We have variables to `font` and `letter spacing`, so you just need to use on `font` and `letter-spacing` property.

All the `letter-spacing` variable is the font + letter, example: `var(--title-giant-letter)`
```

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

### Configure atom-carousel with navigation and pagination

Source: https://context7.com/juntossomosmais/atomium/llms.txt

Set up a carousel with options for looping, autoplay, and both arrow navigation and dot pagination. The 'thumbnails' prop can be used for thumbnail navigation.

```html
<atom-carousel
  id="product-carousel"
  loop="true"
  autoplay="3000"
  has-navigation="true"
  has-pagination="true"
>
  <atom-carousel-item>
    <img src="/images/slide1.jpg" alt="Slide 1" />
  </atom-carousel-item>
  <atom-carousel-item>
    <img src="/images/slide2.jpg" alt="Slide 2" />
  </atom-carousel-item>
  <atom-carousel-item>
    <img src="/images/slide3.jpg" alt="Slide 3" />
  </atom-carousel-item>
</atom-carousel>

<!-- Carousel with thumbnail navigation -->
<atom-carousel
  has-navigation="true"
  has-pagination="true"
  thumbnails='["/images/slide1.jpg","/images/slide2.jpg","/images/slide3.jpg"]'
>
  <atom-carousel-item><img src="/images/slide1.jpg" alt="1" /></atom-carousel-item>
  <atom-carousel-item><img src="/images/slide2.jpg" alt="2" /></atom-carousel-item>
  <atom-carousel-item><img src="/images/slide3.jpg" alt="3" /></atom-carousel-item>
</atom-carousel>

<script>
  // Listen for slide transitions
  window.addEventListener('transitionend', (e) => {
    console.log('Current slide index:', e.detail.currentIndex)
  })
</script>
```

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

### Import Atomium into Project via NPM Link

Source: https://github.com/juntossomosmais/atomium/blob/main/README.md

In your project's directory, run this command to link the globally linked Atomium libraries.

```bash
npm link @juntossomosmais/atomium
```

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

### Link Atomium Libraries Locally

Source: https://github.com/juntossomosmais/atomium/blob/main/README.md

Navigate to the Atomium node_modules directory and run this command to globally link the libraries.

```bash
cd node_modules/@juntossomosmais/atomium
npm link
```

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

### Import JSON Tokens

Source: https://context7.com/juntossomosmais/atomium/llms.txt

Import the JSON tokens file for use in Stylelint configurations or build-time validation.

```javascript
import tokens from '@juntossomosmais/atomium-tokens/tokens.json'

// Use for Stylelint config, build-time token validation, etc.
console.log(tokens['color-brand-primary-regular']) // '#ed6700'
```

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

### Run Tests

Source: https://github.com/juntossomosmais/atomium/blob/main/README.md

Execute all project tests using npm. This command runs the test suite to ensure code quality and functionality.

```sh
npm test
```

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

### Initialize and Control atom-stepper

Source: https://context7.com/juntossomosmais/atomium/llms.txt

Configure the steps and programmatically control the active step of the stepper component. Ensure the 'steps' array is populated before setting 'activeStep'.

```html
<atom-stepper
  id="checkout-stepper"
  active-step="1"
  step-title="Step"
></atom-stepper>

<script>
  const stepper = document.getElementById('checkout-stepper')

  stepper.steps = [
    { title: 'Cart', completed: true },
    { title: 'Shipping', completed: false },
    { title: 'Payment', completed: false },
    { title: 'Confirmation', completed: false },
  ]

  // Move to step index 2
  stepper.activeStep = 2
</script>
```

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

### atom-grid / atom-col Layout System

Source: https://context7.com/juntossomosmais/atomium/llms.txt

A 16-column responsive grid system with breakpoint-aware column sizing and offset/push/pull support.

```APIDOC
## `atom-grid` / `atom-col` Layout System

A 16-column responsive grid built on top of Ionic's grid, with breakpoint-aware column sizing (`size`, `sizeSm`, `sizeMd`, `sizeLg`) and offset/push/pull support.

```html
<atom-grid fixed="true">
  <!-- Two-column layout on desktop, full-width on mobile -->
  <ion-row>
    <atom-col size="16" size-md="8">
      <div class="card">Main Content</div>
    </atom-col>
    <atom-col size="16" size-md="8">
      <div class="card">Sidebar</div>
    </atom-col>
  </ion-row>

  <!-- Three-column layout with offset -->
  <ion-row>
    <atom-col size="4">Col 1</atom-col>
    <atom-col size="4" offset="4">Col 2 (offset by 4)</atom-col>
    <atom-col size="4">Col 3</atom-col>
  </ion-row>
</atom-grid>
```

**`atom-grid` Props:** `fixed` (constrains to max container width).
**`atom-col` Props:** `size`, `sizeSm`, `sizeMd`, `sizeLg` (column span out of 16), `offset`, `offsetSm`, `offsetMd`, `offsetLg`, `push`, `pull`.
```

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

### Implement atom-list-slider with navigation events

Source: https://context7.com/juntossomosmais/atomium/llms.txt

Create a horizontally scrollable list with navigation buttons. Listen for 'clickNext' and 'clickPrev' events to handle user navigation actions. The 'step' prop controls the number of items moved per click.

```html
<atom-list-slider has-navigation="true" step="2">
  <atom-list-slider-item>
    <atom-chip activated="false">Electronics</atom-chip>
  </atom-list-slider-item>
  <atom-list-slider-item>
    <atom-chip>Clothing</atom-chip>
  </atom-list-slider-item>
  <atom-list-slider-item>
    <atom-chip>Books</atom-chip>
  </atom-list-slider-item>
  <atom-list-slider-item>
    <atom-chip>Sports</atom-chip>
  </atom-list-slider-item>
  <atom-list-slider-item>
    <atom-chip>Home & Garden</atom-chip>
  </atom-list-slider-item>
</atom-list-slider>

<script>
  const slider = document.querySelector('atom-list-slider')
  slider.addEventListener('clickNext', () => console.log('Navigated forward'))
  slider.addEventListener('clickPrev', () => console.log('Navigated backward'))
</script>
```

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

### Basic Usage with Framework/Vanilla JS

Source: https://github.com/juntossomosmais/atomium/blob/main/packages/core/README.md

Import the core CSS and define custom elements globally. Then, use Atomium components like `<atom-button>` directly in your JSX or HTML.

```jsx
import '@juntossomosmais/atomium/core.css'

import { defineCustomElements } from '@juntossomosmais/atomium/loader'

defineCustomElements(window)

<atom-button>Click me</atom-button>
```

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

### Import Atomium Tokens as JSON

Source: https://github.com/juntossomosmais/atomium/blob/main/packages/tokens/README.md

Import the JSON file containing all tokens. This is useful for comparisons, such as in Stylelint.

```javascript
import tokens from '@juntossomosmais/atomium-tokens/tokens.json'
```

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

### Display Custom Icons

Source: https://github.com/juntossomosmais/atomium/blob/main/apps/docs/stories/1_4_Icons.mdx

Renders a gallery of custom icons. Ensure `iconsList.custom` is populated.

```javascript
import { Meta, Title, IconGallery, IconItem } from '@storybook/addon-docs/blocks'

import { iconsList } from '../utils/icons-list'

<Meta title="Getting Started/Icons" />

<details class="icon-gallery">
  <summary>Custom Icons</summary>

  <p>Some custom icons have the -colorful variation because they have specific colors that make up their identity.</p>

  <IconGallery>
    {iconsList?.custom?.map((icon) => (
          <IconItem name={icon}>
            <atom-icon icon={icon}></atom-icon>
          </IconItem>
        ))}
  </IconGallery>
</details>
```

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

### Create and Control atom-tooltip

Source: https://context7.com/juntossomosmais/atomium/llms.txt

This snippet demonstrates how to attach a tooltip to an element using its ID and configure its placement and trigger action (hover or click). It also shows how to programmatically open the tooltip and listen for open/close events.

```html
<button id="info-btn" aria-describedby="my-tooltip">
  <atom-icon icon="information-circle-outline"></atom-icon>
</button>

<atom-tooltip id="my-tooltip" element="info-btn" placement="top" action="hover">
  This is helpful information about the feature.
</atom-tooltip>

<!-- Click-triggered tooltip with a dismiss button -->
<span id="more-info">More info</span>
<atom-tooltip element="more-info" placement="bottom-start" action="click">
  Click outside or the X button to close this tooltip.
</atom-tooltip>

<script>
  const tooltip = document.querySelector('atom-tooltip')

  tooltip.addEventListener('atomOpen', () => console.log('Tooltip shown'))
  tooltip.addEventListener('atomClose', () => console.log('Tooltip hidden'))

  // Programmatically show
  tooltip.open = true
</script>
```

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

### Load Atomium Core Web Components via Module Bundler

Source: https://context7.com/juntossomosmais/atomium/llms.txt

Register all atom-* custom elements globally and import core CSS for base styles when using a module bundler like Webpack or Vite.

```js
import '@juntossomosmais/atomium/core.css'
import { defineCustomElements } from '@juntossomosmais/atomium/loader'

defineCustomElements(window)

// Now all atom-* tags are available anywhere in the DOM
document.body.innerHTML = `
  <atom-button color="primary">Submit</atom-button>
  <atom-input label="Name" placeholder="Enter your name"></atom-input>
`
```

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

### Display Material Design Icons

Source: https://github.com/juntossomosmais/atomium/blob/main/apps/docs/stories/1_4_Icons.mdx

Renders a gallery of Material Design Icons. Ensure `iconsList.mdi` is populated.

```javascript
<details class="icon-gallery">
  <summary>Material Design Icons</summary>

  <IconGallery>
    {iconsList?.mdi?.map((icon) => (
          <IconItem name={icon}>
            <atom-icon icon={icon}></atom-icon>
          </IconItem>
        ))}
  </IconGallery>
</details>
```

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

### Load Atomium Core Web Components via CDN

Source: https://context7.com/juntossomosmais/atomium/llms.txt

Load the core CSS and ES module loader directly from the Atomium CDN for use without a bundler.

```html
<!DOCTYPE html>
<html lang="en">
<head>
  <link rel="stylesheet" href="https://atomium.juntossomosmais.com.br/core/3.19.0/core.css">
  <link rel="stylesheet" href="https://atomium.juntossomosmais.com.br/tokens/2.1.0/tokens.css">
</head>
<body>
  <atom-button color="primary" fill="solid">Click me</atom-button>
  <atom-alert color="info" message-title="Hello" message-text="Welcome!"></atom-alert>

  <script type="module">
    import { defineCustomElements } from 'https://atomium.juntossomosmais.com.br/core/3.19.0/loader/index.js'
    document.addEventListener('DOMContentLoaded', () => {
      defineCustomElements()
    })
  </script>
</body>
</html>
```

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

### Box Component Border Radius Usage

Source: https://github.com/juntossomosmais/atomium/blob/main/packages/tokens/stories/6_Misc.mdx

Demonstrates how to apply different border-radius tokens to Box components. Ensure the Box component is imported and available.

```jsx
<Box borderRadius="var(--border-radius)" />
```

```jsx
<Box borderRadius='var(--border-radius-medium)' />
```

```jsx
<Box borderRadius='var(--border-radius-large)' />
```

```jsx
<Box borderRadius="var(--border-radius-full)" />
```

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

### Basic React Component Usage

Source: https://github.com/juntossomosmais/atomium/blob/main/packages/react/README.md

Import the core CSS and the AtomButton component from the Atomium React library. Use the AtomButton component like any other React component.

```jsx
import '@juntossomosmais/atomium/core.css'

import { AtomButton } from '@juntossomosmais/atomium/react'

<AtomButton>Click me</AtomButton>
```

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

### Import CSS Tokens

Source: https://context7.com/juntossomosmais/atomium/llms.txt

Import the main token stylesheet into your JS/TS entry point to use CSS custom properties.

```javascript
// In your JS/TS entry point
import '@juntossomosmais/atomium-tokens/tokens.css'
```

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

### Clone Repository with SSH

Source: https://github.com/juntossomosmais/atomium/blob/main/README.md

Clone the Atomium design system repository using SSH. Ensure you have SSH keys configured with GitHub.

```sh
git clone git@github.com:juntossomosmais/atomium.git
```

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

### Usage with CDN

Source: https://github.com/juntossomosmais/atomium/blob/main/packages/core/README.md

Include Atomium's CSS and loader script via CDN links in your HTML. Ensure the DOM is loaded before defining custom elements.

```html
<head>
  <link rel="stylesheet" href="https://atomium.juntossomosmais.com.br/core/SEMVER/core.css">
  <link rel="stylesheet" href="https://atomium.juntossomosmais.com.br/tokens/SEMVER/tokens.css">
</head>
<body>
  <atom-button>Click me</atom-button>

  <script type="module">
    import { defineCustomElements } from 'https://atomium.juntossomosmais.com.br/core/SEMVER/loader/index.js'

    document.addEventListener('DOMContentLoaded', function () {
      defineCustomElements()
    })
  </script>
</body>
```

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

### atom-container Component

Source: https://context7.com/juntossomosmais/atomium/llms.txt

A layout wrapper that applies a max-width constraint and optional horizontal padding.

```APIDOC
## `atom-container` Component

A layout wrapper that applies a max-width constraint and optional horizontal padding.

```html
<!-- With padding (default) -->
<atom-container>
  <h1>Page Title</h1>
  <p>Content is constrained to the max container width.</p>
</atom-container>

<!-- Without padding (edge-to-edge content) -->
<atom-container has-padding="false">
  <img src="/hero.jpg" style="width: 100%;" alt="Hero" />
</atom-container>
```

**Props:** `hasPadding` (boolean, default `true`).
```

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

### Use Atomium Tokens in CSS

Source: https://github.com/juntossomosmais/atomium/blob/main/packages/tokens/README.md

Import the CSS tokens file to use CSS variables in your stylesheets.

```javascript
import '@juntossomosmais/atomium-tokens/tokens.css'
```

```css
.my-element {
  color: var(--color-brand-primary-regular);
}
```

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

### Handle page changes in atom-pagination

Source: https://context7.com/juntossomosmais/atomium/llms.txt

Listen for the 'atomChangePage' event to detect when a user navigates to a different page and fetch the corresponding data. The event detail contains the new 1-based page number.

```html
<atom-pagination id="my-pagination" page="1" count="20"></atom-pagination>

<script>
  const pagination = document.getElementById('my-pagination')

  pagination.addEventListener('atomChangePage', (e) => {
    const newPage = e.detail // number
    console.log('Navigate to page:', newPage)
    // Fetch data for the new page
    loadData(newPage)
  })
</script>
```

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

### Configure and Control atom-modal

Source: https://context7.com/juntossomosmais/atomium/llms.txt

Use this snippet to configure a modal with a title, buttons, and alert types. Listen for events like primary click, secondary click, and dismissal.

```html
<atom-button id="open-btn" color="primary">Open Modal</atom-button>

<atom-modal
  id="confirm-modal"
  trigger="open-btn"
  header-title="Delete Account"
  primary-button-text="Delete"
  secondary-button-text="Cancel"
  alert-type="error"
  has-divider="true"
></atom-modal>

<script>
  const modal = document.getElementById('confirm-modal')

  modal.addEventListener('atomPrimaryClick', () => {
    console.log('User confirmed deletion')
    modal.isOpen = false
  })

  modal.addEventListener('atomSecondaryClick', () => {
    console.log('User cancelled')
  })

  modal.addEventListener('atomDidDismiss', () => {
    console.log('Modal dismissed')
  })

  modal.addEventListener('atomDidPresent', () => {
    console.log('Modal fully presented')
  })

  // Programmatically open
  modal.isOpen = true

  // Prevent backdrop dismiss
  modal.canDismiss = false
</script>
```

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

### Register ComponentLibrary as a Vue Plugin

Source: https://github.com/juntossomosmais/atomium/blob/main/packages/vue/README.md

Alternatively, register the ComponentLibrary as a plugin with your Vue instance. This is another method for global registration.

```javascript
import { ComponentLibrary } from '@juntossomosmais/atomium/vue'

Vue.use(ComponentLibrary)
```

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

### Displaying a Popover with Action

Source: https://context7.com/juntossomosmais/atomium/llms.txt

Use atom-popover to display rich information triggered by an element. Configure placement, label, and action behavior. Listen for the 'buttonAction' event for click interactions.

```html
<button id="promo-trigger">See Offer</button>

<atom-popover
  element="promo-trigger"
  placement="bottom"
  action="click"
  label="Special Offer"
  action-text="Claim Now"
>
  Get 20% off your next purchase with code SAVE20.
</atom-popover>

<script>
  document.querySelector('atom-popover').addEventListener('buttonAction', () => {
    console.log('User clicked the popover action button')
    // apply promo code
  })
</script>
```

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

### Access Atomium Tokens in JavaScript

Source: https://github.com/juntossomosmais/atomium/blob/main/packages/tokens/README.md

Import all tokens as a module to access them programmatically in JavaScript.

```javascript
import * as tokens from '@juntossomosmais/atomium-tokens'
```

```javascript
primary: tokens.colorBrandPrimaryDark1;
```

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

### Display Typography Sizes

Source: https://github.com/juntossomosmais/atomium/blob/main/packages/tokens/stories/3_Typography.mdx

Renders a set of predefined font sizes for typography. Use this to visualize available text sizes.

```javascript
import { Meta, Typeset } from '@storybook/addon-docs/blocks'
import Table from './components/Table.jsx'

<Meta title='Tokens/Typography' />

# Typography

All typography tokens available in the design system.

## Sizes

<Typeset
  fontSizes={[
    '10px',
    '11px',
    '12px',
    '14px',
    '16px',
    '18px',
    '20px',
    '22px',
    '26px',
    '28px',
    '32px',
    '36px',
    '42px',
    '46px',
    '52px',
  ]}
  sampleText='Atomium is the best!'
/>
```

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

### Configure atom-select Component

Source: https://context7.com/juntossomosmais/atomium/llms.txt

Implement atom-select for dropdown functionality. Pass options as an array of objects, including properties like id, value, label, selected, disabled, and tag. Listen for 'atomChange', 'atomBlur', 'atomCancel', and 'atomDismiss' events.

```html
<atom-select
  id="country-select"
  label="Country"
  name="country"
  placeholder="Choose a country"
  fill="solid"
></atom-select>

<script>
  const sel = document.getElementById('country-select')

  sel.options = [
    { id: '1', value: 'br', label: 'Brazil' },
    { id: '2', value: 'us', label: 'United States' },
    { id: '3', value: 'pt', label: 'Portugal', selected: true },
    { id: '4', value: 'xx', label: 'Unknown', disabled: true },
    // Option with inline tag badge
    { id: '5', value: 'new', label: 'New Entry', tag: { color: 'success', label: 'NEW' } },
  ]

  sel.addEventListener('atomChange', (e) => {
    console.log('Selected value:', e.detail) // string
  })

  sel.addEventListener('atomBlur', () => console.log('Select blurred'))
  sel.addEventListener('atomCancel', () => console.log('Selection cancelled'))
  sel.addEventListener('atomDismiss', () => console.log('Popover dismissed'))
</script>
```

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

### Configure atom-textarea Component

Source: https://context7.com/juntossomosmais/atomium/llms.txt

Use atom-textarea for multi-line text input. Configure rows, auto-grow, maxlength, and counter. Listen for 'atomChange' events to validate input and use 'setFocus' for programmatic focus.

```html
<atom-textarea
  label="Message"
  placeholder="Write your message..."
  rows="6"
  auto-grow="true"
  maxlength="500"
  counter="true"
  error-text="Message is too short"
  helper-text="Minimum 20 characters"
></atom-textarea>

<script>
  const ta = document.querySelector('atom-textarea')

  ta.addEventListener('atomChange', (e) => {
    const value = e.detail // string
    ta.hasError = value.length < 20
  })

  // Programmatic focus
  ta.setFocus()
</script>
```

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

### React Integration with Atomium Components

Source: https://context7.com/juntossomosmais/atomium/llms.txt

Use auto-generated React-wrapped components from the /react sub-path after importing the core CSS. Props and events are fully typed.

```jsx
// main.tsx or App.tsx
import '@juntossomosmais/atomium/core.css'
import { AtomButton, AtomInput, AtomAlert, AtomModal } from '@juntossomosmais/atomium/react'

function App() {
  const [isOpen, setIsOpen] = React.useState(false)
  const [inputVal, setInputVal] = React.useState('')

  return (
    <div>
      <AtomInput
        label="Your name"
        placeholder="Type here..."
        value={inputVal}
        onAtomChange={(e) => setInputVal(e.detail)}
      />
      <AtomButton
        color="primary"
        fill="solid"
        size="default"
        onClick={() => setIsOpen(true)}
      >
        Open Modal
      </AtomButton>
      <AtomAlert
        color="success"
        messageTitle="Saved!"
        messageText="Your data has been saved successfully."
        close
        onAtomClose={() => console.log('Alert closed')}
      />
      <AtomModal
        headerTitle="Confirm Action"
        primaryButtonText="Confirm"
        secondaryButtonText="Cancel"
        isOpen={isOpen}
        onAtomPrimaryClick={() => { console.log('confirmed'); setIsOpen(false) }}
        onAtomSecondaryClick={() => setIsOpen(false)}
        onAtomDidDismiss={() => setIsOpen(false)}
      >
        <p>Are you sure you want to proceed?</p>
      </AtomModal>
    </div>
  )
}
```

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

### Apply Elevation with CSS

Source: https://github.com/juntossomosmais/atomium/blob/main/packages/tokens/stories/7_Elevation.mdx

Use these CSS properties to apply elevation tokens. The `box-shadow` property is for direct shadow application, while `filter: drop-shadow` can be used for more complex shadow effects.

```CSS
box-shadow: var(--elevation-2);
filter: drop-shadow(var(--elevation-8));
```

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

### atom-modal Component

Source: https://context7.com/juntossomosmais/atomium/llms.txt

A versatile modal dialog component with support for headers, footers, alert icons, progress bars, and programmatic control.

```APIDOC
## atom-modal Component

A full-featured modal dialog built on Ionic's `ion-modal`. Supports a title header, optional divider, alert/error icon types, a progress bar, footer action buttons, and programmatic open/close control.

### Props:
`headerTitle`, `isOpen`, `trigger`, `idName`, `primaryButtonText`, `secondaryButtonText`, `hasDivider`, `alertType` (`alert` | `error`), `progress` (0–1), `hasFooter`, `disablePrimaryButton`, `disableSecondaryButton`, `canDismiss`, `metaData`.

### Events:
`atomPrimaryClick`, `atomSecondaryClick`, `atomCloseClick`, `atomDidPresent`, `atomDidDismiss`, `atomIsOpenChange`.

### Example Usage:
```html
<atom-button id="open-btn" color="primary">Open Modal</atom-button>

<atom-modal
  id="confirm-modal"
  trigger="open-btn"
  header-title="Delete Account"
  primary-button-text="Delete"
  secondary-button-text="Cancel"
  alert-type="error"
  has-divider="true"
></atom-modal>

<script>
  const modal = document.getElementById('confirm-modal')

  modal.addEventListener('atomPrimaryClick', () => {
    console.log('User confirmed deletion')
    modal.isOpen = false
  })

  modal.addEventListener('atomSecondaryClick', () => {
    console.log('User cancelled')
  })

  modal.addEventListener('atomDidDismiss', () => {
    console.log('Modal dismissed')
  })

  modal.addEventListener('atomDidPresent', () => {
    console.log('Modal fully presented')
  })

  // Programmatically open
  modal.isOpen = true

  // Prevent backdrop dismiss
  modal.canDismiss = false
</script>
```
```

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

### atom-tooltip Component

Source: https://context7.com/juntossomosmais/atomium/llms.txt

A positioned tooltip component that anchors to an element, supporting hover or click triggers and emitting open/close events.

```APIDOC
## atom-tooltip Component

A positioned tooltip built with Popper.js. Anchors to any element by ID, supports hover (default) and click trigger modes, and fires `atomOpen`/`atomClose` events. On mobile, click mode automatically replaces hover.

### Props:
`element` (target element ID), `placement`, `action` (`hover` | `click`), `open`.

### Events:
`atomOpen`, `atomClose`.

### Example Usage:
```html
<button id="info-btn" aria-describedby="my-tooltip">
  <atom-icon icon="information-circle-outline"></atom-icon>
</button>

<atom-tooltip id="my-tooltip" element="info-btn" placement="top" action="hover">
  This is helpful information about the feature.
</atom-tooltip>

<!-- Click-triggered tooltip with a dismiss button -->
<span id="more-info">More info</span>
<atom-tooltip element="more-info" placement="bottom-start" action="click">
  Click outside or the X button to close this tooltip.
</atom-tooltip>

<script>
  const tooltip = document.querySelector('atom-tooltip')

  tooltip.addEventListener('atomOpen', () => console.log('Tooltip shown'))
  tooltip.addEventListener('atomClose', () => console.log('Tooltip hidden'))

  // Programmatically show
  tooltip.open = true
</script>
```
```

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

### CDN Distribution URLs for Atomium

Source: https://github.com/juntossomosmais/atomium/blob/main/apps/docs/stories/architecture-decision-records/0015-why-use-cdn-for-distribution.mdx

These URLs are used to access Atomium core and tokens via a CDN. Replace SEMVER with the desired semantic version.

```sh
https://atomium.juntossomosmais.com.br/core/SEMVER/
```

```sh
https://atomium.juntossomosmais.com.br/tokens/SEMVER/
```

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

### Display progress with atom-meter

Source: https://context7.com/juntossomosmais/atomium/llms.txt

Use the atom-meter component to visualize progress with semantic color variants and different sizes. The 'has-center-title' prop can be used to center the title when no slot content is provided.

```html
<!-- Basic meter -->
<atom-meter
  title="Storage Used"
  type="warning"
  size="large"
  min="0"
  max="100"
  actual="73"
>
  <span>73 GB of 100 GB</span>
</atom-meter>

<!-- Centered title layout (no slot content) -->
<atom-meter
  title="Goal Progress"
  type="success"
  size="small"
  min="0"
  max="50"
  actual="35"
  has-center-title="true"
></atom-meter>
```