Track HiveGrid Cloud planning reference

This commit is contained in:
david committed 2026-06-26 20:48:01 +02:00
1 parent b3d5ea6764
commit e341c5938a
5784 files changed
+1104929 -3

No files matched your search

+7
View File
@@ -0,0 +1,7 @@
storybook-static/
*.log
# Lost-Pixel generated comparison output. Only the baseline/ tree is
# committed — current/ and difference/ are per-run artifacts.
.lostpixel/current/
.lostpixel/difference/
@@ -0,0 +1,2 @@
current
difference
Binary file not shown.

After

Width:  |  Height:  |  Size: 6.2 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 5.9 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 5.5 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 6.3 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 5.4 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 5.8 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 6.3 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 6.5 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 7.4 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 5.2 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 5.4 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 5.3 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 11 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 7.8 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 5.3 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 9.8 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 7.7 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 18 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 18 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 15 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 7.1 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 5.3 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 6.0 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 8.5 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 8.3 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 9.6 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 7.4 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 20 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 12 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 6.7 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 6.7 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 13 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 6.6 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 7.4 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 7.5 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 5.7 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 9.3 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 10 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 11 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 11 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 6.3 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 11 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 6.6 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 7.3 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 7.3 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 7.3 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 13 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 8.1 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 10 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 9.7 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 10 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 10 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 9.7 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 16 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 6.0 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 13 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 15 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 11 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 12 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 22 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 6.4 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 6.5 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 5.5 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 6.3 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 6.6 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 4.6 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 31 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 28 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 6.3 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 20 KiB

