@geenius/storybook

Shared Storybook v10 preset, manager theme, preview decorators, and Vite preset for Geenius package review surfaces.

@geenius/storybook is infrastructure for stock Storybook, not a custom storybook shell. Consumer packages keep normal .storybook/{main,manager,preview}.ts files and compose the helpers exported here.

Installation

pnpm add -D @geenius/storybook storybook vite @storybook/addon-docs @storybook/addon-a11y @storybook/addon-themes @storybook/addon-vitest

React Storybook apps also install @storybook/react-vite, react, and react-dom. SolidJS Storybook apps also install storybook-solidjs-vite and solid-js.

Storybook and first-party @storybook/* packages are pinned to ^10.3.6. storybook-solidjs-vite is the only framework peer exception because the registry currently publishes the SolidJS framework adapter through 10.0.12.

Public Imports

| Import | Purpose | | --- | --- | | @geenius/storybook | Framework-agnostic errors and shared types | | @geenius/storybook/vite | createStorybookViteConfig for Vite/workspace settings | | @geenius/storybook/manager | applyManagerConfig for branded manager chrome | | @geenius/storybook/themes | Geenius Storybook theme objects and createBrandTheme | | @geenius/storybook/react | React Storybook config, preview, and decorators | | @geenius/storybook/react-css | React helpers plus bundled gn-storybook-* CSS utilities | | @geenius/storybook/react-css/styles.css | React CSS variant stylesheet | | @geenius/storybook/solidjs | SolidJS Storybook config, preview, and decorators | | @geenius/storybook/solidjs-css | SolidJS helpers plus bundled gn-storybook-* CSS utilities | | @geenius/storybook/solidjs-css/styles.css | SolidJS CSS variant stylesheet |

There is no public @geenius/storybook/shared subpath. Import shared symbols from @geenius/storybook.

Root Types And Errors

The root import is the framework-agnostic surface for shared option types and typed preset failures:

import {
  StorybookConfigError,
  StorybookError,
  type StorybookConfigOptions,
  type StorybookErrorMetadata,
} from "@geenius/storybook";

export function readStorybookConfigError(error: unknown): string {
  if (error instanceof StorybookConfigError) {
    return `Invalid Storybook config: ${error.message}`;
  }

  if (error instanceof StorybookError) {
    return `Storybook preset failed: ${error.message}`;
  }

  return "Unknown Storybook failure";
}

export const storiesOnly = (
  options: StorybookConfigOptions,
): string[] => options.stories;

export const configErrorMetadata: StorybookErrorMetadata = {
  context: { variant: "react" },
};

Vite Helper

Most apps get the Vite preset through createStorybookConfig. Config authors who need to compose it directly can import the build-only helper from /vite:

// apps/storybook-react/.storybook/main.ts
import { createStorybookViteConfig } from "@geenius/storybook/vite";
import { mergeConfig } from "vite";

export default {
  stories: ["../src/**/*.stories.@(ts|tsx|mdx)"],
  viteFinal: (config) =>
    mergeConfig(
      config,
      createStorybookViteConfig({ framework: "react", variant: "react" }),
    ),
};

Theme Helper

Storybook web apps usually apply the manager theme through applyManagerConfig. Native or custom manager harnesses can import the theme subpath directly:

import {
  createBrandTheme,
  geeniusDarkTheme,
} from "@geenius/storybook/themes";

export const nativeBrandTheme = createBrandTheme({
  base: "dark",
  packageName: "@geenius/example - Native",
});

export const fallbackTheme = geeniusDarkTheme;

React Setup

// apps/storybook-react/.storybook/main.ts
import { createStorybookConfig } from "@geenius/storybook/react";

export default createStorybookConfig({
  stories: ["../src/**/*.stories.@(ts|tsx|mdx)"],
  variant: "react",
});

// apps/storybook-react/.storybook/manager.ts
import { applyManagerConfig } from "@geenius/storybook/manager";

applyManagerConfig({ packageName: "@geenius/example - React", base: "dark" });

// apps/storybook-react/.storybook/preview.ts
import { createPreview, withProvider } from "@geenius/storybook/react";
import { AppProvider } from "../src/AppProvider";

