@recursica/mantine-adapter 0.6.0 → 0.7.0

package/src/OverStyling.stories.tsx

@@ -0,0 +1,174 @@
+import type { Meta, StoryObj } from "@storybook/react";
+import {
+  Container,
+  Paper,
+  Title,
+  Text,
+  List,
+  Divider,
+  Group,
+  Code,
+} from "@mantine/core";
+import { Button } from "./components/Button/Button";
+
+const OverStylingInfo = () => {
+  return (
+    <Container size="md" py="xl">
+      <Paper withBorder p="xl" radius="md">
+        <Title order={1} mb="md">
+          Over Styling (<Code>overStyled</Code>)
+        </Title>
+        <Text mb="md">
+          By default, all Recursica components are strictly sandboxed. This
+          means they are protected against arbitrary styling configurations
+          (like passing generic React <Code>style</Code> objects, custom{" "}
+          <Code>classNames</Code> injections, or using deep Mantine layout hooks
+          like <Code>bg</Code> and <Code>c</Code>). This strict compile-time and
+          run-time enforcement guarantees that your design system tokens remain
+          true across your application.
+        </Text>
+        <Text mb="md">
+          However, there may be edge cases where a developer absolutely must
+          modify a component beyond what the design tokens natively allow. For
+          this, we provide the <strong>escape hatch</strong> property:{" "}
+          <Code>overStyled={`{true}`}</Code>.
+        </Text>
+
+        <Title order={3} mb="sm">
+          The Core Philosophy
+        </Title>
+        <Text mb="sm">
+          **You should not over-style components.** Using{" "}
+          <Code>overStyled</Code> explicitly signifies that you are breaking
+          design system rules.
+        </Text>
+        <List mb="xl" type="ordered">
+          <List.Item>
+            <strong>Technical Debt:</strong> If over-styling is required, it
+            should be treated as a short-term workaround. Ideally, the component
+            will be refactored once the required layouts or variants are
+            officially integrated into the core Recursica component library.
+          </List.Item>
+          <List.Item>
+            <strong>Auditing & Searching:</strong> Because this pattern creates
+            technical debt, we enforce the explicit <Code>overStyled</Code>{" "}
+            boolean. This provides a highly auditable, easily searchable string.
+            Product managers and engineers can quickly grep the codebase for{" "}
+            <Code>overStyled</Code> (or the <Code>RecursicaOverStyled</Code>{" "}
+            typings) to hunt down components that don't match standard patterns.
+          </List.Item>
+          <List.Item>
+            <strong>Highly Custom Components:</strong> If your application
+            genuinely requires massive custom layouts that the UI kit cannot
+            support, <strong>do not hack the Recursica component</strong>.
+            Instead, it is highly encouraged that you import the underlying
+            primitive component directly from <Code>@mantine/core</Code> and
+            construct your independent feature there. While you can utilize raw
+            Recursica CSS variables on these custom components, note that they
+            are not guaranteed to be accurately maintained as Recursica evolves.
+            Keep strict components strict!
+          </List.Item>
+        </List>
+
+        <Divider mb="xl" />
+
+        <Title order={3} mb="sm">
+          Permitted Layout Properties
+        </Title>
+        <Text mb="sm">
+          Unlike deep styling bounds (colors, typography, padding, dimensions),
+          external <strong>layout spacing properties</strong> like Margins (
+          <Code>m</Code>, <Code>mt</Code>, <Code>mb</Code>, <Code>mx</Code>) are
+          safely <strong>permitted by default</strong>. This allows integrators
+          to structurally compose components alongside siblings without
+          breaching internal token boundaries.
+        </Text>
+        <Text mb="xl">
+          When using layout properties, you have the flexibility to use either
+          ecosystem seamlessly:
+        </Text>
+        <List mb="md" type="ordered">
+          <List.Item>
+            <strong>Mantine Core Values:</strong> Passing standard Mantine sizes
+            (like <Code>mt="md"</Code>) passes straight through to Mantine
+            natively, allowing you to interface completely normally with a
+            parent application's existing Mantine Theme setup that might fall
+            outside Recursica's scope.
+          </List.Item>
+          <List.Item>
+            <strong>Recursica Strict Tokens:</strong> Passing our custom
+            prefixed tokens (like <Code>mt="rec-md"</Code>) signals our internal
+            layout interceptor to securely translate the value directly to our
+            native <Code>recursica_brand_dimensions</Code> CSS variables. This
+            ensures strict design token measurements while sharing the exact
+            same prop interface!
+          </List.Item>
+        </List>
+        <Text mb="sm" fw={500}>
+          Available Recursica Layout Tokens:
+        </Text>
+        <List mb="xl" type="unordered">
+          <List.Item>
+            <Code>rec-none</Code> (0px limit)
+          </List.Item>
+          <List.Item>
+            <Code>rec-sm</Code> (0.5x scaling)
+          </List.Item>
+          <List.Item>
+            <Code>rec-default</Code> (1.0x scaling)
+          </List.Item>
+          <List.Item>
+            <Code>rec-md</Code> (1.5x scaling)
+          </List.Item>
+          <List.Item>
+            <Code>rec-lg</Code> (2.0x scaling)
+          </List.Item>
+          <List.Item>
+            <Code>rec-xl</Code> (3.0x scaling)
+          </List.Item>
+          <List.Item>
+            <Code>rec-2xl</Code> (4.0x scaling)
+          </List.Item>
+        </List>
+
+        <Divider mb="xl" />
+
+        <Title order={3} mb="md">
+          Live Example
+        </Title>
+        <Text mb="xl">
+          Below is a side-by-side comparison. The first is a standard Recursica
+          Button protected by the design tokens mapping. The second flagrantly
+          forces <Code>overStyled={`{true}`}</Code>, allowing Mantine's native
+          styling generics to punch right through the sandbox layout.
+        </Text>
+
+        <Group gap="xl">
+          <div>
+            <Text size="sm" c="dimmed" mb="xs">
+              Strict Baseline (Default)
+            </Text>
+            <Button variant="solid">Standard UI Kit Button</Button>
+          </div>
+          <div>
+            <Text size="sm" c="dimmed" mb="xs">
+              overStyled={`{true}`}
+            </Text>
+            <Button overStyled={true} bg="pink" c="black" radius="xl">
+              Unsafe Pink Marketing Button
+            </Button>
+          </div>
+        </Group>
+      </Paper>
+    </Container>
+  );
+};
+
+const meta: Meta<typeof OverStylingInfo> = {
+  title: "Introduction/Over Styling",
+  component: OverStylingInfo,
+};
+
+export default meta;
+
+export const Default: StoryObj<typeof OverStylingInfo> = {};

