diff --git a/doc/components/accordions.md b/doc/components/accordions.md
new file mode 100644
index 0000000000..4abf44ec19
--- /dev/null
+++ b/doc/components/accordions.md
@@ -0,0 +1,104 @@
+# Accordions
+
+## Accordion
+
+Accordion groups multiple AccordionItem components stacked vertically, helping present expandable content as a
+coherent set.
+
+### Usage
+
+#### Use for
+
+- Grouping multiple AccordionItem elements as a single stacked section
+- Building accordion groups where the only allowed children are AccordionItem elements
+- Presenting expandable and collapsible content blocks in a clear hierarchy
+
+#### Don't use for
+
+- Do not use Accordion when content does not need expand/collapse behavior
+- Do not mix unrelated content under one Accordion group without clear section meaning
+- Do not place children other than AccordionItem inside Accordion
+- Do not insert extra dividers between items by default, since `Accordion` already renders separators
+
+## AccordionItem
+
+AccordionItem is the interactive unit inside an Accordion: it renders a tappable header that toggles an
+accessible, animated content panel.
+
+### Usage
+
+#### Use for
+
+- Building each expandable row inside an Accordion group
+- Showing a header (title/asset/right content) that toggles panel visibility with chevron state
+- Providing accessible expand/collapse behavior with `aria-expanded`, `aria-controls`, and labelled panel
+ region
+
+#### Don't use for
+
+- Do not use AccordionItem outside an Accordion context, since open state and toggle come from
+ `useAccordionContext`
+- Do not omit meaningful title/asset labelling when relying on computed accessibility labels
+- Do not bypass the built-in toggle/transition behavior for custom interaction patterns that break consistency
+
+## BoxedAccordion
+
+BoxedAccordion groups multiple BoxedAccordionItem components in a stacked expandable set; the visible box
+treatment is applied by each item.
+
+### Usage
+
+#### Use for
+
+- Grouping multiple accordion items as a single expandable/collapsible section
+- Building groups where the only allowed children are BoxedAccordionItem elements
+- Presenting related expandable content with clearer visual boundaries
+
+#### Don't use for
+
+- Do not use BoxedAccordion when content does not need expand/collapse behavior
+- Do not mix unrelated content in the same boxed accordion group
+- Do not use mixed asset types within the same accordion group when visual consistency is required
+- Do not place children other than BoxedAccordionItem inside BoxedAccordion
+
+## BoxedAccordionItem
+
+BoxedAccordionItem is the interactive unit of a BoxedAccordion: it behaves like AccordionItem and applies the
+visible boxed styling at item level.
+
+### Usage
+
+#### Use for
+
+- Building each expandable row inside a BoxedAccordion group
+- Showing a tappable header that toggles an accessible content panel with chevron state
+- Keeping AccordionItem behavior while adding a stronger boxed visual grouping
+
+#### Don't use for
+
+- Do not use BoxedAccordionItem outside a BoxedAccordion/Accordion grouped context
+- Do not omit meaningful item labeling when relying on computed accessibility labels
+- Do not replace built-in toggle and transition behavior with inconsistent custom interaction patterns
+
+## Accessibility
+
+### Accordion group
+
+By default, accordion headers are rendered as interactive button-like controls and the group has no list role.
+When the accordion should be exposed as a grouped list in your context, set roles explicitly on the container
+and items (for example `role="list"` on `Accordion` and `role="listitem"` on each item wrapper).
+
+### Slot
+
+Accordion content areas (`asset`, `right`, and panel `content`) accept custom content. Because these areas are
+fully customizable, ensure custom controls, icons, and media preserve accessible names, focus order, and
+semantics.
+
+### Heading hierarchy
+
+Accordion heading levels are configurable.
+
+- By default, no document heading level is enforced
+- Set `titleAs` (for example `h2`, `h3`) when the accordion title should participate in the page heading
+ outline
+- Keep levels consistent with surrounding content hierarchy
diff --git a/doc/components/avatar.md b/doc/components/avatar.md
new file mode 100644
index 0000000000..223affc475
--- /dev/null
+++ b/doc/components/avatar.md
@@ -0,0 +1,18 @@
+# Avatar
+
+Avatar is the visual representation of a user or entity, using photo, initials, or icon depending on available
+identity content.
+
+## Usage
+
+### Use for
+
+- Identifying people or entities in lists, headers, cards, and profile-related surfaces
+- Showing profile photos when available, with initials or a generic user icon as fallback
+- Indicating lightweight status or new activity with a small badge when relevant
+
+### Don't use for
+
+- Do not use avatar style differences to communicate critical meaning without supporting text
+- Do not mix unrelated avatar sizes and treatments in the same content group without hierarchy intent
+- Do not overuse badges on avatars when there is no clear notification or status purpose
diff --git a/doc/components/badge.md b/doc/components/badge.md
new file mode 100644
index 0000000000..dfcb6a630a
--- /dev/null
+++ b/doc/components/badge.md
@@ -0,0 +1,33 @@
+# Badge
+
+Badge is a compact, informative indicator used to signal unread or pending status on top of another UI
+element.
+
+## Usage
+
+### Use for
+
+- Signaling small counts or attention states attached to icons, icon buttons, or entry points
+- Highlighting notification-like updates without interrupting the main content flow
+- Showing either a dot (status only) or a numeric count when exact quantity matters
+- Communicating overflow counts compactly (values above nine are displayed as `+9`)
+
+### Don't use for
+
+- Do not rely on it as the only accessible message, since the badge itself is decorative for screen readers
+- Do not show a badge for zero state (no pending content)
+
+## Accessibility
+
+### Decorative behavior
+
+Badge is decorative for assistive technologies. Its visual dot/number is not announced directly by screen
+readers.
+
+### Accessible label on the related control
+
+When Badge wraps an interactive element (for example an icon button), include the unread/pending meaning in
+the interactive element label (for example via `aria-label`).
+
+- Example: `"Shopping cart with 2 items"`
+- Do not expose only `"Shopping cart"` if the badge count is important for task completion
diff --git a/doc/components/breadcrumbs.md b/doc/components/breadcrumbs.md
new file mode 100644
index 0000000000..4840077942
--- /dev/null
+++ b/doc/components/breadcrumbs.md
@@ -0,0 +1,31 @@
+# Breadcrumbs
+
+Breadcrumbs are a navigational element to help users to understand where they are in a website as well as
+content structure and hierarchy.
+
+## Usage
+
+### Use for
+
+- Applying the documented component pattern in product UI
+- Keeping user experience coherent across screens and flows
+
+### Don't use for
+
+- Don't use Breadcrumbs to show steps in a process.
+- Do not replace a more suitable semantic component with this one
+- Do not customize behavior in ways that conflict with Mística guidance
+
+## Accessibility
+
+### Accessibility label
+
+You can add an accessibility label to Breadcrumbs to describe the navigation type via `aria-label`. By
+default, the component uses `"Breadcrumb"`.
+
+If your product language is not English, provide a localized `aria-label` explicitly.
+
+### Current page semantics
+
+Breadcrumbs expose the current location as the last item with `aria-current="page"`. Provide the current page
+title through `title`, and include only previous navigable levels in `breadcrumbs`.
diff --git a/doc/components/buttons.md b/doc/components/buttons.md
new file mode 100644
index 0000000000..889bc0fbde
--- /dev/null
+++ b/doc/components/buttons.md
@@ -0,0 +1,253 @@
+# Buttons
+
+## ButtonPrimary
+
+ButtonPrimary represents the main action users should take in a given view or step.
+
+### Usage
+
+#### Use for
+
+- Highlighting the most important action in a screen or flow step
+- Driving forward progression in tasks where a clear next action is needed
+- Giving visual priority to the single action with highest business or user value
+
+#### Don't use for
+
+- Do not place multiple primary buttons in the same decision area
+- Do not use primary styling for secondary or cancel actions
+- Do not combine with competing emphasis patterns that weaken action hierarchy
+
+## ButtonSecondary
+
+ButtonSecondary represents a complementary action with less visual priority than the primary action.
+
+### Usage
+
+#### Use for
+
+- Offering alternative or supporting actions next to a primary button
+- Handling neutral decisions such as back, cancel, edit, or optional paths
+- Providing actions that should remain visible but not dominate the screen hierarchy
+
+#### Don't use for
+
+- Do not use secondary styling for the main conversion or progression action
+- Do not present too many secondary actions in one group, which can dilute clarity
+- Do not use secondary buttons for destructive actions, use buttonDanger or buttonLinkDanger instead
+
+## ButtonDanger
+
+ButtonDanger is reserved for high-risk, destructive actions that require clear visual warning.
+
+### Usage
+
+#### Use for
+
+- Triggering irreversible or risky operations such as delete, remove, or reset
+- Making destructive intent explicit so users can distinguish it from neutral actions
+- Pairing with confirmation patterns when accidental activation would have high impact
+
+#### Don't use for
+
+- Do not use buttonDanger for normal navigation or low-risk actions
+- Do not place multiple danger actions together without clear separation and context
+- Do not make destructive actions the default visual choice in routine flows
+
+## ButtonLink
+
+ButtonLink provides low-emphasis actions and lightweight navigation in button form.
+
+### Usage
+
+#### Use for
+
+- Presenting tertiary actions that should remain visible with minimal visual weight
+- Offering contextual navigation from inline sections or supporting action groups
+- Use buttonLinks for low-friction actions that do not compete with primary controls
+
+#### Don't use for
+
+- Do not use link emphasis for the main call to action
+- Do not mix too many link actions in the same area without clear prioritization
+- Do not use it for destructive decisions where stronger warning semantics are required
+
+## ButtonLinkDanger
+
+ButtonLinkDanger is a low-emphasis destructive action used when risk exists but should not dominate the
+interface.
+
+### Usage
+
+#### Use for
+
+- Offering destructive options with lighter emphasis than a full danger button
+- Placing secondary-risk actions in contextual areas where a subtle warning is enough
+- Pairing with confirmation steps when the destructive outcome is not easily reversible
+
+#### Don't use for
+
+- Do not use it for primary destructive decisions that require maximum prominence, use buttonDanger instead
+- Do not combine with non-destructive link actions without clear visual grouping
+- Do not rely on color alone; provide surrounding context that explains the risk
+
+## IconButton
+
+IconButton exposes a compact icon-only action with accessible labeling, visual variants, and optional loading
+feedback for async interactions.
+
+### Usage
+
+#### Use for
+
+- Triggering frequent, low-text actions where space is constrained and icon meaning is familiar
+- Supporting toolbars and dense layouts where compact touch targets are needed
+- Providing immediate async feedback with spinner state during long-running button actions
+- Applying visual emphasis (`neutral`, `brand`, `danger`) that matches action intent
+
+#### Don't use for
+
+- Do not use ambiguous or uncommon icons for destructive or high-risk actions
+- Do not omit accessible naming (`aria-label` or `aria-labelledby`) for icon-only controls
+- Do not place too many icon buttons together without clear hierarchy and grouping
+- Do not use IconButton when visible text is needed to remove action ambiguity
+
+#### Example
+
+> **Important:** `Icon` receives the component reference (not a JSX element). Do not use children.
+
+```tsx
+
+```
+
+## ToggleIconButton
+
+ToggleIconButton switches between checked and unchecked icon states using the same compact visual language as
+IconButton.
+
+### Usage
+
+#### Use for
+
+- Toggling a binary preference or status where both states can be represented with clear icons
+- Keeping compact two-state actions consistent with IconButton sizing and visual variants
+- Showing distinct accessible labels and assets for checked and unchecked states
+- Supporting asynchronous state changes where visual feedback should remain stable until completion
+
+#### Don't use for
+
+- Do not use ToggleIconButton for multi-step or multi-option choices beyond two states
+- Do not use the same icon/label for checked and unchecked states when meaning changes
+- Do not omit accessible naming for each state; state intent must be understandable to assistive tech
+- Do not use toggle interactions when the action is not reversible or does not represent a true on/off state
+
+#### Example
+
+```tsx
+
+```
+
+## ButtonGroup
+
+ButtonGroup organizes primary, secondary, and optional link actions into a coherent action block with
+responsive alignment.
+
+### Usage
+
+#### Use for
+
+- Grouping related call-to-action buttons so decision hierarchy is clear at a glance
+- Pairing primary and secondary actions with an optional supporting link action
+- Building reusable action blocks where button presence can vary by context
+
+#### Don't use for
+
+- Do not include unrelated actions in the same group just to save space
+- Do not flatten hierarchy by styling all actions with equal emphasis
+- Do not force rendering when no actions are available; avoid empty action containers
+- Do not overuse centered alignment if it reduces scanability in dense layouts
+
+## ButtonFixedFooterLayout
+
+ButtonFixedFooterLayout keeps primary actions anchored in a fixed footer while content scrolls independently.
+
+### Usage
+
+#### Use for
+
+- Keeping critical call-to-action buttons persistently visible during long or scrollable flows
+- Presenting primary and secondary actions in a stable full-width footer area
+- Building task-completion screens where action access must remain constant across viewport sizes
+- Pairing action persistence with scrollable body content without losing context
+
+#### Don't use for
+
+- Do not use fixed footer actions for lightweight screens where inline buttons are sufficient
+- Do not include too many footer actions; keep hierarchy clear with one main action and optional
+ secondary/link
+- Do not keep an empty footer visible when no actionable buttons are present
+- Do not use this pattern when fixed controls could obstruct essential page content
+
+## ButtonLayout
+
+ButtonLayout arranges primary, secondary, and optional link actions into a structured block with explicit
+alignment variants.
+
+### Usage
+
+#### Use for
+
+- Composing action areas tied to a specific content block or screen section
+- Defining clear action hierarchy with primary and secondary buttons plus optional supporting link
+- Choosing layout intent by alignment (`full-width`, `left`, `center`, `right`) to match context
+- Keeping action order predictable, including right-aligned layouts where action sequence is intentionally
+ adjusted
+
+#### Don't use for
+
+- Do not mix unrelated actions in one layout block without a shared objective
+- Do not use conflicting alignment patterns within the same action area
+- Do not flatten hierarchy by giving all actions equal visual prominence
+- Do not add excessive actions that reduce decision clarity
+
+## Accessibility
+
+### Role
+
+Define button semantics according to the real interaction outcome so users can anticipate what happens after
+activation.
+
+- Use action semantics for in-place actions (`onPress`, submit)
+- Use navigation semantics for destination changes (`to`/`href`) instead of simulating links with click-only
+ handlers
+- Avoid forcing `role="link"` on action buttons when `to`/`href` can express navigation natively
+
+### Contextual menu and dialog triggers
+
+If a button opens a contextual surface, expose that relationship explicitly.
+
+- Use `aria-haspopup="menu"` or `aria-haspopup="dialog"` depending on the target surface
+- Pair with `aria-expanded` to communicate open/closed state when applicable
+- Use `aria-controls` to reference the controlled element when there is a stable target id
+
+### Repeated button labels
+
+Repeated visible labels (for example multiple `"See more"` buttons) can be ambiguous for screen reader users.
+
+- Keep visible labels unique whenever possible
+- When repeated labels are required by design, provide additional context through `aria-label` or
+ `aria-describedby`
+- Include destination or object context in the accessible name (for example `"See more plans"`)
+
+### Buttons without visible labels
+
+Buttons with no visible text (for example IconButton and ToggleIconButton) must include accessible naming.
+
+- Provide `aria-label` or `aria-labelledby` for icon-only controls
+- For ToggleIconButton, ensure checked/unchecked states expose distinct labels that describe each state action
+- Do not rely on icon shape alone to communicate purpose
diff --git a/doc/components/callout.md b/doc/components/callout.md
new file mode 100644
index 0000000000..35ac75925d
--- /dev/null
+++ b/doc/components/callout.md
@@ -0,0 +1,48 @@
+# Callout
+
+A snippet of information that draws attention to important content. Always includes a description.
+
+## Usage
+
+### Use for
+
+- Informative type: Drawing attention to useful information, tips, or non-urgent recommendations
+- Warning type: Alerting users about situations that require attention but are not blocking
+- Critical type: Notifying users about critical information or important consequences they should be aware of
+
+### Don't use for
+
+- Never use as a substitute for form or system error messages
+- Never use as a substitute for feedback after a user action
+
+## Accessibility
+
+### Role
+
+Callout is rendered as a `section` element and allows overriding semantics through the `role` prop when
+needed.
+
+### Content announcement options
+
+Depending on urgency, you can configure callout announcement behavior by choosing an appropriate role.
+
+- Use polite-style semantics for informative, non-urgent content
+- Use assertive-style semantics only for urgent content that should interrupt current speech output
+- Choose role values intentionally so announcements match the real importance of the message
+
+### Title accessibility label
+
+The title supports an accessibility label via `title={{text, 'aria-label'}}`, allowing screen readers to
+announce contextual text that differs from the visible title when necessary.
+
+### Dismiss action label
+
+You can pass `closeButtonLabel` to provide a more contextual accessible name for the dismiss action. By
+default, the close action label is "Close" (localized by theme texts when available).
+
+### Heading hierarchy
+
+Callout heading levels are configurable.
+
+- Title defaults to `h2` (`titleAs="h2"`)
+- Adjust heading level to keep a consistent outline in the surrounding page structure
diff --git a/doc/components/cards.md b/doc/components/cards.md
new file mode 100644
index 0000000000..bf3f7fee8b
--- /dev/null
+++ b/doc/components/cards.md
@@ -0,0 +1,326 @@
+# Cards
+
+## DataCard
+
+DataCard presents structured informational content with optional media, hierarchy, actions, and supporting
+slots in a reusable card surface.
+
+### Usage
+
+#### Use for
+
+- Displaying data-rich summaries that combine title hierarchy, supporting text, and contextual metadata
+- Grouping informative content with optional actions (primary, secondary, link) in a single card container
+- Building modular content blocks for dashboards, listings, and discovery experiences
+- Using optional slots, top actions, and footer areas when extra context or secondary interactions are needed
+
+#### Don't use for
+
+- Do not overload the card with too many simultaneous actions and slots
+- Do not use this pattern when a simpler list row or text block better fits the information density
+- Do not let decorative assets dominate over the data hierarchy and actionable intent
+- Do not create inconsistent card variants in the same collection without clear hierarchy
+
+## MediaCard
+
+MediaCard combines media and content in one card surface, balancing visual storytelling with clear text
+hierarchy and actions.
+
+### Usage
+
+#### Use for
+
+- Presenting content where image or video provides key context for the card message
+- Building discovery and editorial card collections with consistent media-plus-text structure
+- Combining optional top actions, slot content, and CTA buttons in a single modular card pattern
+- Adapting composition by media position when visual emphasis should support, not overpower, text hierarchy
+
+#### Don't use for
+
+- Do not use media-heavy cards for dense data-first scenarios better served by informational card patterns
+- Do not overload each card with too many competing actions and secondary elements
+- Do not rely on decorative media that weakens readability or action clarity
+- Do not mix unrelated media positioning strategies in one card set without clear layout rationale
+
+## CoverCard
+
+CoverCard is a media-first card pattern that combines image or video backgrounds with layered content.
+
+### Usage
+
+#### Use for
+
+- Highlighting featured content where visual media is the primary entry point
+- Combining headline hierarchy, contextual metadata, and actions in a single promotional surface
+- Supporting editorial, campaign, or discovery cards that need strong visual impact with clear call-to-action
+- Using optional top actions and footer areas when secondary interactions or extra context are needed
+
+#### Don't use for
+
+- Do not use CoverCard for dense informational layouts where media is not the main signal
+- Do not overload the card with too many competing actions in top, body, and footer at once
+- Do not rely on background imagery alone; ensure text and actions remain legible over media
+- Do not use decorative media that conflicts with the card’s content hierarchy or action intent
+
+## NakedCard
+
+NakedCard is a transparent card surface that inherits the surrounding theme context while keeping card content
+structure and actions.
+
+### Usage
+
+#### Use for
+
+- Presenting grouped content with card hierarchy but without an emphasized container background
+- Integrating card content in already-defined surfaces where extra visual chrome would add noise
+- Keeping consistent card anatomy (media/content/actions) while adapting naturally to parent variant context
+- Using `size` variants (including `snap`) to fit compact and dense layout scenarios
+
+#### Don't use for
+
+- Do not use NakedCard when strong visual separation from background is required for comprehension
+- Do not force explicit card variant styling; NakedCard is designed to inherit context variant
+- Do not rely on deprecated small-card patterns when `NakedCard size="snap"` is the intended approach
+- Do not overload transparent cards with excessive actions that reduce scanability on busy backgrounds
+
+## HighlightedCard
+
+HighlightedCard is a legacy highlighted media-card pattern; use the equivalent MediaCard layout in new
+designs.
+
+### Usage
+
+#### Use for
+
+- Maintaining backward-compatible highlighted card layouts in existing screens
+- Showing media-supported content where right-positioned visual context improves scanability
+- Supporting migration scenarios where legacy highlighted cards are being progressively replaced
+- Prefering the equivalent `MediaCard` composition for new product work
+
+#### Don't use for
+
+- Do not create new UI patterns based on this deprecated variant
+- Do not mix legacy highlighted cards and modern media card variants without intentional transition strategy
+- Do not use highlighted treatment when content does not require visual emphasis
+- Do not prioritize legacy convenience over consistent modern card-system usage
+
+## PosterCard
+
+PosterCard is a legacy media-first card kept for backward compatibility; use CoverCard for new designs.
+
+### Usage
+
+#### Use for
+
+- Maintaining existing legacy surfaces that still rely on PosterCard behavior
+- Supporting transitional migrations where replacing all legacy poster cards is not yet feasible
+- Preserving compatibility in older flows while aligning new work to CoverCard patterns
+- Using it temporarily when refactoring deprecated props toward current card APIs
+
+#### Don't use for
+
+- Do not use PosterCard for new product experiences; use CoverCard instead
+- Do not introduce new dependencies on deprecated PosterCard-only prop patterns
+- Do not mix legacy and modern card variants inconsistently within the same content family
+- Do not postpone migration planning when CoverCard already satisfies the target use case
+
+## SnapCard
+
+Deprecated alias of `DataCard` in snap size for compact, actionable data cards.
+
+### Usage
+
+#### Use for
+
+- Keeping legacy implementations stable while migrating to `DataCard size=\"snap\"`
+- Compact content cards with clear hierarchy (pretitle/title/subtitle/description) and optional primary action
+- Small promotional or informative entry points that open a richer detail view
+
+#### Don't use for
+
+- Do not use in new work; use `DataCard size=\"snap\"` instead
+- Do not use when content requires extended reading or many controls; move to a larger card size or another
+ layout
+- Do not add optional elements just because they are available; keep snap cards concise and scannable
+
+## SmallNakedCard
+
+Deprecated alias of `NakedCard` in snap size, for compact transparent cards that inherit the surrounding theme
+variant.
+
+### Usage
+
+#### Use for
+
+- Maintaining legacy screens that already use this component while migrating to `NakedCard size=\"snap\"`
+- Compact, lightweight card entries on transparent backgrounds where the card should inherit the current
+ variant context
+- Short teaser content that links to a more detailed destination
+
+#### Don't use for
+
+- Do not use in new designs; use `NakedCard size=\"snap\"` instead
+- Do not use when you need strong surface/background separation; choose a non-naked card variant
+- Do not overload this compact format with long text, dense metadata, or multiple competing actions
+
+## DisplayDataCard
+
+DisplayDataCard is the display-sized data card pattern for high-prominence information blocks; prefer the
+equivalent DataCard size variant in new designs.
+
+### Usage
+
+#### Use for
+
+- Presenting high-visibility data cards that need a larger visual footprint than default card sizes
+- Highlighting key informational modules in editorial or promotional layouts
+- Maintaining continuity in legacy screens that already use this display-card pattern
+- Prefering the display size option in `DataCard` for new implementations
+
+#### Don't use for
+
+- Do not introduce this legacy variant in new component compositions when the modern `DataCard` size option is
+ available
+- Do not use display-sized cards in dense grids where compact scanning is the priority
+- Do not fill large cards with minimal content that weakens visual balance and hierarchy
+- Do not mix multiple card sizing paradigms in one section without intentional layout rationale
+
+## DisplayMediaCard
+
+DisplayMediaCard is the large-format media card variant for prominent visual modules; prefer equivalent sizing
+through modern media-card patterns in new designs.
+
+### Usage
+
+#### Use for
+
+- Maintaining legacy large media-card compositions already present in existing product surfaces
+- Highlighting high-priority editorial or promotional content with an expanded media footprint
+- Preserving visual continuity in sections that depend on this specific display-style card rhythm
+- Prefering current card-size and layout variants for new implementations
+
+#### Don't use for
+
+- Do not introduce this legacy variant in new card systems when modern equivalents are available
+- Do not use oversized media cards in dense, scan-first grids
+- Do not combine multiple display-size card patterns without clear visual hierarchy
+- Do not fill large card surfaces with minimal content that reduces design balance
+
+## EmptyStateCard
+
+EmptyStateCard communicates absence of content in a boxed surface with supportive messaging and optional
+recovery actions.
+
+### Usage
+
+#### Use for
+
+- Explaining blank or initial states in a clear, calm card format
+- Pairing concise title and description with a focused next action
+- Using a simple visual cue (icon or image) to reinforce context when no data is available
+- Guiding users toward recovery or next steps with small, low-friction actions
+
+#### Don't use for
+
+- Do not use empty-state cards for error-heavy or blocking scenarios that need dedicated feedback patterns
+- Do not overload the card with long explanatory copy or multiple competing actions
+- Do not use large primary actions in this pattern when compact action treatment is expected
+- Do not present decorative visuals without clear supporting message and intent
+
+## CardActionIconButton
+
+CardActionIconButton is a compact icon-only action for card top-action areas, including both single-action and
+toggle-action behavior.
+
+### Usage
+
+#### Use for
+
+- Adding quick top actions (for example close, favorite, play/pause) in card headers without adding visual
+ noise
+- Keeping card actions consistent with card variants and built-in top-action spacing
+- Using toggle icon actions when the card action represents a clear checked/unchecked state
+- Providing concise, specific labels so icon-only actions remain accessible
+
+#### Don't use for
+
+- Do not use it for primary card call-to-action buttons; use the card button slots for primary actions
+- Do not use ambiguous icons without a clear accessible label describing the action
+- Do not add too many top actions in the same card; keep hierarchy and scanability clear
+- Do not use toggle mode when the interaction is not a real two-state behavior
+
+## CardActionSpinner
+
+CardActionSpinner is a small inline spinner meant for card action loading states (for example media control
+loading) inside the top-action area.
+
+### Usage
+
+#### Use for
+
+- Showing that a card action is processing while the rest of the card remains visible
+- Replacing a top-action icon temporarily during short async transitions
+- Communicating non-blocking loading at the action level instead of card- or page-level loading
+- Keeping loading feedback compact in dense card layouts
+
+#### Don't use for
+
+- Do not use it as a standalone page or section loading pattern; use broader loading components instead
+- Do not keep it visible after the async action has completed or failed
+- Do not pair spinner-only actions with missing accessibility context in adjacent controls
+- Do not use multiple simultaneous spinners in the same card action cluster when one status is enough
+
+## Accessibility
+
+### Role
+
+When a card is interactive, expose semantics that match the interaction outcome so users can anticipate the
+result.
+
+- Use action semantics for in-place actions (`onPress`)
+- Use navigation semantics for destination changes (`href`/`to`) instead of simulating links with action-only
+ handlers
+- Avoid forcing `role="link"` on action cards when `href`/`to` can express navigation natively
+
+### Heading hierarchy
+
+Card heading levels are configurable.
+
+- `titleAs` defaults to `h3`
+- `pretitleAs` defaults to `span`/paragraph semantics (non-heading unless explicitly changed)
+
+If you change defaults:
+
+- If only one heading exists, that heading is announced first
+- If both pretitle and title are headings, the one with higher hierarchy is read first
+- Do not assign the same heading level to pretitle and title
+
+### Accessibility label
+
+The labeling strategy depends on where interaction happens.
+
+- Card without inner actions (full-card interaction): provide `aria-label` or `aria-labelledby` on the
+ interactive card container
+- Card with button/link actions: label each interactive element (main buttons and top actions) with clear,
+ action-specific names
+- For top actions, always provide explicit labels because icon-only controls require accessible naming
+
+### Image
+
+When a card includes an image, provide meaningful `imageAlt` when the image conveys content.
+
+- For decorative/background-only media, keep alt text empty
+- Cover/background media should be treated as decorative unless it carries essential information
+
+### Text limitation
+
+Cards support visual text truncation (`*LinesMax` props).
+
+- Prefer layouts that expose full text
+- If truncation is required, keep complete meaning available to assistive technologies
+- Do not depend on clipped visual text as the only place where critical information appears
+
+### Slot
+
+Slots (`slot`, `footerSlot`, custom top actions) accept arbitrary content. Because these regions are fully
+customizable, ensure custom controls, icons, and media preserve accessible names, focus order, and semantics.
diff --git a/doc/components/carousels.md b/doc/components/carousels.md
new file mode 100644
index 0000000000..db488e205d
--- /dev/null
+++ b/doc/components/carousels.md
@@ -0,0 +1,222 @@
+# Carousels
+
+## Carousel
+
+Carousel presents related content in horizontal pages with optional bullets, arrows, and autoplay controls.
+
+### Usage
+
+#### Use for
+
+- Browsing related cards or modules when horizontal exploration is the intended interaction
+- Revealing progressive content with clear page feedback (page bullets) and optional directional controls
+- Supporting both manual navigation and optional autoplay for highlight-driven content
+- Adapting visible items by breakpoint so collections stay readable across devices
+
+#### Don't use for
+
+- Do not place critical content only inside the carousel when users may never swipe to it
+- Do not overload the carousel with too many pages, which weakens orientation and discovery
+- Do not mix competing interaction patterns that make horizontal navigation unclear
+- Do not force autoplay for content that requires careful reading or deliberate comparison
+
+## CenteredCarousel
+
+CenteredCarousel emphasizes one item at a time on mobile while preserving multi-item browsing on larger
+screens.
+
+### Usage
+
+#### Use for
+
+- Highlighting one primary card per step in mobile contexts with adjacent items as context
+- Creating storytelling or featured-content flows where focus should remain on the current item
+- Combining focused mobile presentation with denser desktop distribution in the same component pattern
+- Keeping horizontal progression clear when each item deserves individual attention
+
+#### Don't use for
+
+- Do not use it for dense, comparison-first grids where multiple items must be equally visible at once
+- Do not overload each slide with heavy content that breaks quick horizontal scanning
+- Do not hide mandatory actions exclusively inside non-initial slides
+- Do not use centered emphasis when all items should carry the same immediate priority
+
+## Slideshow
+
+Use slideshow for full-width, page-by-page sequences of visual content with optional bullets, controls, and
+autoplay.
+
+### Usage
+
+#### Use for
+
+- Showing a small sequence of prominent slides one page at a time
+- Can wrap full-width components like hero or coverHero to use them as slides
+- Letting people move between pages with swipe/scroll gestures plus optional previous/next controls
+- Providing orientation in the sequence with bullets, including inverse bullets on visual backgrounds when
+ needed
+- Running optional autoplay for passive browsing contexts where motion is secondary and can be paused
+
+#### Don't use for
+
+- Do not use for long or dense collections where users need fast scanning; use list/grid or carousel patterns
+ instead
+- Do not force autoplay in primary task flows or when users need to read/interact with slide content
+- Do not depend on autoplay alone to communicate critical information; each slide must remain understandable
+ when viewed manually
+- Do not hide navigation affordances when there are multiple slides; provide bullets and/or controls so
+ position and movement are clear
+
+## PageBullets
+
+PageBullets indicates carousel pagination state, helping users understand position and progress across pages.
+
+### Usage
+
+#### Use for
+
+- Showing current page position in carousels and slideshows with multiple pages
+- Reinforcing orientation when users swipe through visual or editorial content
+- Supporting compact pagination feedback when full page controls are not always visible
+- Keeping page-state communication consistent across breakpoints and item-per-page changes
+
+#### Don't use for
+
+- Do not use PageBullets as the only navigation mechanism when explicit previous/next controls are required
+- Do not display bullets for single-page carousels with no real pagination state
+- Do not combine conflicting pagination metaphors in the same carousel surface
+- Do not treat bullets as decorative dots without meaningful current-page feedback
+
+## CarouselAutoplayControl
+
+CarouselAutoplayControl toggles carousel autoplay state, including pause/play and restart behavior when the
+last page is reached.
+
+### Usage
+
+#### Use for
+
+- Giving users explicit control over autoplay behavior in moving carousels
+- Supporting pause/play expectations for accessibility and reading comfort
+- Providing replay intent when autoplay reaches the final page
+- Integrating autoplay control in carousel headers or control groups with consistent icon behavior
+
+#### Don't use for
+
+- Do not enable autoplay controls when carousel autoplay is not part of the experience
+- Do not force autoplay in content where users need full manual reading pace
+- Do not hide autoplay state changes; users should clearly understand whether motion is active
+- Do not use autoplay control as a substitute for clear manual pagination controls
+
+## CarouselContextConsumer
+
+CarouselContextConsumer reads shared carousel actions and state to render custom controls aligned with active
+carousel behavior.
+
+### Usage
+
+#### Use for
+
+- Building custom bullets, arrows, or autoplay controls that react to real carousel state
+- Accessing carousel navigation callbacks without prop-drilling through multiple layers
+- Keeping custom control components visually flexible while preserving behavior consistency
+- Integrating carousel state into bespoke layouts that still follow carousel interaction rules
+
+#### Don't use for
+
+- Do not use CarouselContextConsumer outside CarouselContextProvider
+- Do not cache context values as static assumptions when carousel state is dynamic
+- Do not use consumer-only patterns when default built-in controls already cover requirements
+- Do not mix unrelated non-carousel concerns into carousel context-driven components
+
+## CarouselContextProvider
+
+CarouselContextProvider shares carousel navigation and state props so custom controls stay synchronized with
+carousel behavior.
+
+### Usage
+
+#### Use for
+
+- Coordinating custom carousel controls with internal carousel state from a single source
+- Exposing navigation actions (`goPrev`, `goNext`, `goToPage`) to external control compositions
+- Keeping bullets, page controls, and autoplay controls synchronized across custom layouts
+- Building advanced carousel UIs without duplicating internal carousel state logic
+
+#### Don't use for
+
+- Do not build custom carousel controls outside provider scope when synchronized behavior is required
+- Do not mix multiple providers around the same control set without clear separation
+- Do not use provider patterns when default carousel controls already satisfy the experience
+- Do not bypass context and recreate competing autoplay/navigation state manually
+
+## CarouselPageControls
+
+CarouselPageControls provides previous/next arrow navigation for carousels, with contextual enable/disable
+behavior and page-aware labeling.
+
+### Usage
+
+#### Use for
+
+- Enabling explicit previous/next navigation in carousels where swipe alone is not enough
+- Providing stronger navigation affordance for desktop and accessibility-focused interactions
+- Supporting page-aware movement where control availability reflects current position
+- Complementing bullets with direct directional controls in multi-page content sets
+
+#### Don't use for
+
+- Do not show page controls when there is only one reachable page
+- Do not keep arrows visually enabled when movement is not possible
+- Do not overload small mobile layouts with controls that obscure core carousel content
+- Do not use page controls as a substitute for clear content hierarchy inside each slide
+
+## useCarouselContext
+
+useCarouselContext provides reusable behavior to keep component logic consistent across the product.
+
+### Usage
+
+#### Use for
+
+- Sharing common state and behavior across multiple components
+- Keeping implementation aligned with Mística patterns
+
+#### Don't use for
+
+- Do not duplicate equivalent logic when this utility already exists
+- Do not use it without understanding its side effects and scope
+
+## Accessibility
+
+### Accessibility label
+
+Carousel exposes a landmark region. Provide `aria-label` or `aria-labelledby` so assistive technologies can
+identify the carousel purpose.
+
+- Use `aria-label` when no visible heading is available
+- Use `aria-labelledby` when a nearby visible heading should name the carousel
+- Keep labels specific to the content set (for example, "Featured plans carousel")
+
+### Slide structure and navigation
+
+Carousel content is exposed as a list with list items, and controls provide explicit previous/next labels.
+
+- Keep each slide understandable when reached independently
+- Ensure previous/next controls remain available when multiple pages exist
+
+### Autoplay behavior
+
+Autoplay is optional and should never be the only way to consume content.
+
+- Always provide pause/play controls when autoplay is enabled
+- Prefer autoplay only for non-critical, passive browsing contexts
+- Autoplay stops on user interaction and when reduced motion preferences are active
+- If autoplay loops are disabled, autoplay pauses automatically on the last page
+
+### Bullet pagination
+
+Bullets communicate current position, but they should not be the only orientation signal in complex carousels.
+
+- Combine bullets with clear content hierarchy and, when needed, page controls
+- Avoid showing pagination affordances when there is only one page
diff --git a/doc/components/checkbox.md b/doc/components/checkbox.md
new file mode 100644
index 0000000000..5ea3a645ee
--- /dev/null
+++ b/doc/components/checkbox.md
@@ -0,0 +1,50 @@
+# Checkbox
+
+Checkbox lets users select one, several, or no options, with each option operating independently.
+
+## Usage
+
+### Use for
+
+- Allowing multiple selections in a set where choices are not mutually exclusive
+- Capturing binary opt-in/opt-out preferences for a single option
+- Presenting independent options that users can toggle in any order
+- Supporting clear keyboard and touch interaction for inclusive form completion
+
+### Don't use for
+
+- Do not use checkboxes when only one option can be selected (use radio pattern instead)
+- Do not group unrelated options under the same checkbox set without clear context
+- Do not rely on visual check state alone; always provide clear labels or accessible naming
+- Do not use checkbox interactions for read-only status indicators
+- Do not compose a standalone checkbox inside row layouts that already support checkboxes; use `Row` or
+ `BoxedRow` with built-in checkbox support instead
+
+## Accessibility
+
+### Accessibility label
+
+Each checkbox needs a clear accessible name.
+
+- Prefer a visible text label (`children`) when possible
+- Use `aria-label` or `aria-labelledby` when no visible label is available
+- Avoid generic labels such as "Option" without contextual meaning
+
+### Role
+
+Checkbox defaults to `role="checkbox"` and exposes checked state through `aria-checked`.
+
+- Use `role="menuitemcheckbox"` only when the checkbox is part of a menu pattern
+- Keep role semantics aligned with the surrounding UI context
+
+### Keyboard interaction
+
+Checkbox supports keyboard toggling with `Space` when enabled.
+
+- Ensure disabled checkboxes are not focusable/actionable
+- Do not block or override standard keyboard behavior in custom wrappers
+
+### Group context
+
+When several checkboxes represent one decision set, provide clear group context (for example, heading or
+fieldset/legend) so relationships are understandable to assistive technologies.
diff --git a/doc/components/chip.md b/doc/components/chip.md
new file mode 100644
index 0000000000..acbc855435
--- /dev/null
+++ b/doc/components/chip.md
@@ -0,0 +1,47 @@
+# Chip
+
+Chip is a compact interactive label element used for navigation, selection state, or removable contextual
+metadata. Use Tag instead when the content is non-interactive status/category information.
+
+## Usage
+
+### Use for
+
+- Offering compact navigation entry points in horizontal groups or dense UI areas
+- Showing selectable/toggled state in lightweight filter or option sets
+- Displaying removable tags with a close action when users need to dismiss applied context
+- Adding optional iconography or badge counters to improve discoverability and status signaling
+
+### Don't use for
+
+- Do not use chips as the primary call-to-action for critical task completion
+- Do not overload chips with long labels; keep text short and scannable
+- Do not use Chip for passive status/category labels with no interaction; use Tag in those cases
+- Do not mix too many chip behaviors (navigation, toggle, close) in one group without clear intent
+- Do not rely on badge or icon alone to convey meaning; label text should stay self-explanatory
+
+## Accessibility
+
+### Accessibility label
+
+The accessible name of each chip should match its visible text label and remain descriptive in context.
+
+- Use clear, specific chip text labels (avoid ambiguous labels like `More` without context)
+- When repeated labels are unavoidable, add contextual accessible naming in the interactive wrapper
+- Keep label meaning consistent between visible text and screen reader output
+
+### Chip with close button
+
+Dismissible chips expose a dedicated close action as a button, announced by assistive technologies with a
+localized close/remove label by default.
+
+- Use `closeButtonLabel` when the default close wording is not specific enough for the context
+- Prefer contextual labels such as `Remove filter: Sports` instead of generic `Close`
+- Ensure visual removal is paired with clear announced intent through the dismiss button label
+
+### Active chip
+
+When chips represent active filters or selected state, do not rely only on color to communicate state.
+
+- Prefer adding a leading icon to reinforce active state
+- Keep active-state meaning understandable in both visual and non-visual usage contexts
diff --git a/doc/components/community.md b/doc/components/community.md
new file mode 100644
index 0000000000..088c4e2784
--- /dev/null
+++ b/doc/components/community.md
@@ -0,0 +1,125 @@
+# Community
+
+## AdvancedDataCard
+
+AdvancedDataCard is an extended data card that combines structured content (title hierarchy, description) with
+composable extra blocks, optional footer actions, and touchable behavior in a single card surface.
+
+### Usage
+
+#### Use for
+
+- Displaying data-rich summaries that need composable extra content blocks (value blocks, progress blocks,
+ etc.)
+- Building modular cards that combine text hierarchy with structured data visualizations
+- Presenting detailed information with optional footer actions (buttons, images, links)
+
+#### Don't use for
+
+- Simple data presentations where a standard DataCard is sufficient
+- Layouts that don't require composable extra blocks — prefer DataCard instead
+- Non-card contexts where a list row or standalone block is more appropriate
+
+## HighlightedValueBlock
+
+HighlightedValueBlock displays prominent numeric or text values with optional headline, pretitle,
+strikethrough pricing, and supporting descriptions. Designed to be used as an extra block inside
+AdvancedDataCard.
+
+### Usage
+
+#### Use for
+
+- Highlighting key values (prices, scores, quantities) with large typography emphasis
+- Showing price comparisons with strikethrough values and promotional headlines
+- Displaying multiple heading-value pairs with supporting descriptions
+
+#### Don't use for
+
+- Simple single-line value display — use ValueBlock instead
+- Content that doesn't need visual emphasis on numeric values
+
+## InformationBlock
+
+InformationBlock presents a title and description alongside a right-aligned value with optional secondary
+strikethrough value. Designed to be used as an extra block inside AdvancedDataCard.
+
+### Usage
+
+#### Use for
+
+- Showing labeled data with a corresponding value (e.g., plan details with pricing)
+- Displaying value comparisons with a secondary strikethrough value
+
+#### Don't use for
+
+- Standalone information display outside of a card context
+- Complex data that requires more than a single value pair
+
+## ProgressBlock
+
+ProgressBlock combines a title, progress bar, heading value, and optional description in a single block.
+Designed to be used as an extra block inside AdvancedDataCard.
+
+### Usage
+
+#### Use for
+
+- Showing progress toward a goal with a visual progress bar and numeric value
+- Displaying consumption or usage metrics with contextual descriptions
+
+#### Don't use for
+
+- Standalone progress indicators outside of a card — use ProgressBar directly
+- Simple percentage display without supporting context
+
+## RowBlock
+
+RowBlock displays a title with either a right-aligned description or a stacking group in a horizontal row
+layout. Designed to be used as an extra block inside AdvancedDataCard.
+
+### Usage
+
+#### Use for
+
+- Displaying key-value pairs in a horizontal layout within a card
+- Showing a label with a right-aligned stacking group (e.g., avatars, icons)
+
+#### Don't use for
+
+- Complex multi-line content — use InformationBlock or other blocks instead
+- Standalone rows outside of a card context — use Row or BoxedRow instead
+
+## SimpleBlock
+
+SimpleBlock displays an image alongside a description with an optional right-aligned text. Designed to be used
+as an extra block inside AdvancedDataCard.
+
+### Usage
+
+#### Use for
+
+- Showing a small image with a text description inside a card
+- Displaying brand logos or icons with accompanying labels
+
+#### Don't use for
+
+- Image-heavy layouts — use MediaCard or CoverCard instead
+- Content without an image — use RowBlock instead
+
+## ValueBlock
+
+ValueBlock displays a title with a large prominent value and optional description lines. Designed to be used
+as an extra block inside AdvancedDataCard.
+
+### Usage
+
+#### Use for
+
+- Showing a single key metric or value with a label and optional description
+- Displaying currency amounts, scores, or quantities with emphasis
+
+#### Don't use for
+
+- Multiple values with comparison — use HighlightedValueBlock instead
+- Values that need a progress indicator — use ProgressBlock instead
diff --git a/doc/components/component-categories.js b/doc/components/component-categories.js
new file mode 100644
index 0000000000..0a34a0c110
--- /dev/null
+++ b/doc/components/component-categories.js
@@ -0,0 +1,390 @@
+// @ts-check
+// Component categories based on Storybook structure (src/__stories__)
+// Each category maps to a grouped file in doc/components/ and skills/mistica-react/references/components/
+
+/** @type {Record} */
+const categories = {
+ accordions: {
+ title: 'Accordions',
+ components: ['Accordion', 'AccordionItem', 'BoxedAccordion', 'BoxedAccordionItem'],
+ },
+ buttons: {
+ title: 'Buttons',
+ components: [
+ 'ButtonPrimary',
+ 'ButtonSecondary',
+ 'ButtonDanger',
+ 'ButtonLink',
+ 'ButtonLinkDanger',
+ 'IconButton',
+ 'ToggleIconButton',
+ 'ButtonGroup',
+ 'ButtonFixedFooterLayout',
+ 'ButtonLayout',
+ ],
+ },
+ cards: {
+ title: 'Cards',
+ components: [
+ 'DataCard',
+ 'MediaCard',
+ 'CoverCard',
+ 'NakedCard',
+ 'HighlightedCard',
+ 'PosterCard',
+ 'SnapCard',
+ 'SmallNakedCard',
+ 'DisplayDataCard',
+ 'DisplayMediaCard',
+ 'EmptyStateCard',
+ 'CardActionIconButton',
+ 'CardActionSpinner',
+ ],
+ },
+ carousels: {
+ title: 'Carousels',
+ components: [
+ 'Carousel',
+ 'CenteredCarousel',
+ 'Slideshow',
+ 'PageBullets',
+ 'CarouselAutoplayControl',
+ 'CarouselContextConsumer',
+ 'CarouselContextProvider',
+ 'CarouselPageControls',
+ 'useCarouselContext',
+ ],
+ },
+ mosaic: {
+ title: 'Mosaic',
+ components: ['HorizontalMosaic', 'VerticalMosaic'],
+ },
+ 'data-visualizations': {
+ title: 'Data Visualizations',
+ components: ['Meter'],
+ },
+ 'progress-indicators': {
+ title: 'Progress Indicators',
+ components: ['ProgressBar', 'ProgressBarStepped'],
+ },
+ 'empty-states': {
+ title: 'Empty States',
+ components: ['EmptyState'],
+ },
+ feedback: {
+ title: 'Feedback',
+ components: [
+ 'FeedbackScreen',
+ 'ErrorFeedbackScreen',
+ 'InfoFeedbackScreen',
+ 'SuccessFeedbackScreen',
+ 'SuccessFeedback',
+ ],
+ },
+ snackbar: {
+ title: 'Snackbar',
+ components: ['Snackbar', 'useSnackbar'],
+ },
+ callout: {
+ title: 'Callout',
+ components: ['Callout'],
+ },
+ tooltip: {
+ title: 'Tooltip',
+ components: ['Tooltip'],
+ },
+ popover: {
+ title: 'Popover',
+ components: ['Popover'],
+ },
+ forms: {
+ title: 'Forms',
+ components: ['Form', 'useForm', 'useFieldProps'],
+ },
+ checkbox: {
+ title: 'Checkbox',
+ components: ['Checkbox'],
+ },
+ 'radio-button': {
+ title: 'Radio Button',
+ components: ['RadioButton', 'RadioGroup'],
+ },
+ select: {
+ title: 'Select',
+ components: ['Select'],
+ },
+ switch: {
+ title: 'Switch',
+ components: ['Switch'],
+ },
+ slider: {
+ title: 'Slider',
+ components: ['Slider'],
+ },
+ counter: {
+ title: 'Counter',
+ components: ['Counter'],
+ },
+ headers: {
+ title: 'Headers',
+ components: ['Header', 'HeaderLayout', 'MainSectionHeader', 'MainSectionHeaderLayout'],
+ },
+ hero: {
+ title: 'Hero',
+ components: ['Hero', 'CoverHero'],
+ },
+ hooks: {
+ title: 'Hooks',
+ components: [
+ 'useDocumentVisibility',
+ 'useElementDimensions',
+ 'useIsInViewport',
+ 'useIsInverseVariant',
+ 'useIsInverseOrMediaVariant',
+ 'useModalState',
+ 'useScreenSize',
+ 'useTheme',
+ 'useThemeVariant',
+ 'useWindowHeight',
+ 'useWindowSize',
+ 'useWindowWidth',
+ ],
+ },
+ 'input-fields': {
+ title: 'Input Fields',
+ components: [
+ 'TextField',
+ 'TextFieldBase',
+ 'EmailField',
+ 'PasswordField',
+ 'SearchField',
+ 'IntegerField',
+ 'DecimalField',
+ 'PhoneNumberField',
+ 'PhoneNumberFieldLite',
+ 'IbanField',
+ 'PinField',
+ 'Autocomplete',
+ 'DateField',
+ 'DateTimeField',
+ 'TimeField',
+ 'MonthField',
+ 'CreditCardFields',
+ 'CreditCardNumberField',
+ 'CreditCardExpirationField',
+ 'CvvField',
+ 'DoubleField',
+ 'formatPhoneLite',
+ 'FileUpload',
+ 'FileItem',
+ ],
+ },
+ layout: {
+ title: 'Layout',
+ components: [
+ 'ResponsiveLayout',
+ 'Grid',
+ 'GridItem',
+ 'GridLayout',
+ 'Stack',
+ 'Inline',
+ 'Box',
+ 'NegativeBox',
+ 'Boxed',
+ 'Align',
+ 'FixedFooterLayout',
+ 'FixedToTop',
+ 'MasterDetailLayout',
+ 'HorizontalScroll',
+ 'Divider',
+ ],
+ },
+ lists: {
+ title: 'Lists',
+ components: [
+ 'Row',
+ 'RowList',
+ 'BoxedRow',
+ 'BoxedRowList',
+ 'OrderedList',
+ 'UnorderedList',
+ 'ListItem',
+ ],
+ },
+ loading: {
+ title: 'Loading',
+ components: ['LoadingScreen', 'BrandLoadingScreen', 'LoadingBar', 'Spinner'],
+ },
+ modals: {
+ title: 'Modals',
+ components: [
+ 'Sheet',
+ 'SheetBody',
+ 'SheetRoot',
+ 'showSheet',
+ 'NativeSheetImplementation',
+ 'ActionsSheet',
+ 'ActionsListSheet',
+ 'InfoSheet',
+ 'RadioListSheet',
+ 'Drawer',
+ 'useDialog',
+ ],
+ },
+ menu: {
+ title: 'Menu',
+ components: ['Menu', 'MenuItem', 'MenuSection'],
+ },
+ 'navigation-bars': {
+ title: 'Navigation',
+ components: [
+ 'MainNavigationBar',
+ 'NavigationBar',
+ 'NavigationBarAction',
+ 'NavigationBarActionGroup',
+ 'FunnelNavigationBar',
+ ],
+ },
+ avatar: {
+ title: 'Avatar',
+ components: ['Avatar'],
+ },
+ badge: {
+ title: 'Badge',
+ components: ['Badge'],
+ },
+ breadcrumbs: {
+ title: 'Breadcrumbs',
+ components: ['Breadcrumbs'],
+ },
+ tag: {
+ title: 'Tag',
+ components: ['Tag'],
+ },
+ chip: {
+ title: 'Chip',
+ components: ['Chip'],
+ },
+ 'stacking-group': {
+ title: 'StackingGroup',
+ components: ['StackingGroup'],
+ },
+ stepper: {
+ title: 'Stepper',
+ components: ['Stepper'],
+ },
+ primitives: {
+ title: 'Primitives',
+ components: [
+ 'Image',
+ 'Video',
+ 'VideoElement',
+ 'Circle',
+ 'Touchable',
+ 'Placeholder',
+ 'FadeIn',
+ 'ScreenReaderOnly',
+ ],
+ },
+ rating: {
+ title: 'Rating',
+ components: ['Rating', 'InfoRating'],
+ },
+ skeletons: {
+ title: 'Skeletons',
+ components: ['SkeletonCircle', 'SkeletonLine', 'SkeletonRectangle', 'SkeletonRow', 'SkeletonText'],
+ },
+ skipLink: {
+ title: 'Skip Link',
+ components: ['SkipLink', 'SkipLinkNav'],
+ },
+ table: {
+ title: 'Table',
+ components: ['Table'],
+ },
+ tabs: {
+ title: 'Tabs',
+ components: ['Tabs'],
+ },
+ text: {
+ title: 'Text',
+ components: [
+ 'Text',
+ 'Text1',
+ 'Text2',
+ 'Text3',
+ 'Text4',
+ 'Text5',
+ 'Text6',
+ 'Text7',
+ 'Text8',
+ 'Text9',
+ 'Text10',
+ ],
+ },
+ textLink: {
+ title: 'Text Link',
+ components: ['TextLink'],
+ },
+ timer: {
+ title: 'Timer',
+ components: ['TextTimer', 'Timer'],
+ },
+ timeline: {
+ title: 'Timeline',
+ components: ['Timeline', 'TimelineItem'],
+ },
+ titles: {
+ title: 'Titles',
+ components: ['Title1', 'Title2', 'Title3', 'Title4'],
+ },
+ logo: {
+ title: 'Logo',
+ components: [
+ 'Logo',
+ 'BlauLogo',
+ 'EsimflagLogo',
+ 'MovistarLogo',
+ 'MovistarNewLogo',
+ 'O2Logo',
+ 'O2NewLogo',
+ 'TelefonicaLogo',
+ 'TuLogo',
+ 'VivoLogo',
+ ],
+ },
+ utilities: {
+ title: 'Utilities',
+ components: [
+ 'ThemeConfig',
+ 'ThemeContext',
+ 'ThemeContextProvider',
+ 'ThemeVariant',
+ 'TrackingConfig',
+ 'useTrackingConfig',
+ 'OverscrollColorProvider',
+ 'useSetOverscrollColor',
+ 'TopDistanceContext',
+ 'Overlay',
+ 'FocusTrap',
+ 'Portal',
+ 'applyAlpha',
+ 'createNestableContext',
+ 'NestableContext',
+ ],
+ },
+ community: {
+ title: 'Community',
+ components: [
+ 'AdvancedDataCard',
+ 'HighlightedValueBlock',
+ 'InformationBlock',
+ 'ProgressBlock',
+ 'RowBlock',
+ 'SimpleBlock',
+ 'ValueBlock',
+ ],
+ },
+};
+
+module.exports = {categories};
diff --git a/doc/components/counter.md b/doc/components/counter.md
new file mode 100644
index 0000000000..b96242170a
--- /dev/null
+++ b/doc/components/counter.md
@@ -0,0 +1,37 @@
+# Counter
+
+A counter is a component used to increase or decrease a numeric value.
+
+## Usage
+
+### Use for
+
+- Letting users adjust quantities in clear step-by-step increments
+- Managing bounded numeric values where minimum and maximum limits matter
+- Replacing a free numeric input when quick tap-based increase/decrease is preferable
+- Supporting basket-like flows where reaching minimum can map to a remove action
+
+### Don't use for
+
+- Do not use for large-range or high-precision numeric editing that needs direct text input
+- Do not hide the meaning of the value; provide nearby context for what is being counted
+- Do not allow counter use when quantity changes should be blocked by business constraints
+- Do not use remove-at-min behavior unless deletion is a clear and expected outcome
+
+## Accessibility
+
+### Accessibility label
+
+Counter supports dedicated accessibility labels for each action and for the value announcement.
+
+- `increaseLabel` for the add button
+- `decreaseLabel` for the decrease button
+- `removeLabel` for the remove action (when min value maps to delete)
+- `valueLabel` for the live-announced quantity context
+
+Use clear, contextual wording so users understand both the action and its effect on quantity.
+
+### Value announcement
+
+The counter value is announced through a live region (`aria-live="polite"`). Include meaningful `valueLabel`
+context (for example, `items in cart`) so announcements remain explicit when the number changes.
diff --git a/doc/components/data-visualizations.md b/doc/components/data-visualizations.md
new file mode 100644
index 0000000000..25eb03d910
--- /dev/null
+++ b/doc/components/data-visualizations.md
@@ -0,0 +1,48 @@
+# Data Visualizations
+
+## Meter
+
+Meter visualizes values within a bounded range using segmented linear, angular, or circular shapes, with
+optional extra content for context.
+
+### Usage
+
+#### Use for
+
+- Showing one or multiple quantitative segments inside a fixed 0–100 range
+- Comparing distribution across categories when segmented arcs or bars improve readability
+- Choosing linear, angular, or circular meter shapes according to available space and emphasis
+- Displaying summary value context with optional extra content near the chart
+
+#### Don't use for
+
+- Do not use Meter as a task completion indicator with explicit step progression; use ProgressBar instead
+- Do not overload the visualization with too many tiny segments that become visually indistinguishable
+- Do not use decorative colors without clear semantic meaning across segments
+- Do not hide critical quantitative meaning only in color; provide understandable surrounding context
+
+## Accessibility
+
+### Text alternative for meter information
+
+Ensure the information represented by Meter is also available in nearby text (title, legend, or summary).
+
+- Do not rely only on shape/color to communicate value meaning
+- Include explicit context such as metric name, current value, and limit/reference
+
+### Hide from screen readers
+
+Meter can be hidden from assistive technologies with `aria-hidden`. Use this only when equivalent value and
+context are already provided in surrounding accessible text.
+
+- If Meter is hidden, ensure adjacent content fully explains the metric
+- Example context: `Data Usage` + `You have used 75% of your 100 GB monthly limit`
+
+### Accessibility label
+
+By default, Meter is announced with percentage-based value semantics (for example, progress-style output with
+current value and segment breakdown).
+
+- Use `aria-label` to customize announcement wording when the metric uses units like `GB`, `steps`, or
+ `tasks completed`
+- Use `aria-labelledby` when a visible title/legend should provide the accessible name
diff --git a/doc/components/empty-states.md b/doc/components/empty-states.md
new file mode 100644
index 0000000000..326d1b4a5a
--- /dev/null
+++ b/doc/components/empty-states.md
@@ -0,0 +1,20 @@
+# Empty States
+
+EmptyState communicates full-page absence scenarios with clear messaging, supportive imagery, and optional
+recovery actions.
+
+## Usage
+
+### Use for
+
+- Handling full-view no-content or first-use scenarios that need explanation and guidance
+- Combining clear title + short description with one focused action path
+- Supporting visual reinforcement through icon, small image, or large illustrative image variants
+- Guiding users toward next steps without leaving the current context
+
+### Don't use for
+
+- Do not use EmptyState for temporary loading or transient errors that need other feedback patterns
+- Do not overload the screen with long emotional copy and multiple competing actions
+- Do not use decorative imagery without clear explanatory message and actionable next step
+- Do not mix multiple empty-state visual styles in one flow without a clear hierarchy rationale
diff --git a/doc/components/feedback.md b/doc/components/feedback.md
new file mode 100644
index 0000000000..74d763f2d2
--- /dev/null
+++ b/doc/components/feedback.md
@@ -0,0 +1,110 @@
+# Feedback
+
+## FeedbackScreen
+
+FeedbackScreen is the base full-screen feedback pattern for communicating important status moments with
+message hierarchy and optional actions.
+
+### Usage
+
+#### Use for
+
+- Building focused status screens with clear structure: visual asset, title, description, optional extra
+ context
+- Presenting decisive moments where users need explicit guidance before continuing
+- Keeping action completion accessible with anchored footer actions on smaller viewports
+- Supporting responsive feedback layouts with optional media support and consistent message hierarchy
+
+#### Don't use for
+
+- Do not use a full feedback screen for minor status updates that can be communicated inline
+- Do not use `FeedbackScreen` for inline or section-level confirmation; use `SuccessFeedback` instead
+- Do not overload the screen with long copy and multiple competing actions
+- Do not mix feedback intent (success, info, error) in one message block without a clear dominant outcome
+- Do not remove clear next-step actions when the user must recover or continue
+
+## ErrorFeedbackScreen
+
+ErrorFeedbackScreen presents a dedicated full-screen error state with clear explanation and recovery actions
+when in-flow error handling is not enough.
+
+### Usage
+
+#### Use for
+
+- Handling blocking failures where users cannot continue without explicit recovery guidance
+- Showing clear error context with optional reference details for support or troubleshooting
+- Providing focused next steps through one primary recovery action and optional secondary options
+- Communicating critical failure states with strong visual signal and consistent layout hierarchy
+
+#### Don't use for
+
+- Do not use full-screen error feedback for minor inline validation or non-blocking issues
+- Do not overload the screen with technical detail that prevents fast user recovery
+- Do not present multiple competing actions when one clear recovery path is available
+- Do not hide contextual information users need to understand what failed and what to do next
+
+## InfoFeedbackScreen
+
+InfoFeedbackScreen presents neutral, informative full-screen feedback with optional actions to help users
+decide the next step.
+
+### Usage
+
+#### Use for
+
+- Explaining important neutral states that need user attention but are not errors or explicit success outcomes
+- Providing contextual information plus one clear action to continue, learn more, or retry later
+- Presenting policy, status, or eligibility messages that require acknowledgment in a focused layout
+- Keeping informational communication consistent with the broader feedback-screen family
+
+#### Don't use for
+
+- Do not use this pattern for destructive failures that require error-oriented feedback
+- Do not use it for celebratory completion states that should use success feedback patterns
+- Do not overload informational screens with long content better suited to dedicated pages
+- Do not present ambiguous messaging without a clear user next step
+
+## SuccessFeedbackScreen
+
+SuccessFeedbackScreen communicates completion of an important action with positive visual reinforcement and
+optional follow-up actions.
+
+### Usage
+
+#### Use for
+
+- Confirming meaningful task completion when users benefit from an explicit success moment
+- Reinforcing positive outcomes with clear title, supportive description, and optional next-step actions
+- Handling end-of-flow confirmations where users need certainty before moving on
+- Providing a consistent success pattern across skins and responsive layouts
+
+#### Don't use for
+
+- Do not use a dedicated success screen for routine actions that can be acknowledged inline
+- Do not interrupt user flow with celebratory feedback when immediate continuation is expected
+- Do not add excessive messaging once success is already clear from context
+- Do not present too many post-success actions that dilute the primary next step
+
+## SuccessFeedback
+
+Use success feedback for inline or section-level confirmation after a completed action, with optional
+supporting text, actions, and image.
+
+### Usage
+
+#### Use for
+
+- Confirming that an operation finished successfully without taking over the whole screen
+- Showing a clear success message with optional description, extra contextual content, and follow-up actions
+- Embedding success feedback inside longer pages or flows where additional content remains visible below
+- Reinforcing positive completion states with success iconography and optional brand/image treatment
+
+#### Don't use for
+
+- Do not use for error or neutral informational states; use the corresponding feedback variant
+- Do not use when users must pause on a dedicated completion screen; choose the full-screen feedback pattern
+ instead
+- Do not overload the component with dense content or many actions; keep completion messaging concise
+- Do not rely on visual treatment alone for next steps; provide explicit action labels when continuation is
+ required
diff --git a/doc/components/forms.md b/doc/components/forms.md
new file mode 100644
index 0000000000..cc5cfcdec0
--- /dev/null
+++ b/doc/components/forms.md
@@ -0,0 +1,94 @@
+# Forms
+
+## Form
+
+Form orchestrates field registration, validation, submission state, and accessibility error announcements for
+Mística form flows.
+
+### Usage
+
+#### Use for
+
+- Handling form submission with validated values and normalized raw values
+- Keeping field validation, required checks, and error state consistent across inputs
+- Coordinating multi-field flows with optional auto-jump behavior and next-field progression
+- Managing submit/loading state so fields are automatically disabled while sending
+- Announcing grouped submit errors to screen readers in a single form-level summary
+
+#### Don't use for
+
+- Do not bypass Form when fields need shared validation/submission behavior
+- Do not submit forms without clear field labels; error summaries use registered field labels
+- Do not rely only on visual errors; preserve screen-reader error announcements
+- Do not keep disabled fields as required validation targets; disabled fields are excluded from
+ validation/submission
+
+## useForm
+
+useForm exposes Form context state and actions for advanced field orchestration and custom form components.
+
+### Usage
+
+#### Use for
+
+- Reading form status (`filling`/`sending`) and current values from custom field components
+- Triggering form validation/submission or custom navigation flows (`jumpToNext`)
+- Registering custom focusable controls and setting field-level errors programmatically
+- Integrating non-text controls with form state while preserving shared behavior
+
+#### Don't use for
+
+- Do not use it outside a Form context for production logic
+- Do not duplicate context state manually when Form already provides it
+- Do not skip field registration in custom controls that need validation, focus, or summary integration
+
+## useFieldProps
+
+useFieldProps connects text-like inputs to Form with value processing, validation, labeling, and error
+handling.
+
+### Usage
+
+#### Use for
+
+- Wiring custom text inputs to Form state (`rawValues` and processed `values`)
+- Reusing blur validation rules (required + custom validator)
+- Keeping helper text/error messaging and disabled/sending states synchronized
+- Registering input references so Form can focus and summarize fields with errors
+
+#### Don't use for
+
+- Do not use it for controls that are not input-like text fields
+- Do not mix incompatible controlled/uncontrolled patterns in the same field
+- Do not override label/error semantics in ways that break error summary announcements
+
+## Accessibility
+
+### Accessibility label
+
+Give every field a clear label users can understand quickly.
+
+- Use helper/error text to explain constraints and recovery steps, not as decoration
+
+### Error announcements
+
+Plan error feedback at two levels:
+
+- Field-level: immediate feedback near the affected input
+- Form-level: one summary when multiple fields fail on submit
+
+By default, the summary starts with:
+
+- "Check the following errors:" (localized in supported languages)
+
+Customize the summary text when default wording is not specific enough for your flow.
+
+### Focus and navigation on errors
+
+- Move users to the first blocking issue after submit
+- Avoid aggressive auto-focus behavior that causes unexpected picker popups
+
+### Disabled fields
+
+- Do not expect disabled fields to be completed or validated
+- Keep disabled state intentional and clearly explained when needed
diff --git a/doc/components/headers.md b/doc/components/headers.md
new file mode 100644
index 0000000000..55c5865f27
--- /dev/null
+++ b/doc/components/headers.md
@@ -0,0 +1,124 @@
+# Headers
+
+## Header
+
+Header organizes section-level textual hierarchy with optional headline, pretitle, title, and description in a
+readable, accessible structure.
+
+### Usage
+
+#### Use for
+
+- Presenting section intros where users need clear context before interacting with content
+- Structuring short content hierarchy (headline, pretitle, title, description) without creating custom
+ typography stacks
+- Adapting header density with standard and small visual modes while preserving hierarchy
+- Keeping semantic heading order clear when title and pretitle levels differ
+
+#### Don't use for
+
+- Do not overload the header with long paragraph content better suited to body sections
+- Do not use conflicting heading levels that weaken document hierarchy
+- Do not add decorative text layers that compete with the main title intent
+- Do not treat Header as a full page shell when layout orchestration is needed
+
+## HeaderLayout
+
+HeaderLayout provides the responsive shell for page headers, combining breadcrumbs, header content, and
+optional extra areas in one coherent top section.
+
+### Usage
+
+#### Use for
+
+- Composing page-top structures that combine navigation breadcrumbs and header messaging
+- Positioning optional extra content below or side-by-side with the main header depending on viewport strategy
+- Managing branded and default header background behavior consistently across responsive layouts
+- Enabling controlled bleed-style transitions for hero-like top sections when needed
+
+#### Don't use for
+
+- Do not use HeaderLayout when only simple text heading content is needed without layout composition
+- Do not mix side-by-side and stacked extra content patterns inconsistently within the same flow
+- Do not force bleed/brand treatment where the page context does not require high-emphasis top sections
+- Do not skip responsive spacing logic for breadcrumbs and header presence
+
+## MainSectionHeader
+
+MainSectionHeader introduces major sections with high-prominence title, optional supporting description, and
+optional primary action.
+
+### Usage
+
+#### Use for
+
+- Introducing top-level sections where users need immediate orientation and emphasis
+- Pairing concise section context with one clear, related call to action
+- Creating strong visual hierarchy for key content entry points in desktop and mobile layouts
+- Supporting page starts where section intent should be explicit before users scroll
+
+#### Don't use for
+
+- Do not use it for low-priority subsection headings that need lighter hierarchy
+- Do not add multiple competing actions that weaken the main section intent
+- Do not combine with oversized adjacent navigation elements that create visual overload
+- Do not write long descriptive blocks where concise section framing is expected
+
+## MainSectionHeaderLayout
+
+MainSectionHeaderLayout wraps MainSectionHeader in a responsive, brand-aware top-area layout with consistent
+spacing and width control.
+
+### Usage
+
+#### Use for
+
+- Placing `MainSectionHeader` within a consistent page-top container across breakpoints
+- Applying predictable horizontal/vertical spacing for major section introductions
+- Enabling brand-variant top-area treatment while keeping content width readable
+- Standardizing top-section layout in pages that repeat the same header composition
+
+#### Don't use for
+
+- Do not use this layout wrapper when your header is not a `MainSectionHeader` pattern
+- Do not combine inconsistent top spacing systems in adjacent sections
+- Do not force brand-style top treatment in neutral contexts without design rationale
+- Do not treat this as a generic content container for non-header page regions
+
+## Accessibility
+
+### Heading hierarchy
+
+Header heading levels are configurable.
+
+- `Header` title defaults to `h2` (`titleAs`) and supports `h1` to `h6`
+- `MainSectionHeader` title defaults to `h1` (`titleAs`)
+- `Header` pretitle supports `h1` to `h6` (`pretitleAs`) and is non-heading by default
+
+If you change defaults:
+
+- If only one heading exists, that heading is announced first
+- If both pretitle and title are headings, the one with higher hierarchy is read first
+- Do not assign the same heading level to pretitle and title
+
+### Text limitation
+
+Headers support visual text truncation.
+
+- Prefer layouts that expose full text
+- If truncation is required, keep complete meaning available to assistive technologies
+- Do not truncate critical section intent
+
+### Slot
+
+Header compositions can include custom content (headline nodes, breadcrumbs, or `extra` in `HeaderLayout`).
+Because these areas are fully customizable, ensure custom controls, icons, and media preserve accessible names,
+focus order, and semantics.
+
+### Breadcrumbs and page-top composition
+
+In `HeaderLayout`, breadcrumbs and header content are composed at the top of the page.
+
+- Ensure breadcrumbs use a clear navigation label and current-page semantics
+- Keep header text concise so users can quickly understand page context before main content
+- Do not duplicate equivalent top-level headings in adjacent regions
diff --git a/doc/components/hero.md b/doc/components/hero.md
new file mode 100644
index 0000000000..0a673603f2
--- /dev/null
+++ b/doc/components/hero.md
@@ -0,0 +1,108 @@
+# Hero
+
+## Hero
+
+A hero is a promotional section at the top of the page with clear call-to-action focus; use CoverHero instead
+when you need media as the background.
+
+### Usage
+
+#### Use for
+
+- Introducing high-priority page narratives with strong visual impact and clear user direction
+- Combining media and messaging in a balanced hero composition that adapts across breakpoints
+- Placing one primary action (plus optional supporting actions) near the core value proposition
+- Supporting campaign and discovery surfaces where top-of-page emphasis is intentional
+- Using foreground media composition (not full media background) when content hierarchy must stay clear
+- As a slide in a slideshow for presenting multiple content
+
+#### Don't use for
+
+- Do not use hero treatments for low-priority content that does not need top-level emphasis
+- Do not overload the hero with excessive text, extra slots, and competing actions
+- Do not let media dominate readability; headline and CTA should remain clear and actionable
+- Do not mix inconsistent media placement and background variants without clear layout rationale
+- Do not use Hero when the section requires image/video as background; use CoverHero instead
+
+## CoverHero
+
+CoverHero is a high-impact hero section that combines strong heading hierarchy, optional media background, and
+grouped call-to-action buttons; choose it instead of Hero when media needs to be the section background.
+
+### Usage
+
+#### Use for
+
+- Presenting key page narratives where title, supporting copy, and actions need immediate prominence
+- Building campaign or landing headers with optional background image/video and readable foreground content
+- Pairing main hero messaging with optional side content for complementary context or utility
+- Structuring primary and secondary actions in a consistent hero action group across breakpoints
+- Choosing a hero pattern where media must sit behind content as the background layer
+
+#### Don't use for
+
+- Do not use CoverHero for low-priority sections that do not need top-of-page emphasis
+- Do not overload the hero with excessive text, multiple side elements, and too many actions at once
+- Do not rely on media alone; ensure text hierarchy remains readable over backgrounds
+- Do not use centered and side-content compositions together when they create ambiguous visual focus
+- Do not use CoverHero when media does not need to be background; use Hero for standard foreground
+ compositions
+
+## Accessibility
+
+### Heading hierarchy
+
+Hero heading levels are configurable.
+
+- Title defaults to `h1` (`titleAs`) and supports `h1` to `h6`
+- Pretitle is non-heading by default (`span`) and can be configured with `pretitleAs`
+
+If you change defaults:
+
+- If only one heading exists, that heading is announced first
+- If both pretitle and title are headings, the one with higher hierarchy is read first
+- Do not assign the same heading level to pretitle and title
+
+### Accessibility label
+
+Hero actions should have clear accessible names.
+
+- Assign an accessibility label to each action when visible text is not enough to explain the outcome
+- If multiple actions have similar visible text, add contextual labels so screen reader users can distinguish
+ them
+
+### Images and videos
+
+#### Images
+
+If the hero includes an image:
+
+- Provide descriptive alt text that explains the image content and purpose
+
+If the image is used as a CoverHero background (`backgroundImage`):
+
+- It is treated as decorative and ignored by screen readers
+
+#### Videos
+
+If the hero includes a video:
+
+- If playback exceeds 5 seconds, provide controls so users can pause/stop playback
+- Ensure subtitles are available when the video includes meaningful audio
+- Avoid distraction; pause or stop autoplaying media when it is no longer visible
+
+For additional media guidance, see the accessibility sections in Fundamentals, Customization, and Primitives,
+and the Meter accessibility guidance in Data visualizations.
+
+### Text limitation
+
+Hero supports visual text truncation (`descriptionLinesMax`, `titleLinesMax`, `pretitleLinesMax`).
+
+- Prefer layouts that expose full text
+- If truncation is required, keep complete meaning available to assistive technologies
+
+### Slot
+
+Hero and CoverHero allow custom content through slots (`extra`, `sideExtra`, `headline`). Because these areas
+are fully customizable, ensure custom controls, icons, and media preserve accessible names, focus order, and
+semantics.
diff --git a/doc/components/hooks.md b/doc/components/hooks.md
new file mode 100644
index 0000000000..70f72c0c79
--- /dev/null
+++ b/doc/components/hooks.md
@@ -0,0 +1,193 @@
+# Hooks
+
+## useDocumentVisibility
+
+useDocumentVisibility provides reusable behavior to keep component logic consistent across the product.
+
+### Usage
+
+#### Use for
+
+- Sharing common state and behavior across multiple components
+- Keeping implementation aligned with Mística patterns
+
+#### Don't use for
+
+- Do not duplicate equivalent logic when this utility already exists
+- Do not use it without understanding its side effects and scope
+
+## useElementDimensions
+
+useElementDimensions provides reusable behavior to keep component logic consistent across the product.
+
+### Usage
+
+#### Use for
+
+- Sharing common state and behavior across multiple components
+- Keeping implementation aligned with Mística patterns
+
+#### Don't use for
+
+- Do not duplicate equivalent logic when this utility already exists
+- Do not use it without understanding its side effects and scope
+
+## useIsInViewport
+
+useIsInViewport provides reusable behavior to keep component logic consistent across the product.
+
+### Usage
+
+#### Use for
+
+- Sharing common state and behavior across multiple components
+- Keeping implementation aligned with Mística patterns
+
+#### Don't use for
+
+- Do not duplicate equivalent logic when this utility already exists
+- Do not use it without understanding its side effects and scope
+
+## useIsInverseVariant
+
+useIsInverseVariant provides reusable behavior to keep component logic consistent across the product.
+
+### Usage
+
+#### Use for
+
+- Sharing common state and behavior across multiple components
+- Keeping implementation aligned with Mística patterns
+
+#### Don't use for
+
+- Do not duplicate equivalent logic when this utility already exists
+- Do not use it without understanding its side effects and scope
+
+## useIsInverseOrMediaVariant
+
+useIsInverseOrMediaVariant provides reusable behavior to keep component logic consistent across the product.
+
+### Usage
+
+#### Use for
+
+- Sharing common state and behavior across multiple components
+- Keeping implementation aligned with Mística patterns
+
+#### Don't use for
+
+- Do not duplicate equivalent logic when this utility already exists
+- Do not use it without understanding its side effects and scope
+
+## useModalState
+
+useModalState provides reusable behavior to keep component logic consistent across the product.
+
+### Usage
+
+#### Use for
+
+- Sharing common state and behavior across multiple components
+- Keeping implementation aligned with Mística patterns
+
+#### Don't use for
+
+- Do not duplicate equivalent logic when this utility already exists
+- Do not use it without understanding its side effects and scope
+
+## useScreenSize
+
+useScreenSize provides reusable behavior to keep component logic consistent across the product.
+
+### Usage
+
+#### Use for
+
+- Sharing common state and behavior across multiple components
+- Keeping implementation aligned with Mística patterns
+
+#### Don't use for
+
+- Do not duplicate equivalent logic when this utility already exists
+- Do not use it without understanding its side effects and scope
+
+## useTheme
+
+useTheme provides reusable behavior to keep component logic consistent across the product.
+
+### Usage
+
+#### Use for
+
+- Sharing common state and behavior across multiple components
+- Keeping implementation aligned with Mística patterns
+
+#### Don't use for
+
+- Do not duplicate equivalent logic when this utility already exists
+- Do not use it without understanding its side effects and scope
+
+## useThemeVariant
+
+useThemeVariant provides reusable behavior to keep component logic consistent across the product.
+
+### Usage
+
+#### Use for
+
+- Sharing common state and behavior across multiple components
+- Keeping implementation aligned with Mística patterns
+
+#### Don't use for
+
+- Do not duplicate equivalent logic when this utility already exists
+- Do not use it without understanding its side effects and scope
+
+## useWindowHeight
+
+useWindowHeight provides reusable behavior to keep component logic consistent across the product.
+
+### Usage
+
+#### Use for
+
+- Sharing common state and behavior across multiple components
+- Keeping implementation aligned with Mística patterns
+
+#### Don't use for
+
+- Do not duplicate equivalent logic when this utility already exists
+- Do not use it without understanding its side effects and scope
+
+## useWindowSize
+
+useWindowSize provides reusable behavior to keep component logic consistent across the product.
+
+### Usage
+
+#### Use for
+
+- Sharing common state and behavior across multiple components
+- Keeping implementation aligned with Mística patterns
+
+#### Don't use for
+
+- Do not duplicate equivalent logic when this utility already exists
+- Do not use it without understanding its side effects and scope
+
+## useWindowWidth
+
+useWindowWidth provides reusable behavior to keep component logic consistent across the product.
+
+### Usage
+
+#### Use for
+
+- Sharing common state and behavior across multiple components
+- Keeping implementation aligned with Mística patterns
+
+#### Don't use for
+
+- Do not duplicate equivalent logic when this utility already exists
+- Do not use it without understanding its side effects and scope
diff --git a/doc/components/input-fields.md b/doc/components/input-fields.md
new file mode 100644
index 0000000000..acc02c45d0
--- /dev/null
+++ b/doc/components/input-fields.md
@@ -0,0 +1,525 @@
+# Input Fields
+
+## TextField
+
+Use text field as the default Mística input for free-text entry, with built-in form integration, validation support, and optional suggestions.
+
+### Usage
+
+#### Use for
+
+- Most user-facing single-line text inputs in forms
+- Multiline free-text entry when users need to write longer content
+- Form flows that need consistent label, helper/error messaging, validation, and optional/required behavior
+- Inputs that benefit from controlled suggestions/autocomplete guidance
+- Scenarios where you want a ready-to-use field component instead of building directly on `TextFieldBase`
+
+#### Don't use for
+
+- Do not use for read-only display data
+- Do not rely on placeholder text as the only label
+- Do not hide helper/error context users need to complete a form correctly
+- Do not choose this component when a more specific field type (for example email, password, phone, or
+ numeric) better matches the input constraints
+- Do not use uncontrolled patterns for suggestion-driven inputs
+
+## TextFieldBase
+
+Foundation primitive used to build Mística text-input fields, including labeling, helper/error feedback, and shared interaction states.
+
+### Usage
+
+#### Use for
+
+- Creating or extending custom Mística field components on top of the shared text-input foundation
+- Collecting typed user input with a persistent label, placeholder support, and helper/error text
+- Fields that benefit from additional affordances such as prefix text, start/end icons, or optional copy
+ protection
+- Multiline inputs where users need character-count feedback against a maximum length
+- Guided entry scenarios with controlled suggestions/autocomplete behavior
+- Building consistent form fields that adapt to focus, filled, disabled, error, and read-only states
+
+#### Don't use for
+
+- Do not use as a passive display container for non-editable content
+- Do not choose this base primitive first when a specialized Mística field already covers the use case
+- Do not rely on placeholder text as the only field label; keep labels explicit and persistent
+- Do not hide validation/help context users need to recover from errors
+- Do not add suggestions in uncontrolled mode; suggestion-driven fields must keep input state controlled
+- Do not overload a single field with too many visual affordances if they reduce readability or input clarity
+
+## EmailField
+
+EmailField captures email addresses with email-optimized input behavior and built-in format validation.
+
+### Usage
+
+#### Use for
+
+- Collecting user email addresses in signup, login recovery, and contact flows
+- Providing email-specific keyboard/input mode support to reduce entry friction
+- Validating basic address structure early to prevent malformed submissions
+- Keeping identity/contact inputs consistent across forms with clear error feedback
+
+#### Don't use for
+
+- Do not use EmailField for usernames or identifiers that are not email addresses
+- Do not accept invalid email formatting without visible guidance to correct it
+- Do not hide required context (for example, why email is needed) in sensitive flows
+- Do not rely only on placeholder text; provide a clear, persistent field label
+
+## PasswordField
+
+PasswordField captures sensitive credentials with masked input, accessible show/hide control, and form validation support.
+
+### Usage
+
+#### Use for
+
+- Collecting account credentials and other sensitive secrets in authentication or security flows
+- Allowing users to reveal/hide password text when they need to verify typed content
+- Preserving editing continuity when toggling visibility so users can correct input confidently
+- Integrating with form-level validation, helper text, and optional state handling
+
+#### Don't use for
+
+- Do not use PasswordField for non-sensitive text inputs that should stay visible by default
+- Do not remove clear visibility-toggle affordance in contexts where typing errors are common
+- Do not expose sensitive values by default; visibility should remain user-controlled
+- Do not hide password requirements or error guidance when users need them to succeed
+
+## SearchField
+
+SearchField captures query input for discovery flows with optional search icon, clear action, and autosuggest integration.
+
+### Usage
+
+#### Use for
+
+- Capturing free-text queries in search and filtering experiences
+- Supporting suggestion-driven discovery when users need guidance while typing
+- Providing quick reset behavior through a clear control to restart search intent
+- Keeping search affordance recognizable with optional leading search icon
+
+#### Don't use for
+
+- Do not use SearchField for strict structured data inputs that require fixed formats
+- Do not overload search with heavy validation patterns that block exploratory typing
+- Do not hide no-results or empty-suggestion feedback when discovery relies on it
+- Do not remove clear affordance in long-query contexts where users need fast reset
+
+## IntegerField
+
+IntegerField captures whole-number input with digit-only sanitization and numeric keypad support on mobile devices.
+
+### Usage
+
+#### Use for
+
+- Collecting whole-number values such as quantities, counts, ages, or integer limits
+- Reducing input errors by automatically filtering non-numeric characters during typing
+- Supporting form flows where mobile numeric keyboard entry improves speed and accuracy
+- Pairing integer entry with helper text and validation feedback for allowed ranges or business rules
+
+#### Don't use for
+
+- Do not use IntegerField for decimal, currency, or formatted values that require separators
+- Do not use it for identifiers that may include letters or symbols
+- Do not rely on digit filtering alone when domain constraints also require min/max or rule-based validation
+- Do not hide range expectations; users should understand valid numeric boundaries before submission
+
+## DecimalField
+
+DecimalField captures numeric values with fractional precision, adapting decimal separator behavior to the user locale.
+
+### Usage
+
+#### Use for
+
+- Entering amounts, measurements, or rates that require decimal precision
+- Supporting international users with locale-appropriate decimal separator input behavior
+- Limiting fractional precision when business rules require fixed decimal scale
+- Reducing formatting errors by allowing only numeric and decimal-separator characters
+
+#### Don't use for
+
+- Do not use DecimalField for integer-only values when no fractional part is allowed
+- Do not allow unlimited decimals in flows that require strict precision consistency
+- Do not use this field for identifiers (for example card numbers or IDs) that are not numeric quantities
+- Do not hide expected number format when locale differences can create ambiguity
+
+## PhoneNumberField
+
+PhoneNumberField captures phone numbers with robust as-you-type international formatting and optional E.164 normalization.
+
+### Usage
+
+#### Use for
+
+- Capturing phone numbers in products that require reliable international formatting behavior
+- Guiding users with region-aware as-you-type formatting to reduce entry errors
+- Normalizing values to E.164 when backend systems require canonical phone formats
+- Supporting form validation and suggestion flows for contact and account verification journeys
+
+#### Don't use for
+
+- Do not use PhoneNumberField when lightweight local formatting is enough; use PhoneNumberFieldLite instead
+- Do not hide country/prefix expectations when users can enter numbers from multiple regions
+- Do not rely only on visual formatting as validation for number correctness
+- Do not use it for non-telephone identifiers that may include unrelated symbols or patterns
+
+## PhoneNumberFieldLite
+
+PhoneNumberFieldLite captures phone numbers with a lightweight formatter for a limited country set and common numbering patterns.
+
+### Usage
+
+#### Use for
+
+- Capturing phone numbers in performance-sensitive flows where a simplified formatter is sufficient
+- Supporting common phone patterns for the built-in country subset (for example ES, BR, DE, GB)
+- Keeping phone entry lightweight while still offering structured formatting and optional E.164 output
+- Handling products with constrained regional scope and predictable numbering conventions
+
+#### Don't use for
+
+- Do not use PhoneNumberFieldLite for broad international support with complex numbering rules; use
+ PhoneNumberField instead
+- Do not assume all national formats are covered; Lite intentionally handles a subset of cases
+- Do not use it when strict telecom-grade formatting fidelity is required across many countries
+- Do not hide regional limitations from product requirements and validation strategy
+
+## IbanField
+
+IbanField captures IBAN account identifiers with automatic formatting, uppercase normalization, and built-in IBAN validity checks.
+
+### Usage
+
+#### Use for
+
+- Capturing bank account identifiers specifically in IBAN format inside payment and account forms
+- Reducing entry errors with automatic grouping and uppercase normalization while users type
+- Providing immediate validation feedback when IBAN structure or checksum is invalid
+- Integrating with form flows that require label, helper text, optional state, and validation messaging
+
+#### Don't use for
+
+- Do not use IbanField for non-IBAN identifiers such as local account numbers without IBAN rules
+- Do not replace it with a generic text field when IBAN-specific validation is required
+- Do not hide or delay error guidance in critical payment steps where correction speed matters
+- Do not overload the field with unrelated instructions; keep helper text focused on IBAN entry
+
+## PinField
+
+PinField captures short verification codes in segmented digit inputs, with optional masked display and SMS one-time-code autofill support.
+
+### Usage
+
+#### Use for
+
+- Entering OTP, PIN, or verification codes where each digit should be clear and easy to scan
+- Supporting fast code completion with paste/autocomplete behavior across segmented inputs
+- Enabling SMS one-time-code autofill in flows where automatic code retrieval is expected
+- Using masked code presentation for higher-sensitivity verification steps
+
+#### Don't use for
+
+- Do not use PinField for long passwords or arbitrary free-text input
+- Do not hide helper/error feedback when code requirements or failures need clarification
+- Do not force SMS autofill in security contexts where code visibility must remain fully user-controlled
+- Do not use segmented code input when the journey does not rely on fixed-length numeric verification
+
+## Autocomplete
+
+Autocomplete helps users choose a valid value from suggested options while typing, with fast keyboard and touch interaction.
+
+### Usage
+
+#### Use for
+
+- Helping users find and select from a known set of values without scanning a long list
+- Reducing typing effort in fields where valid options can be suggested from partial input
+- Supporting fast keyboard flows (arrow navigation, enter to select, tab to confirm)
+- Providing a clear empty-state message when no suggestions match
+
+#### Don't use for
+
+- Do not use it for free-text fields when users should be allowed to submit any value
+- Do not provide ambiguous or very similar suggestions that are hard to distinguish
+- Do not hide critical options behind autocomplete when users need a full browsable list
+- Do not rely only on placeholder text; always provide a clear field label and context
+
+## DateField
+
+DateField captures calendar dates with platform-appropriate picker behavior and optional range constraints.
+
+### Usage
+
+#### Use for
+
+- Collecting single date values in forms where calendar precision is required
+- Guiding users with familiar native date-picking experiences when supported by the platform
+- Enforcing valid date windows (minimum and maximum) for business rules such as booking or eligibility
+- Keeping date entry consistent across browsers through fallback picker behavior when native support differs
+
+#### Don't use for
+
+- Do not use DateField for date-time capture when time selection is also required
+- Do not allow out-of-range dates without clear user feedback
+- Do not replace date pickers with free-text formats that increase entry errors
+- Do not use this field for non-date identifiers that only look numeric
+
+## DateTimeField
+
+DateTimeField captures a combined date and time value with platform-appropriate picker behavior and range validation.
+
+### Usage
+
+#### Use for
+
+- Scheduling scenarios where users must provide both calendar date and exact time in one step
+- Enforcing valid datetime windows for booking, delivery, reservation, or eligibility constraints
+- Providing native date-time selection when available while preserving cross-browser consistency through
+ fallback picker support
+- Keeping temporal input unified to reduce context switching between separate date and time fields
+
+#### Don't use for
+
+- Do not use DateTimeField when only a date or only a time is required
+- Do not allow out-of-range datetime values without explicit error feedback
+- Do not split tightly coupled date/time decisions across distant form areas
+- Do not replace picker interactions with ambiguous free-text datetime entry
+
+## TimeField
+
+information that the user needs to enter in the field.
+
+### Usage
+
+#### Use for
+
+- For a better understanding of input usage in forms read our forms documentation.
+- Collecting user input with clear labels and contextual help text
+- Supporting validation and accessible feedback in form flows
+
+#### Don't use for
+
+- Do not use this component to display read-only information
+- Do not hide validation context that users need to complete the task
+
+## MonthField
+
+MonthField captures month-and-year values with calendar affordance, range validation, and adaptive native/fallback picker behavior.
+
+### Usage
+
+#### Use for
+
+- Collecting month/year inputs such as billing cycle, subscription period, or contract start month
+- Restricting selection to allowed date ranges when business rules define valid periods
+- Providing consistent month selection experience across devices with native picker when available
+- Supporting form flows where users need clear validation feedback for out-of-range values
+
+#### Don't use for
+
+- Do not use MonthField when day-level precision is required; use a date field instead
+- Do not use it for free-form date text entry patterns that expect arbitrary formats
+- Do not hide min/max constraints from users when only specific months are valid
+- Do not use month selection for non-temporal categorical choices
+
+## CreditCardFields
+
+CreditCardFields groups card number, expiration date, and CVV into a single, optimized payment input block.
+
+### Usage
+
+#### Use for
+
+- Building checkout forms where core card inputs should be presented as one coherent unit
+- Preserving a familiar payment flow: card number first, then expiration and CVV together
+- Improving scanability and completion speed through structured spacing and paired secondary fields
+- Adapting security-code expectations to card type so users enter the right CVV length
+
+#### Don't use for
+
+- Do not split these fields across distant sections when users are expected to complete payment in one step
+- Do not rearrange the input order in ways that break common checkout expectations
+- Do not remove contextual labels for expiration and CVV; users need immediate field clarity
+- Do not use this grouped pattern outside card-payment scenarios
+
+## CreditCardNumberField
+
+CreditCardNumberField captures payment card numbers with guided spacing, card-type recognition, and validity-aware progression.
+
+### Usage
+
+#### Use for
+
+- Entering payment card numbers in checkout and billing flows with reduced input friction
+- Helping users scan and verify long numbers through automatic 4-digit grouping
+- Providing immediate brand cues (Visa, Mastercard, Amex) to increase confidence while typing
+- Enforcing accepted-card and validity constraints before moving users to the next field
+
+#### Don't use for
+
+- Do not use it for generic numeric identifiers outside card-payment contexts
+- Do not remove card validation feedback when accepted brands are restricted
+- Do not break familiar card-number grouping patterns with custom formatting
+- Do not auto-advance to the next step unless card length and validation are complete
+
+## CreditCardExpirationField
+
+CreditCardExpirationField captures card expiry in a guided `MM/YY` format with built-in validity checks.
+
+### Usage
+
+#### Use for
+
+- Capturing payment card expiration dates in a standardized and familiar format
+- Reducing input friction with automatic formatting and month normalization as users type
+- Validating expiry in context (month/year completeness and non-expired dates)
+- Supporting checkout flows where valid expiry should move users smoothly to the next step
+
+#### Don't use for
+
+- Do not use this field for generic date entry outside credit-card expiration use cases
+- Do not request full-date patterns (day/month/year) when only month and year are needed
+- Do not hide expiration errors; users should clearly understand when a card date is invalid or expired
+- Do not break the expected `MM/YY` interaction pattern with custom masking behavior
+
+## CvvField
+
+CvvField captures the card security code with numeric input, card-aware guidance, and strict length validation.
+
+### Usage
+
+#### Use for
+
+- Collecting card security codes in payment forms where CVV is required
+- Helping users locate the CVV with contextual visual guidance (info popover)
+- Enforcing the expected security-code length for the selected card context
+- Supporting smooth checkout progression when a valid CVV is completed
+
+#### Don't use for
+
+- Do not use this field for generic PIN or password entry outside card-payment flows
+- Do not hide CVV help when card-location confusion is likely for users
+- Do not accept incomplete or mismatched code lengths without clear feedback
+- Do not auto-advance to the next step unless CVV length and validation are satisfied
+
+## DoubleField
+
+DoubleField arranges two related form inputs side by side to reduce vertical space and keep paired data entry coherent.
+
+### Usage
+
+#### Use for
+
+- Pairing strongly related fields that users typically complete together
+- Building compact form sections where two inputs should be read and completed in one row
+- Applying intentional width ratios (`50/50`, `40/60`, `60/40`) when one field needs more horizontal space
+- Supporting payment and profile scenarios where grouped field relationships improve completion speed
+
+#### Don't use for
+
+- Do not pair unrelated fields just to save space
+- Do not use narrow ratios when both fields require long values or complex helper/error text
+- Do not stack many DoubleField rows in dense forms if readability and scanning suffer
+- Do not use this pattern when responsive or accessibility needs call for independent full-width inputs
+
+## formatPhoneLite
+
+formatPhoneLite allows users to enter and validate form information in a consistent and accessible way.
+
+### Usage
+
+#### Use for
+
+- Collecting user input with clear labels and contextual help text
+- Supporting validation and accessible feedback in form flows
+
+#### Don't use for
+
+- Do not use this component to display read-only information
+- Do not hide validation context that users need to complete the task
+
+## FileUpload
+
+FileUpload handles file selection through click-to-browse and optional drag-and-drop, with built-in file list display, error feedback, and support for single or multiple file uploads.
+
+### Usage
+
+#### Use for
+
+- Collecting user files (documents, images, media) in forms with click-to-browse or drag-and-drop interaction
+- Displaying selected files with type-aware icons, file size, and individual remove actions
+- Supporting multiple file selection with optional append mode to accumulate files across interactions
+- Building custom upload experiences using the render prop for full control over layout and behavior
+
+#### Don't use for
+
+- Do not use FileUpload for inline image editing or cropping workflows
+- Do not use it for large batch uploads that need progress tracking per file — handle progress externally via the render prop
+- Do not rely on the default file list when custom file presentation (thumbnails, status badges) is required — use renderFiles or the render prop instead
+
+## FileItem
+
+FileItem displays a single selected file inside a FileUpload, showing file name, type-aware icon, formatted size, and a remove button.
+
+### Usage
+
+#### Use for
+
+- Rendering individual file entries within the default or custom file list of a FileUpload
+- Providing a consistent file row with icon, name, size, and remove action
+
+#### Don't use for
+
+- Do not use FileItem outside of a file upload context
+- Do not use it when files need custom status indicators (progress, errors per file) — build a custom file row instead
+
+## Accessibility
+
+### Accessibility label
+
+Input fields should always have a clear accessible name.
+
+- Keep accessible and visible labels aligned so users get one consistent meaning
+- Use concise labels that explain what the field expects
+- Keep helper text short and actionable so users understand what to do next
+- If a field is disabled, assistive technologies announce it as unavailable
+
+### In case of error
+
+Provide both local and global error guidance in complex forms:
+
+- Field-level: immediate message on the affected input
+- Form-level: one summary when multiple fields fail on submit
+
+By default, the summary starts with:
+
+- "Check the following errors:" (localized in supported languages)
+
+Customize summary wording when default copy is too generic for your product flow.
+
+### Inputs with actions
+
+When fields include icon actions, ensure action labels explain the outcome.
+
+- Password visibility toggle: "Show password" / "Hide password"
+- Search clear action: "Clear search"
+- CVV help action: "Show CVV help" / "Hide CVV help"
+
+### OTP and PIN field
+
+`PinField` (used for OTP/PIN flows) supports explicit group labeling.
+
+- Provide a non-visible label when there is no visible label in context
+- Associate with a visible label when one already exists nearby
+
+### Prefixes
+
+Prefix content can be missed by assistive technologies if treated as decorative.
+
+- If prefix information is meaningful, include it in the field label or helper text so screen reader users receive
+ that context
diff --git a/doc/components/layout.md b/doc/components/layout.md
new file mode 100644
index 0000000000..cfd2c07045
--- /dev/null
+++ b/doc/components/layout.md
@@ -0,0 +1,362 @@
+# Layout
+
+## ResponsiveLayout
+
+ResponsiveLayout provides a responsive page container that keeps content within adaptive bounds or expands to
+full width when needed.
+
+### Usage
+
+#### Use for
+
+- Wrapping page sections in consistent responsive margins and maximum content widths
+- Keeping layout rhythm stable across mobile, tablet, and desktop breakpoints
+- Applying container-level variant/background surfaces around a responsive content area
+- Switching to full-width mode when content intentionally needs edge-to-edge presentation
+
+#### Don't use for
+
+- Do not nest multiple ResponsiveLayout wrappers unnecessarily, as it can create redundant spacing behavior
+- Do not use full-width mode by default when readable bounded content is expected
+- Do not mix container variants and custom backgrounds without clear hierarchy intent
+- Do not use ResponsiveLayout to solve component-level spacing issues that belong inside local layouts
+
+## Grid
+
+Grid is a responsive layout primitive for arranging content in rows and columns with controlled spacing and
+alignment.
+
+### Usage
+
+#### Use for
+
+- Building multi-column layouts where content needs consistent structural rhythm
+- Defining responsive track patterns with fixed counts or auto-fill behavior
+- Controlling horizontal and vertical spacing independently across breakpoints
+- Aligning groups of elements within a shared grid context for dashboards, cards, and content blocks
+
+#### Don't use for
+
+- Do not use Grid when simpler stack/inline patterns solve the layout more clearly
+- Do not force complex track definitions that reduce readability and maintainability
+- Do not rely on fixed dimensions that break content adaptability at smaller sizes
+- Do not use layout-only structure as a substitute for semantic grouping and headings
+
+## GridItem
+
+GridItem defines how each element occupies and aligns within a Grid, including span, start position, and
+ordering.
+
+### Usage
+
+#### Use for
+
+- Positioning individual blocks precisely inside a Grid layout
+- Spanning items across multiple rows or columns when visual hierarchy requires larger footprints
+- Controlling per-item alignment and order for responsive composition refinements
+- Creating balanced layouts where featured elements coexist with standard-sized content
+
+#### Don't use for
+
+- Do not overuse manual start/span overrides when natural grid flow already works
+- Do not create fragmented layouts with excessive custom placement rules
+- Do not use item reordering in ways that hurt reading flow or accessibility expectations
+- Do not treat GridItem positioning as a replacement for meaningful content hierarchy
+
+## GridLayout
+
+GridLayout provides predefined responsive column templates to compose balanced page sections with predictable
+proportions.
+
+### Usage
+
+#### Use for
+
+- Building page sections with templates that distribute space across a 12-column area, such as `6+6`, `8+4`,
+ `4+6`, `5+4`, and `3+9`
+- Structuring two-area compositions (main + side content) without manually managing low-level grid math
+- Controlling vertical rhythm and collapse behavior for responsive transitions from desktop to smaller
+ breakpoints
+
+#### Don't use for
+
+- Do not use GridLayout when your composition requires fully custom per-item placement better suited to `Grid`
+- Do not mix inconsistent templates in adjacent sections without clear visual rationale
+- Do not force wide split templates for content that needs single-column reading focus
+- Do not ignore collapse behavior when designing tablet/mobile experiences
+
+## Stack
+
+Use stack to arrange content vertically with a predefined spacing scale, including responsive spacing and
+distribution modes.
+
+### Usage
+
+#### Use for
+
+- Building vertical layouts where each child needs consistent separation
+- Applying the supported spacing scale values (0, 2, 4, 8, 12, 16, 24, 32, 40, 48, 56, 64, 72, 80) between
+ blocks, including responsive values by breakpoint
+- Distributing children across available vertical space with `between`, `around`, or `evenly` when a
+ flex-style layout is needed
+- Grouping semantic lists by setting list roles so each child is exposed as a list item
+
+#### Don't use for
+
+- Do not use stack as a replacement for components that already define their own internal structure and
+ spacing
+- Do not assume arbitrary spacing values are supported; keep to the provided spacing scale
+- Do not use flex distribution modes when fixed spacing values communicate hierarchy better
+- Do not rely on visual grouping alone when content is a real list; provide the appropriate semantic role
+
+## Inline
+
+Inline arranges elements in a horizontal row with controlled spacing, optional wrapping, and responsive gap
+behavior across breakpoints.
+
+### Usage
+
+#### Use for
+
+- Composing compact horizontal groups such as chips, metadata, tags, or inline actions
+- Keeping consistent spacing between sibling elements with optional responsive spacing rules
+- Allowing items to wrap onto multiple lines while preserving horizontal rhythm
+- Building simple list-like horizontal collections when semantic list roles are needed
+
+#### Don't use for
+
+- Do not use Inline for vertical stacking patterns better handled by Stack or column layouts
+- Do not force no-wrap behavior when content length is unpredictable and likely to overflow
+- Do not combine mixed spacing strategies that produce inconsistent alignment between breakpoints
+- Do not rely on Inline alone to solve complex grid compositions with asymmetrical structure
+
+## Box
+
+Box is a low-level spacing primitive used to apply consistent, responsive padding around content.
+
+### Usage
+
+#### Use for
+
+- Applying consistent spacing rhythm around content blocks
+- Adapting padding by breakpoint (mobile/tablet/desktop) without custom CSS
+- Wrapping sections that need lightweight structural separation before using higher-level layout components
+
+#### Don't use for
+
+- Do not treat Box as a full layout system for complex composition
+- Do not use it to replace semantic UI components that already define spacing behavior
+- Do not rely on custom styling through this primitive; keep it focused on spacing and simple structure
+
+## NegativeBox
+
+NegativeBox offsets horizontal container gutters by applying negative side margins, allowing content to bleed
+to one or both edges.
+
+### Usage
+
+#### Use for
+
+- Letting selected content extend beyond standard horizontal padding in constrained layouts
+- Aligning edge-to-edge media or separators with surrounding full-bleed patterns
+- Applying controlled left, right, or bilateral gutter compensation without custom wrapper styles
+- Resolving specific alignment mismatches when parent container padding must be preserved
+
+#### Don't use for
+
+- Do not use NegativeBox as a general spacing system; reserve it for targeted gutter compensation
+- Do not stack multiple negative-offset wrappers, which can create unpredictable overflow
+- Do not use it to hide structural layout issues that should be solved at container level
+- Do not apply edge bleed to critical text content when readability relies on safe horizontal padding
+
+## Boxed
+
+Boxed is a themed surface container used to group content inside a bounded, variant-aware block.
+
+### Usage
+
+#### Use for
+
+- Grouping related content inside a clear visual container with consistent radius and background
+- Creating emphasized sections that adapt to theme variant contexts (default, brand, alternative, negative,
+ media)
+- Applying responsive container dimensions when layout needs controlled width or height across breakpoints
+- Building card-like blocks where content should read as one unit
+
+#### Don't use for
+
+- Do not use Boxed as a replacement for semantic components with their own interaction patterns
+- Do not mix too many container variants in the same section without clear hierarchy
+- Do not rely on fixed dimensions that can break content adaptability
+- Do not use boxed emphasis for every section; reserve it for meaningful grouping
+
+## Align
+
+Align is a layout primitive that positions children on the horizontal and vertical axes using x/y alignment
+props, with optional width and height constraints.
+
+### Usage
+
+#### Use for
+
+- Positioning content with simple axis-based alignment (`x` and `y`: start, center, end)
+- Wrapping one or more elements in a container with optional `width` and `height`
+- Passing telemetry or testing metadata through prefixed `dataAttributes`
+
+#### Don't use for
+
+- Do not use `Align` as a substitute for semantic layout structures that require dedicated components
+- Do not rely on `Align` for complex multi-area layouts better handled by grid or other layout primitives
+
+## FixedFooterLayout
+
+FixedFooterLayout keeps footer content anchored to the bottom when space allows, while preserving readable
+scrollable content above it.
+
+### Usage
+
+#### Use for
+
+- Keeping key actions persistently reachable at the bottom during long mobile-first flows
+- Combining scrollable content with a stable footer action zone without covering focused elements
+- Supporting responsive behavior where footer fixation adapts to available viewport height
+- Maintaining visual continuity with contextual elevation and safe-area-aware spacing
+
+#### Don't use for
+
+- Do not use fixed footers for short/simple screens where inline actions are clearer
+- Do not overload the footer with too many controls; keep it focused on essential actions
+- Do not assume the footer is always fixed on every viewport; layout should still work when it is not
+- Do not ignore background and contrast transitions between content area and footer layer
+
+## FixedToTop
+
+FixedToTop coordinates stacked fixed-top elements by sharing cumulative top offset, avoiding overlap between
+layered sticky regions.
+
+### Usage
+
+#### Use for
+
+- Building interfaces with multiple fixed/sticky top layers that must stack predictably
+- Positioning new fixed-top elements relative to already occupied top space
+- Keeping global UI regions (for example headers and contextual bars) visually aligned during scroll
+- Preserving layout coherence when different components need awareness of top offset accumulation
+
+#### Don't use for
+
+- Do not use this pattern when only one fixed-top element exists and no stacking logic is needed
+- Do not hardcode top offsets that can conflict with accumulated fixed-top height
+- Do not mix unmanaged fixed-position elements with FixedToTop-managed layers in the same stack
+- Do not treat FixedToTop as a visual component; its role is layout coordination
+
+## MasterDetailLayout
+
+MasterDetailLayout adapts list-detail experiences across breakpoints, switching from single-pane on smaller
+screens to split-pane on larger screens.
+
+### Usage
+
+#### Use for
+
+- Building master-detail flows where users browse a collection and open one item for deeper context
+- Preserving a focused single-pane experience on mobile/tablet while keeping side-by-side context on desktop
+- Supporting transitions between list view and detail view without changing overall page architecture
+- Handling responsive information density where desktop benefits from concurrent master and detail visibility
+
+#### Don't use for
+
+- Do not use MasterDetailLayout when both panes must always be visible on all breakpoints
+- Do not use it for unrelated side-by-side content that is not a true master-detail relationship
+- Do not overload the master pane with complex controls that compete with detail comprehension
+- Do not rely on this layout for multi-column dashboards requiring more than two coordinated regions
+
+## HorizontalScroll
+
+HorizontalScroll creates a horizontal overflow area so content can be explored by sideways scrolling when
+items do not fit in the available width.
+
+### Usage
+
+#### Use for
+
+- Presenting rows of cards, chips, or media previews that need horizontal exploration
+- Preserving item size and composition when compressing into narrow viewports would harm readability
+- Enabling simple, touch-friendly sideways navigation without introducing carousel pagination logic
+- Hiding the scrollbar only in polished surfaces where discoverability of horizontal movement remains clear
+
+#### Don't use for
+
+- Do not hide the scrollbar when users need clear affordance to understand the area is scrollable
+- Do not place long-form text flows in HorizontalScroll; it is for lateral scanning patterns
+- Do not use HorizontalScroll as a replacement for components that require grouped pages and controls
+- Do not rely on it to solve poor content hierarchy; simplify item density and priorities first
+
+## Divider
+
+Divider is a subtle visual separator used to split related content areas while preserving rhythm and
+scanability.
+
+### Usage
+
+#### Use for
+
+- Separating adjacent content blocks that belong to the same section but need clearer visual boundaries
+- Improving scanability in dense lists, cards, and stacked layouts
+- Reinforcing content grouping without introducing heavy structural containers
+- Keeping separator styling consistent with the active theme variant
+
+#### Don't use for
+
+- Do not use dividers where spacing alone already provides clear separation
+- Do not stack multiple dividers to simulate complex layout structures
+- Do not rely on dividers as the only cue for section hierarchy when headings are needed
+- Do not add separators after every minor element if it creates visual noise
+
+#### Built-in separators
+
+- `RowList` already renders dividers between rows
+- `Accordion` already renders dividers between accordion items
+- `Menu`/`MenuSection` already includes section separators
+- `Drawer` and `Sheet` patterns render contextual dividers based on scroll state
+- Prefer these built-in separators before adding extra `Divider` instances manually
+
+## Accessibility
+
+### Preserve semantics over visual layout
+
+Use layout primitives for visual structure, and add semantics in the content they organize.
+
+- Do not rely on spacing/alignment wrappers to communicate meaning
+- Add headings, list semantics, and landmark roles in the content they wrap
+- Use region naming (`aria-label` / `aria-labelledby`) when a section needs a clear accessible name
+
+### Lists and grouped content
+
+When a layout visually behaves like a list, ensure users also get list context.
+
+- Add list semantics when users need to perceive grouped list items
+- Keep list labels specific when multiple grouped regions are present
+
+### Reading order and visual reordering
+
+Keep DOM order aligned with reading order, especially in responsive layouts.
+
+- Avoid visual reordering that breaks reading and focus order
+- Ensure master/detail content remains understandable in both single-pane and split-pane views
+- If content priority changes by breakpoint, verify keyboard and screen reader flow in each breakpoint
+
+### Scrollable and fixed regions
+
+Scrollable and fixed regions need clear purpose cues.
+
+- Provide nearby heading/label context for horizontally scrollable content
+- If scrollbars are hidden, keep alternative affordances that reveal overflow
+- Keep fixed footer actions clearly labeled and easy to reach
+
+### Decorative separators
+
+`Divider` is visual separation, not structure.
+
+- Do not use dividers as the only cue for hierarchy or section meaning
+- Keep semantic grouping in headings, lists, and landmarks, with dividers as complementary decoration
diff --git a/doc/components/lists.md b/doc/components/lists.md
new file mode 100644
index 0000000000..d9acccd86c
--- /dev/null
+++ b/doc/components/lists.md
@@ -0,0 +1,181 @@
+# Lists
+
+## Row
+
+Row is a flexible list item pattern for navigation, selection, and status display with optional leading asset
+and trailing actions.
+
+### Usage
+
+#### Use for
+
+- Building scannable list items with clear hierarchy (title, optional supporting text, optional right-side
+ info)
+- Creating tappable rows for navigation or inline actions with automatic chevron affordance
+- Combining content with controls (switch, checkbox, radio, icon action) when a row needs quick state change
+- Showing optional badges, detail text, and assets to communicate priority and context
+
+#### Don't use for
+
+- Do not mix inconsistent asset styles within the same list group
+- Do not overload a single row with too many secondary elements that reduce scanability
+- Do not use row-level interaction and control interaction in a confusing way without clear tap targets
+- Do not use this pattern for dense tabular data where table semantics fit better
+
+## RowList
+
+RowList groups multiple Row items into a single accessible list with consistent spacing and separators.
+
+### Usage
+
+#### Use for
+
+- Grouping related Row items into one structured section
+- Presenting navigational or settings options with consistent vertical rhythm
+- Preserving list semantics for assistive technologies while keeping a clean visual split between items
+- Building modular page sections where rows can be added, removed, or updated over time
+
+#### Don't use for
+
+- Do not combine unrelated row categories in a single list without section separation
+- Do not use RowList for free-form content blocks that are not row-based interactions
+- Do not remove visual consistency between items by introducing ad-hoc row spacing patterns
+- Do not add manual dividers between rows by default, since `RowList` already includes separators
+
+## BoxedRow
+
+BoxedRow applies the Row interaction model inside a boxed container for stronger visual separation and
+emphasis.
+
+### Usage
+
+#### Use for
+
+- Presenting high-importance row items that need stronger boundaries than a plain list
+- Grouping row content in card-like surfaces while keeping the same row anatomy and behavior
+- Distinguishing specific sections (for example, highlighted settings or featured options) from standard lists
+
+#### Don't use for
+
+- Do not use BoxedRow as a generic container when row semantics are not needed
+- Do not mix too many visual variants in the same boxed group without clear hierarchy
+- Do not use danger styling for non-destructive content
+
+## BoxedRowList
+
+BoxedRowList stacks multiple BoxedRow items with consistent spacing to create separated, card-like list
+groups.
+
+### Usage
+
+#### Use for
+
+- Grouping several BoxedRow items when each entry needs clear visual separation
+- Building modular sections of prominent actions or settings in a card-based layout
+- Keeping boxed row collections visually consistent across screens with a stable vertical rhythm
+
+#### Don't use for
+
+- Do not use BoxedRowList for dense, utility-first lists where plain RowList is more appropriate
+- Do not mix boxed and non-boxed rows in the same group without intentional visual hierarchy
+- Do not turn boxed lists into generic layout wrappers unrelated to row interactions
+
+## OrderedList
+
+OrderedList presents items in an explicit sequence, helping users follow ordered steps, ranked priorities, or
+procedural flows.
+
+### Usage
+
+#### Use for
+
+- Presenting step-by-step instructions where users should follow a defined order
+- Displaying ranked or prioritized lists where numeric position carries meaning
+- Structuring procedural guidance in onboarding, setup, or task-completion contexts
+- Maintaining semantic `ol` behavior so assistive technologies announce sequence correctly
+
+#### Don't use for
+
+- Do not use OrderedList when order is arbitrary or interchangeable; use UnorderedList instead
+- Do not fake progression with numbered items when the flow is not truly sequential
+- Do not split one logical sequence into multiple independent ordered lists without clear transitions
+- Do not use ordered markers as decoration when users are not expected to process item order
+
+## UnorderedList
+
+UnorderedList groups related items where sequence is not meaningful, preserving semantic list structure for
+accessibility and scanning.
+
+### Usage
+
+#### Use for
+
+- Presenting related points, features, or requirements where item order does not imply priority or step flow
+- Keeping content scannable with consistent list rhythm and semantic `ul` behavior
+- Combining text and rich `ListItem` content while preserving list semantics for assistive technologies
+- Structuring supporting information blocks that benefit from bullet-style grouping
+
+#### Don't use for
+
+- Do not use UnorderedList when users must follow a strict sequence; use OrderedList instead
+- Do not overload items with long paragraph-like content that reduces bullet scanability
+- Do not mix unrelated content types in one list without a clear grouping rationale
+- Do not use list styling for purely decorative alignment when no semantic grouping exists
+
+## ListItem
+
+ListItem is the content unit used inside ordered and unordered lists, supporting default markers, custom
+icons, or markerless variants.
+
+### Usage
+
+#### Use for
+
+- Building individual entries inside `UnorderedList` and `OrderedList` with consistent spacing and readability
+- Using default markers for standard list semantics when no custom visual cue is needed
+- Using custom icons when each item benefits from an explicit visual meaning
+- Removing markers only when surrounding context already communicates list grouping clearly
+
+#### Don't use for
+
+- Do not use ListItem outside list containers when no list semantics are intended
+- Do not mix marker, markerless, and icon styles arbitrarily within the same list without rationale
+- Do not use decorative icons that compete with or obscure item meaning
+- Do not remove markers in dense informational lists where scanability depends on strong item separation
+
+## Accessibility
+
+### Role
+
+Choose list semantics according to the content purpose.
+
+- Keep row groups exposed as lists when they represent related options
+- Use ordered vs unordered lists based on whether order changes meaning
+- Add clear list names when multiple list regions coexist
+
+### Heading hierarchy
+
+Row heading levels are configurable.
+
+- Title defaults to `span` (not a heading)
+- Set `titleAs` when the row title should participate in the page heading outline
+- Keep levels consistent with surrounding content hierarchy
+
+### Accessibility label
+
+Label rows so users can understand each action without guessing.
+
+- Provide explicit labels when row content could be ambiguous
+- In informational rows, prefer one concise summary label when full visual content is noisy for assistive tech
+- In dual-interaction rows, ensure both the main row action and right-side action remain distinguishable
+
+### Badge
+
+If a row includes a badge, ensure its meaning is represented in accessible text.
+
+- Provide badge meaning through row text or an explicit `aria-label` when the badge value alone is ambiguous
+
+### Slot
+
+Slots (`extra`, `right`) accept custom content. Because these areas are fully customizable, ensure custom
+controls, icons, and media preserve accessible names, focus order, and semantics.
diff --git a/doc/components/loading.md b/doc/components/loading.md
new file mode 100644
index 0000000000..1f075d4378
--- /dev/null
+++ b/doc/components/loading.md
@@ -0,0 +1,118 @@
+# Loading
+
+## LoadingScreen
+
+LoadingScreen communicates blocking progress states with a centered loading indicator and short contextual
+messaging.
+
+### Usage
+
+#### Use for
+
+- Covering full-screen waits when users must pause before continuing
+- Pairing loading motion with clear, task-specific copy that explains what is happening
+- Showing one or more short loading messages that can rotate over time during longer waits
+- Keeping transition in/out smooth so completion feels continuous instead of abrupt
+
+#### Don't use for
+
+- Do not use vague, generic copy when a concrete action can be described
+- Do not use a full-screen loader for non-blocking operations that can run inline
+- Do not overload the screen with long text; keep messages brief and easy to scan
+- Do not keep users waiting without visible feedback changes during long operations
+
+## BrandLoadingScreen
+
+BrandLoadingScreen adds brand-led loading motion and styling to full-screen waiting states while preserving
+clear progress messaging.
+
+### Usage
+
+#### Use for
+
+- Showing full-screen loading moments where brand expression is part of the experience
+- Combining branded animation with short explanatory text to keep users oriented
+- Creating high-recognition wait states for app launch, transitions, or key journey handoffs
+- Keeping close transitions coordinated so logo motion and text exit feel unified
+
+#### Don't use for
+
+- Do not use branded loading where neutral system feedback is more appropriate
+- Do not let brand animation overshadow clarity of the loading message
+- Do not introduce custom motion patterns that conflict with the skin-defined loading behavior
+- Do not use this pattern for small or local loading states inside page sections
+
+## LoadingBar
+
+LoadingBar shows a global, indeterminate progress indicator for ongoing background activity while the current
+screen remains usable.
+
+### Usage
+
+#### Use for
+
+- Signaling background loading states that affect the page globally but do not require full blocking overlays
+- Giving immediate feedback after navigation or async actions when completion time is unknown
+- Keeping users informed that work is in progress while allowing them to retain context on screen
+- Using a lightweight global loading affordance when skeletons or inline loaders are not appropriate
+
+#### Don't use for
+
+- Do not use LoadingBar as a determinate progress meter for tasks with known completion percentages
+- Do not keep the bar visible longer than the real loading state, as this reduces trust in feedback
+- Do not replace localized loading indicators when only a specific section is loading
+- Do not stack multiple simultaneous global loading bars; aggregate loading signals into one state
+
+## Spinner
+
+spinner. You can see how to apply spinner in buttons here.
+
+### Usage
+
+#### Use for
+
+- Collecting user input with clear labels and contextual help text
+- Supporting validation and accessible feedback in form flows
+
+#### Don't use for
+
+- Don't use a spinner when:
+- If you don’t want the spinner to be read by a screen reader, it can be deactivated.
+
+## Accessibility
+
+### Announce loading state clearly
+
+Use short, specific loading copy so assistive technologies can communicate what is happening.
+
+- Prefer contextual messages (for example, `Loading your plan details`) over generic-only text
+- Keep loading text concise and avoid rapid message churn that causes noisy announcements
+
+### Full-screen loading patterns
+
+`LoadingScreen` and `BrandLoadingScreen` are blocking states and should provide clear status context.
+
+- Keep title/description meaningful so users understand why interaction is paused
+- Preserve heading hierarchy when using titles in long page flows
+- Avoid adding unrelated interactive controls while the blocking loader is active
+
+### Spinner semantics
+
+Use spinner states as progress feedback, not as decoration.
+
+- Add a clear loading label when context is not already obvious
+- Hide spinner from assistive technologies only when equivalent status text is already announced nearby
+
+### LoadingBar behavior
+
+`LoadingBar` is a visual global progress cue and should not be the only accessibility signal.
+
+- Pair it with nearby status text or another announced loading context when users need explicit updates
+- Avoid relying on motion/color alone to communicate background activity
+
+### Live region hygiene
+
+Avoid overlapping loading announcements from multiple components at the same time.
+
+- Keep one primary loading announcement per task
+- Avoid duplicate announcements when combining loading text and loading indicators
diff --git a/doc/components/logo.md b/doc/components/logo.md
new file mode 100644
index 0000000000..36e0c8f10a
--- /dev/null
+++ b/doc/components/logo.md
@@ -0,0 +1,202 @@
+# Logo
+
+## Logo
+
+Logo renders the active brand mark from the current skin, supporting approved logo compositions and responsive sizing.
+
+### Usage
+
+#### Use for
+
+- Rendering the correct brand logo automatically in multi-brand products that follow current theme skin
+- Applying approved logo compositions (for example, isotype, imagotype, or vertical variants) according to
+ placement context
+- Keeping brand marks responsive and consistent across breakpoints with a single shared component
+- Making the logo interactive only when it represents a real navigation or action target
+
+#### Don't use for
+
+- Do not alter logo proportions, spacing, or approved variants
+- Do not use a brand variant that does not match the product context
+- Do not hardcode a brand-specific logo when the interface should adapt to the active skin
+- Do not use logo interactions as decorative behavior without clear user expectation
+
+## BlauLogo
+
+BlauLogo renders the Blau brand mark with approved visual treatment and responsive sizing behavior.
+
+### Usage
+
+#### Use for
+
+- Showing a fixed Blau brand logo in product headers, navigation, and branded touchpoints
+- Keeping brand consistency when the product should not switch logos by active skin
+- Applying approved logo compositions and spacing in constrained and responsive layouts
+- Using it as an optional home/navigation affordance when logo click behavior is expected
+
+#### Don't use for
+
+- Do not alter logo proportions, spacing, or approved variants
+- Do not use a brand variant that does not match the product context
+- Do not use BlauLogo in multi-brand contexts that should adapt automatically; use Logo instead
+- Do not treat the logo as decorative background content or promotional artwork
+
+## EsimflagLogo
+
+EsimflagLogo renders the Esimflag brand mark with approved visual treatment and responsive sizing behavior.
+
+### Usage
+
+#### Use for
+
+- Showing a fixed Esimflag brand logo in product headers, navigation, and branded touchpoints
+- Keeping brand consistency when the product should not switch logos by active skin
+- Applying approved logo compositions and spacing in constrained and responsive layouts
+- Using it as an optional home/navigation affordance when logo click behavior is expected
+
+#### Don't use for
+
+- Do not alter logo proportions, spacing, or approved variants
+- Do not use a brand variant that does not match the product context
+- Do not use EsimflagLogo in multi-brand contexts that should adapt automatically; use Logo instead
+- Do not treat the logo as decorative background content or promotional artwork
+
+## MovistarLogo
+
+MovistarLogo renders the Movistar brand mark with approved visual treatment and responsive sizing behavior.
+
+### Usage
+
+#### Use for
+
+- Showing a fixed Movistar brand logo in product headers, navigation, and branded touchpoints
+- Keeping brand consistency when the product should not switch logos by active skin
+- Applying approved logo compositions and spacing in constrained and responsive layouts
+- Using it as an optional home/navigation affordance when logo click behavior is expected
+
+#### Don't use for
+
+- Do not alter logo proportions, spacing, or approved variants
+- Do not use a brand variant that does not match the product context
+- Do not use MovistarLogo in multi-brand contexts that should adapt automatically; use Logo instead
+- Do not treat the logo as decorative background content or promotional artwork
+
+## MovistarNewLogo
+
+MovistarNewLogo renders the Movistar New brand mark with approved visual treatment and responsive sizing behavior.
+
+### Usage
+
+#### Use for
+
+- Showing a fixed Movistar New brand logo in product headers, navigation, and branded touchpoints
+- Keeping brand consistency when the product should not switch logos by active skin
+- Applying approved logo compositions and spacing in constrained and responsive layouts
+- Using it as an optional home/navigation affordance when logo click behavior is expected
+
+#### Don't use for
+
+- Do not alter logo proportions, spacing, or approved variants
+- Do not use a brand variant that does not match the product context
+- Do not use MovistarNewLogo in multi-brand contexts that should adapt automatically; use Logo instead
+- Do not treat the logo as decorative background content or promotional artwork
+
+## O2Logo
+
+O2Logo renders the O2 brand mark with approved visual treatment and responsive sizing behavior.
+
+### Usage
+
+#### Use for
+
+- Showing a fixed O2 brand logo in product headers, navigation, and branded touchpoints
+- Keeping brand consistency when the product should not switch logos by active skin
+- Applying approved logo compositions and spacing in constrained and responsive layouts
+- Using it as an optional home/navigation affordance when logo click behavior is expected
+
+#### Don't use for
+
+- Do not alter logo proportions, spacing, or approved variants
+- Do not use a brand variant that does not match the product context
+- Do not use O2Logo in multi-brand contexts that should adapt automatically; use Logo instead
+- Do not treat the logo as decorative background content or promotional artwork
+
+## O2NewLogo
+
+O2NewLogo renders the O2 New brand mark with approved visual treatment and responsive sizing behavior.
+
+### Usage
+
+#### Use for
+
+- Showing a fixed O2 New brand logo in product headers, navigation, and branded touchpoints
+- Keeping brand consistency when the product should not switch logos by active skin
+- Applying approved logo compositions and spacing in constrained and responsive layouts
+- Using it as an optional home/navigation affordance when logo click behavior is expected
+
+#### Don't use for
+
+- Do not alter logo proportions, spacing, or approved variants
+- Do not use a brand variant that does not match the product context
+- Do not use O2NewLogo in multi-brand contexts that should adapt automatically; use Logo instead
+- Do not treat the logo as decorative background content or promotional artwork
+
+## TelefonicaLogo
+
+TelefonicaLogo renders the Telefónica brand mark with approved visual treatment and responsive sizing behavior.
+
+### Usage
+
+#### Use for
+
+- Showing a fixed Telefónica brand logo in product headers, navigation, and branded touchpoints
+- Keeping brand consistency when the product should not switch logos by active skin
+- Applying approved logo compositions and spacing in constrained and responsive layouts
+- Using it as an optional home/navigation affordance when logo click behavior is expected
+
+#### Don't use for
+
+- Do not alter logo proportions, spacing, or approved variants
+- Do not use a brand variant that does not match the product context
+- Do not use TelefonicaLogo in multi-brand contexts that should adapt automatically; use Logo instead
+- Do not treat the logo as decorative background content or promotional artwork
+
+## TuLogo
+
+TuLogo renders the Tu brand mark with approved visual treatment and responsive sizing behavior.
+
+### Usage
+
+#### Use for
+
+- Showing a fixed Tu brand logo in product headers, navigation, and branded touchpoints
+- Keeping brand consistency when the product should not switch logos by active skin
+- Applying approved logo compositions and spacing in constrained and responsive layouts
+- Using it as an optional home/navigation affordance when logo click behavior is expected
+
+#### Don't use for
+
+- Do not alter logo proportions, spacing, or approved variants
+- Do not use a brand variant that does not match the product context
+- Do not use TuLogo in multi-brand contexts that should adapt automatically; use Logo instead
+- Do not treat the logo as decorative background content or promotional artwork
+
+## VivoLogo
+
+VivoLogo renders the Vivo brand mark with approved visual treatment and responsive sizing behavior.
+
+### Usage
+
+#### Use for
+
+- Showing a fixed Vivo brand logo in product headers, navigation, and branded touchpoints
+- Keeping brand consistency when the product should not switch logos by active skin
+- Applying approved logo compositions and spacing in constrained and responsive layouts
+- Using it as an optional home/navigation affordance when logo click behavior is expected
+
+#### Don't use for
+
+- Do not alter logo proportions, spacing, or approved variants
+- Do not use a brand variant that does not match the product context
+- Do not use VivoLogo in multi-brand contexts that should adapt automatically; use Logo instead
+- Do not treat the logo as decorative background content or promotional artwork
diff --git a/doc/components/menu.md b/doc/components/menu.md
new file mode 100644
index 0000000000..0bfed54bbb
--- /dev/null
+++ b/doc/components/menu.md
@@ -0,0 +1,106 @@
+# Menu
+
+## Menu
+
+Menu displays contextual actions from a trigger, with adaptive positioning, keyboard navigation, and dismiss
+behavior through overlay interaction.
+
+### Usage
+
+#### Use for
+
+- Presenting grouped actions or navigation options in a compact contextual surface
+- Organizing options into sections when users need quick scanning and clear grouping
+- Keeping interaction patterns coherent in overflow and contextual action scenarios
+- Supporting accessible keyboard interaction for action discovery and activation
+
+#### Don't use for
+
+- Do not use Menu as primary page navigation for always-visible destinations
+- Do not overload menus with long, dense content that reduces quick decision making
+- Do not add manual separators between menu sections by default, since section dividers are built in
+- Do not keep critical actions only inside hidden menus when direct visibility is required
+
+## MenuItem
+
+MenuItem represents an actionable row inside a menu, with optional icon, destructive emphasis, disabled state,
+or checkbox control behavior.
+
+### Usage
+
+#### Use for
+
+- Presenting a single contextual action in compact menu surfaces
+- Adding optional leading icons when they improve recognition speed without ambiguity
+- Showing destructive options with stronger visual emphasis to signal risk
+- Representing on/off choices with menuitem-checkbox behavior when selection state is relevant
+
+#### Don't use for
+
+- Do not use unclear labels that force users to infer action outcomes
+- Do not combine too many icon styles and action tones in one menu without hierarchy
+- Do not expose unavailable actions without disabled context that explains why
+- Do not use MenuItem as a substitute for full form controls when persistent state editing is needed
+
+## MenuSection
+
+MenuSection groups related menu items and automatically renders a divider between sections for clearer
+scanability.
+
+### Usage
+
+#### Use for
+
+- Grouping related actions into clear clusters inside a single menu surface
+- Improving menu scanability by separating action groups with built-in section dividers
+- Structuring overflow menus where users need quick orientation by action category
+- Keeping section composition lightweight by rendering only meaningful groups
+
+#### Don't use for
+
+- Do not add manual divider components between MenuSection blocks; separation is already built in
+- Do not create many single-item sections when grouping does not add semantic value
+- Do not use empty sections as spacing hacks in menu layouts
+- Do not split tightly related actions across different sections without clear rationale
+
+## Accessibility
+
+### Role
+
+Use menu patterns for short contextual actions, not for full-page navigation.
+
+- Keep menu options action-oriented and concise
+- Use checkbox-like menu items only for lightweight toggle decisions
+
+### Trigger relationship
+
+Keep trigger and menu relationship understandable for assistive technologies.
+
+- Expose trigger state so users know a menu opens and whether it is expanded
+- Keep trigger label explicit so users understand what menu is being opened
+
+### Keyboard interaction
+
+Menu supports keyboard navigation and activation.
+
+- Arrow keys move focus across enabled menu items
+- `Enter`/`Space` activates the focused item
+- `Esc` closes the menu
+- Focus returns to the trigger when the menu closes
+
+Avoid overriding these patterns in custom wrappers.
+
+### Accessibility label
+
+Menu item label text is used as the accessible action name.
+
+- Keep labels short, specific, and action-oriented
+- Avoid ambiguous labels like `More` or `Open` without context
+- For destructive actions, keep wording explicit (for example, `Delete account`)
+
+### Sections and separators
+
+`MenuSection` includes built-in visual separators to group related actions.
+
+- Use sections to improve scanability and semantic grouping of related options
+- Do not add redundant manual dividers between sections
diff --git a/doc/components/modals.md b/doc/components/modals.md
new file mode 100644
index 0000000000..d4d8b717a9
--- /dev/null
+++ b/doc/components/modals.md
@@ -0,0 +1,283 @@
+# Modals
+
+## Sheet
+
+Sheet presents temporary, focus-trapped bottom-sheet content for contextual decisions, actions, and
+lightweight task flows.
+
+### Usage
+
+#### Use for
+
+- Presenting contextual options or explanations without navigating away from the current screen
+- Supporting mobile-friendly bottom-sheet interactions with clear dismissal behavior
+- Hosting short, focused interactions such as single selection, action lists, or informative content
+- Keeping temporary decision points consistent across web and hybrid sheet experiences
+
+#### Don't use for
+
+- Do not use Sheet for complex multi-step workflows that require full-page ownership
+- Do not overload sheets with dense content that reduces scanability and quick decision making
+- Do not hide critical irreversible actions inside transient sheet surfaces without stronger confirmation
+ flows
+- Do not stack multiple sheet layers at once
+
+## SheetBody
+
+SheetBody structures sheet content with sticky title/actions regions, optional descriptive text, and
+scroll-aware dividers.
+
+### Usage
+
+#### Use for
+
+- Composing sheet content with consistent title, subtitle, description, and action areas
+- Keeping primary actions persistently reachable through sticky bottom action zones
+- Improving readability with structured spacing and optional multi-paragraph description support
+- Preserving context during scroll using sticky headers and divider cues
+
+#### Don't use for
+
+- Do not place long unstructured content without hierarchy inside SheetBody
+- Do not overload sticky action areas with too many competing controls
+- Do not omit clear title context when the sheet drives a user decision
+- Do not use SheetBody outside sheet containers as a generic page layout wrapper
+
+## SheetRoot
+
+SheetRoot is the global host that mounts and resolves sheet experiences triggered through showSheet.
+
+### Usage
+
+#### Use for
+
+- Providing a single top-level integration point for imperative sheet orchestration
+- Enabling lazy-loaded sheet rendering and promise-based result handling from anywhere in the app
+- Supporting optional native sheet delegation in hybrid environments with web fallback behavior
+- Keeping sheet lifecycle and focus-return behavior centralized and predictable
+
+#### Don't use for
+
+- Do not mount multiple independent SheetRoot instances for the same experience
+- Do not trigger sheets before SheetRoot is mounted in the application tree
+- Do not treat SheetRoot as presentational UI; it is an orchestration host
+- Do not bypass root-level sheet orchestration with ad-hoc parallel modal systems
+
+## showSheet
+
+showSheet opens a typed sheet flow imperatively and returns a promise with user outcome or dismissal result.
+
+### Usage
+
+#### Use for
+
+- Triggering contextual sheet interactions from events where declarative placement is not practical
+- Handling sheet outcomes through explicit result actions (for example submit, dismiss, primary, secondary)
+- Coordinating selection and action sheets with a single async control flow
+- Integrating native sheet implementations with graceful web fallback when needed
+
+#### Don't use for
+
+- Do not call showSheet when another sheet is already open
+- Do not ignore returned outcomes; resolution should drive explicit follow-up behavior
+- Do not rely on showSheet without mounting SheetRoot first
+- Do not use imperative sheet launching for static always-visible UI content
+
+## NativeSheetImplementation
+
+NativeSheetImplementation is a Mística component used to build consistent and accessible product interfaces.
+
+### Usage
+
+#### Use for
+
+- Applying the documented component pattern in product UI
+- Keeping user experience coherent across screens and flows
+
+#### Don't use for
+
+- Do not replace a more suitable semantic component with this one
+- Do not customize behavior in ways that conflict with Mística guidance
+
+## ActionsSheet
+
+ActionsSheet presents a short decision block in a bottom sheet using a primary action, optional secondary
+action, and optional text link.
+
+### Usage
+
+#### Use for
+
+- Confirming or resolving a focused decision with a clear action hierarchy
+- Showing one main action, with optional fallback (secondary) and optional low-emphasis link action
+- Supporting quick, modal decisions where selecting any action should complete and close the sheet
+- Combining short contextual copy (title/subtitle/description) with immediately actionable choices
+
+#### Don't use for
+
+- Do not use it for long forms or multi-step tasks that require users to stay in context
+- Do not add multiple competing primary actions; keep a single clear primary outcome
+- Do not use link actions as the primary path when a primary button is expected
+- Do not overload the sheet with long explanatory content that delays action
+
+## ActionsListSheet
+
+ActionsListSheet presents a bottom sheet with a clear list of selectable actions, optionally enriched with
+icons and destructive emphasis.
+
+### Usage
+
+#### Use for
+
+- Showing a compact list of mutually independent actions in a bottom sheet
+- Supporting quick decision flows where tapping an action should immediately execute and close the sheet
+- Emphasizing risky actions using the destructive visual treatment
+- Adding optional icons (brand/image or UI icon) to improve scanability when action labels alone are not
+ enough
+
+#### Don't use for
+
+- Do not use it for long, complex task flows that require persistent context or multi-step forms
+- Do not include too many actions; keep the list short enough to scan and decide quickly
+- Do not mark multiple actions as destructive unless they are truly high-risk
+- Do not rely only on icons to communicate meaning; labels must remain clear on their own
+
+#### Example
+
+```tsx
+showSheet({
+ type: 'ACTIONS_LIST',
+ props: {
+ title: 'Options',
+ items: [
+ {id: 'edit', title: 'Edit'},
+ {id: 'share', title: 'Share', icon: {url: '/icons/share.svg'}},
+ {id: 'delete', title: 'Delete', style: 'destructive'},
+ ],
+ },
+});
+```
+
+> The `icon` field in items accepts `{ url: string; urlDark?: string }`. The `{ Icon: ComponentType }` variant
+> is **deprecated** — use `url` instead.
+
+## InfoSheet
+
+InfoSheet presents explanatory content in a modal sheet with a titled context, optional supporting copy, and a
+structured list of informational items.
+
+### Usage
+
+#### Use for
+
+- Explaining policies, steps, or conditions in a focused modal context before users continue
+- Presenting short, scannable itemized information with icons or bullets and optional item descriptions
+- Providing a clear close/acknowledge action when users finish reading the informational content
+- Grouping contextual guidance that benefits from temporary emphasis without leaving the current flow
+
+#### Don't use for
+
+- Do not use InfoSheet for complex multi-step task completion that requires full-form interactions
+- Do not overload the sheet with long paragraphs or dense legal text that harms scanability
+- Do not mix unrelated item types and icon semantics that reduce comprehension consistency
+- Do not use it as a generic action menu; it is primarily for informative, explanatory content
+
+## RadioListSheet
+
+RadioListSheet presents single-choice options inside a bottom sheet using radio-list rows, optimized for
+responsive selection flows.
+
+### Usage
+
+#### Use for
+
+- Letting users pick one option from a contextual list without leaving the current screen
+- Presenting option labels, descriptions, and optional assets in a scan-friendly sheet format
+- Supporting mobile quick-select flows where choosing an option can immediately close the sheet
+- Supporting desktop confirmation flows where users review selection before pressing a confirm action
+
+#### Don't use for
+
+- Do not use RadioListSheet for multi-select decisions; use checkbox-based patterns instead
+- Do not use it when the option set is so large that list-in-sheet scanning becomes inefficient
+- Do not hide the selection consequence when the sheet closes automatically on mobile
+- Do not split one decision across multiple sheets when one coherent choice list is enough
+
+## Drawer
+
+The drawer component is only meant for web implementations. When designing for native we recommend to use a
+modal view.
+
+### Usage
+
+#### Use for
+
+- Presenting secondary tasks or supporting flows without leaving the current page context
+- Showing focused dialog-like content with optional title, description, and action area
+- Handling web overlay interactions that need dismiss by close button, overlay tap, or ESC when appropriate
+- Keeping primary/secondary/link actions anchored at the bottom for clear decision completion
+
+#### Don't use for
+
+- Do not use Drawer for core page journeys that deserve full-page navigation
+- Do not overload the panel with long, multi-step flows that exceed a focused side-surface interaction
+- Do not remove clear dismissal affordances when the flow is intended to be dismissible
+- Do not add manual separators inside title/action boundaries; Drawer already manages contextual dividers on
+ scroll
+
+## useDialog
+
+useDialog provides reusable behavior to keep component logic consistent across the product.
+
+### Usage
+
+#### Use for
+
+- Sharing common state and behavior across multiple components
+- Keeping implementation aligned with Mística patterns
+
+#### Don't use for
+
+- Do not duplicate equivalent logic when this utility already exists
+- Do not use it without understanding its side effects and scope
+
+## Accessibility
+
+### Title and context
+
+Every modal should explain why it is open and what users can do next.
+
+- Use a clear, task-oriented title
+- Add concise supporting text when users need extra context before acting
+- Keep one decision/task per modal to avoid cognitive overload
+
+### Focus and navigation
+
+Users should be able to complete or dismiss the modal without losing orientation.
+
+- Keep one modal/sheet open at a time
+- Ensure keyboard users can reach all modal actions in a logical order
+- Return users to a predictable place after closing (normally the trigger)
+
+### Dismiss behavior
+
+Dismiss patterns should be clear and consistent with interaction risk.
+
+- For dismissible flows, provide an explicit close action
+- For confirm/critical flows, avoid accidental dismissal patterns
+- Keep close/dismiss labels contextual when `Close` is too generic
+
+### Trigger and action labels
+
+Modal usage should remain understandable before and after opening.
+
+- Use explicit trigger labels (for example, `Open payment options`)
+- Label primary/secondary actions by outcome (for example, `Save changes`, `Discard`)
+- Avoid ambiguous action text like `Continue` when the result is unclear
+
+### Imperative modal flows
+
+When using `showSheet`/`useDialog`, treat outcomes as part of the accessible flow.
+
+- Handle each result explicitly so users get clear feedback after closing
+- Avoid parallel modal systems that can create competing focus/announcement contexts
diff --git a/doc/components/mosaic.md b/doc/components/mosaic.md
new file mode 100644
index 0000000000..b95f982aa5
--- /dev/null
+++ b/doc/components/mosaic.md
@@ -0,0 +1,68 @@
+# Mosaic
+
+## HorizontalMosaic
+
+HorizontalMosaic groups content into swipeable mosaic pages with alternating layouts to keep discovery flows
+visually dynamic.
+
+### Usage
+
+#### Use for
+
+- Building swipeable discovery sections where users browse grouped cards horizontally
+- Highlighting mixed-priority items with alternating horizontal and square compositions per page
+- Showing curated content sets where carousel bullets/controls help navigation between groups
+- Rendering adaptable items that respond well to `horizontal` and `square` grid modes
+
+#### Don't use for
+
+- Do not use HorizontalMosaic when users need to compare many items at once without pagination
+- Do not use it for dense textual content that requires strict reading continuity
+- Do not include item designs that break when aspect ratio changes between mosaic slots
+- Do not use it when a static, list-semantic composition is more appropriate; use VerticalMosaic instead
+
+## VerticalMosaic
+
+VerticalMosaic arranges content in static mosaic blocks with list semantics, combining vertical and square
+slots for scannable editorial layouts.
+
+### Usage
+
+#### Use for
+
+- Building non-carousel mosaics where users scan groups of up to four related items
+- Preserving semantic list behavior for assistive technologies in content collections
+- Emphasizing one featured item while supporting it with secondary square items
+- Creating stable, page-level compositions where all visible items are available at once
+
+#### Don't use for
+
+- Do not use VerticalMosaic when horizontal swipe navigation is expected; use HorizontalMosaic instead
+- Do not force uniform card ratios if your design requires equal tiles in every slot
+- Do not overload each item with long copy that breaks compact mosaic readability
+- Do not rely on custom manual placement patterns outside the supported 1–4 item structures per block
+
+## Accessibility
+
+### Accessibility label
+
+Give each mosaic a clear accessible name in context.
+
+- For `HorizontalMosaic`, set `aria-label` or `aria-labelledby` so carousel navigation is announced with
+ meaningful context
+- For `VerticalMosaic`, also set `aria-label` or `aria-labelledby` when nearby headings are not enough
+- Keep item labels unique and specific so users can distinguish cards
+
+### Role
+
+Use `VerticalMosaic` when list semantics are important for the flow.
+
+- Keep the default list semantics unless a different structure is intentionally required
+- If you override semantics with custom `role` and `itemRole`, choose a valid parent-child combination
+
+### Slot
+
+When using item render functions (`gridMode`), preserve equivalent content and interactions across modes.
+
+- Ensure interactive elements inside each item have descriptive accessible names
+- Do not let accessibility depend on visual layout
diff --git a/doc/components/navigation-bars.md b/doc/components/navigation-bars.md
new file mode 100644
index 0000000000..d8b5a8173e
--- /dev/null
+++ b/doc/components/navigation-bars.md
@@ -0,0 +1,135 @@
+# Navigation
+
+## MainNavigationBar
+
+MainNavigationBar provides primary product navigation with section switching, responsive desktop menus, and
+mobile burger-menu behavior.
+
+### Usage
+
+#### Use for
+
+- Organizing top-level product areas with clear section navigation from a persistent header
+- Supporting responsive navigation patterns that adapt from desktop section menus to mobile burger menu
+- Combining brand/logo presence with primary navigation and optional high-priority right-side actions
+- Managing information architecture where users need predictable access to multiple main sections
+
+#### Don't use for
+
+- Do not use MainNavigationBar for simple single-flow screens with only back/title needs
+- Do not overload section menus with deep, hard-to-scan content hierarchies
+- Do not mix inconsistent section interaction patterns that confuse open/close behavior
+- Do not use it for short transactional funnels where reduced navigation is preferable
+
+## NavigationBar
+
+NavigationBar is the standard top app bar for page-level navigation, supporting back navigation, title, and
+contextual right-side actions.
+
+### Usage
+
+#### Use for
+
+- Structuring screen-level navigation with clear title context and optional back behavior
+- Hosting a small set of high-priority contextual actions in the right area
+- Keeping page chrome stable across flows where users move between hierarchical views
+- Building standard app-level headers when global section menus are not required
+
+#### Don't use for
+
+- Do not use NavigationBar as a global multi-section site menu; use MainNavigationBar instead
+- Do not overcrowd the right slot with many competing actions
+- Do not hide essential navigation intent behind ambiguous icon-only controls
+- Do not use it as a funnel-specific confirmation header when funnel behavior is needed
+
+## NavigationBarAction
+
+NavigationBarAction is an interactive header control used for concise contextual actions in navigation bars.
+
+### Usage
+
+#### Use for
+
+- Triggering high-priority contextual actions from the top navigation area
+- Providing compact entry points to search, close, edit, or secondary utility behaviors
+- Maintaining consistent interaction affordance for header-level touch targets
+- Combining with NavigationBarActionGroup when multiple related actions are required
+
+#### Don't use for
+
+- Do not use NavigationBarAction for primary content actions better placed in page body
+- Do not place destructive or high-risk actions without clear affordance and confirmation pattern
+- Do not rely on ambiguous controls that lack clear meaning in the current screen context
+- Do not overload the navigation bar with many standalone actions instead of grouped prioritization
+
+## NavigationBarActionGroup
+
+NavigationBarActionGroup arranges multiple navigation-bar actions into a compact, coherent right-side action
+cluster.
+
+### Usage
+
+#### Use for
+
+- Grouping two or more related header actions with consistent spacing and visual rhythm
+- Keeping right-side navigation bar actions organized when more than one control is needed
+- Preserving clear scanability of utility actions in compact top-bar areas
+- Supporting predictable action placement across screens that share similar header controls
+
+#### Don't use for
+
+- Do not group unrelated or conflicting actions that should be separated by context
+- Do not add too many controls in one group, reducing tappability and clarity
+- Do not use action groups as a substitute for overflow or menu patterns when action count grows
+- Do not place low-priority actions in the primary header action cluster
+
+## FunnelNavigationBar
+
+FunnelNavigationBar is a simplified top bar for focused transactional flows, keeping only essential branding
+and contextual actions.
+
+### Usage
+
+#### Use for
+
+- Guiding users through linear checkout, onboarding, or form funnels with minimal navigation distraction
+- Keeping focus on task completion while preserving essential brand and utility actions
+- Replacing broad section navigation when users should stay inside a constrained flow
+- Maintaining consistent funnel framing across multi-step transactional journeys
+
+#### Don't use for
+
+- Do not use FunnelNavigationBar when users need access to full primary section navigation
+- Do not add excessive secondary actions that compete with completion flow
+- Do not use it as a generic app header outside funnel-style task contexts
+- Do not combine it with parallel global menus that break focused journey intent
+
+## Accessibility
+
+### Heading hierarchy
+
+Provide a clear, descriptive page title in `NavigationBar`.
+
+- Keep heading hierarchy consistent in the screen content below it
+
+### Accessibility label
+
+Add explicit accessible labels to icon-only `NavigationBarAction` controls.
+
+- Ensure purpose is clear without visual context (for example, search, close, help, cart)
+- For back navigation, ensure the destination is predictable (for example, previous screen or parent section)
+- Keep header actions short and high-priority
+
+### Keyboard interaction
+
+When a section opens additional menu content, ensure users can operate the full flow with keyboard only.
+
+- Open, move through items, dismiss, and continue navigation
+- In `MainNavigationBar`, use concise and distinct section titles so menu triggers are easy to differentiate
+
+### Slot
+
+If section content is customized, preserve the same accessibility quality as default menu content.
+
+- Keep clear labels, logical focus order, and reachable interactive elements
+- In `FunnelNavigationBar`, keep only essential actions for task completion
diff --git a/doc/components/popover.md b/doc/components/popover.md
new file mode 100644
index 0000000000..bbf2bb00be
--- /dev/null
+++ b/doc/components/popover.md
@@ -0,0 +1,45 @@
+# Popover
+
+Popover presents richer contextual content in a dismissible anchored surface, suitable for guidance that needs
+more space than a tooltip.
+
+## Usage
+
+### Use for
+
+- Showing contextual explanations that need title, description, media, or extra content blocks
+- Presenting supplementary information that should remain visible until the user dismisses it
+- Anchoring richer helper content to a specific target without navigating away from current context
+- Offering non-primary actions or extended guidance where tooltip brevity is insufficient
+
+### Don't use for
+
+- Do not use Popover for very short hints where Tooltip is more lightweight and appropriate
+- Do not overload popovers with complex workflows that should be full dialogs or pages
+- Do not hide mandatory, high-risk decisions inside contextual popovers without clearer flow ownership
+- Do not allow content growth that compromises readability or positioning near the target
+
+## Accessibility
+
+### Accessibility label
+
+Use a clearly labeled trigger so users understand what additional content will open.
+
+- If the trigger is icon-only, provide an explicit accessible label (for example, "Open delivery details")
+- Ensure all interactive elements inside the popover have descriptive accessible names
+- When the same screen can open multiple overlays, set `closeButtonLabel` with contextual wording
+
+### Focus and navigation
+
+Preserve a logical focus flow.
+
+- Users should be able to open the popover, read or interact with content, close it, and continue from a
+ predictable place
+- If you control visibility with `open`, always wire `onClose` to the same state update so dismiss actions and
+ external close events keep UI and accessibility state in sync
+
+### Content scope
+
+Keep popover content concise and scannable, with a clear title and supporting description when needed.
+
+- Do not place critical confirmations or blocking decisions in popovers; use dialogs instead
diff --git a/doc/components/primitives.md b/doc/components/primitives.md
new file mode 100644
index 0000000000..a1d0e28288
--- /dev/null
+++ b/doc/components/primitives.md
@@ -0,0 +1,162 @@
+# Primitives
+
+## Image
+
+Image displays responsive media with controlled aspect ratio, loading skeleton, and graceful error fallback to
+keep layouts stable while assets load or fail.
+
+### Usage
+
+#### Use for
+
+- Displaying responsive media in cards, lists, and hero content while preserving intended composition ratios
+- Preventing layout jumps with fixed size or aspect-ratio containers during image loading
+- Providing resilient experiences with loading and error fallbacks when network or asset quality is variable
+- Using circular or rectangular presentation intentionally to match avatar-style vs content-image semantics
+
+#### Don't use for
+
+- Do not omit meaningful alternative text when the image conveys essential information
+- Do not rely on unconstrained image sizes that cause reflow or inconsistent cropping across breakpoints
+- Do not disable loading/error fallback patterns in contexts where reliability and perceived performance
+ matter
+- Do not mix arbitrary border radius and fit strategies without clear visual-system rationale
+
+## Video
+
+Use video for embedded media playback with responsive sizing, poster/error fallbacks, and controllable
+autoplay/loading behavior.
+
+### Usage
+
+#### Use for
+
+- Showing inline video content in cards, pages, or media sections with fixed dimensions or aspect ratio
+- Providing a poster image so layout remains stable while media loads or when playback is stopped
+- Delivering multiple video sources/formats for broader playback compatibility
+- Scenarios that need controlled playback behavior (manual, when-loaded autoplay, or streaming autoplay)
+- Experiences where custom play/pause/stop/load handling is orchestrated from parent logic
+
+#### Don't use for
+
+- Do not rely on autoplay as the only way users can consume important information
+- Do not omit fallback strategy (poster/error handling) when video availability is uncertain
+- Do not use heavy video assets in contexts where lightweight images communicate the same message
+- Do not choose inconsistent aspect ratios across related media blocks if visual rhythm matters
+- Do not treat this as background decoration only when no meaningful media interaction/value is provided
+
+## VideoElement
+
+VideoElement is a Mística component used to build consistent and accessible product interfaces.
+
+### Usage
+
+#### Use for
+
+- Applying the documented component pattern in product UI
+- Keeping user experience coherent across screens and flows
+
+#### Don't use for
+
+- Do not replace a more suitable semantic component with this one
+- Do not customize behavior in ways that conflict with Mística guidance
+
+## Circle
+
+Circle is a circular container used to frame visual content or compact UI elements with optional background
+and border styling.
+
+### Usage
+
+#### Use for
+
+- Displaying circular visual elements such as avatars, icons, or decorative media crops
+- Framing short content inside a compact round shape when circular emphasis is part of the visual language
+- Applying consistent circular backgrounds (solid, image-based, or custom) across related UI blocks
+- Adding subtle boundary definition with optional border when contrast is needed
+
+#### Don't use for
+
+- Do not use Circle as a generic layout wrapper for non-circular compositions
+- Do not place long text or complex multi-line content inside a circular frame
+- Do not rely on decorative circles alone to communicate critical information
+- Do not use low-contrast background and border combinations that reduce legibility
+
+## Touchable
+
+Touchable is a Mística component used to build consistent and accessible product interfaces.
+
+### Usage
+
+#### Use for
+
+- Applying the documented component pattern in product UI
+- Keeping user experience coherent across screens and flows
+
+#### Don't use for
+
+- Do not replace a more suitable semantic component with this one
+- Do not customize behavior in ways that conflict with Mística guidance
+
+## Placeholder
+
+Placeholder renders a neutral framed block for temporary visual stand-ins when real media or content is not
+yet available.
+
+### Usage
+
+#### Use for
+
+- Reserving layout space for pending media or components during design, QA, or prototyping stages
+- Visualizing intended content dimensions before final assets are integrated
+- Maintaining stable page composition when temporary stand-in blocks are needed
+- Communicating “content pending” states in internal previews and non-final environments
+
+#### Don't use for
+
+- Do not use Placeholder as a loading indicator in production flows; use skeleton/loading patterns instead
+- Do not present placeholders as final user-facing content in released experiences
+- Do not rely on placeholder blocks for critical information hierarchy or interaction affordances
+- Do not use generic placeholders when real fallback content can improve clarity and accessibility
+
+## FadeIn
+
+FadeIn is a lightweight wrapper that animates children from transparent to visible using a configurable fade
+transition (`duration` and `delay`).
+
+### Usage
+
+#### Use for
+
+- Revealing newly mounted content without abrupt appearance changes
+- Delaying visual entrance of secondary content by setting a custom `delay` (for example `1s`)
+- Tuning fade speed with `duration` when adapting motion rhythm to context
+- Wrapping any content block that should fade in while preserving existing layout and semantics
+
+#### Don't use for
+
+- Do not use FadeIn as the only indicator of critical state changes; pair with clear text/structure
+- Do not apply long or stacked delays that make content feel unresponsive
+- Do not use invalid CSS time values for `duration`/`delay`; pass valid values like `0.3s` or `200ms`
+- Do not wrap large full-screen transitions that need dedicated navigation/screen transition patterns
+
+## ScreenReaderOnly
+
+ScreenReaderOnly exposes content to assistive technologies while keeping it visually hidden in the interface.
+
+### Usage
+
+#### Use for
+
+- Providing additional descriptive text for screen reader users when visual UI elements lack explicit labels
+- Supplying hidden headings, context, or instructions that improve non-visual navigation
+- Adding accessible names for icon-only or highly condensed controls where visible text is intentionally
+ omitted
+- Preserving semantic structure while keeping visual layouts clean and uncluttered
+
+#### Don't use for
+
+- Do not hide information that sighted users also need to complete the task
+- Do not use ScreenReaderOnly to mask missing visible labels when visible clarity is required
+- Do not duplicate excessive hidden text that creates noisy or repetitive screen reader output
+- Do not rely on hidden-only instructions as the primary UX for critical or high-risk actions
diff --git a/doc/components/progress-indicators.md b/doc/components/progress-indicators.md
new file mode 100644
index 0000000000..49a86775df
--- /dev/null
+++ b/doc/components/progress-indicators.md
@@ -0,0 +1,69 @@
+# Progress Indicators
+
+## ProgressBar
+
+ProgressBar provides continuous linear feedback for task completion progress as a percentage.
+
+### Usage
+
+#### Use for
+
+- Showing completion progress for ongoing tasks in a clear linear direction
+- Communicating percent-based progress when users need reassurance that work is advancing
+- Reflecting continuous progression where completion can be expressed on a 0–100 scale
+- Keeping users informed during long-running operations with incremental completion updates
+
+#### Don't use for
+
+- Do not use ProgressBar to compare multiple category values; use Meter for segmented value visualization
+- Do not use ProgressBar for milestone-based step journeys; use ProgressBarStepped instead
+- Do not show misleading precision when underlying progress is approximate or uncertain
+- Do not leave progress indicators static without updates during long operations
+- Do not use reverse or directional effects to imply discrete step changes in wizard-like flows
+
+## ProgressBarStepped
+
+ProgressBarStepped shows progress across discrete milestones, highlighting completed and current steps in
+multi-step flows.
+
+### Usage
+
+#### Use for
+
+- Representing multi-step journeys where each stage is a meaningful milestone
+- Showing users their current step position and completed steps at a glance
+- Communicating both forward and backward movement between steps in editable flows
+- Reinforcing orientation in onboarding, checkout, and wizard-like task sequences
+
+#### Don't use for
+
+- Do not use ProgressBarStepped for continuous percentage-based progress without discrete stages
+- Do not define too many tiny steps that make milestone progress hard to perceive
+- Do not use it when step boundaries are unclear or can change unpredictably for users
+- Do not hide the step context from surrounding content; users should understand what each stage means
+
+## Accessibility
+
+### Accessibility label
+
+Provide a clear accessible name with process context whenever possible.
+
+- Prefer labels like "Loading images, 10% complete" or "Order in warehouse, step 2 of 5"
+- Avoid generic labels like "Loading" when the process can be described more precisely
+- `ProgressBar` includes a default loading label and progress value text, but you should still set a
+ contextual `aria-label` or `aria-labelledby`
+- For `ProgressBarStepped`, set `aria-label` or `aria-labelledby` so the step progress belongs to a clearly
+ identified flow
+
+### Hide from screen readers
+
+If the visual progress indicator is redundant with nearby announced information, hide it from assistive
+technologies with `aria-hidden`.
+
+### Status announcements
+
+Progress indicators do not automatically announce status transitions or errors.
+
+- Pair them with explicit status messages in the UI for key events such as completion, failure, or blocked
+ steps
+- Keep updates truthful and meaningful: do not present overly precise values when progress is estimated
diff --git a/doc/components/radio-button.md b/doc/components/radio-button.md
new file mode 100644
index 0000000000..add91091a3
--- /dev/null
+++ b/doc/components/radio-button.md
@@ -0,0 +1,67 @@
+# Radio Button
+
+## RadioButton
+
+RadioButton represents a single mutually exclusive option within a RadioGroup, enabling clear one-choice
+selection.
+
+### Usage
+
+#### Use for
+
+- Offering one explicit choice among a small set of alternatives visible at once
+- Making option comparison easy when users should see all available choices before selecting
+- Supporting single-choice interactions with direct click/tap and keyboard selection behavior
+- Pairing each option with concise labels so the selected state is immediately understandable
+
+#### Don't use for
+
+- Do not use standalone RadioButton without RadioGroup context
+- Do not use radios for independent multi-select scenarios; use checkboxes instead
+- Do not present too many options in one radio set when scanability degrades
+- Do not use ambiguous labels that make mutually exclusive choices unclear
+- Do not compose standalone radio controls inside row layouts that already support radio selection; use `Row`
+ or `BoxedRow` within a `RadioGroup` instead
+
+## RadioGroup
+
+RadioGroup manages a set of mutually exclusive options, including selection state and keyboard navigation
+across radio items.
+
+### Usage
+
+#### Use for
+
+- Grouping related RadioButton options into one coherent single-selection decision
+- Ensuring accessible selection patterns with radiogroup semantics and arrow-key navigation
+- Structuring form decisions where exactly one option should be chosen at a time
+- Managing default and controlled selection states in predictable one-choice workflows
+
+#### Don't use for
+
+- Do not use RadioGroup when users can select multiple options independently
+- Do not split one logical decision across multiple disconnected radio groups
+- Do not hide the group context or question prompt users need to make an informed selection
+- Do not use RadioGroup for long, dynamic option catalogs better served by other selector patterns
+
+## Accessibility
+
+### Accessibility label
+
+Always give each `RadioGroup` a clear accessible name with `aria-label` or `aria-labelledby`.
+
+- Keep option labels unique and specific to avoid ambiguity when moving through radios with a screen reader
+- For custom-rendered radios (`render` prop), ensure visible label text is programmatically associated with
+ the radio using `labelId`
+
+### Disabled state
+
+Use `disabled` only when selection is truly unavailable.
+
+- Provide nearby explanation when the reason is not obvious from context
+
+### Controlled state
+
+In controlled mode, keep `value` and `onChange` synchronized.
+
+- Selection state announced to assistive technologies must always match what is visually selected
diff --git a/doc/components/rating.md b/doc/components/rating.md
new file mode 100644
index 0000000000..239b57aab0
--- /dev/null
+++ b/doc/components/rating.md
@@ -0,0 +1,74 @@
+# Rating
+
+## Rating
+
+Rating captures user feedback through an interactive icon scale, supporting quantitative and qualitative
+evaluation patterns.
+
+### Usage
+
+#### Use for
+
+- Capturing user sentiment or score input as an explicit interactive choice
+- Using quantitative ratings (for example, stars) when users evaluate intensity on a numeric scale
+- Using qualitative ratings (for example, emotion icons) when users express satisfaction categories
+- Collecting feedback in moments where immediate, low-friction selection is preferable to text entry
+
+#### Don't use for
+
+- Do not use Rating to display static historical scores; use InfoRating for read-only display
+- Do not use unlabeled or unclear icon sets that make score meaning ambiguous
+- Do not force rating input when feedback is optional and users need a neutral skip path
+- Do not mix qualitative and quantitative semantics in the same user task without a clear rationale
+
+## InfoRating
+
+InfoRating displays read-only scores with rating icons, including accessible value narration for assistive
+technologies.
+
+### Usage
+
+#### Use for
+
+- Displaying existing ratings in product cards, lists, and summaries without enabling user editing
+- Communicating score magnitude quickly with compact iconography, including optional half values
+- Supporting accessible reading of score context when no visible textual score is present
+- Reusing the same rating visual language as input ratings while keeping the state non-interactive
+
+#### Don't use for
+
+- Do not use InfoRating to collect user feedback; use Rating when interaction is required
+- Do not present decorative ratings without meaningful value context for assistive technologies
+- Do not over-precision score displays when the source data does not justify half-step granularity
+- Do not use rating visuals as the only trust signal; pair with enough surrounding product context
+
+## Accessibility
+
+### Role
+
+Choose the rating variant according to user intent.
+
+- Use `Rating` when users must select a value
+- Use `InfoRating` when the value is informative only
+
+### Accessibility label
+
+Name the rating context so users understand what is being rated.
+
+- Provide explicit labels when nearby context is not enough
+- Keep labels concise and contextual (for example, `Product satisfaction rating`)
+- For read-only ratings, ensure value meaning is clear in the accessible name/context
+
+### Value meaning
+
+When rating value conveys decision-critical information, make the scale explicit.
+
+- For interactive Rating, keep option labels understandable (quantitative or qualitative)
+- For InfoRating, do not rely only on icon shape/color; pair with surrounding text or explicit label context
+
+### Keyboard interaction
+
+Interactive rating should be easy to reach and operate with keyboard.
+
+- Ensure it is reachable in normal tab order
+- Do not override standard keyboard navigation patterns in custom wrappers
diff --git a/doc/components/select.md b/doc/components/select.md
new file mode 100644
index 0000000000..82674301a4
--- /dev/null
+++ b/doc/components/select.md
@@ -0,0 +1,33 @@
+# Select
+
+Allow users to make a single selection between multiple options.
+
+## Usage
+
+### Use for
+
+- Capturing one choice from a predefined list when users should select, not type
+- Presenting compact option sets in forms where vertical space is limited
+- Supporting platform-native picker behavior on mobile devices for familiar interaction
+- Providing a controlled dropdown experience with clear selected-state feedback on desktop
+
+### Don't use for
+
+- Do not use Select for multi-select decisions; use checkbox or dedicated multi-select patterns instead
+- Do not use it for very long option catalogs where search/filter interaction is needed
+- Do not hide labels or helper text when option meaning is ambiguous
+- Do not force custom dropdown behavior when native mobile selection is more usable
+
+## Accessibility
+
+### Accessibility label
+
+Always provide a clear, descriptive `label` that explains the decision users are making.
+
+- Keep option text concise and unambiguous so choices are easy to understand when announced one by one
+
+### Helper and error text
+
+Include helper text when users need extra context, and use error text for invalid states.
+
+- Keep validation feedback explicit so users understand what needs to change
diff --git a/doc/components/skeletons.md b/doc/components/skeletons.md
new file mode 100644
index 0000000000..ef733558b4
--- /dev/null
+++ b/doc/components/skeletons.md
@@ -0,0 +1,103 @@
+# Skeletons
+
+## SkeletonCircle
+
+It is a more atomic type of skeleton to create compositions that do not fit with the rest of the skeleton
+types.
+
+### Usage
+
+#### Use for
+
+- Representing circular loading placeholders such as avatars, profile images, or round icons
+- Composing custom skeleton layouts that require circular visual anchors
+- Preserving expected media footprint in list rows and identity-driven components
+- Pairing with line/text skeletons to build richer loading compositions
+
+#### Don't use for
+
+- Do not use SkeletonCircle for rectangular media slots; use SkeletonRectangle instead
+- Do not use circular placeholders when final content is not round-shaped
+- Do not keep circular skeletons visible after actual media is ready
+- Do not combine circle sizes inconsistently in the same loading pattern without hierarchy rationale
+
+## SkeletonLine
+
+SkeletonLine displays a single loading placeholder bar for short linear content blocks.
+
+### Usage
+
+#### Use for
+
+- Representing one pending text line, label, or compact metadata element
+- Preserving horizontal rhythm while content is loading asynchronously
+- Matching simple one-line placeholders in tight list or form contexts
+- Building custom skeleton compositions where a single line unit is needed
+
+#### Don't use for
+
+- Do not use SkeletonLine to represent multi-paragraph text blocks; use SkeletonText instead
+- Do not keep line skeletons visible after content is already available
+- Do not use a single line placeholder when structural loading context is unclear
+- Do not mix inconsistent line widths randomly without content hierarchy intent
+
+## SkeletonRectangle
+
+SkeletonRectangle provides a block-shaped loading placeholder for media and container surfaces of varying
+sizes.
+
+### Usage
+
+#### Use for
+
+- Representing pending image, video, banner, or card-surface content with rectangular geometry
+- Reserving stable layout space while large visual assets load
+- Supporting full-size loading placeholders in media-first cards and sections
+- Matching container-level loading states where line or circular skeletons are insufficient
+
+#### Don't use for
+
+- Do not use SkeletonRectangle for round media placeholders; use SkeletonCircle instead
+- Do not keep rectangular skeletons after real media/content is available
+- Do not use oversized placeholder blocks that distort expected final layout proportions
+- Do not present skeleton rectangles without nearby context when users need clearer loading meaning
+
+## SkeletonRow
+
+Skeleton row can be used to represent components like lists (also in its boxed variant).
+
+### Usage
+
+#### Use for
+
+- Representing list-row loading states that combine avatar/media and one-line text content
+- Preserving row-level structure in feeds, option lists, or summary rows while loading
+- Providing realistic row placeholders for patterns that mirror list-item anatomy
+- Maintaining perceived progress in list-heavy screens where content arrives incrementally
+
+#### Don't use for
+
+- Do not use SkeletonRow for complex card layouts with multiple text blocks and actions
+- Do not use row skeletons when final UI is not row-based
+- Do not keep row placeholders visible after row data is rendered
+- Do not stack excessive row skeletons when a smaller preview set can communicate loading state
+
+## SkeletonText
+
+Skeleton text should be used where text elements like headings, paragraphs, or labels will be rendered.
+
+### Usage
+
+#### Use for
+
+- Representing loading states for text-heavy content blocks with multiple lines
+- Preserving expected text rhythm before headings, paragraphs, or descriptions are available
+- Signaling asynchronous content loading in cards, detail views, and textual summaries
+- Providing a more realistic text placeholder than isolated single-line skeletons
+
+#### Don't use for
+
+- Do not use SkeletonText for media-first placeholders where rectangle or circle shapes are more accurate
+- Do not leave skeleton text active after loading completes
+- Do not use text skeletons when no textual content is expected in the final layout
+- Do not overload screens with too many simultaneous skeleton blocks that harm readability
diff --git a/doc/components/skip-link.md b/doc/components/skip-link.md
new file mode 100644
index 0000000000..5bbfeb1385
--- /dev/null
+++ b/doc/components/skip-link.md
@@ -0,0 +1,62 @@
+# SkipLink
+
+## SkipLink
+
+A skip link allows keyboard and screen reader users to bypass repeated blocks of content and jump directly to
+other content of the page.
+
+### Usage
+
+#### Use for
+
+- Letting keyboard users skip repetitive header/navigation blocks and jump to main content quickly
+- Providing fast access to key page landmarks such as content, filters, or footer regions
+- Improving accessibility in layouts with repeated structural elements across pages
+- Supporting assistive-technology workflows that depend on predictable in-page anchor targets
+
+#### Don't use for
+
+- Do not point SkipLink to missing or unstable target ids
+- Do not use vague link text that does not clearly describe destination context
+- Do not hide critical navigation only inside skip links; they complement, not replace, primary navigation
+- Do not add skip links when there is no repeated block to bypass
+
+## SkipLinkNav
+
+SkipLinkNav groups multiple skip links inside a labeled navigation landmark for accessible quick-jump
+navigation.
+
+### Usage
+
+#### Use for
+
+- Grouping multiple skip destinations in one dedicated accessibility navigation block
+- Providing a clear labeled landmark for assistive technologies to discover skip options
+- Organizing skip links consistently when pages contain several major content regions
+- Maintaining coherent keyboard-first navigation patterns across complex layouts
+
+#### Don't use for
+
+- Do not use SkipLinkNav for regular site navigation menus
+- Do not include redundant skip entries that point to the same destination
+- Do not omit descriptive navigation labeling when multiple skip groups exist
+- Do not overpopulate skip navigation with low-value destinations
+
+## Accessibility
+
+### Accessibility label
+
+Use clear destination-oriented link text so users understand exactly where focus will move.
+
+- For example, "Skip to main content" or "Skip to filters"
+- You can set an accessibility label for each `SkipLink` using `aria-label`; when not provided, the displayed
+ link text is used as the accessible name
+- For multiple skip links, wrap them in `SkipLinkNav` and set a clear `aria-label`
+- When multiple skip links are present, keep their wording distinct
+
+### Skip targets
+
+Keep skip targets stable and meaningful.
+
+- Each `targetId` should point to a real section users expect to reach
+- Prioritize high-value destinations (main content, search/filter region, key complementary sections)
diff --git a/doc/components/slider.md b/doc/components/slider.md
new file mode 100644
index 0000000000..de52048f8f
--- /dev/null
+++ b/doc/components/slider.md
@@ -0,0 +1,43 @@
+# Slider
+
+Use slider for selecting a value by dragging along a bounded range, with optional tooltip feedback while
+interacting.
+
+## Usage
+
+### Use for
+
+- Letting people choose a numeric value within a known min/max interval
+- Fine-tuning values with defined increments (`step`) or snapping to a predefined set of allowed values
+- Exposing immediate value feedback during drag, hover, or focus (for example with the optional tooltip)
+- Inputs where direct manipulation is faster than typing, especially on touch devices
+
+### Don't use for
+
+- Do not use for read-only values; show static text or another non-interactive pattern instead
+- Do not use when users must enter an exact value that is easier to type directly
+- Do not use for binary on/off decisions; use a control designed for toggles or single-choice selection
+- Do not rely only on tooltip value feedback; keep a clear label and accessible naming for the control
+
+## Accessibility
+
+### Accessibility label
+
+Provide an accessible name for the slider whenever possible (`aria-label` or `aria-labelledby`).
+
+- If no accessible name is provided, the control may be announced generically as "slider"
+- Keep label wording task-oriented (what the value controls), not only unit-oriented
+
+### Value feedback
+
+Treat tooltip value display as supportive only.
+
+- Do not rely on tooltip visibility as the only way to understand current value
+- For wide ranges (for example, 0 to 100), pair the slider with an `IntegerField` so users can either drag or
+ type an exact value
+
+### Keyboard interaction
+
+Use predictable bounds and increments (`min`, `max`, `step`).
+
+- Keep keyboard and assistive technology interactions understandable and consistent
diff --git a/doc/components/snackbar.md b/doc/components/snackbar.md
new file mode 100644
index 0000000000..19286df7cb
--- /dev/null
+++ b/doc/components/snackbar.md
@@ -0,0 +1,63 @@
+# Snackbar
+
+## Snackbar
+
+Use snackbar for brief, non-blocking feedback about a recent action, with optional action and dismiss
+controls.
+
+### Usage
+
+#### Use for
+
+- Confirming short-lived outcomes after user actions (for example success/failure of a lightweight operation)
+- Offering one immediate follow-up action in context (button) without interrupting the current flow
+- Showing transient notifications that auto-close, or persistent ones when explicit dismissal is required
+- Communicating message severity through informative and critical snackbar types
+
+#### Don't use for
+
+- Do not use for blocking decisions, multi-step actions, or content that requires sustained attention; use
+ modal/sheet patterns instead
+- Do not place long text or multiple competing actions inside a snackbar
+- Do not depend on stacked snackbars for important communication; consecutive messages replace the current one
+- Do not use as the only place for critical permanent information; snackbars are temporary status feedback
+
+## useSnackbar
+
+useSnackbar provides reusable behavior to keep component logic consistent across the product.
+
+### Usage
+
+#### Use for
+
+- Sharing common state and behavior across multiple components
+- Keeping implementation aligned with Mística patterns
+
+#### Don't use for
+
+- Do not duplicate equivalent logic when this utility already exists
+- Do not use it without understanding its side effects and scope
+
+## Accessibility
+
+### Accessibility label
+
+Keep snackbar messages short, specific, and outcome-oriented.
+
+- Use `buttonAccessibilityLabel` when the visible action text is ambiguous in context
+- Use `closeButtonLabel` when a custom dismiss label improves clarity
+- If dismissal is important for user control, expose a dismiss button (`withDismiss`)
+
+### Dismiss behavior
+
+Choose dismiss behavior based on content priority.
+
+- If the snackbar includes a critical action (other than dismiss), prefer a persistent snackbar
+- If the snackbar has no relevant action, or only a dismiss action, prefer timed auto-dismiss behavior
+
+### Content scope
+
+Treat snackbar as transient feedback only.
+
+- Do not rely on consecutive snackbars for critical information
+- For content that must remain available or requires confirmation, use a more persistent pattern
diff --git a/doc/components/stacking-group.md b/doc/components/stacking-group.md
new file mode 100644
index 0000000000..8feee8f207
--- /dev/null
+++ b/doc/components/stacking-group.md
@@ -0,0 +1,41 @@
+# StackingGroup
+
+Use stacking group to display a compact set of similarly sized items, optionally overlapped, with a `+N`
+overflow indicator.
+
+When the number of children exceeds `maxItems`, StackingGroup automatically replaces the last visible slot
+with the generated `+N` element. That overflow element inherits the configured `moreItemsStyle` shape and
+size, and summarizes the hidden items instead of rendering them individually.
+
+## Usage
+
+### Use for
+
+- Showing small collections of visual items (for example avatars) in a compact horizontal group
+- Creating overlapped compositions (`stacked`) to save space while preserving item count awareness
+- Limiting visible items with `maxItems` and communicating hidden items through the generated `+N` element
+- Keeping overflow styling consistent with the item shape (`circle` or `square`) and size
+
+### Don't use for
+
+- Do not use for content with mixed sizes or complex card layouts; this pattern assumes uniform item sizing
+- Do not use when each hidden item must remain individually identifiable or directly actionable
+- Do not set `maxItems` so low that the `+N` indicator becomes the dominant content
+- Do not rely on overlap when readability is critical; use non-stacked spacing instead
+
+## Accessibility
+
+### Accessibility label
+
+Use clear nearby context (title or label) so users understand what the group represents.
+
+- Ensure each visible item has its own accessible name when items are meaningful (for example, person avatars)
+- If the group is decorative only, hide it from assistive technologies at container level
+
+### Content scope
+
+Treat StackingGroup as a compact visual summary, not as the only way to access member information.
+
+- When using `maxItems`, provide another accessible path to hidden members (for example, a full list or
+ details view)
+- Prefer non-stacked spacing when overlap reduces recognition of faces, logos, or other critical visual cues
diff --git a/doc/components/stepper.md b/doc/components/stepper.md
new file mode 100644
index 0000000000..96290da80d
--- /dev/null
+++ b/doc/components/stepper.md
@@ -0,0 +1,43 @@
+# Stepper
+
+Use stepper to show progress through a linear multi-step flow, highlighting completed and current steps.
+
+## Usage
+
+### Use for
+
+- Communicating where users are within a predefined sequence of steps
+- Flows where step order matters and users benefit from seeing completed, current, and upcoming stages
+- Processes that have clear, short labels for each step so progress remains understandable
+- Interfaces that need accessible step status announcements (current/completed) for assistive technologies
+
+### Don't use for
+
+- Do not use for non-linear navigation where users can jump freely between unrelated sections
+- Do not use when there are too many steps or long labels that make progress hard to scan
+- Do not use as the only guidance in complex flows; pair it with clear page titles and instructions
+- Do not treat it as a clickable navigation menu if the interaction model is only progress indication
+
+## Accessibility
+
+### Accessibility label
+
+Always provide meaningful step labels, even when labels are visually reduced on smaller screens.
+
+- Give the stepper itself a clear accessible name with `aria-label` or `aria-labelledby` (for example,
+ "Checkout progress")
+- Keep labels short, specific, and consistent across steps
+
+### Heading hierarchy
+
+In addition to the stepper label, include a clear page heading for each step.
+
+- For example, "Step 2: Company details" so users always know where they are in the flow
+
+### Role
+
+Stepper is announced as an ordered list.
+
+- Preserve real sequence semantics and do not use it for unrelated or parallel navigation paths
+- If stepper status can change dynamically, ensure surrounding page content and headings are updated
+ consistently with the new current step
diff --git a/doc/components/switch.md b/doc/components/switch.md
new file mode 100644
index 0000000000..eee660befd
--- /dev/null
+++ b/doc/components/switch.md
@@ -0,0 +1,39 @@
+# Switch
+
+Use switch for immediate on/off settings, ensuring each control has a clear visible or accessible label.
+
+## Usage
+
+### Use for
+
+- Binary preferences or settings that can be turned on and off independently
+- Cases where the state change is immediate and does not require a separate confirmation action
+- Interfaces with short, explicit labels (or accessible labels) so users understand the effect of each toggle
+
+### Don't use for
+
+- Do not use for choosing one option among many; use radio/select patterns for single-choice selection
+- Do not use for irreversible, high-impact actions that require explicit confirmation
+- Do not leave switches unlabeled or ambiguously labeled; provide clear visible text or
+ `aria-label`/`aria-labelledby`
+- Do not use as a read-only status indicator; use non-interactive status text or badges instead
+- Do not compose a standalone switch inside row layouts that already support switches; use `Row` or `BoxedRow`
+ with built-in switch support instead
+
+## Accessibility
+
+### Accessibility label
+
+Always give each switch a clear, descriptive label that explains the effect of turning it on or off.
+
+- If visible text is missing or ambiguous, use an existing nearby UI label via `aria-labelledby`, or provide a
+ hidden label with `aria-label`
+- Keep labels unique when multiple switches appear together
+- For custom-rendered switch content, ensure the visible text remains programmatically associated with the
+ switch
+
+### Disabled state
+
+Use disabled state only when the setting is truly unavailable.
+
+- Provide nearby explanation when the reason is not obvious
diff --git a/doc/components/table.md b/doc/components/table.md
new file mode 100644
index 0000000000..4ea3891359
--- /dev/null
+++ b/doc/components/table.md
@@ -0,0 +1,47 @@
+# Table
+
+Use table for structured row-and-column data, with responsive behavior for mobile scrolling or collapsed row
+cards.
+
+## Usage
+
+### Use for
+
+- Displaying comparable structured data across multiple rows and columns
+- Data sets that need clear column headers and optional row headers for better scanning and accessibility
+- Tables that require per-row actions while keeping actions aligned and consistent
+- Responsive scenarios where mobile users either scroll horizontally or see rows collapsed into card-like
+ blocks
+- Representing empty states directly inside the table container when no rows are available
+
+### Don't use for
+
+- Do not use for unstructured rich content layouts; use cards or list compositions instead
+- Do not hide headers unless users can still understand each cell context (especially in responsive/collapsed
+ views)
+- Do not force dense tables on small screens without choosing an appropriate responsive mode
+- Do not overload rows with too many actions; keep row actions focused and scannable
+- Do not use table when each item requires unique layout or long-form content rather than comparison
+
+## Accessibility
+
+### Accessibility label
+
+Give each table a clear accessible title using `aria-label` or `aria-labelledby`.
+
+- Prefer referencing existing visible UI text with `aria-labelledby` when possible
+- If row actions are present, give each action a descriptive accessible label
+
+### Column headers
+
+Keep column headers explicit and meaningful, including the actions column.
+
+- Headers can be visually hidden when needed, but only if table context remains complete for assistive
+ technologies
+- In responsive or collapsed-row layouts, ensure each data value still has clear header context
+
+### Empty state
+
+When the table has no rows, provide a clear empty-state message.
+
+- Explain the situation and possible next step
diff --git a/doc/components/tabs.md b/doc/components/tabs.md
new file mode 100644
index 0000000000..da380e292e
--- /dev/null
+++ b/doc/components/tabs.md
@@ -0,0 +1,34 @@
+# Tabs
+
+Use tabs to switch between related sections within the same context, with one active tab at a time.
+
+## Usage
+
+### Use for
+
+- Organizing peer sections of content that belong to the same page or task context
+- Allowing quick switching between views while keeping the user in place
+- Short tab labels (with optional icons) that remain scannable in horizontal navigation
+- Accessible tab interfaces with clear tablist, tab, and tabpanel relationships and keyboard arrow navigation
+
+### Don't use for
+
+- Do not use tabs for primary app/site navigation between unrelated destinations
+- Do not use when users need to compare multiple sections side by side; tabs hide non-selected content
+- Do not create too many tabs with long labels that cause poor discoverability and scrolling overhead
+- Do not break tab-to-panel semantics when providing custom panel rendering
+
+## Accessibility
+
+### Accessibility label
+
+Give the tab list a clear accessible name with `aria-label` or `aria-labelledby`.
+
+- Keep tab labels short, distinct, and task-oriented
+- If icons are used, do not rely on icon-only meaning; keep clear text labels
+
+### Content scope
+
+Keep panel content focused on one topic per tab.
+
+- Do not place unrelated controls in the tab strip
diff --git a/doc/components/tag.md b/doc/components/tag.md
new file mode 100644
index 0000000000..3b05ce100b
--- /dev/null
+++ b/doc/components/tag.md
@@ -0,0 +1,40 @@
+# Tag
+
+Use tag to display short categorical or status labels, with optional icon and badge count in a compact visual
+token.
+
+## Usage
+
+### Use for
+
+- Highlighting concise status/category signals such as promo, info, active/inactive, success, warning, or
+ error
+- Attaching short contextual metadata to cards, list items, or headers without taking much space
+- Adding a small icon or badge/count when extra context is needed while preserving compact layout
+- Using small or default tag size to match information density of the surrounding UI
+
+### Don't use for
+
+- Do not use for long text, descriptions, or content that requires wrapping and detailed reading
+- Do not use as a primary action control; tags communicate state/category rather than trigger complex
+ interactions
+- Do not use Tag for interactive behaviors (selection, navigation, dismissal); use Chip for those interaction
+ patterns
+- Do not combine too many tags in tight spaces if they reduce scanability
+- Do not rely on color alone to convey meaning; keep label text explicit and understandable
+
+## Accessibility
+
+### Tag text
+
+Keep tag text short, explicit, and self-explanatory so meaning is understandable without relying on color.
+
+- Avoid ambiguous labels like "Active" without nearby context when multiple entities or states are present
+- Treat icons and badge counts as complementary cues; the text label should still communicate the core status
+ or category
+
+### Density and truncation
+
+If many tags are shown together, prioritize the most relevant ones to reduce cognitive load for all users.
+
+- When truncation can occur in narrow layouts, ensure full meaning is still available in surrounding content
diff --git a/doc/components/text-link.md b/doc/components/text-link.md
new file mode 100644
index 0000000000..7ed272735a
--- /dev/null
+++ b/doc/components/text-link.md
@@ -0,0 +1,38 @@
+# TextLink
+
+Use text link (or hyperlink) to create inline linkable text.
+
+## Usage
+
+### Use for
+
+- Inline navigation or lightweight contextual actions embedded in text content
+- Short, descriptive link copy that clearly communicates destination or result
+- Cases where link styling (always-underlined or underline-on-hover) helps preserve reading flow
+- Links that should follow form state behavior (for example disabling while a form is sending)
+
+### Don't use for
+
+- Do not use as the primary call-to-action when a button pattern is more appropriate
+- Do not rely on generic text like “click here”; link text should remain meaningful out of context
+- Do not fake link semantics with custom roles when native link navigation is available
+- Do not place dense clusters of text links where users may struggle to identify the main action
+
+## Accessibility
+
+### Accessibility label
+
+Write link text that clearly describes destination or result when read out of context.
+
+- Avoid generic copy such as "here" or "more"
+- If visible copy is not sufficient in context, provide a more descriptive accessible name with `aria-label`
+- When a link opens in a new tab/window, make sure that behavior is clearly communicated to users
+
+### Disabled state
+
+Avoid using disabled links in most cases.
+
+- A disabled link often behaves like plain text and creates confusion about whether an action is available
+- Prefer reframing the UI with regular text until navigation becomes available
+- If link availability depends on form state, ensure users still understand why navigation is temporarily
+ unavailable
diff --git a/doc/components/text.md b/doc/components/text.md
new file mode 100644
index 0000000000..4124ec570d
--- /dev/null
+++ b/doc/components/text.md
@@ -0,0 +1,203 @@
+# Text
+
+## Text
+
+Foundational typography primitive for custom text rendering when preset components (`Text1`–`Text10`) do not
+cover the need.
+
+### Usage
+
+#### Use for
+
+- Building custom text compositions that need explicit control of size, line-height, weight, truncation, or
+ semantic element (`as`)
+- Advanced typography cases that still must integrate with Mística theme variants and accessibility attributes
+- Implementing edge cases where preset levels (`Text1`–`Text10`) are not sufficient
+- Rendering text with controlled behaviors like multi-line truncation, alignment, transform, and hyphenation
+
+#### Don't use for
+
+- Do not use this primitive by default when a text preset communicates hierarchy correctly
+- Do not break typographic consistency by creating arbitrary one-off sizes for standard product copy
+- Do not use styling alone to convey structure; keep proper semantic tags for headings and content
+- Do not overuse truncation when full content is required for comprehension
+
+## Text1
+
+Small preset text level for compact supporting information and dense UI metadata.
+
+### Usage
+
+#### Use for
+
+- Compact secondary information such as helper labels, table headers, or low-emphasis metadata
+- Dense layouts where readability must be preserved without increasing visual weight
+- Supporting copy that should remain clearly below body text in hierarchy
+
+#### Don't use for
+
+- Do not use for primary body copy that users must read continuously
+- Do not use for headings or key messages that need strong prominence
+- Do not rely on this level when accessibility requires larger, easier-to-read copy
+
+## Text2
+
+Low-emphasis preset text level for secondary copy that remains more readable than compact metadata styles.
+
+### Usage
+
+#### Use for
+
+- Secondary explanatory text near controls, cards, and list rows
+- Supporting content that should be visible but not dominate the screen
+- Lightweight descriptive copy under stronger titles or values
+
+#### Don't use for
+
+- Do not use for the main reading text in long-form content blocks
+- Do not use for top-level headings or high-priority messaging
+- Do not mix this level inconsistently when adjacent elements require clearer hierarchy separation
+
+## Text3
+
+Baseline preset text level for standard body copy in most product interfaces.
+
+### Usage
+
+#### Use for
+
+- Default body text in forms, cards, dialogs, and content sections
+- General-purpose readable copy where no special prominence is required
+- Paragraphs and descriptions that users need to read comfortably
+
+#### Don't use for
+
+- Do not use for minor metadata that should be visually quieter
+- Do not use for headlines that need stronger visual hierarchy
+- Do not mix many body sizes in the same block when one consistent level is enough
+
+## Text4
+
+Emphasized text preset for short content blocks that need more presence than standard body text.
+
+### Usage
+
+#### Use for
+
+- Short prominent descriptions, callouts, or intro copy above regular body text
+- Intermediate hierarchy between body copy and section headings
+- UI moments where emphasis is needed without using display-level typography
+
+#### Don't use for
+
+- Do not use for long dense paragraphs where a calmer body level improves readability
+- Do not use as the main page headline level
+- Do not apply this emphasis to every text block, or hierarchy loses meaning
+
+## Text5
+
+High-emphasis text preset for section-leading copy and compact subheading use cases.
+
+### Usage
+
+#### Use for
+
+- Subsection titles and introductory statements above body content
+- Prominent supporting copy in cards, banners, and feedback components
+- Short textual anchors that need quick scanning in complex layouts
+
+#### Don't use for
+
+- Do not use for long paragraph content
+- Do not use as the largest page headline level when stronger hierarchy is required
+- Do not skip semantics; if it is a heading, render with an appropriate heading element
+
+## Text6
+
+Heading-oriented preset for strong section titles and key interface messages.
+
+### Usage
+
+#### Use for
+
+- Primary section headings inside pages and major containers
+- High-visibility titles in feedback, onboarding, or transactional summaries
+- Clear hierarchy breaks before supporting descriptions and actions
+
+#### Don't use for
+
+- Do not use for regular body or helper text
+- Do not overuse this level in small components where it competes with surrounding content
+- Do not present heading-styled text without corresponding semantic structure
+
+## Text7
+
+Prominent heading preset for high-priority titles that need stronger visual impact than section headings.
+
+### Usage
+
+#### Use for
+
+- High-priority screen titles and standout content headers
+- Hero-like title areas that still sit within regular page layouts
+- Short textual anchors that must be noticed quickly
+
+#### Don't use for
+
+- Do not use for dense body content or long paragraphs
+- Do not use multiple Text7 blocks in the same visual area without clear hierarchy
+- Do not use when a lower heading level already solves the hierarchy need
+
+## Text8
+
+Display-oriented preset for large headings in standout surfaces such as hero or campaign blocks.
+
+### Usage
+
+#### Use for
+
+- Large, attention-grabbing headings in hero and promotional contexts
+- High-impact title moments where hierarchy must be immediately clear
+- Short display copy that benefits from strong typographic presence
+
+#### Don't use for
+
+- Do not use in dense layout areas where large typography reduces readability
+- Do not use for long multiline paragraphs
+- Do not overuse alongside other display levels in the same section
+
+## Text9
+
+Large display text preset for very prominent titles and high-impact messaging moments.
+
+### Usage
+
+#### Use for
+
+- Very prominent hero or campaign headlines
+- Major entry-point titles where visual emphasis is intentionally high
+- Short statements designed to be scanned immediately
+
+#### Don't use for
+
+- Do not use in standard content flows where smaller heading levels preserve rhythm
+- Do not use for supporting or secondary copy
+- Do not combine with long body text in the same block without clear spacing/hierarchy separation
+
+## Text10
+
+Top display typography level for the most prominent titles in exceptional, high-visibility contexts.
+
+### Usage
+
+#### Use for
+
+- Highest-emphasis headings such as flagship hero titles or exceptional campaign moments
+- Very short, high-importance statements that need maximum visual prominence
+- Landing or cover areas where a single dominant typographic anchor is required
+
+#### Don't use for
+
+- Do not use for regular interface headings or repeated section titles
+- Do not use for paragraph content or explanatory text
+- Do not apply this level in constrained spaces where it harms readability or layout balance
diff --git a/doc/components/timeline.md b/doc/components/timeline.md
new file mode 100644
index 0000000000..719f7f3462
--- /dev/null
+++ b/doc/components/timeline.md
@@ -0,0 +1,52 @@
+# Timeline
+
+## Timeline
+
+The Timeline component is used to represent events in a chronological timeline. It can be used to visually and
+organizedly display processes,.
+
+### Usage
+
+#### Use for
+
+- Applying the documented component pattern in product UI
+- Keeping user experience coherent across screens and flows
+
+#### Don't use for
+
+- Don't use a timeline to guide a user through a step flow use the stepper or
+- Do not replace a more suitable semantic component with this one
+- Do not customize behavior in ways that conflict with Mística guidance
+
+## TimelineItem
+
+TimelineItem is a Mística component used to build consistent and accessible product interfaces.
+
+### Usage
+
+#### Use for
+
+- Applying the documented component pattern in product UI
+- Keeping user experience coherent across screens and flows
+
+#### Don't use for
+
+- Do not replace a more suitable semantic component with this one
+- Do not customize behavior in ways that conflict with Mística guidance
+
+## Accessibility
+
+### Accessibility label
+
+Give the timeline a clear accessible name (`aria-label` or `aria-labelledby`).
+
+- Ensure each `TimelineItem` includes meaningful textual content (step title, status, or event description),
+ not only decorative visual assets
+- Use short, explicit labels for states and milestones
+
+### Role
+
+Keep item order consistent with real chronology so list navigation matches the expected sequence.
+
+- Mark exactly one current step/event at a time in linear flows
+- Keep current status synchronized with the surrounding page content
diff --git a/doc/components/timer.md b/doc/components/timer.md
new file mode 100644
index 0000000000..59911bf76a
--- /dev/null
+++ b/doc/components/timer.md
@@ -0,0 +1,70 @@
+# Timer
+
+## TextTimer
+
+Use text timer for inline countdowns embedded in sentences or short blocks of copy.
+
+### Usage
+
+#### Use for
+
+- Showing a live countdown inside running text without breaking reading flow
+- Compact deadline messaging (for example offers or verification windows) where space is limited
+- Countdowns that need flexible unit granularity (from seconds up to days) and optional short/long labels
+- Contexts where accessible timer announcements are needed while keeping visual output lightweight
+
+#### Don't use for
+
+- Do not use when the timer must be the primary visual element; use the display `Timer` component instead
+- Do not combine too many units/long labels in narrow layouts if it harms readability
+- Do not use for static date/time display with no countdown behavior
+- Do not depend on inline timer text alone for critical task deadlines without supporting explanatory context
+
+## Timer
+
+Use timer for prominent countdown displays with segmented time units, optionally boxed for stronger visual
+emphasis.
+
+### Usage
+
+#### Use for
+
+- Highlighting countdowns as a key visual element in a screen or section
+- Showing time units in a clear display format (days/hours/minutes/seconds) with configurable min and max
+ units
+- Promotional, transactional, or time-limited contexts where users must quickly scan remaining time
+- Boxed presentation when countdowns need extra contrast or placement over rich backgrounds/images
+
+#### Don't use for
+
+- Do not use for subtle inline references inside paragraph text; use `TextTimer` for that pattern
+- Do not display unnecessary units when simpler granularity communicates urgency better
+- Do not treat timer styling as decoration without a real time-based behavior
+- Do not rely on the visual countdown alone for critical instructions; pair it with explicit contextual
+ messaging
+
+## Accessibility
+
+`TextTimer` and `Timer` share the same accessibility considerations.
+
+### Accessibility label
+
+Add an accessibility label (`aria-label`) to provide countdown context.
+
+- For example: "Offer countdown" or "Verification code expires in"
+- If no label is provided, assistive technology still announces the remaining time, but users may miss context
+ about what the countdown refers to
+
+### Value announcement
+
+Regardless of visual style, screen readers announce the timer in a long countdown format.
+
+- For example: "A label. 0 hours, 0 minutes and 1 second"
+- Choose min and max time units that match user decisions (for example, avoid showing days when users only
+ need minute-level urgency)
+
+### Content scope
+
+For critical deadlines, pair the timer with clear nearby text that explains consequence and next action.
+
+- For example, "Request a new code when this reaches zero"
diff --git a/doc/components/titles.md b/doc/components/titles.md
new file mode 100644
index 0000000000..5adbe4f9ec
--- /dev/null
+++ b/doc/components/titles.md
@@ -0,0 +1,93 @@
+# Titles
+
+## Title1
+
+Compact overline-style section title for low-emphasis grouping labels, typically uppercase and secondary in
+tone.
+
+### Usage
+
+#### Use for
+
+- Labeling functional sub-sections with a subtle heading level above primary content titles
+- Categorization headers that should separate blocks without dominating the layout
+- Header rows that may include lightweight right-side companion content (for example a small link/value)
+
+#### Don't use for
+
+- Do not use as the main page or section headline when stronger hierarchy is required
+- Do not use for long heading text; keep this level short and scannable
+- Do not rely on visual style only; keep proper heading semantics via the appropriate heading element
+
+## Title2
+
+Standard section heading level for dividing related content blocks with clear but balanced prominence.
+
+### Usage
+
+#### Use for
+
+- Structuring primary sections inside a page or container
+- Creating clear hierarchy above body content, lists, and cards
+- Section headers that can optionally include right-aligned supporting content
+
+#### Don't use for
+
+- Do not use when a lower-emphasis label level (Title1) is sufficient
+- Do not use as the top-most headline when page-level emphasis is needed
+- Do not overload right-side companion content so the title loses clarity
+
+## Title3
+
+High-emphasis section heading for prominent content groupings such as commercial or featured blocks.
+
+### Usage
+
+#### Use for
+
+- Highlighting important section starts where stronger emphasis than Title2 is needed
+- Grouping featured or commercial content areas that must stand out in scanning
+- Title rows that may include concise right-side supporting content
+
+#### Don't use for
+
+- Do not use repeatedly for every section in dense screens, or hierarchy becomes noisy
+- Do not use for minor labels or metadata-level headings
+- Do not use as a substitute for the page’s principal heading when a top-level title is required
+
+## Title4
+
+Top title level for primary page or view headings when maximum hierarchy prominence is needed.
+
+### Usage
+
+#### Use for
+
+- Main heading of a page, screen, or major view entry point
+- High-visibility title moments that establish immediate context for the whole surface
+- Header compositions that may include compact right-aligned complementary information or action text
+
+#### Don't use for
+
+- Do not use for regular subsection titles inside content modules
+- Do not place multiple Title4 elements in the same visual scope
+- Do not use long multiline copy as a page title when a shorter, clearer heading is possible
+
+## Accessibility
+
+### Heading hierarchy
+
+Title heading levels are configurable.
+
+- Set the `as` prop (`h1` to `h6`) based on real page hierarchy instead of relying on visual size alone
+- Visual style and semantic level are independent: changing the tag updates accessibility structure without
+ requiring visual redesign
+- Use one clear top-level heading per view/surface scope when possible, and nest lower levels consistently
+ below it
+
+### Accessibility label
+
+Keep title text concise and meaningful so headings work well in assistive-technology heading navigation.
+
+- If right-side companion content is used, ensure it supports (rather than replaces) the meaning of the
+ heading
diff --git a/doc/components/tooltip.md b/doc/components/tooltip.md
new file mode 100644
index 0000000000..76f16c4ee7
--- /dev/null
+++ b/doc/components/tooltip.md
@@ -0,0 +1,45 @@
+# Tooltip
+
+Tooltip shows short, contextual helper text near a target on hover, focus, or touch, then dismisses when
+interaction ends.
+
+## Usage
+
+### Use for
+
+- Providing brief, supplementary clarification for controls, icons, or labels
+- Surfacing contextual hints that improve understanding without interrupting task flow
+- Supporting non-critical helper content discoverable on hover/focus/tap interactions
+- Keeping messages concise so users can parse them quickly in transient surfaces
+
+### Don't use for
+
+- Do not place critical instructions or mandatory requirements only in a tooltip
+- Do not use Tooltip for long-form, structured, or interactive content; use Popover instead
+- Do not rely on tooltip-only content for accessibility-critical task completion
+- Do not attach tooltips to every element when context is already clear without extra help
+
+## Accessibility
+
+### Accessibility label
+
+Do not treat tooltip content as guaranteed screen-reader content.
+
+- Include essential helper text in the interactive element's accessible name/description
+- If tooltip text is important for understanding an action, incorporate that meaning into the trigger's
+ `aria-label` (or equivalent accessible labeling strategy)
+
+### Trigger requirements
+
+Avoid attaching tooltips to non-interactive elements.
+
+- Use interactive targets so keyboard and assistive technology users can discover the same help
+- Ensure the trigger control is still understandable without tooltip visibility (especially on touch devices)
+
+### Content scope
+
+Keep tooltip copy brief and supplementary, not required for completing the task.
+
+- Do not place critical instructions or mandatory requirements only in a tooltip
+- For mandatory guidance, place instructions persistently in visible content rather than only in transient
+ tooltip surfaces
diff --git a/doc/components/utilities.md b/doc/components/utilities.md
new file mode 100644
index 0000000000..e855912c83
--- /dev/null
+++ b/doc/components/utilities.md
@@ -0,0 +1,260 @@
+# Utilities
+
+## ThemeConfig
+
+ThemeConfig provides reusable behavior to keep component logic consistent across the product.
+
+### Usage
+
+#### Use for
+
+- Sharing common state and behavior across multiple components
+- Keeping implementation aligned with Mística patterns
+
+#### Don't use for
+
+- Do not duplicate equivalent logic when this utility already exists
+- Do not use it without understanding its side effects and scope
+
+## ThemeContext
+
+ThemeContext provides reusable behavior to keep component logic consistent across the product.
+
+### Usage
+
+#### Use for
+
+- Sharing common state and behavior across multiple components
+- Keeping implementation aligned with Mística patterns
+
+#### Don't use for
+
+- Do not duplicate equivalent logic when this utility already exists
+- Do not use it without understanding its side effects and scope
+
+## ThemeContextProvider
+
+ThemeContextProvider provides reusable behavior to keep component logic consistent across the product.
+
+### Usage
+
+#### Use for
+
+- Sharing common state and behavior across multiple components
+- Keeping implementation aligned with Mística patterns
+
+#### Don't use for
+
+- Do not duplicate equivalent logic when this utility already exists
+- Do not use it without understanding its side effects and scope
+
+## ThemeVariant
+
+Theme variant/context: Adjustments at the component level based on configuration.
+
+### Usage
+
+#### Use for
+
+- Applying the documented component pattern in product UI
+- Keeping user experience coherent across screens and flows
+
+#### Don't use for
+
+- Do not replace a more suitable semantic component with this one
+- Do not customize behavior in ways that conflict with Mística guidance
+
+## TrackingConfig
+
+TrackingConfig provides reusable behavior to keep component logic consistent across the product.
+
+### Usage
+
+#### Use for
+
+- Sharing common state and behavior across multiple components
+- Keeping implementation aligned with Mística patterns
+
+#### Don't use for
+
+- Do not duplicate equivalent logic when this utility already exists
+- Do not use it without understanding its side effects and scope
+
+## useTrackingConfig
+
+useTrackingConfig provides reusable behavior to keep component logic consistent across the product.
+
+### Usage
+
+#### Use for
+
+- Sharing common state and behavior across multiple components
+- Keeping implementation aligned with Mística patterns
+
+#### Don't use for
+
+- Do not duplicate equivalent logic when this utility already exists
+- Do not use it without understanding its side effects and scope
+
+## OverscrollColorProvider
+
+OverscrollColorProvider provides reusable behavior to keep component logic consistent across the product.
+
+### Usage
+
+#### Use for
+
+- Sharing common state and behavior across multiple components
+- Keeping implementation aligned with Mística patterns
+
+#### Don't use for
+
+- Do not duplicate equivalent logic when this utility already exists
+- Do not use it without understanding its side effects and scope
+
+## useSetOverscrollColor
+
+useSetOverscrollColor provides reusable behavior to keep component logic consistent across the product.
+
+### Usage
+
+#### Use for
+
+- Sharing common state and behavior across multiple components
+- Keeping implementation aligned with Mística patterns
+
+#### Don't use for
+
+- Do not duplicate equivalent logic when this utility already exists
+- Do not use it without understanding its side effects and scope
+
+## TopDistanceContext
+
+TopDistanceContext provides reusable behavior to keep component logic consistent across the product.
+
+### Usage
+
+#### Use for
+
+- Sharing common state and behavior across multiple components
+- Keeping implementation aligned with Mística patterns
+
+#### Don't use for
+
+- Do not duplicate equivalent logic when this utility already exists
+- Do not use it without understanding its side effects and scope
+
+## Overlay
+
+Overlay provides a full-viewport interaction layer behind temporary surfaces, enabling outside-click dismissal
+and optional body scroll lock.
+
+### Usage
+
+#### Use for
+
+- Dimming or blocking background interaction while a modal, menu, or transient surface is open
+- Enabling outside-tap/click dismissal patterns for contextual surfaces
+- Preventing background page scroll when focus should remain on the active overlayed content
+- Creating consistent full-screen interaction coverage across desktop and mobile browsers
+
+#### Don't use for
+
+- Do not use Overlay as a standalone content container for primary page layouts
+- Do not lock body scroll when background interaction should remain available
+- Do not rely on overlay dismissal for destructive or irreversible flows without explicit confirmation
+- Do not stack multiple independent overlays when a single coordinated layer can manage focus and dismissal
+
+## FocusTrap
+
+FocusTrap keeps keyboard focus constrained within a subtree while it is active, helping modal surfaces remain
+accessible and self-contained.
+
+### Usage
+
+#### Use for
+
+- Trapping tab navigation inside active dialogs, drawers, popovers, or other temporary surfaces
+- Preventing focus from escaping to background content while a modal interaction is open
+- Grouping related focus locks when multiple coordinated trapped regions are needed
+- Temporarily disabling the trap when the same surface transitions between modal and non-modal behavior
+
+#### Don't use for
+
+- Do not use FocusTrap for non-modal inline content where free page navigation is expected
+- Do not leave background content interactive without matching dismissal/focus management strategy
+- Do not nest independent focus traps without intentional coordination, as this can break keyboard flow
+- Do not rely on focus trapping alone for accessibility; pair it with clear labels and predictable dismissal
+
+## Portal
+
+Portal renders children outside the parent DOM hierarchy (into `document.body`), which is useful for overlays
+and floating layers that need independent stacking and positioning.
+
+### Usage
+
+#### Use for
+
+- Rendering modals, overlays, tooltips, or menus that must escape ancestor clipping or stacking contexts
+- Isolating floating UI layers from parent layout constraints while preserving React state ownership
+- Mounting temporary surfaces near the document root for reliable fixed/absolute positioning behavior
+- Keeping layered UI predictable across complex containers with transforms or overflow rules
+
+#### Don't use for
+
+- Do not use Portal for regular in-flow content that should participate in local layout
+- Do not assume portal rendering solves focus/keyboard handling by itself; manage accessibility explicitly
+- Do not mount many unrelated portals when one coordinated layer strategy is enough
+- Do not forget cleanup expectations for temporary surfaces and listeners attached to portaled content
+
+## applyAlpha
+
+applyAlpha returns a color with an updated alpha channel, supporting raw skin RGB CSS variables, hex, rgb, and
+rgba inputs for consistent translucent styling.
+
+### Usage
+
+#### Use for
+
+- Applying opacity consistently without duplicating manual rgba conversions across components
+- Working directly with `skinVars.rawColors` tokens and preserving theme-driven color behavior
+- Normalizing alpha application across mixed color input formats in reusable styling utilities
+
+#### Don't use for
+
+- Do not pass out-of-range alpha values; keep alpha between `0` and `1`
+- Do not use applyAlpha as a substitute for semantic color-token selection
+- Do not assume the resulting translucent color always meets contrast requirements; validate accessibility
+- Do not rely on color-format fallbacks in critical paths when deterministic color output is required
+
+## createNestableContext
+
+createNestableContext provides reusable behavior to keep component logic consistent across the product.
+
+### Usage
+
+#### Use for
+
+- Sharing common state and behavior across multiple components
+- Keeping implementation aligned with Mística patterns
+
+#### Don't use for
+
+- Do not duplicate equivalent logic when this utility already exists
+- Do not use it without understanding its side effects and scope
+
+## NestableContext
+
+NestableContext provides reusable behavior to keep component logic consistent across the product.
+
+### Usage
+
+#### Use for
+
+- Sharing common state and behavior across multiple components
+- Keeping implementation aligned with Mística patterns
+
+#### Don't use for
+
+- Do not duplicate equivalent logic when this utility already exists
+- Do not use it without understanding its side effects and scope