@@ -0,0 +1,45 @@
/**
* Smoke test for the Storybook-local i18next bootstrap (#62 Task F).
*
* The point of this test is to lock in the contract that the locale
* toolbar global drives a real `react-i18next` instance — not just html
* attributes — so future stories that call `useTranslation` resolve
* against the bundled `apps/web/public/locales` tree at the picked
* language. Failures here mean a story would render English even when
* the toolbar reads "DE", which is precisely the regression we're
* guarding against now that the locale picker is functional.
*/
import { describe, expect, it } from "vitest";
import { getStorybookI18n, setStorybookLocale } from "./i18n";
describe("storybook i18n bootstrap", () => {
it("seeds the `common` namespace for both shipped locales", () => {
const i18n = getStorybookI18n();
// `action.save` lives in `common.json` and is present in both EN + DE.
expect(i18n.hasResourceBundle("en", "common")).toBe(true);
expect(i18n.hasResourceBundle("de", "common")).toBe(true);
expect(i18n.getResource("en", "common", "action.save")).toBe("Save");
expect(i18n.getResource("de", "common", "action.save")).toBeTruthy();
});
it("switches language when the toolbar global flips", async () => {
const i18n = getStorybookI18n();
setStorybookLocale("de");
// changeLanguage is async; wait one microtask for the i18next promise.
await Promise.resolve();
expect(i18n.language).toBe("de");
setStorybookLocale("en");
await Promise.resolve();
expect(i18n.language).toBe("en");
});
it("falls back to the default locale for unknown values", async () => {
const i18n = getStorybookI18n();
// `ar` is registered as a toolbar item for RTL preview but we don't
// ship Arabic resources — the helper must coerce it back to the
// configured default so stories don't render empty keys.
setStorybookLocale("ar");
await Promise.resolve();
expect(["de", "en"]).toContain(i18n.language);
});
});
@@ -0,0 +1,67 @@
/**
* Minimal in-Storybook i18next instance (#62 Task F).
*
* Bootstraps a real (synchronous) i18next + react-i18next instance so the
* locale toolbar global has actual effect on stories that call
* `useTranslation`. Resources are inlined at build time via Vite's
* `import.meta.glob` against the apps/web public-locales tree, so we don't
* need an i18next-http-backend (Storybook has no Express loader to serve
* them from).
*
* Only a handful of namespaces are seeded — the ones today's 21 stories
* could plausibly reference (`common`, `translations`, `auth`, `errors`).
* Adding more is a one-line resource-map change.
*/
import i18next, { type i18n as I18n } from "i18next";
import { initReactI18next } from "react-i18next";
import { defaultLocale, i18nConfig, supportedLocales, type SupportedLocale } from "@toolctrl/i18n";
type LocaleResources = Record<string, Record<string, unknown>>;
type ResourceTree = Partial<Record<SupportedLocale | "ar", LocaleResources>>;
// Eager glob — Vite inlines every matched JSON at build time, which is fine
// for a 9-file, <100kB locale tree. The pattern resolves relative to this
// file: ../../../apps/web/public/locales/<locale>/<ns>.json.
const localeModules = import.meta.glob("../../../apps/web/public/locales/*/*.json", {
eager: true,
}) as Record<string, { default: Record<string, unknown> }>;
function buildResources(): ResourceTree {
const out: ResourceTree = {};
for (const [path, mod] of Object.entries(localeModules)) {
// path looks like ".../apps/web/public/locales/en/common.json"
const match = /\/locales\/([^/]+)\/([^/]+)\.json$/.exec(path);
if (!match) continue;
const [, locale, namespace] = match;
const bucket = (out[locale as SupportedLocale] ??= {});
bucket[namespace] = mod.default;
}
return out;
}
let cached: I18n | undefined;
export function getStorybookI18n(): I18n {
if (cached) return cached;
const resources = buildResources();
const instance = i18next.createInstance();
instance.use(initReactI18next).init({
...i18nConfig,
lng: defaultLocale,
resources: resources as Record<string, Record<string, Record<string, unknown>>>,
// Storybook stories run client-only — no SSR hydration concerns, so we
// can synchronously init. `react.useSuspense: false` already set in the
// shared config blocks suspending decorators.
initImmediate: false,
});
cached = instance;
return instance;
}
export function setStorybookLocale(locale: string): void {
const instance = getStorybookI18n();
const target = supportedLocales.includes(locale as SupportedLocale) ? locale : defaultLocale;
if (instance.language !== target) {
void instance.changeLanguage(target);
}
}
@@ -0,0 +1,58 @@
import path from "node:path";
import { fileURLToPath } from "node:url";
import { mergeConfig, type UserConfig } from "vite";
import tailwindcss from "@tailwindcss/vite";
import type { StorybookConfig } from "@storybook/react-vite";
const here = path.dirname(fileURLToPath(import.meta.url));
const webAppRoot = path.resolve(here, "../../../apps/web/app");
const config: StorybookConfig = {
stories: [
"../src/**/*.mdx",
"../src/**/*.stories.@(ts|tsx|mdx)",
"../../../packages/ui/src/**/*.stories.@(ts|tsx|mdx)",
"../../../packages/ui-app/src/**/*.stories.@(ts|tsx|mdx)",
"../../../packages/ui-subframe/src/**/*.stories.@(ts|tsx|mdx)",
"../../../packages/ui-mock/src/**/*.stories.@(ts|tsx|mdx)",
],
addons: [
"@storybook/addon-essentials",
"@storybook/addon-a11y",
"@storybook/addon-interactions",
"@storybook/addon-themes",
],
framework: {
name: "@storybook/react-vite",
options: {},
},
docs: {
autodocs: "tag",
},
typescript: {
check: false,
reactDocgen: false,
},
core: {
disableTelemetry: true,
},
// Mirror apps/web's Vite pipeline for the Tailwind-v4 surface so future
// stories can import the real components from packages/ui / apps/web
// instead of the temporary `_demo-primitives.tsx`. Today's 21 stories
// use inline-styles + CSS-variable tokens declared in `preview.css`, so
// adding the Tailwind plugin is a no-op for them but unblocks the
// migration path. See docs/improvement-plan/08-mobile-cli-storybook-sdk/storybook.md
// ("real Tailwind-v4 preview pipeline" deviation).
async viteFinal(viteConfig) {
return mergeConfig(viteConfig, {
plugins: [tailwindcss()],
resolve: {
alias: {
"~": webAppRoot,
},
},
} satisfies UserConfig);
},
};
export default config;
@@ -0,0 +1,180 @@
/*
* Storybook preview stylesheet.
*
* Layered as:
* 1. `@import "tailwindcss"` — pulls the full Tailwind v4 runtime via the
* @tailwindcss/vite plugin wired in `.storybook/main.ts`. This unlocks
* Tailwind utility classes inside stories that import real
* `packages/ui` / `apps/web` components. Today's 21 stories use inline
* styles + the CSS-variable tokens declared further down, so the
* Tailwind import is additive — no visual change to existing stories.
* 2. `@custom-variant dark` — mirrors apps/web/app/globals.css so the
* `dark:` utility flips alongside the `.dark` root class that
* `withThemeByClassName` applies from the theme toolbar global.
* 3. The CSS-variable token block below — the design-token surface the
* existing demo primitives (`_demo-primitives.tsx`) read via
* `var(--color-primary)` etc. Kept verbatim so the 21 in-flight
* stories stay visually stable while the real-component migration
* ramps up (#62 follow-up).
*
* The web app's full theme (HSL channel system, Tremor palette, typography
* scale) lives in apps/web/app/globals.css; we keep the Storybook surface
* intentionally narrow so the preview builds quickly and stays readable.
*/
@import "tailwindcss";
/*
* Subframe design-system theme + content sources.
* Storybook runs its own Tailwind-v4 pipeline rooted at apps/storybook, so it neither loads
* the Subframe theme tokens nor scans the Subframe component files in apps/web/app. Without
* these, Subframe-backed components (Button, TextInput, …) render unstyled here and in
* lostpixel visual regression. Mirror apps/web/app/globals.css's Subframe wiring.
*/
@import "../../../apps/web/app/ui/theme.css";
@source "../../../apps/web/app/ui";
@source "../../../apps/web/app/components/ui";
@custom-variant dark (&:is(.dark *));
/*
* apps/web design-token surface (#62 follow-up).
*
* Mirrors apps/web/app/globals.css so real shadcn components imported from
* apps/web/app/components/ui resolve `bg-primary`, `text-foreground`,
* `border-border`, etc. The HSL channel system + `@theme inline` mapping is
* load-bearing for the cva variants in those components.
*
* The legacy `--color-bg`/`--color-fg`/etc. block at the bottom is kept for
* backward compatibility with un-migrated demo primitives.
*/
:root {
--background: hsl(0 0% 100%);
--foreground: hsl(240 10% 3.9%);
--muted: hsl(240 4.8% 95.9%);
--muted-foreground: hsl(240 3.8% 46.1%);
--popover: hsl(0 0% 100%);
--popover-foreground: hsl(240 10% 3.9%);
--card: hsl(0 0% 100%);
--card-foreground: hsl(240 10% 3.9%);
--border: hsl(240 5.9% 90%);
--input: hsl(240 5.9% 90%);
--primary: hsl(240 5.9% 10%);
--primary-foreground: hsl(0 0% 98%);
--secondary: hsl(240 4.8% 95.9%);
--secondary-foreground: hsl(240 5.9% 10%);
--accent: hsl(240 4.8% 95.9%);
--accent-foreground: hsl(240 5.9% 10%);
--destructive: hsl(0 84.2% 60.2%);
--destructive-foreground: hsl(0 0% 98%);
--ring: hsl(240 5.9% 10%);
--radius: 0.5rem;
/* Legacy demo-primitive tokens (kept for un-migrated stories). */
--color-bg: #ffffff;
--color-fg: #0f172a;
--color-muted: #64748b;
--color-border: #e2e8f0;
--color-success: #16a34a;
--color-warning: #d97706;
color-scheme: light;
}
.dark {
--background: hsl(240 10% 3.9%);
--foreground: hsl(0 0% 98%);
--muted: hsl(240 3.7% 15.9%);
--muted-foreground: hsl(240 5% 64.9%);
--popover: hsl(240 10% 3.9%);
--popover-foreground: hsl(0 0% 98%);
--card: hsl(240 10% 3.9%);
--card-foreground: hsl(0 0% 98%);
--border: hsl(240 3.7% 15.9%);
--input: hsl(240 3.7% 15.9%);
--primary: hsl(0 0% 98%);
--primary-foreground: hsl(240 5.9% 10%);
--secondary: hsl(240 3.7% 15.9%);
--secondary-foreground: hsl(0 0% 98%);
--accent: hsl(240 3.7% 15.9%);
--accent-foreground: hsl(0 0% 98%);
--destructive: hsl(0 62.8% 30.6%);
--destructive-foreground: hsl(0 0% 98%);
--ring: hsl(240 4.9% 83.9%);
/* Legacy demo-primitive tokens (kept for un-migrated stories). */
--color-bg: #0b0b0c;
--color-fg: #f8fafc;
--color-muted: #94a3b8;
--color-border: #1f2937;
color-scheme: dark;
}
@theme inline {
--radius-sm: calc(var(--radius) - 4px);
--radius-md: calc(var(--radius) - 2px);
--radius-lg: var(--radius);
--radius-xl: calc(var(--radius) + 4px);
--color-background: var(--background);
--color-foreground: var(--foreground);
--color-card: var(--card);
--color-card-foreground: var(--card-foreground);
--color-popover: var(--popover);
--color-popover-foreground: var(--popover-foreground);
--color-primary: var(--primary);
--color-primary-foreground: var(--primary-foreground);
--color-secondary: var(--secondary);
--color-secondary-foreground: var(--secondary-foreground);
--color-muted: var(--muted);
--color-muted-foreground: var(--muted-foreground);
--color-accent: var(--accent);
--color-accent-foreground: var(--accent-foreground);
--color-destructive: var(--destructive);
--color-border: var(--border);
--color-input: var(--input);
--color-ring: var(--ring);
}
html,
body {
background: var(--color-bg);
color: var(--color-fg);
font-family:
Inter,
ui-sans-serif,
system-ui,
-apple-system,
BlinkMacSystemFont,
"Segoe UI",
sans-serif;
margin: 0;
}
/*
* Coarse Tailwind-like helpers retained so the preview's `withWrapper`
* decorator works even if a story disables the Tailwind pipeline via
* `parameters.tailwind.disable` (escape hatch — none in use today). When
* the Tailwind v4 plugin is active these are shadowed by the real utility
* generation, so removing them is safe once we're confident no stories
* rely on the bespoke definitions.
*/
.font-sans {
font-family:
Inter,
ui-sans-serif,
system-ui,
sans-serif;
}
.text-sm {
font-size: 0.875rem;
}
.text-foreground {
color: var(--color-fg);
}
.bg-background {
background: var(--color-bg);
}
.min-h-\[60px\] {
min-height: 60px;
}
.p-6 {
padding: 1.5rem;
}
@@ -0,0 +1,126 @@
import type { Preview, Decorator } from "@storybook/react";
import { withThemeByClassName } from "@storybook/addon-themes";
import React from "react";
import { I18nextProvider } from "react-i18next";
import { getDirection, supportedLocales } from "@toolctrl/i18n";
import { getStorybookI18n, setStorybookLocale } from "./i18n";
import "./preview.css";
const LOCALE_TOOLBAR_DESCRIPTION = "Active language - flips Tailwind rtl: variants, <html lang/dir>, and the in-canvas i18next instance";
const RTL_PREVIEW_TITLE = "AR (RTL preview)";
// i18n decorator (#62 Task F + #72 i18n-foundation).
//
// Two responsibilities:
// 1. Sync `<html lang>` / `<html dir>` so any `rtl:` Tailwind variants
// light up exactly as they would in the running app.
// 2. Switch the in-canvas i18next instance to the picked locale and wrap
// every story in `<I18nextProvider>` so `useTranslation` calls in
// future stories (and any real `packages/ui` components we import
// once the Tailwind v4 pipeline is wired) resolve against the seeded
// `apps/web/public/locales` tree.
//
// The instance is lazy-built on first render — for the existing 21 stories
// (none of which call `useTranslation`) this is effectively a no-op beyond
// updating the html attributes.
const withLocale: Decorator = (Story, context) => {
const locale = (context.globals.locale ?? "en") as string;
const dir = getDirection(locale);
if (typeof document !== "undefined") {
document.documentElement.setAttribute("lang", locale);
document.documentElement.setAttribute("dir", dir);
}
setStorybookLocale(locale);
const i18n = getStorybookI18n();
return (
<I18nextProvider i18n={i18n}>
<Story />
</I18nextProvider>
);
};
const withWrapper: Decorator = (Story) => (
<div className="text-foreground bg-background min-h-[60px] p-6 font-sans text-sm">
<Story />
</div>
);
const preview: Preview = {
parameters: {
layout: "padded",
controls: {
matchers: {
color: /(background|color)$/i,
date: /Date$/i,
},
},
backgrounds: {
default: "light",
values: [
{ name: "light", value: "#ffffff" },
{ name: "dark", value: "#0b0b0c" },
],
},
a11y: {
// WCAG-2.2-AA target ruleset for live in-Storybook accessibility
// feedback. Mirrors packages/ui-app/test-setup/axe.ts so devs see the
// same violations during design as their unit tests will catch.
//
// Disable per-story only with `parameters.a11y.disable = true` and a
// code-comment justification. Spec:
// docs/improvement-plan/10-compliance-polish/wcag-internal.md
element: "#storybook-root",
manual: false,
config: {
rules: [
// High-signal contrast rule — Storybook can compute real CSS so we
// keep it enabled (jsdom can't, which is why vitest-axe disables it).
{ id: "color-contrast", enabled: true },
{ id: "color-contrast-enhanced", enabled: false },
// Region landmarks aren't meaningful for an isolated component
// story; verified separately by route-level audits.
{ id: "region", enabled: false },
],
},
options: {
runOnly: {
type: "tag",
values: ["wcag2a", "wcag2aa", "wcag21a", "wcag21aa", "wcag22aa", "best-practice"],
},
reporter: "v2",
},
},
},
globalTypes: {
locale: {
name: "Locale",
description: LOCALE_TOOLBAR_DESCRIPTION,
defaultValue: "en",
toolbar: {
icon: "globe",
items: [
...supportedLocales.map((code) => ({ value: code, title: code.toUpperCase() })),
// RTL preview locale. We don't ship Arabic translations yet, but
// the decorator still flips direction so we can spot layout breaks.
{ value: "ar", title: RTL_PREVIEW_TITLE },
],
showName: true,
dynamicTitle: true,
},
},
},
decorators: [
// `withThemeByClassName` registers its own `theme` global + toolbar item
// (key `theme`, values `light`/`dark`) and applies the class to <html>.
// We intentionally don't re-declare it in `globalTypes` above to avoid
// a duplicate toolbar entry — the addon owns that surface.
withThemeByClassName({
themes: { light: "light", dark: "dark" },
defaultTheme: "light",
}),
withLocale,
withWrapper,
],
};
export default preview;
@@ -0,0 +1,53 @@
/**
* Storybook test-runner configuration (Phase 08 #62).
*
* The test-runner spins up Playwright + Chromium, walks every story
* registered in `main.ts`, and applies the `postVisit` hook below to
* each one. The hook re-runs the same axe-rules ruleset the in-canvas
* `@storybook/addon-a11y` panel uses (see `.storybook/preview.tsx`)
* but in a real headless Chromium where `color-contrast` actually
* resolves CSS — failures here are real WCAG-2.2-AA regressions and
* MUST be fixed (or explicitly opted-out via `parameters.a11y.disable
* = true` with a justification comment in the story).
*
* The `getStoryContext` / `injectAxe` / `checkA11y` triple is the
* documented integration recipe; we override the axe-context to the
* Storybook root so out-of-frame chrome (toolbar etc.) is ignored.
*/
import type { TestRunnerConfig } from "@storybook/test-runner";
import { getStoryContext } from "@storybook/test-runner";
import { checkA11y, configureAxe, injectAxe } from "axe-playwright";
const config: TestRunnerConfig = {
async preVisit(page) {
await injectAxe(page);
},
async postVisit(page, context) {
const storyContext = await getStoryContext(page, context);
const a11yParameter = (storyContext.parameters as {
a11y?: { disable?: boolean; config?: unknown; options?: unknown };
}).a11y;
if (a11yParameter?.disable) {
return;
}
if (a11yParameter?.config || a11yParameter?.options) {
await configureAxe(page, {
rules: ((a11yParameter.config as { rules?: unknown[] } | undefined)?.rules ?? []) as never[],
});
}
await checkA11y(page, "#storybook-root", {
detailedReport: true,
detailedReportOptions: { html: true },
axeOptions: a11yParameter?.options as Parameters<typeof checkA11y>[2] extends infer T
? T extends { axeOptions?: infer A }
? A
: undefined
: undefined,
});
},
};
export default config;
+35
View File
@@ -0,0 +1,35 @@
# `@toolctrl/storybook`
Aggregated Storybook for the boilerplate UI packages (`@toolctrl/ui`,
`@toolctrl/ui-app`, `@toolctrl/ui-subframe`, `@toolctrl/ui-mock`).
## Run locally
```bash
pnpm install
pnpm --filter @toolctrl/storybook storybook
# -> http://localhost:6006
```
## Build static site
```bash
pnpm --filter @toolctrl/storybook build-storybook
# -> apps/storybook/storybook-static
```
## Where do stories live?
Stories are **co-located** in each UI package:
```
packages/ui/src/stories/*.stories.tsx
packages/ui-app/src/stories/*.stories.tsx
packages/ui-subframe/src/stories/*.stories.tsx
packages/ui-mock/src/stories/*.stories.tsx
```
`apps/storybook/.storybook/main.ts` aggregates them via globs — adding a new
story file is enough, no manual registration.
See `docs/architecture/storybook.md` for the full guide.
@@ -0,0 +1,50 @@
/**
* Lost-Pixel visual-regression config (Phase 08 #62).
*
* Lost-Pixel walks the built static Storybook, screenshots every story,
* and diffs each shot against a committed baseline under
* `.lostpixel/baseline/`. A pixel-diff above `threshold` fails CI and
* uploads the diff image as an artifact.
*
* NOT enabled in CI yet — the `visual-regression` job in
* `.github/workflows/storybook.yml` / `.gitea/workflows/storybook.yml`
* is gated on the baseline directory being populated. An operator runs
* `pnpm --filter @toolctrl/storybook visual-regression:update` once
* against a known-good build and commits the generated baseline PNGs;
* from then on the job blocks PRs on unintended visual drift.
*
* See docs/architecture/storybook.md § Visual-regression for the
* bootstrap runbook.
*/
import type { CustomProjectConfig } from "lost-pixel";
export const config: CustomProjectConfig = {
// Point at the static build produced by `build-storybook`. Lost-Pixel
// serves it itself, so this is a path, not a URL.
storybookShots: {
storybookUrl: "./storybook-static",
},
// Baseline PNGs live in-repo so a diff is reviewable in the PR.
imagePathBaseline: "./.lostpixel/baseline",
imagePathCurrent: "./.lostpixel/current",
imagePathDifference: "./.lostpixel/difference",
// 0.1 % pixel-diff tolerance — absorbs sub-pixel font AA jitter
// between CI runners without masking real layout regressions.
threshold: 0.001,
// Lower than the default so CI doesn't stall on a cold cache; the
// story set is small (~21 stories).
waitBeforeScreenshot: 500,
// Generate the comparison even when there is no baseline yet so the
// first operator run produces a full baseline set.
generateOnly: false,
// CI integration is opt-in; left unset so a local run never tries to
// post to an external service.
// apiKey / setPendingStatusCheck deliberately omitted.
};
export default config;
@@ -0,0 +1,50 @@
{
"name": "@toolctrl/storybook",
"version": "0.0.0",
"private": true,
"type": "module",
"scripts": {
"storybook": "storybook dev -p 6006 --no-open",
"build-storybook": "storybook build -o storybook-static",
"test:storybook": "test-storybook --config-dir .storybook --url ${TARGET_URL:-http://127.0.0.1:6006}",
"visual-regression": "lost-pixel",
"visual-regression:update": "lost-pixel update",
"typecheck": "tsc -p tsconfig.json --noEmit"
},
"dependencies": {
"@radix-ui/react-avatar": "^1.1.11",
"@radix-ui/react-slot": "^1.2.4",
"@toolctrl/i18n": "workspace:*",
"class-variance-authority": "^0.7.1",
"clsx": "^2.1.1",
"tailwind-merge": "^3.5.0"
},
"devDependencies": {
"@storybook/addon-a11y": "^8.6.14",
"@storybook/addon-essentials": "^8.6.14",
"@storybook/addon-interactions": "^8.6.14",
"@storybook/addon-themes": "^8.6.14",
"@storybook/blocks": "^8.6.14",
"@storybook/react": "^8.6.14",
"@storybook/react-vite": "^8.6.14",
"@storybook/test": "^8.6.14",
"@storybook/test-runner": "^0.22.1",
"@tailwindcss/vite": "4.2.4",
"@types/react": "^19.0.8",
"@types/react-dom": "^19.0.0",
"axe-playwright": "^2.1.0",
"http-server": "^14.1.1",
"i18next": "^23.16.3",
"lost-pixel": "^3.22.0",
"react-i18next": "^15.7.4",
"storybook": "^8.6.14",
"tailwindcss": "^4.1.12",
"typescript": "^5.3.2",
"vite": "7.3.0",
"wait-on": "^9.0.0"
},
"peerDependencies": {
"react": "19.2.3",
"react-dom": "19.2.3"
}
}
@@ -0,0 +1,32 @@
import { Meta } from "@storybook/blocks";
<Meta title="welcome/introduction" />
# Toolctrl UI — Storybook
This Storybook aggregates components from the four UI packages of the
boilerplate:
| Package | Layer | Notes |
| --- | --- | --- |
| `@toolctrl/ui` | base primitives | shadcn / radix wrappers |
| `@toolctrl/ui-app` | composites | tenant-app shell pieces |
| `@toolctrl/ui-subframe` | designer output | Subframe-generated components |
| `@toolctrl/ui-mock` | fixtures | mock pages + sample data for hot-swap drills |
Use the sidebar to browse component stories. Each story exposes its props as
Controls and runs an **a11y check** via `@storybook/addon-a11y`.
## Conventions
- **CSF-3** — every story file exports a default `Meta` plus named story
objects.
- **Co-located** — stories live next to the source in
`packages/<pkg>/src/stories/`.
- **Pure renders** — stories should not depend on the running web app; pull
fixtures from `@toolctrl/ui-mock` when needed.
- **A11y** — violations fail the story; opt-out with
`parameters: { a11y: { disable: true } }` plus a code comment explaining
why.
See `docs/architecture/storybook.md` for the full author guide.
@@ -0,0 +1,44 @@
import { Meta } from "@storybook/blocks";
<Meta title="welcome/theme-guide" />
# Theme Guide
The Storybook preview ships a minimal token surface in
`apps/storybook/.storybook/preview.css` so stories can render with theme
parity to the web app without compiling Tailwind v4 at story-build time.
## Available CSS variables
| Token | Light | Dark |
| --- | --- | --- |
| `--color-bg` | `#ffffff` | `#0b0b0c` |
| `--color-fg` | `#0f172a` | `#f8fafc` |
| `--color-muted` | `#64748b` | `#94a3b8` |
| `--color-border` | `#e2e8f0` | `#1f2937` |
| `--color-primary` | `#2563eb` | `#60a5fa` |
| `--color-primary-foreground` | `#ffffff` | `#0b0b0c` |
| `--color-destructive` | `#dc2626` | `#f87171` |
| `--color-destructive-foreground` | `#ffffff` | `#0b0b0c` |
| `--color-accent` | `#f1f5f9` | `#1e293b` |
| `--color-accent-foreground` | `#0f172a` | `#f8fafc` |
| `--color-card` | `#ffffff` | `#111827` |
| `--color-card-foreground` | `#0f172a` | `#f8fafc` |
| `--color-success` | `#16a34a` | `#16a34a` |
| `--color-warning` | `#d97706` | `#d97706` |
## Light / Dark toggle
The toolbar exposes a theme switcher (powered by
`@storybook/addon-themes`) that toggles the `dark` class on the preview
root. Stories using the variables above flip automatically.
## Roadmap
- Wire the real `apps/web/app/globals.css` (Tailwind v4) into the preview
once the v4 + Storybook 8 builder integration is verified for our React
Router runtime.
- Add brand-tenant toolbar globals so stories can preview against the
`packages/brand/themes/` palettes.
See `docs/architecture/storybook.md` for the author guide.
@@ -0,0 +1,19 @@
{
"compilerOptions": {
"target": "ESNext",
"module": "ESNext",
"moduleResolution": "Bundler",
"lib": ["DOM", "DOM.Iterable", "ES2022"],
"jsx": "react-jsx",
"strict": true,
"skipLibCheck": true,
"isolatedModules": true,
"esModuleInterop": true,
"resolveJsonModule": true,
"allowImportingTsExtensions": false,
"noEmit": true,
"types": ["vite/client"],
"baseUrl": "."
},
"include": [".storybook/**/*.ts", ".storybook/**/*.tsx", "src/**/*.ts", "src/**/*.tsx", "src/**/*.mdx", "lostpixel.config.ts"]
}