Skip to content

🪢 Open source agent evals & observability: Trace, evaluate, and improve LLM applications with one open platform.

chore(storybook): Move non-component stories out of design-system dir (#16606)

Ben Bachem1ceaa862a257
diff --git a/.agents/skills/storybook/SKILL.md b/.agents/skills/storybook/SKILL.md
index bd17ae665f..c686588037 100644
--- a/.agents/skills/storybook/SKILL.md
+++ b/.agents/skills/storybook/SKILL.md
@@ -6,5 +6,5 @@ description: Use when writing or reviewing Storybook stories (`.stories.tsx`) fo
# Storybook Component Stories
Before writing or reviewing Storybook stories, read and follow the canonical
-[Writing Good Stories](../../../web/storybook/docs/WritingGoodStories.mdx)
+[Writing Good Stories](../../../web/.storybook/docs/WritingGoodStories.mdx)
guide.
diff --git a/web/src/components/design-system/OverlayLayers.mdx b/web/.storybook/docs/OverlayLayers.mdx
similarity index 100%
rename from web/src/components/design-system/OverlayLayers.mdx
rename to web/.storybook/docs/OverlayLayers.mdx
diff --git a/web/.storybook/docs/Overview.mdx b/web/.storybook/docs/Overview.mdx
new file mode 100644
index 0000000000..7148f92c37
--- /dev/null
+++ b/web/.storybook/docs/Overview.mdx
@@ -0,0 +1,25 @@
+import { Meta } from "@storybook/addon-docs/blocks";
+
+<Meta />
+
+# Overview
+
+Storybook is the shared workspace for documenting Langfuse's interface and developing UI components in isolation. It keeps design guidance and component examples easy to discover without requiring the full application.
+
+Before modifying content in this Storybook, please read the [Writing Good Stories](?path=/docs/design-writing-good-stories--docs) page.
+
+## Structure
+
+Our Storybook is organized into three sections with different purposes:
+
+#### Design
+
+Design contains the curated documentation for Langfuse's visual language, patterns, and conventions. Use it for guidance that should remain stable and help contributors make consistent product decisions.
+
+#### Playground
+
+Playground contains isolated component stories and supporting technical documentation. Use it to develop, test, and explore components independently from the application. New component stories belong here by default unless they are part of a configured feature folder.
+
+#### Features
+
+Features contains stories grouped by product area. Use a feature folder when several related stories are easier to discover and review together. Keep these stories colocated with the feature implementation.
diff --git a/web/src/components/design-system/ThemeTokens/Charts.stories.tsx b/web/.storybook/docs/ThemeTokens/Charts.stories.tsx
similarity index 85%
rename from web/src/components/design-system/ThemeTokens/Charts.stories.tsx
rename to web/.storybook/docs/ThemeTokens/Charts.stories.tsx
index 541d84c065..bc713956d7 100644
--- a/web/src/components/design-system/ThemeTokens/Charts.stories.tsx
+++ b/web/.storybook/docs/ThemeTokens/Charts.stories.tsx
@@ -1,4 +1,4 @@
-import preview from "../../../../.storybook/preview";
+import preview from "../../preview";
import { Charts as ChartsPage } from "./Charts";
const meta = preview.meta({
diff --git a/web/src/components/design-system/ThemeTokens/Charts.tsx b/web/.storybook/docs/ThemeTokens/Charts.tsx
similarity index 100%
rename from web/src/components/design-system/ThemeTokens/Charts.tsx
rename to web/.storybook/docs/ThemeTokens/Charts.tsx
diff --git a/web/src/components/design-system/ThemeTokens/Color.stories.tsx b/web/.storybook/docs/ThemeTokens/Color.stories.tsx
similarity index 84%
rename from web/src/components/design-system/ThemeTokens/Color.stories.tsx
rename to web/.storybook/docs/ThemeTokens/Color.stories.tsx
index 6fde1ce3df..75e1726621 100644
--- a/web/src/components/design-system/ThemeTokens/Color.stories.tsx
+++ b/web/.storybook/docs/ThemeTokens/Color.stories.tsx
@@ -1,4 +1,4 @@
-import preview from "../../../../.storybook/preview";
+import preview from "../../preview";
import { Color as ColorPage } from "./Color";
const meta = preview.meta({
diff --git a/web/src/components/design-system/ThemeTokens/Color.tsx b/web/.storybook/docs/ThemeTokens/Color.tsx
similarity index 100%
rename from web/src/components/design-system/ThemeTokens/Color.tsx
rename to web/.storybook/docs/ThemeTokens/Color.tsx
diff --git a/web/src/components/design-system/ThemeTokens/Layout.stories.tsx b/web/.storybook/docs/ThemeTokens/Layout.stories.tsx
similarity index 85%
rename from web/src/components/design-system/ThemeTokens/Layout.stories.tsx
rename to web/.storybook/docs/ThemeTokens/Layout.stories.tsx
index 9225221356..1dceb02f2b 100644
--- a/web/src/components/design-system/ThemeTokens/Layout.stories.tsx
+++ b/web/.storybook/docs/ThemeTokens/Layout.stories.tsx
@@ -1,4 +1,4 @@
-import preview from "../../../../.storybook/preview";
+import preview from "../../preview";
import { Layout as LayoutPage } from "./Layout";
const meta = preview.meta({
diff --git a/web/src/components/design-system/ThemeTokens/Layout.tsx b/web/.storybook/docs/ThemeTokens/Layout.tsx
similarity index 100%
rename from web/src/components/design-system/ThemeTokens/Layout.tsx
rename to web/.storybook/docs/ThemeTokens/Layout.tsx
diff --git a/web/src/components/design-system/ThemeTokens/Typography.stories.tsx b/web/.storybook/docs/ThemeTokens/Typography.stories.tsx
similarity index 86%
rename from web/src/components/design-system/ThemeTokens/Typography.stories.tsx
rename to web/.storybook/docs/ThemeTokens/Typography.stories.tsx
index 43a9ed1ae6..bb06d2f19a 100644
--- a/web/src/components/design-system/ThemeTokens/Typography.stories.tsx
+++ b/web/.storybook/docs/ThemeTokens/Typography.stories.tsx
@@ -1,4 +1,4 @@
-import preview from "../../../../.storybook/preview";
+import preview from "../../preview";
import { Typography as TypographyPage } from "./Typography";
const meta = preview.meta({
diff --git a/web/src/components/design-system/ThemeTokens/Typography.tsx b/web/.storybook/docs/ThemeTokens/Typography.tsx
similarity index 100%
rename from web/src/components/design-system/ThemeTokens/Typography.tsx
rename to web/.storybook/docs/ThemeTokens/Typography.tsx
diff --git a/web/src/components/design-system/ThemeTokens/docsChrome.tsx b/web/.storybook/docs/ThemeTokens/docsChrome.tsx
similarity index 100%
rename from web/src/components/design-system/ThemeTokens/docsChrome.tsx
rename to web/.storybook/docs/ThemeTokens/docsChrome.tsx
diff --git a/web/src/components/design-system/ThemeTokens/parseThemeTokens.ts b/web/.storybook/docs/ThemeTokens/parseThemeTokens.ts
similarity index 100%
rename from web/src/components/design-system/ThemeTokens/parseThemeTokens.ts
rename to web/.storybook/docs/ThemeTokens/parseThemeTokens.ts
diff --git a/web/src/components/design-system/ThemeTokens/shared.tsx b/web/.storybook/docs/ThemeTokens/shared.tsx
similarity index 99%
rename from web/src/components/design-system/ThemeTokens/shared.tsx
rename to web/.storybook/docs/ThemeTokens/shared.tsx
index 58eeed8757..e6506edc9d 100644
--- a/web/src/components/design-system/ThemeTokens/shared.tsx
+++ b/web/.storybook/docs/ThemeTokens/shared.tsx
@@ -14,7 +14,7 @@
import { ChevronRight } from "lucide-react";
import { type ReactNode, useSyncExternalStore } from "react";
-import globalsCss from "../../../styles/globals.css?raw";
+import globalsCss from "../../../src/styles/globals.css?raw";
import {
CropFrame as Panel,
DocsPageHeader as PageHeader,
diff --git a/web/storybook/docs/WritingGoodStories.mdx b/web/.storybook/docs/WritingGoodStories.mdx
similarity index 100%
rename from web/storybook/docs/WritingGoodStories.mdx
rename to web/.storybook/docs/WritingGoodStories.mdx
diff --git a/web/.storybook/main.ts b/web/.storybook/main.ts
index dae1eb256b..0f9892b0a2 100644
--- a/web/.storybook/main.ts
+++ b/web/.storybook/main.ts
@@ -76,7 +76,7 @@ const config: StorybookConfig = {
stories: [
// Curated design-system documentation shown under Design.
{
- directory: "../storybook/docs",
+ directory: "./docs",
files: "**/*.mdx",
titlePrefix: "Design",
},
@@ -94,7 +94,7 @@ const config: StorybookConfig = {
})),
// Design-system reference pages shown directly under Design.
...DESIGN_REFERENCE_STORIES.map((storyPath) => ({
- directory: "../src/components/design-system",
+ directory: "./docs",
files: `${storyPath}.stories.${STORY_EXTENSIONS}`,
titlePrefix: "Design",
})),
diff --git a/web/.storybook/preview.tsx b/web/.storybook/preview.tsx
index 6fe372dfb9..973376d3d0 100644
--- a/web/.storybook/preview.tsx
+++ b/web/.storybook/preview.tsx
@@ -15,7 +15,7 @@ import { TooltipProvider } from "../src/components/ui/tooltip";
import { ThemeProvider } from "../src/features/theming/ThemeProvider";
import { MarkdownContextProvider } from "../src/features/theming/useMarkdownContext";
import { LAYER_ORDER } from "../src/components/ui/layer";
-import "../src/styles/globals.css";
+import "./storybook.css";
import "./docs.css";
// Mirror the global CSS that _app.tsx imports so vendored components
// (react18-json-view, streamdown markdown) render identically to the app.
@@ -176,6 +176,10 @@ export default definePreview({
options: {
storySort: (a, b) => {
const sectionOrder = ["Design", "Playground"];
+ const designDocOrder = [
+ "Design/Overview",
+ "Design/Writing Good Stories",
+ ];
const aSectionIndex = sectionOrder.indexOf(a.title.split("/")[0] ?? "");
const bSectionIndex = sectionOrder.indexOf(b.title.split("/")[0] ?? "");
const sectionDifference =
@@ -183,6 +187,14 @@ export default definePreview({
(bSectionIndex === -1 ? sectionOrder.length : bSectionIndex);
if (sectionDifference !== 0) return sectionDifference;
+ const aDesignDocIndex = designDocOrder.indexOf(a.title);
+ const bDesignDocIndex = designDocOrder.indexOf(b.title);
+ if (aDesignDocIndex !== bDesignDocIndex) {
+ if (aDesignDocIndex === -1) return 1;
+ if (bDesignDocIndex === -1) return -1;
+ return aDesignDocIndex - bDesignDocIndex;
+ }
+
// Returning 0 preserves Storybook's existing stable order. Only
// partition test stories when both entries belong to the same component.
if (a.title !== b.title) return 0;
diff --git a/web/.storybook/storybook.css b/web/.storybook/storybook.css
new file mode 100644
index 0000000000..6c4f10947c
--- /dev/null
+++ b/web/.storybook/storybook.css
@@ -0,0 +1,3 @@
+@import "../src/styles/globals.css";
+
+@source "./docs";
diff --git a/web/.storybook/tsconfig.json b/web/.storybook/tsconfig.json
index 3b78ec6f27..dfa298daef 100644
--- a/web/.storybook/tsconfig.json
+++ b/web/.storybook/tsconfig.json
@@ -1,4 +1,4 @@
{
- "extends": "@repo/typescript-config/base.json",
- "include": ["**/*.ts"]
+ "extends": "../tsconfig.json",
+ "include": ["**/*.ts", "**/*.tsx", "../next-env.d.ts", "../types/global.d.ts"]
}
diff --git a/web/.structure-baseline.json b/web/.structure-baseline.json
index a0207fbfed..f8a1a422bc 100644
--- a/web/.structure-baseline.json
+++ b/web/.structure-baseline.json
@@ -8,9 +8,6 @@
"src/components/date-picker.tsx: filename not PascalCase; 3 components: DatePicker, DatePickerWithRange, TimeRangePicker",
"src/components/date-range-dropdowns.tsx: filename not PascalCase",
"src/components/deleteButton.tsx: filename not PascalCase; 7 components: DeleteButton, DeleteTraceButton, DeleteDatasetButton, DeleteDashboardButton, DeleteMonitorButton, DeleteEvalConfigButton, DeleteEvaluationModelButton",
- "src/components/design-system/ThemeTokens/docsChrome.tsx: filename not PascalCase; 5 components: Eyebrow, SpecChip, DocsPageHeader, DocsSection, CropFrame",
- "src/components/design-system/ThemeTokens/Layout.tsx: 7 components: RadiiSection, LayoutOffsetsSection, LayeringSection, LayerSystemSection, AnimationsSection, BreakpointsNote, Layout",
- "src/components/design-system/ThemeTokens/shared.tsx: filename not PascalCase; 5 components: Swatch, EmptyCell, TokenRow, TokenSection, CollapsedSection",
"src/components/error-page.tsx: filename not PascalCase; 2 components: ErrorPage, ErrorPageWithSentry",
"src/components/grouped-score-badge.tsx: filename not PascalCase",
"src/components/layouts/app-layout/index.tsx: filename not PascalCase",
@@ -202,7 +199,6 @@
"src/app/layout.tsx: extra exports: metadata",
"src/components/ChatMessages/messageSearch/context.tsx: extra exports: useMessageSearchActions, useOptionalMessageSearchActions, useOptionalMessageSearchPageId, useMessageSearch, useSyncMessageSearchMessages",
"src/components/date-picker.tsx: extra exports: nextRangeForDayClick, isRangeWithinMaxDuration",
- "src/components/design-system/ThemeTokens/shared.tsx: extra exports: parsed, rootEntries, buildContext, useIsDarkTheme, useTokenContexts, PAGE_TOKEN_MATCHERS, allTokenNames, pageForToken, unassignedTokens, findTokenDeclaration",
"src/components/editor/CodeMirrorEditor.tsx: extra exports: getPromptVariableDiagnostics, applyCodeMirrorSearchQuery, setActiveSearchMarkCodeMirrorRange, unsetActiveSearchMarkCodeMirrorRange",
"src/components/grouped-score-badge.tsx: extra exports: groupScoresByName",
"src/components/ItemBadge.tsx: extra exports: renderFilterIcon",
diff --git a/web/storybook/docs/Overview.mdx b/web/storybook/docs/Overview.mdx
deleted file mode 100644
index 33b38dcff1..0000000000
--- a/web/storybook/docs/Overview.mdx
+++ /dev/null
@@ -1,27 +0,0 @@
-import { Meta } from "@storybook/addon-docs/blocks";
-
-<Meta />
-
-# Overview
-
-Storybook is the shared workspace for documenting Langfuse's interface and
-developing UI components in isolation. It keeps design guidance and component
-examples easy to discover without requiring the full application.
-
-Before modifying content in this Storybook, please read the [Writing Good Stories](?path=/docs/design-writing-good-stories--docs) page.
-
-## Structure
-
-Our Storybook is split into two sections with different purposes:
-
-#### Design
-
-Design contains the curated documentation for Langfuse's visual language,
-patterns, and conventions. Use it for guidance that should remain stable and
-help contributors make consistent product decisions.
-
-#### Playground
-
-Playground contains isolated component stories and supporting technical
-documentation. Use it to develop, test, and explore components independently
-from the application. New component stories belong here by default.