From 01985434ea222c1402cad04a9dbf5280dfc6d41b Mon Sep 17 00:00:00 2001
From: Frankie Yan <8531248+frankieyan@users.noreply.github.com>
Date: Mon, 7 Sep 2026 15:26:57 -0700
Subject: [PATCH] docs(divider): Add Storybook story and docs page

Co-Authored-By: Claude <noreply@anthropic.com>
---
 src/divider/divider.mdx         | 31 ++++++++++++++++++++++
 src/divider/divider.stories.tsx | 47 +++++++++++++++++++++++++++++++++
 2 files changed, 78 insertions(+)
 create mode 100644 src/divider/divider.mdx
 create mode 100644 src/divider/divider.stories.tsx

diff --git a/src/divider/divider.mdx b/src/divider/divider.mdx
new file mode 100644
index 000000000..6e7f91f31
--- /dev/null
+++ b/src/divider/divider.mdx
@@ -0,0 +1,31 @@
+import { Canvas, Controls, Meta, Subtitle, Title } from '@storybook/addon-docs/blocks'
+
+import * as DividerStories from './divider.stories'
+
+<Meta of={DividerStories} />
+
+<Title />
+
+<Subtitle>Horizontal rule that separates content.</Subtitle>
+
+## Basic usage
+
+`Divider` renders an `<hr>` with the given `weight`, and defaults to `tertiary`.
+
+<Canvas of={DividerStories.Default} />
+
+### API
+
+<Controls of={DividerStories.Default} />
+
+## Weights
+
+The weight sets the line color. Ordered by contrast against the background: `secondary` is the
+faintest, then `primary`, then `tertiary`.
+
+<Canvas of={DividerStories.Weights} />
+
+## Dividers between stacked items
+
+`Stack` draws the same dividers between its children through its own `dividers` prop. Prefer that
+over placing a `Divider` between each item.
diff --git a/src/divider/divider.stories.tsx b/src/divider/divider.stories.tsx
new file mode 100644
index 000000000..bca1ad529
--- /dev/null
+++ b/src/divider/divider.stories.tsx
@@ -0,0 +1,47 @@
+import * as React from 'react'
+
+import { Stack } from '../stack'
+import { Text } from '../text'
+
+import { Divider } from './divider'
+
+import type { Meta, StoryObj } from '@storybook/react-vite'
+
+const weights = ['primary', 'secondary', 'tertiary'] as const
+
+const meta = {
+    title: '📐 Layout/Divider',
+    component: Divider,
+    parameters: {
+        badges: ['accessible'],
+        figma: {
+            path: 'Web › Components / Todoist › Dividers › Divider',
+            url: 'https://www.figma.com/design/LYlWNzvhMDh907l07mPPQk/Product-Library---Web?node-id=1751-25739',
+        },
+    },
+} satisfies Meta<typeof Divider>
+
+export default meta
+
+type Story = StoryObj<typeof meta>
+
+export const Default: Story = {
+    args: {
+        weight: 'tertiary',
+    },
+}
+
+export const Weights: Story = {
+    render: () => (
+        <Stack space="xlarge">
+            {weights.map((weight) => (
+                <Stack key={weight} space="small">
+                    <Text variant="caption-1" tone="secondary">
+                        {weight}
+                    </Text>
+                    <Divider weight={weight} />
+                </Stack>
+            ))}
+        </Stack>
+    ),
+}