export default createPreview({
  decorators: [withProvider(AppProvider)],
  defaultTheme: "dark",
});

For react-css, import the stylesheet before creating the preview:

import "@geenius/storybook/react-css/styles.css";
import { createPreview } from "@geenius/storybook/react-css";

export default createPreview({ defaultTheme: "dark" });

SolidJS Setup

// apps/storybook-solidjs/.storybook/main.ts
import { createStorybookConfig } from "@geenius/storybook/solidjs";

export default createStorybookConfig({
  stories: ["../src/**/*.stories.@(ts|tsx|mdx)"],
  variant: "solidjs",
});

// apps/storybook-solidjs/.storybook/preview.ts
import { createPreview, withProvider } from "@geenius/storybook/solidjs";
import { AppProvider } from "../src/AppProvider";

export default createPreview({
  decorators: [withProvider(AppProvider)],
  defaultTheme: "dark",
});

For solidjs-css, import @geenius/storybook/solidjs-css/styles.css before calling createPreview.

Local Apps

This repository owns the full private Storybook verification matrix:

apps/storybook-react/
apps/storybook-react-css/
apps/storybook-react-shadcn/
apps/storybook-react-ant/
apps/storybook-react-chakra/
apps/storybook-react-mui/
apps/storybook-react-mantine/
apps/storybook-react-heroui/
apps/storybook-react-daisyui/
apps/storybook-react-native/
apps/storybook-solidjs/
apps/storybook-solidjs-css/
apps/storybook-solidjs-ark/
apps/storybook-solidjs-kobalte/
apps/storybook-solidjs-solidui/

Each web app uses the stock Storybook v10 shape:

apps/storybook-<variant>/
  .storybook/main.ts
  .storybook/manager.ts
  .storybook/preview.ts
  src/stories/*.stories.tsx

variants.json is the source for app enumeration, published subpaths, size budgets, coverage thresholds, and Playwright/Storybook fanout. Launch-variant lists hardcoded outside that manifest should be treated as drift.

Run app builds and registry parity with:

pnpm test:storybook:build
pnpm test:storybook

React Native Harness

apps/storybook-react-native/ is a native evidence harness, not a web Storybook app. Stories use @storybook/react-native and React Native primitives with stable testID and accessibilityLabel selectors such as geenius-storybook-react-native, storybook-welcome, and storybook-status-*.

Native gates are exposed through the app scripts:

pnpm --filter @geenius/storybook-app-react-native test
pnpm --filter @geenius/storybook-app-react-native test:behavior
pnpm --filter @geenius/storybook-app-react-native test:a11y
pnpm --filter @geenius/storybook-app-react-native test:visual

The verifier checks native bootstrap behavior, selector-based a11y coverage, and dark/light visual baselines in apps/storybook-react-native/__visual__/goldens/native-harness.{dark,light}.svg.

Testing

The PR-blocking release gate is:

pnpm test:gauntlet

It runs lint, app lint, publint, type-check, unit tests, convention tests, cross-variant contract tests, packed smoke, packed type checks, bundle budgets, supply-chain audit, license checks, and SBOM generation.

The full pre-release lane is:

pnpm test:all

It adds Storybook app builds, Storybook parity, DB N/A guards, Playwright e2e, accessibility, visual regression, performance smoke, coverage, differential coverage, and SBOM output.

Contributing Tests

Variant coverage is driven by variants.json. Add or update variants there first, then let the root scripts discover package filters, Storybook apps, Playwright projects, coverage thresholds, and bundle budgets.

When adding behavior, cover it at the narrowest useful layer:

• Sub-package Vitest files under packages/<runtime>/src/__tests__/ for preset, preview, theme, CSS, and utility behavior.
• Root contract tests under __tests__/ for published exports, cross-variant parity, conventions, tarball purity, packed import smoke, type checks, and Storybook story parity.
• Playwright specs under e2e/ for public-subpath browser behavior, accessibility, keyboard/focus contracts, visual snapshots, and web-vitals smoke.

Update visual baselines with:

pnpm test:visual --update-snapshots

License

FSL-1.1-Apache-2.0. See LICENSE.