package/src/Version.stories.tsx

@@ -0,0 +1,56 @@
+import type { Meta, StoryObj } from "@storybook/react";
+import ReactMarkdown from "react-markdown";
+import {
+  Container,
+  Paper,
+  Title,
+  TypographyStylesProvider,
+  Group,
+  Anchor,
+  Divider,
+} from "@mantine/core";
+import pkg from "../package.json";
+import changelog from "../CHANGELOG.md?raw";
+
+const VersionInfo = () => {
+  return (
+    <Container size="md" py="xl">
+      <Paper withBorder p="xl" radius="md">
+        <Title order={1} mb="xs">
+          Mantine Adapter v{pkg.version}
+        </Title>
+        <Group mb="xl" gap="md">
+          <Anchor
+            href="https://github.com/borderux/recursica"
+            target="_blank"
+            rel="noopener noreferrer"
+          >
+            GitHub Repository
+          </Anchor>
+          <Anchor
+            href="https://recursica.com"
+            target="_blank"
+            rel="noopener noreferrer"
+          >
+            Documentation & Website
+          </Anchor>
+        </Group>
+        <Divider mb="xl" />
+        <TypographyStylesProvider>
+          <ReactMarkdown>{changelog}</ReactMarkdown>
+        </TypographyStylesProvider>
+      </Paper>
+    </Container>
+  );
+};
+
+const meta: Meta<typeof VersionInfo> = {
+  title: "Introduction/Version Info",
+  component: VersionInfo,
+};
+
+export default meta;
+
+type Story = StoryObj<typeof VersionInfo>;
+
+export const Default: Story = {};

