chore(Docs): Add component docs

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

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

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

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`.