;
+
+/**
+ * Basic tabs with package manager examples
+ */
+export const Basic: Story = {
+ args: {
+ items: ["pnpm", "npm", "yarn"],
+ children: (
+ <>
+
+ pnpm: Fast, disk space efficient package manager.
+
+ pnpm install
+
+
+
+ npm is a package manager for the JavaScript
+ programming language.
+
+ npm install
+
+
+
+ Yarn used to have funny emojis and then it had a lot
+ of major versions.
+
+ yarn install
+
+
+
+ ),
+ },
+};
+
+/**
+ * Tabs with a default selected index
+ */
+export const WithDefaultIndex: Story = {
+ args: {
+ items: ["pnpm", "npm", "yarn"],
+ defaultIndex: 1,
+ children: (
+ <>
+ pnpm content
+ npm content (default selected)
+ yarn content
+
+ ),
+ },
+ play: async ({ canvasElement }) => {
+ const canvas = within(canvasElement);
+
+ // Check that the second tab is selected by default
+ const npmTab = canvas.getByRole("tab", { name: "npm" });
+ await expect(npmTab).toHaveAttribute("aria-selected", "true");
+
+ // Check that the npm content is visible
+ const npmContent = canvas.getByText("npm content (default selected)");
+ await expect(npmContent).toBeVisible();
+ },
+};
+
+/**
+ * Tabs with disabled items
+ */
+export const WithDisabledTabs: Story = {
+ args: {
+ items: [
+ "Active Tab",
+ { label: "Disabled Tab", disabled: true },
+ "Another Active Tab",
+ ],
+ children: (
+ <>
+ Content for active tab
+ Content for disabled tab
+ Content for another active tab
+
+ ),
+ },
+ play: async ({ canvasElement }) => {
+ const canvas = within(canvasElement);
+
+ // Check that the disabled tab has the correct attribute
+ const disabledTab = canvas.getByRole("tab", { name: "Disabled Tab" });
+ await expect(disabledTab).toHaveAttribute("disabled", "");
+
+ // Try to click the disabled tab - it should not become selected
+
+ const activeTab = canvas.getByRole("tab", { name: "Active Tab" });
+ await expect(activeTab).toHaveAttribute("aria-selected", "true");
+ },
+};
+
+/**
+ * Test tab switching interaction
+ */
+export const TabSwitching: Story = {
+ args: {
+ items: ["First", "Second", "Third"],
+ onChange: fn(),
+ children: (
+ <>
+ First panel content
+ Second panel content
+ Third panel content
+
+ ),
+ },
+ play: async ({ args, canvasElement }) => {
+ const canvas = within(canvasElement);
+
+ const secondTab = canvas.getByRole("tab", { name: "Second" });
+ await userEvent.click(secondTab);
+
+ await expect(args.onChange).toHaveBeenCalledWith(1);
+ await expect(secondTab).toHaveAttribute("aria-selected", "true");
+
+ const thirdTab = canvas.getByRole("tab", { name: "Third" });
+ await userEvent.click(thirdTab);
+
+ await expect(args.onChange).toHaveBeenCalledWith(2);
+ await expect(canvas.getByText("Third panel content")).toBeVisible();
+ await expect(thirdTab).toHaveAttribute("aria-selected", "true");
+ },
+};
+
+/**
+ * Test URL search params synchronization
+ * This tests the complex logic of syncing tab state with URLSearchParams
+ */
+export const URLSearchParamsSync: Story = {
+ args: {
+ items: ["react", "vue", "angular"],
+ searchParamKey: "framework",
+ children: (
+ <>
+
+ React is a JavaScript library for building user interfaces.
+
+ Vue.js is a progressive JavaScript framework.
+
+ Angular is a platform for building mobile and desktop web
+ applications.
+
+
+ ),
+ },
+ parameters: {
+ nextjs: {
+ appDirectory: true,
+ navigation: {
+ query: {
+ framework: "vue",
+ },
+ },
+ },
+ },
+};
+
+/**
+ * Test localStorage persistence
+ * This tests the complex logic of syncing tab state across browser tabs/windows
+ */
+export const LocalStoragePersistence: Story = {
+ args: {
+ items: ["Tab 1", "Tab 2", "Tab 3"],
+ storageKey: "test-tabs-storage",
+ children: (
+ <>
+ Content 1
+ Content 2
+ Content 3
+
+ ),
+ },
+ play: async ({ canvasElement }) => {
+ const canvas = within(canvasElement);
+
+ // Clear localStorage first
+ localStorage.removeItem("test-tabs-storage");
+
+ // Click on Tab 2
+ const tab2 = canvas.getByRole("tab", { name: "Tab 2" });
+ await userEvent.click(tab2);
+
+ // Check that the value was stored in localStorage (slugified key)
+ const storedValue = localStorage.getItem("test-tabs-storage");
+ await expect(storedValue).toBe("tab-2");
+
+ // Simulate storage event from another tab/window
+ window.dispatchEvent(
+ new StorageEvent("storage", {
+ key: "test-tabs-storage",
+ newValue: "tab-3",
+ }),
+ );
+
+ // Wait a bit for the effect to trigger
+ await new Promise((resolve) => setTimeout(resolve, 100));
+
+ // Tab 3 should now be selected
+ const tab3 = canvas.getByRole("tab", { name: "Tab 3" });
+ await expect(tab3).toHaveAttribute("aria-selected", "true");
+
+ // Clean up
+ localStorage.removeItem("test-tabs-storage");
+ },
+};
+
+/**
+ * Tabs with custom keys
+ * Tests the custom key feature for tab identification
+ */
+export const WithCustomKeys: Story = {
+ args: {
+ items: [
+ { label: "Getting Started", key: "intro", disabled: false },
+ { label: "API Reference", key: "api", disabled: false },
+ { label: "Examples", key: "examples", disabled: false },
+ ],
+ searchParamKey: "section",
+ children: (
+ <>
+ Introduction and getting started guide
+ Complete API documentation
+ Code examples and tutorials
+
+ ),
+ },
+ play: async ({ canvasElement }) => {
+ const canvas = within(canvasElement);
+
+ // Clear search params
+ const url = new URL(window.location.href);
+ url.searchParams.delete("section");
+ window.history.replaceState(null, "", url.toString());
+
+ // Click on API Reference
+ const apiTab = canvas.getByRole("tab", { name: "API Reference" });
+ await userEvent.click(apiTab);
+
+ // URL should use the custom key 'api' instead of slugified label
+ await expect(window.location.search).toContain("section=api");
+
+ // Click on Examples
+ const examplesTab = canvas.getByRole("tab", { name: "Examples" });
+ await userEvent.click(examplesTab);
+
+ await expect(window.location.search).toContain("section=examples");
+ },
+};
+
+/**
+ * Test controlled mode
+ * Tabs can be controlled externally via selectedIndex prop
+ */
+export const ControlledMode: Story = {
+ render: function ControlledTabs() {
+ const [selectedIndex, setSelectedIndex] = React.useState(0);
+
+ return (
+
+
+ setSelectedIndex(0)} variant="tertiary">
+ Select Tab 1
+
+ setSelectedIndex(1)} variant="tertiary">
+ Select Tab 2
+
+ setSelectedIndex(2)} variant="tertiary">
+ Select Tab 3
+
+
+
+ Content 1
+ Content 2
+ Content 3
+
+
+
+ {["pnpm", "npm", "yarn"].map((item) => (
+ {item}
+ ))}
+
+
+ {["pnpm", "npm", "yarn"].map((item) => (
+ {item}
+ ))}
+
+
+ This one doesn't have a `storageKey`, so it's not connected:
+
+ {["pnpm", "npm", "yarn"].map((item) => (
+ {item}
+ ))}
+
+
+ );
+ },
+};
+
+export const ContentInHiddenPanelOpensByHash: Story = {
+ args: {
+ items: ["Docker", "Binary"],
+ children: (
+ <>
+
+
+ Navigate to #binary
+
+
+
+ Binary
+
+
+ ),
+ },
+};
+
+export const MultipleTabsInParams: Story = {
+ parameters: {
+ nextjs: {
+ appDirectory: true,
+ navigation: {
+ query: "tab=shrimp&tab=brown-rice&tab=mango&tab=ponzu",
+ },
+ },
+ },
+ render() {
+ return (
+
+
+ Protein
+
+ π
+ π
+ π§
+ π¦
+
+
+
+
+ Base
+
+ π
+ π
+ π₯¬
+ π₯
+
+
+
+
+ Toppings
+
+ π«
+ π₯
+ π₯
+ π₯
+
+
+
+
+ Sauce
+
+ πΆ
+ π
+ πΆοΈ
+ π«
+
+
+
+ {children}
+
+ );
+};
+
+const moveFocusWithLeftAndRight = (
+ event: React.KeyboardEvent,
+) => {
+ if (
+ event.target instanceof HTMLElement &&
+ event.target.tagName === "BUTTON"
+ ) {
+ let next: Element | null | undefined;
+ switch (event.key) {
+ case "ArrowLeft":
+ next = event.target.previousElementSibling;
+ break;
+ case "ArrowRight":
+ next = event.target.nextElementSibling;
+ break;
+ }
+ if (next && next instanceof HTMLElement && next.tagName === "BUTTON") {
+ event.preventDefault();
+ next.focus();
+ }
+ }
+};
diff --git a/packages/design-system/src/text-link.stories.tsx b/packages/design-system/src/text-link.stories.tsx
new file mode 100644
index 00000000..044cccba
--- /dev/null
+++ b/packages/design-system/src/text-link.stories.tsx
@@ -0,0 +1,30 @@
+import { Meta, StoryObj } from "@storybook/react";
+import { hiveThemeDecorator } from "./__storybook__/hive-theme-decorator";
+import { ArrowIcon } from "./icons";
+import { TextLink, TextLinkProps } from "./text-link";
+
+export default {
+ title: "Components/TextLink",
+ component: TextLink,
+ decorators: [hiveThemeDecorator],
+ args: {
+ href: "#",
+ },
+} satisfies Meta;
+
+export const WithUnderline: StoryObj = {
+ args: {
+ children: "The Guild",
+ },
+};
+
+export const WithArrow: StoryObj = {
+ args: {
+ children: (
+ <>
+ Learn more
+
+
+ ),
+ },
+};
diff --git a/packages/design-system/src/text-link.tsx b/packages/design-system/src/text-link.tsx
new file mode 100644
index 00000000..fd31858a
--- /dev/null
+++ b/packages/design-system/src/text-link.tsx
@@ -0,0 +1,57 @@
+import React from "react";
+
+import { Anchor, AnchorProps } from "./anchor";
+import { cn } from "./cn";
+import { ArrowIcon } from "./icons";
+
+export type TextLinkProps = AnchorProps & {
+ variant?: "dark" | "default";
+};
+
+export function TextLink({
+ children,
+ className,
+ variant = "default",
+ ...rest
+}: TextLinkProps) {
+ const hasArrow =
+ children &&
+ flattenFragments(children).some(
+ (child) =>
+ typeof child === "object" &&
+ child &&
+ "type" in child &&
+ child.type === ArrowIcon,
+ );
+
+ return (
+
+ {children}
+
+ );
+}
+
+function flattenFragments(children: React.ReactNode): React.ReactNode[] {
+ return React.Children.toArray(children).flatMap((child) =>
+ typeof child === "object" &&
+ "type" in child &&
+ child.type === React.Fragment
+ ? ((child as React.ReactElement<{ children?: React.ReactNode[] }>).props
+ .children ?? [])
+ : child,
+ );
+}
diff --git a/packages/design-system/src/theme-switcher.tsx b/packages/design-system/src/theme-switcher.tsx
new file mode 100644
index 00000000..ef8a8262
--- /dev/null
+++ b/packages/design-system/src/theme-switcher.tsx
@@ -0,0 +1,19 @@
+"use client";
+
+import { useTheme } from "next-themes";
+import { FC, ReactNode } from "react";
+
+export const ThemeSwitcherButton: FC<{ children: ReactNode }> = ({
+ children,
+}) => {
+ const { resolvedTheme, setTheme } = useTheme();
+
+ return (
+
+ );
+};
diff --git a/packages/design-system/src/tools-and-libraries-cards/index.tsx b/packages/design-system/src/tools-and-libraries-cards/index.tsx
new file mode 100644
index 00000000..99783b92
--- /dev/null
+++ b/packages/design-system/src/tools-and-libraries-cards/index.tsx
@@ -0,0 +1,52 @@
+import { HTMLAttributes } from "react";
+
+import { CallToAction } from "../call-to-action";
+import { cn } from "../cn";
+import { Heading } from "../heading";
+import { AncillaryProductCard, MainProductCard } from "../product-card";
+import { FOUR_MAIN_PRODUCTS, SIX_HIGHLIGHTED_PRODUCTS } from "../products";
+
+export interface ToolsAndLibrariesCardsProps extends HTMLAttributes {
+ isHive?: boolean;
+}
+export function ToolsAndLibrariesCards({
+ className,
+ isHive,
+ ...rest
+}: ToolsAndLibrariesCardsProps) {
+ return (
+
+
+ Discover the complete ecosystem of tools and libraries
+
+ Complete GraphQL Federation Stack
+
+ {FOUR_MAIN_PRODUCTS.map((product) => (
+
+ ))}
+
+
+ Our libraries to support all your GraphQL needs
+
+
+ {SIX_HIGHLIGHTED_PRODUCTS.map((product) => (
+
+ ))}
+
+
+ Explore the Ecosystem
+
+
+ );
+}
diff --git a/packages/design-system/src/tools-and-libraries-cards/tools-and-libraries.stories.ts b/packages/design-system/src/tools-and-libraries-cards/tools-and-libraries.stories.ts
new file mode 100644
index 00000000..971193dd
--- /dev/null
+++ b/packages/design-system/src/tools-and-libraries-cards/tools-and-libraries.stories.ts
@@ -0,0 +1,16 @@
+import { Meta, StoryObj } from "@storybook/react";
+import { ToolsAndLibrariesCards } from ".";
+import { hiveThemeDecorator } from "../__storybook__/hive-theme-decorator";
+
+export default {
+ title: "Hive/ToolsAndLibrariesCards",
+ component: ToolsAndLibrariesCards,
+ decorators: [hiveThemeDecorator],
+ parameters: {
+ forcedLightMode: true,
+ },
+} satisfies Meta;
+
+export const Default: StoryObj = {
+ name: "ToolsAndLibrariesCards",
+};
diff --git a/packages/design-system/src/types/components.ts b/packages/design-system/src/types/components.ts
new file mode 100644
index 00000000..42c89cd7
--- /dev/null
+++ b/packages/design-system/src/types/components.ts
@@ -0,0 +1,153 @@
+import { ComponentProps, ReactElement, ReactNode } from "react";
+
+// Image props compatible with @unpic/react
+export interface IImage {
+ alt: string;
+ className?: string;
+ height: number;
+ priority?: boolean;
+ src: string;
+ width: number;
+}
+
+interface IVideo {
+ placeholder: string;
+ src: string;
+}
+
+// Simplified video props (was react-player)
+export interface ReactPlayerProps {
+ controls?: boolean;
+ height?: number | string;
+ loop?: boolean;
+ muted?: boolean;
+ playing?: boolean;
+ url?: string;
+ width?: number | string;
+}
+
+export type ILink = Pick<
+ ComponentProps<"a">,
+ "className" | "onClick" | "rel" | "style" | "target" | "title"
+> & {
+ children?: ReactNode;
+ newWindow?: boolean;
+} & {
+ href: { pathname?: string } | string;
+};
+
+export interface IFeatureListProps {
+ className?: string;
+ description?: string;
+ items: {
+ description: string;
+ image: IImage;
+ link?: ILink;
+ title: string;
+ }[];
+ link?: ILink;
+ title?: string;
+}
+
+export interface IInfoListProps {
+ className?: string;
+ items: {
+ description: ReactNode | string;
+ link?: ILink;
+ title: ReactNode | string;
+ }[];
+ title?: ReactNode | string;
+}
+
+export interface IHeroVideoProps {
+ className?: string;
+ description: ReactNode | string;
+ flipped?: boolean;
+ link?: ILink;
+ title: ReactNode | string;
+ video: IVideo;
+ videoProps?: ReactPlayerProps;
+}
+
+export interface IHeroIllustrationProps {
+ className?: string;
+ description: ReactNode | string;
+ flipped?: boolean;
+ image: IImage;
+ link?: ILink;
+ title: ReactNode | string;
+}
+
+export interface IHeroGradientProps {
+ className?: string;
+ colors?: string[];
+ description: ReactNode | string;
+ image?: IImage;
+ link?: ILink | ILink[];
+ title: ReactNode | string;
+ version?: ReactNode | string;
+}
+
+export interface IHeroMarketplaceProps {
+ className?: string;
+ description: ReactNode | string;
+ image?: IImage;
+ link: ILink;
+ title: ReactNode | string;
+}
+
+export interface IMarketplaceItemProps {
+ description: ReactNode | string;
+ image: IImage;
+ link: Omit;
+ modal?: {
+ content: (() => ReactNode) | ReactNode | string;
+ header: {
+ description?: ILink | string;
+ image?: IImage;
+ };
+ };
+ tags?: string[];
+ title: string;
+ update: string;
+ weeklyNPMDownloads?: number;
+}
+
+export interface IMarketplaceItemsProps {
+ items: IMarketplaceItemProps[];
+}
+
+export interface IMarketplaceListProps {
+ className?: string;
+ colorScheme?: "green" | "neutral";
+ items: IMarketplaceItemProps[];
+ pagination: number;
+ placeholder: ReactElement | string;
+ title?: string;
+}
+
+export interface IMarketplaceSearchProps {
+ className?: string;
+ colorScheme?: "green" | "neutral";
+ placeholder: string;
+ primaryList: IMarketplaceListProps;
+ queryList?: IMarketplaceListProps;
+ secondaryList?: IMarketplaceListProps;
+ tagsFilter?: readonly string[] | string[];
+ title: ReactNode | string;
+}
+
+export interface ISchemaPageProps {
+ editorData: Omit[];
+ schemaName: string;
+ tags?: string[];
+}
+
+export interface IEditorProps {
+ children: ReactNode;
+ frameworks?: string[];
+ image?: string;
+ operations?: string;
+ schema?: string;
+ title: string;
+}
diff --git a/packages/design-system/src/types/global.d.ts b/packages/design-system/src/types/global.d.ts
new file mode 100644
index 00000000..faace3bc
--- /dev/null
+++ b/packages/design-system/src/types/global.d.ts
@@ -0,0 +1,10 @@
+interface Crisp {
+ push: (args: unknown[]) => void;
+}
+
+interface Window {
+ $crisp?: Crisp;
+}
+
+// Adds $crisp to globalThis
+declare var $crisp: Crisp | undefined;
diff --git a/packages/design-system/src/types/images.d.ts b/packages/design-system/src/types/images.d.ts
new file mode 100644
index 00000000..4172ee86
--- /dev/null
+++ b/packages/design-system/src/types/images.d.ts
@@ -0,0 +1,67 @@
+declare module "*.svg" {
+ const src: string;
+ export default src;
+}
+
+declare module "*.svg?svgr" {
+ const content: React.FC>;
+ export default content;
+}
+
+declare module "*.jpg" {
+ const content: {
+ blurDataURL?: string;
+ height: number;
+ src: string;
+ width: number;
+ };
+ export default content;
+}
+
+declare module "*.jpeg" {
+ const content: {
+ blurDataURL?: string;
+ height: number;
+ src: string;
+ width: number;
+ };
+ export default content;
+}
+
+declare module "*.png" {
+ const content: {
+ blurDataURL?: string;
+ height: number;
+ src: string;
+ width: number;
+ };
+ export default content;
+}
+
+declare module "*.webp" {
+ const content: {
+ blurDataURL?: string;
+ height: number;
+ src: string;
+ width: number;
+ };
+ export default content;
+}
+
+declare module "*.gif" {
+ const content: { height: number; src: string; width: number };
+ export default content;
+}
+
+declare module "*.mdx" {
+ import { ComponentType } from "react";
+ const MDXComponent: ComponentType<{
+ components?: Record;
+ }>;
+ export default MDXComponent;
+}
+
+declare module "*.module.css" {
+ const classes: Record;
+ export default classes;
+}
diff --git a/packages/design-system/src/types/severity.ts b/packages/design-system/src/types/severity.ts
new file mode 100644
index 00000000..7fff046f
--- /dev/null
+++ b/packages/design-system/src/types/severity.ts
@@ -0,0 +1 @@
+export type Severity = "critical" | "neutral" | "positive" | "warning";
diff --git a/packages/design-system/src/types/utility.ts b/packages/design-system/src/types/utility.ts
new file mode 100644
index 00000000..b3e1b35f
--- /dev/null
+++ b/packages/design-system/src/types/utility.ts
@@ -0,0 +1,8 @@
+export type Prettify = { [K in keyof T]: T[K] } & {};
+
+export type UnionToIntersection = Prettify<
+ // eslint-disable-next-line @typescript-eslint/no-explicit-any
+ (T extends any ? (x: T) => any : never) extends (x: infer R) => any
+ ? R
+ : never
+>;
diff --git a/packages/design-system/src/use-hash.ts b/packages/design-system/src/use-hash.ts
new file mode 100644
index 00000000..3ea22a71
--- /dev/null
+++ b/packages/design-system/src/use-hash.ts
@@ -0,0 +1,20 @@
+"use client";
+
+// don't need to memoize string `hash` value
+"use no memo";
+
+import { useEffect, useState } from "react";
+
+export function useHash() {
+ const [hash, setHash] = useState("");
+
+ useEffect(() => {
+ const handleHashChange = () => setHash(location.hash.replace("#", ""));
+ handleHashChange();
+
+ globalThis.addEventListener("hashchange", handleHashChange);
+ return () => globalThis.removeEventListener("hashchange", handleHashChange);
+ }, []);
+
+ return hash;
+}
diff --git a/packages/design-system/src/version-dropdown.stories.tsx b/packages/design-system/src/version-dropdown.stories.tsx
new file mode 100644
index 00000000..12185d32
--- /dev/null
+++ b/packages/design-system/src/version-dropdown.stories.tsx
@@ -0,0 +1,26 @@
+import { Meta, StoryObj } from "@storybook/react";
+import { hiveThemeDecorator } from "./__storybook__/hive-theme-decorator";
+import { VersionDropdown, VersionDropdownProps } from "./version-dropdown";
+
+const decorator = (Story: React.FC