package/src/components/Accordion/ACCORDION_IMPLEMENTATION_NOTES.md

@@ -0,0 +1,48 @@
+# Accordion – implementation notes
+
+Decisions and design tweaks strictly tailored for the UI Kit's Accordion wrapped against `@mantine/core`. Use this when managing components possessing deeply nested state logic (e.g., active toggles, nested headers mapping external design properties).
+
+---
+
+## 1. Hybrid Composition API (Smart Rendering Flow)
+
+**Decision:** We fundamentally maintain the exact library composition API structure (`<Accordion>`, `<Accordion.Item>`, `<Accordion.Control>`, `<Accordion.Panel>`) while actively supporting an auto-completing flattened prop schema matching the unified Recursica API (`title`, `leftIcon`, `divider`).
+**Implementation:** Avoid rigid raw parameter dumps. Mantine dynamically injects explicit `id` logic, keyboard ARIA mapping, and focus tracking correctly across `Control` to `Panel` DOM connections natively. By exposing the hierarchical mapping 1:1, Recursica safely adopts these capabilities. However, to strictly support Recursica's unified prop mapping interface:
+
+- **Auto-Construction:** If integrators natively pass `title` and/or `leftIcon` props into `<AccordionItem>`, the component structurally auto-generates the internal `AccordionControl` sub-wrappers mapping the text and SVG natively, whilst treating `children` implicitly as the Panel contents.
+- **Graceful Falldown:** If `title` is heavily omitted, the node immediately falls backward into raw Mantine composability expecting integrators mapped `<Accordion.Control>` entirely manually.
+
+---
+
+## 2. Default Configuration Reset (`unstyled`)
+
+**Decision:** We strip Mantine's inner styles away completely from Accordion mappings by leveraging React's default `variant="unstyled"`.
+**Implementation:** In `Accordion.tsx`, `<MantineAccordion>` binds `variant="unstyled"`. This effectively deletes Mantine's precomputed padding, borders, and shadow mappings allowing our targeted `classNames` inside `Accordion.module.css` to become the exact source of foundational truth without "fighting" `!important` tags or unpredictable flex-layouts inherited globally.
+
+---
+
+## 3. Strict SVG Icons Wrapper (`.iconLeftWrapper`)
+
+**Decision:** Identical logic enforced as seen within Buttons: SVG scales dynamically inside `.mantine-leftSection` based on SVGs internal definition boundaries potentially corrupting header gaps.
+**Implementation:** `AccordionControl` captures `<span className={styles.iconLeftWrapper} aria-hidden>` forcing `object-fit: contain` mapped exactly to the `properties_icon-left-size` Recursica dimension token forcing integrator SVG overrides inline perfectly.
+
+---
+
+## 4. Transparent Global Hover Fixes
+
+**Decision:** We nullify internal Mantine button hover actions and exclusively utilize Recursica's hover structure natively.
+**Implementation:** We construct `.control::after` pseudo-objects dynamically pulling our `hover-color` & `hover-opacity` bindings. Mantine's native action sets `.control:hover { background-color: var(...) }` dynamically causing internal layer overlaps. We enforce `background-color: transparent` strictly overriding it, preserving our pseudo-overlay layer-cascade cleanly.
+
+---
+
+## 5. Active Target Hooks (`[data-active]`)
+
+**Decision:** Collapsed and expanded state tracking requires separate background maps across `AccordionItem`.
+**Implementation:** Rather than syncing React `useState` hooks matching `Accordion.value`, we defer to Mantine's inherent DOM mapping: `.item[data-active]` implicitly triggers exactly when Mantine registers an expansion state swap changing values down dynamically on the element layer, perfectly binding to `--recursica_..._background-expanded`.
+
+---
+
+## 6. Nullifying Isolated State Bounds (`open` boolean)
+
+**Decision:** We do not bind isolated `open={true}` state properties natively on individual `<AccordionItem>` configurations.
+**Implementation:** Recursica natively dictates an item-level `open` tracking mapping. However, internally mapping boolean flags structurally across specific tree nodes heavily corrupts Mantine's DOM layout algorithms mapping parent-driven transition listeners. Mantine forces all expanded-height logic to run symmetrically off the `<Accordion value="...">` string matching array to accurately bind ARIA transitions. We explicitly ignore isolated item `<AccordionItem open={...}>` booleans to shield the rendering sequence cleanly.

package/src/components/Accordion/Accordion.module.css

@@ -0,0 +1,261 @@
+/* ==== ACCORDION CONTAINER ==== */
+.root {
+  box-sizing: border-box;
+  margin: 0;
+  display: flex;
+  flex-direction: column;
+
+  border-style: solid;
+  border-width: var(
+    --recursica_ui-kit_components_accordion_properties_border-size
+  );
+  border-radius: var(
+    --recursica_ui-kit_components_accordion_properties_border-radius
+  );
+  border-color: var(
+    --recursica_ui-kit_components_accordion_properties_colors_border-color
+  );
+  background-color: var(
+    --recursica_ui-kit_components_accordion_properties_colors_background
+  );
+  box-shadow: var(--recursica_ui-kit_components_accordion_properties_elevation);
+
+  max-width: var(--recursica_ui-kit_components_accordion_properties_max-width);
+  min-width: var(--recursica_ui-kit_components_accordion_properties_min-width);
+  padding: var(--recursica_ui-kit_components_accordion_properties_padding);
+
+  /* Ensure gaps between items */
+  gap: var(--recursica_ui-kit_components_accordion_properties_item-gap);
+}
+
+/* ==== ACCORDION ITEM ==== */
+.item {
+  box-sizing: border-box;
+  margin: 0;
+  position: relative;
+  transition: all 0.2s ease;
+
+  /* Overriding Mantine Default Borders natively */
+  border-bottom: none;
+
+  border-style: solid;
+  border-color: var(
+    --recursica_ui-kit_components_accordion-item_properties_colors_divider
+  );
+  border-width: var(
+    --recursica_ui-kit_components_accordion-item_properties_divider-size
+  );
+  border-radius: var(
+    --recursica_ui-kit_components_accordion-item_properties_border-radius
+  );
+  box-shadow: var(
+    --recursica_ui-kit_components_accordion-item_properties_elevation
+  );
+
+  background-color: var(
+    --recursica_ui-kit_components_accordion-item_properties_colors_background-collapsed
+  );
+}
+.item[data-active] {
+  background-color: var(
+    --recursica_ui-kit_components_accordion-item_properties_colors_background-expanded
+  );
+}
+.noDivider {
+  border-bottom: none !important;
+  border-bottom-width: 0 !important;
+}
+
+/* ==== ACCORDION CONTROL (HEADER) ==== */
+.control {
+  box-sizing: border-box;
+  width: 100%;
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+
+  /* Re-apply gap defined by UI Kit for icons vs text */
+  gap: var(--recursica_ui-kit_components_accordion-item_properties_icon-gap);
+
+  /* Strip Mantine's baked padding directly */
+  padding: var(
+      --recursica_ui-kit_components_accordion-item_properties_padding-vertical
+    )
+    var(
+      --recursica_ui-kit_components_accordion-item_properties_padding-horizontal
+    );
+  background-color: transparent;
+
+  transition: background-color 0.15s ease;
+  position: relative;
+  z-index: 1;
+  color: var(
+    --recursica_ui-kit_components_accordion-item_properties_colors_text
+  );
+
+  /* Header Typography */
+  font-family: var(
+    --recursica_ui-kit_components_accordion-item_properties_header-text_font-family
+  );
+  font-size: var(
+    --recursica_ui-kit_components_accordion-item_properties_header-text_font-size
+  );
+  font-weight: var(
+    --recursica_ui-kit_components_accordion-item_properties_header-text_font-weight
+  );
+  font-style: var(
+    --recursica_ui-kit_components_accordion-item_properties_header-text_font-style
+  );
+  letter-spacing: var(
+    --recursica_ui-kit_components_accordion-item_properties_header-text_letter-spacing
+  );
+  line-height: var(
+    --recursica_ui-kit_components_accordion-item_properties_header-text_line-height
+  );
+  text-decoration: var(
+    --recursica_ui-kit_components_accordion-item_properties_header-text_text-decoration
+  );
+  text-transform: var(
+    --recursica_ui-kit_components_accordion-item_properties_header-text_text-transform
+  );
+}
+
+/* Mantine natively places hover states on the control node. 
+   We explicitly override it with our layer hover tokens via an overlay ::after structure
+   so we can cleanly utilize the hover-opacity token! */
+.control:hover {
+  background-color: transparent;
+}
+.control::after {
+  content: "";
+  position: absolute;
+  inset: 0;
+  border-radius: inherit;
+  z-index: -1;
+  pointer-events: none;
+  background-color: var(
+    --recursica_ui-kit_components_accordion-item_properties_hover-color
+  );
+  opacity: 0;
+  transition: opacity 150ms ease;
+}
+.control:hover:not(:disabled)::after {
+  opacity: var(
+    --recursica_ui-kit_components_accordion-item_properties_hover-opacity,
+    0.1
+  );
+}
+
+/* Label logic inside the Control wrapper */
+.label {
+  flex: 1;
+  text-align: left;
+  color: inherit;
+  padding: 0; /* Clear Mantine inner padding */
+}
+
+/* ==== CHEVRON / RIGHT ICON ==== */
+.chevron {
+  flex-shrink: 0;
+  width: var(
+    --recursica_ui-kit_components_accordion-item_properties_icon-right-size
+  );
+  height: var(
+    --recursica_ui-kit_components_accordion-item_properties_icon-right-size
+  );
+  color: var(
+    --recursica_ui-kit_components_accordion-item_properties_colors_icon
+  );
+  margin: 0;
+  transition: transform 200ms ease;
+  display: flex;
+  align-items: center;
+  justify-content: center;
+}
+.chevron > * {
+  width: 100%;
+  height: 100%;
+  object-fit: contain;
+}
+.item[data-active] .chevron {
+  transform: rotate(180deg);
+}
+
+/* ==== LEFT ICON / CUSTOM ICONS ==== */
+.iconLeftWrapper {
+  flex-shrink: 0;
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  width: var(
+    --recursica_ui-kit_components_accordion-item_properties_icon-left-size
+  );
+  height: var(
+    --recursica_ui-kit_components_accordion-item_properties_icon-left-size
+  );
+  color: var(
+    --recursica_ui-kit_components_accordion-item_properties_colors_icon
+  );
+}
+.iconLeftWrapper > * {
+  width: 100%;
+  height: 100%;
+  object-fit: contain;
+}
+
+/* ==== ACCORDION PANEL (CONTENT) ==== */
+.panel {
+  box-sizing: border-box;
+  margin: 0;
+  padding: 0; /* Overriding dynamic layout structure */
+  background-color: var(
+    --recursica_ui-kit_components_accordion-item_properties_colors_content-background
+  );
+}
+
+.content {
+  box-sizing: border-box;
+  /* Strip Mantine padding and apply logic directly mapped */
+  padding: 0
+    var(
+      --recursica_ui-kit_components_accordion-item_properties_padding-horizontal
+    )
+    var(
+      --recursica_ui-kit_components_accordion-item_properties_content-bottom-padding
+    );
+
+  /* Apply offset gap explicitly calculated below header */
+  padding-top: var(
+    --recursica_ui-kit_components_accordion-item_properties_header-content-gap
+  );
+
+  color: var(
+    --recursica_ui-kit_components_accordion-item_properties_colors_content-text
+  );
+
+  /* Content Typography */
+  font-family: var(
+    --recursica_ui-kit_components_accordion-item_properties_content-text_font-family
+  );
+  font-size: var(
+    --recursica_ui-kit_components_accordion-item_properties_content-text_font-size
+  );
+  font-weight: var(
+    --recursica_ui-kit_components_accordion-item_properties_content-text_font-weight
+  );
+  font-style: var(
+    --recursica_ui-kit_components_accordion-item_properties_content-text_font-style
+  );
+  letter-spacing: var(
+    --recursica_ui-kit_components_accordion-item_properties_content-text_letter-spacing
+  );
+  line-height: var(
+    --recursica_ui-kit_components_accordion-item_properties_content-text_line-height
+  );
+  text-decoration: var(
+    --recursica_ui-kit_components_accordion-item_properties_content-text_text-decoration
+  );
+  text-transform: var(
+    --recursica_ui-kit_components_accordion-item_properties_content-text_text-transform
+  );
+}

package/src/components/Accordion/Accordion.stories.tsx

@@ -0,0 +1,145 @@
+import type { Meta, StoryObj } from "@storybook/react";
+import { Accordion } from "./Accordion";
+import { Layer } from "@recursica/adapter-common";
+
+const SVGIcon = () => (
+  <svg
+    xmlns="http://www.w3.org/2000/svg"
+    width="24"
+    height="24"
+    viewBox="0 0 24 24"
+    fill="none"
+    stroke="currentColor"
+    strokeWidth="2"
+    strokeLinecap="round"
+    strokeLinejoin="round"
+  >
+    <path d="M12 2v20M17 5H9.5a3.5 3.5 0 0 0 0 7h5a3.5 3.5 0 0 1 0 7H6" />
+  </svg>
+);
+
+const ChevronIcon = () => (
+  <svg
+    width="24"
+    height="24"
+    viewBox="0 0 24 24"
+    fill="none"
+    xmlns="http://www.w3.org/2000/svg"
+  >
+    <path
+      d="M20.0306 9.53062L12.5306 17.0306C12.461 17.1003 12.3783 17.1557 12.2872 17.1934C12.1962 17.2312 12.0986 17.2506 12 17.2506C11.9014 17.2506 11.8038 17.2312 11.7128 17.1934C11.6218 17.1557 11.539 17.1003 11.4694 17.0306L3.96938 9.53062C3.82865 9.38988 3.74959 9.19901 3.74959 8.99999C3.74959 8.80097 3.82865 8.61009 3.96938 8.46936C4.11011 8.32863 4.30098 8.24957 4.50001 8.24957C4.69903 8.24957 4.8899 8.32863 5.03063 8.46936L12 15.4397L18.9694 8.46936C19.0391 8.39968 19.1218 8.34441 19.2128 8.30669C19.3039 8.26898 19.4015 8.24957 19.5 8.24957C19.5986 8.24957 19.6961 8.26898 19.7872 8.30669C19.8782 8.34441 19.9609 8.39968 20.0306 8.46936C20.1003 8.53905 20.1556 8.62177 20.1933 8.71282C20.231 8.80386 20.2504 8.90144 20.2504 8.99999C20.2504 9.09854 20.231 9.19612 20.1933 9.28716C20.1556 9.37821 20.1003 9.46093 20.0306 9.53062Z"
+      fill="currentColor"
+    />
+  </svg>
+);
+
+const meta: Meta<typeof Accordion> = {
+  title: "UI-Kit/Accordion",
+  component: Accordion,
+  tags: ["autodocs"],
+  parameters: {
+    docs: {
+      description: {
+        component: `
+The \`Accordion\` component intelligently wraps \`@mantine/core\`'s underlying Accordion layers while applying strict native design system mapping via \`recursica_variables_scoped.css\`.
+
+### Hybrid Composition API (Smart-Rendering)
+To maximize flexibility while strictly aligning with the explicit Recursica design logic, the \`AccordionItem\` operates utilizing a **Hybrid Smart-Rendering Flow**:
+
+1. **Auto-Construction (Explicit Mapping)**:
+If you supply the explicitly outlined Recursica properties (\`title\`, \`leftIcon\`) directly onto \`<Accordion.Item>\`, the component auto-generates the necessary \`<Accordion.Control>\` DOM layer inherently bridging the icons and titles visually while leaving the raw \`children\` wrapped neatly as the \`<Accordion.Panel>\`.
+
+2. **Graceful Falldown (Raw Composability)**:
+If you deliberately omit the \`title\` property, the entire mapping system gracefully falls backward yielding exactly to the raw \`@mantine/core\` composition model. Under this context, you must inject your localized \`<Accordion.Control>\` and \`<Accordion.Panel>\` configurations completely manually.
+
+### Architecture Warning (\`open\`)
+To structurally protect the parent wrapper's core transitions tracking architecture (\`<Accordion value="...">\`), this configuration explicitly rejects mapping isolated \`open={true}\` object states natively on specific configurations. Use Mantine's inherent sibling arrays matching the corresponding active value map!
+        `,
+      },
+    },
+  },
+};
+
+export default meta;
+
+export const Default: StoryObj<typeof Accordion> = {
+  render: () => {
+    return (
+      <Layer layer={0} style={{ padding: "24px" }}>
+        <Accordion defaultValue="item-1" chevron={<ChevronIcon />}>
+          <Accordion.Item value="item-1">
+            <Accordion.Control>Billing and Membership</Accordion.Control>
+            <Accordion.Panel>
+              You can manage your billing directly from the dashboard tab. All
+              payments are processed automatically.
+            </Accordion.Panel>
+          </Accordion.Item>
+
+          <Accordion.Item value="item-2">
+            <Accordion.Control>Refund Policy</Accordion.Control>
+            <Accordion.Panel>
+              We offer a 30-day money-back guarantee for all new subscriptions.
+            </Accordion.Panel>
+          </Accordion.Item>
+
+          <Accordion.Item value="item-3">
+            <Accordion.Control>Technical Support</Accordion.Control>
+            <Accordion.Panel>
+              Our support team is available 24/7 via live chat or email.
+            </Accordion.Panel>
+          </Accordion.Item>
+        </Accordion>
+      </Layer>
+    );
+  },
+};
+
+export const WithIcons: StoryObj<typeof Accordion> = {
+  render: () => {
+    return (
+      <Layer layer={0} style={{ padding: "24px" }}>
+        <Accordion defaultValue="security" chevron={<ChevronIcon />}>
+          <Accordion.Item value="security">
+            <Accordion.Control leftIcon={<SVGIcon />}>
+              Security Settings
+            </Accordion.Control>
+            <Accordion.Panel>
+              Enable two-factor authentication (2FA) and monitor active sessions
+              below.
+            </Accordion.Panel>
+          </Accordion.Item>
+
+          <Accordion.Item value="privacy">
+            <Accordion.Control leftIcon={<SVGIcon />}>
+              Privacy Configuration
+            </Accordion.Control>
+            <Accordion.Panel>
+              Choose what data is shared with our analytics partners.
+            </Accordion.Panel>
+          </Accordion.Item>
+        </Accordion>
+      </Layer>
+    );
+  },
+};
+
+export const LayerOne: StoryObj<typeof Accordion> = {
+  render: () => {
+    return (
+      <Layer layer={1} style={{ padding: "24px" }}>
+        <Accordion defaultValue="demo" chevron={<ChevronIcon />}>
+          <Accordion.Item value="demo">
+            <Accordion.Control leftIcon={<SVGIcon />}>
+              Layer 1 Render Engine
+            </Accordion.Control>
+            <Accordion.Panel>
+              This Accordion dynamically updates its colors, borders, and
+              typography variables because it is wrapped securely by the
+              simulated `data-recursica-layer="1"`.
+            </Accordion.Panel>
+          </Accordion.Item>
+        </Accordion>
+      </Layer>
+    );
+  },
+};