refactor: establish local frontend workspace boundaries

OpenSpec change: evolve-frontend-stack

packages/ui/package.json

@@ -0,0 +1,44 @@
+{
+	"name": "@wealthledger/ui",
+	"version": "0.3.0",
+	"private": true,
+	"type": "module",
+	"files": [
+		"dist"
+	],
+	"exports": {
+		".": {
+			"types": "./dist/index.d.ts",
+			"import": "./dist/index.js"
+		},
+		"./theme": {
+			"types": "./dist/theme.d.ts",
+			"import": "./dist/theme.js"
+		},
+		"./styles.css": "./dist/styles.css"
+	},
+	"sideEffects": [
+		"**/*.css"
+	],
+	"scripts": {
+		"build": "vite build && tsc -p tsconfig.json"
+	},
+	"dependencies": {
+		"@wealthledger/tokens": "0.3.0"
+	},
+	"peerDependencies": {
+		"@mantine/core": "9.6.1",
+		"@mantine/hooks": "9.6.1",
+		"react": "19.3.0",
+		"react-dom": "19.3.0"
+	},
+	"devDependencies": {
+		"@storybook/react-vite": "10.6.0",
+		"@testing-library/react": "16.3.3",
+		"@types/react": "19.3.0",
+		"storybook": "10.6.0",
+		"typescript": "5.9.3",
+		"vite": "8.3.0",
+		"vitest": "5.0.0"
+	}
+}

packages/ui/src/EntryCard.module.css

@@ -0,0 +1,95 @@
+.row {
+	display: grid;
+	grid-template-columns: auto minmax(0, 1fr) auto;
+	gap: var(--mantine-spacing-sm);
+	align-items: center;
+	padding: var(--mantine-spacing-md);
+	border-color: var(--wl-color-border);
+	background: var(--wl-color-subtle);
+}
+
+.identity,
+.value {
+	min-width: 0;
+}
+
+.value {
+	text-align: right;
+	white-space: nowrap;
+}
+
+.positive {
+	color: var(--wl-color-positive);
+}
+
+.negative {
+	color: var(--wl-color-negative);
+}
+
+.neutral {
+	color: var(--mantine-color-gray-7);
+}
+
+@media (max-width: 36em) {
+	.row {
+		grid-template-columns: auto minmax(0, 1fr);
+	}
+
+	.value {
+		grid-column: 2;
+		text-align: left;
+	}
+}
+
+.valueFooter {
+	display: grid;
+	align-items: center;
+	justify-items: end;
+	min-height: 28px;
+}
+.valueLabel,
+.actions {
+	grid-area: 1 / 1;
+	transition: opacity 180ms ease;
+}
+.valueLabel {
+	opacity: 0;
+}
+.actions {
+	display: flex;
+}
+@media (hover: hover) and (pointer: fine) {
+	.valueLabel {
+		opacity: 1;
+	}
+	.actions {
+		opacity: 0;
+		pointer-events: none;
+	}
+	.row:hover .actions,
+	.row:focus-within .actions {
+		opacity: 1;
+		pointer-events: auto;
+	}
+	.row:hover .valueLabel,
+	.row:focus-within .valueLabel {
+		opacity: 0;
+	}
+}
+@media (max-width: 36em) {
+	.valueFooter {
+		justify-items: start;
+	}
+}
+@media (pointer: coarse) {
+	.actions button {
+		min-width: 36px;
+		min-height: 36px;
+	}
+}
+@media (prefers-reduced-motion: reduce) {
+	.valueLabel,
+	.actions {
+		transition: none;
+	}
+}

packages/ui/src/EntryCard.stories.tsx

@@ -0,0 +1,37 @@
+import { Button } from "@mantine/core";
+import type { Meta, StoryObj } from "@storybook/react-vite";
+import { fn } from "storybook/test";
+import { EntryCard } from "./EntryCard";
+
+const meta = {
+	title: "Design System/Components/EntryCard",
+	component: EntryCard,
+	tags: ["autodocs"],
+	args: {
+		title:
+			"Учебная запись с очень длинным названием для проверки узкого экрана",
+		metadata: "22.09.2026 · Синтетические данные",
+		initial: "У",
+		imageSrc: "data:image/png;base64,invalid",
+		value: "−1 250,00 ₽",
+		valueLabel: "Тестовое значение",
+		tone: "negative",
+		actions: (
+			<Button size="compact-sm" onClick={fn()}>
+				Открыть пример
+			</Button>
+		),
+	},
+	parameters: {
+		docs: {
+			description: {
+				component:
+					"Готовые строки и slots без финансовых вычислений. Невалидное локальное изображение показывает fallback; действие доступно с клавиатуры и на узком экране. Данные вымышлены.",
+			},
+		},
+	},
+} satisfies Meta<typeof EntryCard>;
+
+export default meta;
+type Story = StoryObj<typeof meta>;
+export const LongContentAndFallback: Story = {};

packages/ui/src/EntryCard.test.tsx

@@ -0,0 +1,35 @@
+import { MantineProvider } from "@mantine/core";
+import { fireEvent, render, screen } from "@testing-library/react";
+import { assert, describe, expect, it } from "vitest";
+import { EntryCard } from "./EntryCard";
+
+describe("EntryCard", () => {
+	it("keeps the fallback after an image fails", () => {
+		const props = {
+			title: "Пример",
+			metadata: "Описание",
+			initial: "У",
+			value: "—",
+			valueLabel: "Неизвестно",
+			tone: "neutral" as const,
+			imageSrc: "data:image/png;base64,invalid",
+		};
+		const { container, rerender } = render(
+			<MantineProvider>
+				<EntryCard {...props} />
+			</MantineProvider>,
+		);
+		// Decorative image has no accessible name; trigger its actual failure event.
+		const image = container.querySelector("img");
+		assert(image);
+		fireEvent.error(image);
+		rerender(
+			<MantineProvider>
+				<EntryCard {...props} title="Обновлённый пример" />
+			</MantineProvider>,
+		);
+		expect(container.querySelector("img")).toBeNull();
+		expect(screen.getByText("У")).toBeInTheDocument();
+		expect(screen.getByText("Обновлённый пример")).toBeInTheDocument();
+	});
+});

packages/ui/src/EntryCard.tsx

@@ -0,0 +1,72 @@
+import { Avatar, Paper, Stack, Text } from "@mantine/core";
+import { type FC, type ReactNode, useState } from "react";
+import classes from "./EntryCard.module.css";
+
+type EntryCardProps = {
+	title: string;
+	metadata: string;
+	details?: ReactNode;
+	actions?: ReactNode;
+	initial: string;
+	icon?: ReactNode;
+	color?: string;
+	imageSrc?: string | null;
+	value: string;
+	valueLabel: string;
+	tone: "positive" | "negative" | "neutral";
+};
+
+const EntryCard: FC<EntryCardProps> = (props) => {
+	const [imageFailed, setImageFailed] = useState(false);
+	return (
+		<Paper
+			className={classes.row}
+			withBorder
+			style={
+				props.color
+					? {
+							background: `color-mix(in srgb, var(--mantine-color-${props.color}-0) 45%, var(--wl-color-surface))`,
+						}
+					: undefined
+			}
+		>
+			<Avatar
+				alt=""
+				aria-hidden="true"
+				radius="md"
+				size={40}
+				src={imageFailed ? null : props.imageSrc}
+				onError={() => setImageFailed(true)}
+			>
+				{props.icon ?? props.initial}
+			</Avatar>
+			<Stack className={classes.identity} gap={2}>
+				<Text fw={700} lineClamp={1}>
+					{props.title}
+				</Text>
+				<Text c="dimmed" size="sm">
+					{props.metadata}
+				</Text>
+				{props.details}
+			</Stack>
+			<Stack className={classes.value} gap={2}>
+				<Text className={classes[props.tone]} fw={700}>
+					{props.value}
+				</Text>
+				<div className={props.actions ? classes.valueFooter : undefined}>
+					<Text
+						className={`${classes[props.tone]} ${props.actions ? classes.valueLabel : ""}`}
+						size="sm"
+					>
+						{props.valueLabel}
+					</Text>
+					{props.actions && (
+						<div className={classes.actions}>{props.actions}</div>
+					)}
+				</div>
+			</Stack>
+		</Paper>
+	);
+};
+
+export { EntryCard };

packages/ui/src/LoadingSkeleton.stories.tsx

@@ -0,0 +1,35 @@
+import { Paper, Skeleton } from "@mantine/core";
+import type { Meta, StoryObj } from "@storybook/react-vite";
+import { LoadingSkeleton } from "./LoadingSkeleton";
+
+const meta = {
+	title: "Design System/Components/LoadingSkeleton",
+	component: LoadingSkeleton,
+	tags: ["autodocs"],
+	args: { label: "Загрузка содержимого" },
+	argTypes: {
+		label: { control: "text" },
+		children: { table: { disable: true } },
+	},
+	parameters: {
+		docs: {
+			description: {
+				component:
+					"Общая status/busy область для initial или partial loading. Передайте доступную метку и только декоративные Skeleton shapes без интерактивных элементов. Геометрию определяет владелец section/page (см. Product/AccountPageLoading). При refetch сохраняйте уже видимые данные; для действия используйте Button loading. Этот пример не запускает запрос и не демонстрирует query lifecycle.",
+			},
+		},
+	},
+	render: (args) => (
+		<Paper p="md" withBorder>
+			<LoadingSkeleton {...args}>
+				<Skeleton h={24} w="60%" />
+				<Skeleton h={72} />
+				<Skeleton h={16} w="80%" />
+			</LoadingSkeleton>
+		</Paper>
+	),
+} satisfies Meta<typeof LoadingSkeleton>;
+
+export default meta;
+type Story = StoryObj<typeof meta>;
+export const Initial: Story = { name: "Загрузка области" };

packages/ui/src/LoadingSkeleton.tsx

@@ -0,0 +1,18 @@
+import { Stack } from "@mantine/core";
+import type { FC, PropsWithChildren } from "react";
+
+type LoadingSkeletonProps = PropsWithChildren<{
+	label: string;
+}>;
+
+const LoadingSkeleton: FC<LoadingSkeletonProps> = (props) => {
+	const { children, label } = props;
+
+	return (
+		<Stack aria-busy="true" aria-label={label} gap="md" role="status">
+			{children}
+		</Stack>
+	);
+};
+
+export { LoadingSkeleton };

packages/ui/src/StateView.stories.tsx

@@ -0,0 +1,78 @@
+import { Button } from "@mantine/core";
+import type { Meta, StoryObj } from "@storybook/react-vite";
+import type { ComponentProps } from "react";
+import { fn } from "storybook/test";
+import { StateView } from "./StateView";
+
+type StateStoryArgs = ComponentProps<typeof StateView> & {
+	withAction: boolean;
+	onAction: () => void;
+};
+
+const meta = {
+	title: "Design System/Components/StateView",
+	component: StateView,
+	tags: ["autodocs"],
+	args: {
+		title: "Нет учебных данных",
+		text: "Синтетическое пустое состояние. Пользовательские данные не загружаются.",
+		error: false,
+		withAction: false,
+		onAction: fn(),
+	},
+	argTypes: {
+		title: { control: "text" },
+		text: { control: "text" },
+		error: { control: "boolean" },
+		action: { table: { disable: true } },
+		withAction: {
+			control: "boolean",
+			description: "Показать необязательное действие StateView",
+		},
+		onAction: { control: false },
+	},
+	parameters: {
+		docs: {
+			description: {
+				component:
+					"Общее empty/error состояние WealthLedger с необязательным действием. Error сохраняет alert semantics. Для initial loading используйте skeleton страницы, для refetch — локальное предупреждение рядом с сохранёнными данными. Кнопка вызывает только Actions; API recovery и полный пользовательский сценарий здесь не проверяются.",
+			},
+		},
+	},
+	render: (args) => {
+		const { withAction, onAction, ...stateProps } = args;
+		return (
+			<StateView
+				{...stateProps}
+				action={
+					withAction ? (
+						<Button onClick={onAction} variant="default">
+							{args.error ? "Повторить локально" : "Выполнить пример"}
+						</Button>
+					) : undefined
+				}
+			/>
+		);
+	},
+} satisfies Meta<StateStoryArgs>;
+
+export default meta;
+
+type Story = StoryObj<typeof meta>;
+export const Empty: Story = { name: "Пустое состояние" };
+export const EmptyWithAction: Story = {
+	name: "Пустое состояние с действием",
+	args: { withAction: true },
+};
+export const Failed: Story = {
+	name: "Ошибка",
+	args: {
+		error: true,
+		title: "Учебная ошибка",
+		text: "Демонстрация недоступных данных без вызова API.",
+	},
+};
+export const ErrorWithAction: Story = {
+	name: "Ошибка с retry",
+	args: { ...Failed.args, withAction: true },
+};

packages/ui/src/StateView.test.tsx

@@ -0,0 +1,37 @@
+import { MantineProvider } from "@mantine/core";
+import { render, screen } from "@testing-library/react";
+import { describe, expect, it } from "vitest";
+import { LoadingSkeleton } from "./LoadingSkeleton";
+import { StateView } from "./StateView";
+
+describe("StateView", () => {
+	it("renders an accessible structural loading region", () => {
+		render(
+			<MantineProvider>
+				<LoadingSkeleton label="Загрузка">
+					<div />
+				</LoadingSkeleton>
+			</MantineProvider>,
+		);
+
+		expect(screen.getByRole("status", { name: "Загрузка" })).toHaveAttribute(
+			"aria-busy",
+			"true",
+		);
+	});
+
+	it("renders an accessible error state", () => {
+		render(
+			<MantineProvider>
+				<StateView
+					error
+					text="Попробуйте обновить страницу позже."
+					title="Что-то пошло не так"
+				/>
+				,
+			</MantineProvider>,
+		);
+
+		expect(screen.getByRole("alert")).toHaveTextContent("Что-то пошло не так");
+	});
+});

packages/ui/src/StateView.tsx

@@ -0,0 +1,26 @@
+import { Paper, Stack, Text, Title } from "@mantine/core";
+import type { FC, ReactNode } from "react";
+
+type StateViewProps = {
+	title: string;
+	text: string;
+	action?: ReactNode;
+	error?: boolean;
+};
+
+const StateView: FC<StateViewProps> = (props) => {
+	const { title, text, action, error = false } = props;
+	const role = error ? "alert" : undefined;
+
+	return (
+		<Paper p="xl" radius="md" shadow="xs" withBorder role={role}>
+			<Stack align="flex-start" gap="sm">
+				<Title order={2}>{title}</Title>
+				<Text c="dimmed">{text}</Text>
+				{action}
+			</Stack>
+		</Paper>
+	);
+};
+
+export { StateView };

packages/ui/src/index.ts

@@ -0,0 +1,3 @@
+export { EntryCard } from "./EntryCard";
+export { LoadingSkeleton } from "./LoadingSkeleton";
+export { StateView } from "./StateView";

packages/ui/src/styles.css

@@ -0,0 +1,39 @@
+* {
+	box-sizing: border-box;
+}
+body {
+	margin: 0;
+	background: var(--wl-color-canvas);
+	color: var(--wl-color-text);
+}
+a {
+	color: inherit;
+	text-decoration: none;
+}
+
+@media (prefers-reduced-motion: no-preference) {
+	.mantine-Modal-content {
+		animation: modal-appear 220ms ease-out;
+	}
+
+	.mantine-Modal-overlay {
+		animation: modal-backdrop-appear 220ms ease-out;
+	}
+}
+
+@keyframes modal-appear {
+	from {
+		opacity: 0;
+		transform: translateY(8px) scale(0.98);
+	}
+	to {
+		opacity: 1;
+		transform: translateY(0) scale(1);
+	}
+}
+
+@keyframes modal-backdrop-appear {
+	from {
+		opacity: 0;
+	}
+}

packages/ui/src/theme.test.ts

@@ -0,0 +1,29 @@
+import { DEFAULT_THEME, mergeMantineTheme } from "@mantine/core";
+import source from "@wealthledger/tokens/tokens.json";
+import { describe, expect, it } from "vitest";
+import { colorRoles, cssVariablesResolver, theme } from "./theme";
+
+describe("design theme adapter", () => {
+	it("preserves scale-aware sizes, unscaled breakpoints and shadow layers", () => {
+		expect(theme.spacing?.md).toBe("calc(1rem * var(--mantine-scale))");
+		expect(theme.fontSizes?.sm).toBe("calc(0.875rem * var(--mantine-scale))");
+		expect(theme.breakpoints?.sm).toBe("48em");
+		expect(theme.shadows?.sm).toContain(
+			"calc(-0.3125rem * var(--mantine-scale))",
+		);
+		expect(theme.shadows?.sm).toContain("rgba(0, 0, 0, 0.04)");
+	});
+
+	it("keeps default-shade roles attached to native filled variables", () => {
+		const resolved = mergeMantineTheme(DEFAULT_THEME, theme);
+		const variables = cssVariablesResolver(resolved).variables;
+		expect(colorRoles.primary).toBe("blue");
+		expect(variables["--wl-color-primary"]).toBe(
+			"var(--mantine-color-blue-filled)",
+		);
+		expect(variables["--wl-color-canvas"]).toBe("var(--mantine-color-gray-2)");
+		expect(Object.keys(variables)).toHaveLength(
+			Object.keys(source.color.roles).length,
+		);
+	});
+});

packages/ui/src/theme.ts

@@ -0,0 +1,86 @@
+import "./styles.css";
+import {
+	type CSSVariablesResolver,
+	colorsTuple,
+	createTheme,
+	getThemeColor,
+	type MantinePrimaryShade,
+	Modal,
+	rem,
+	rgba,
+} from "@mantine/core";
+import designTokens from "@wealthledger/tokens/tokens.json";
+
+const { color, typography, spacing, radius, shadows, breakpoints } =
+	designTokens;
+const mapValues = <T, U>(values: Record<string, T>, convert: (value: T) => U) =>
+	Object.fromEntries(
+		Object.entries(values).map(([name, value]) => [name, convert(value)]),
+	);
+
+const colorRoles = mapValues(color.roles, (role) =>
+	role.shade === null ? role.color : `${role.color}.${role.shade}`,
+);
+
+const theme = createTheme({
+	respectReducedMotion: true,
+	components: {
+		Modal: Modal.extend({
+			defaultProps: {
+				overlayProps: { blur: 3 },
+				transitionProps: {
+					transition: "fade-down",
+					duration: 220,
+					exitDuration: 180,
+					timingFunction: "ease-out",
+				},
+			},
+		}),
+	},
+	primaryColor: color.roles.primary.color,
+	primaryShade: color.primaryShade as MantinePrimaryShade,
+	defaultRadius: radius.default,
+	white: color.base.white,
+	black: color.base.black,
+	colors: mapValues(color.palettes, colorsTuple),
+	fontFamily: typography.fontFamily,
+	fontFamilyMonospace: typography.fontFamilyMonospace,
+	fontSizes: mapValues(typography.fontSizes, (value) => rem(value)),
+	fontWeights: mapValues(typography.fontWeights, String),
+	lineHeights: mapValues(typography.lineHeights, String),
+	headings: {
+		fontFamily: typography.fontFamily,
+		fontWeight: String(typography.fontWeights.bold),
+		sizes: mapValues(typography.headings, (value) => ({
+			fontSize: rem(value.fontSize),
+			lineHeight: String(value.lineHeight),
+		})),
+	},
+	spacing: mapValues(spacing.values, (value) => rem(value)),
+	radius: mapValues(radius.values, (value) => rem(value)),
+	shadows: mapValues(shadows.values, (layers) =>
+		layers
+			.map(
+				(layer) =>
+					`${rem(layer.offsetX)} ${rem(layer.offsetY)} ${rem(layer.blur)} ${rem(layer.spread)} ${rgba(color.base[layer.color as keyof typeof color.base], layer.opacity)}`,
+			)
+			.join(", "),
+	),
+	breakpoints: mapValues(
+		breakpoints.values,
+		(value) => `${value}${breakpoints.unit}`,
+	),
+});
+
+const cssVariablesResolver: CSSVariablesResolver = (resolvedTheme) => ({
+	variables: Object.fromEntries(
+		Object.entries(colorRoles).map(([role, reference]) => [
+			`--wl-color-${role}`,
+			getThemeColor(reference, resolvedTheme),
+		]),
+	),
+	light: {},
+	dark: {},
+});
+
+export { colorRoles, cssVariablesResolver, designTokens, theme };

packages/ui/tsconfig.json

@@ -0,0 +1,19 @@
+{
+	"compilerOptions": {
+		"target": "ES2023",
+		"lib": ["ES2023", "DOM"],
+		"module": "ESNext",
+		"moduleResolution": "Bundler",
+		"resolveJsonModule": true,
+		"strict": true,
+		"skipLibCheck": true,
+		"verbatimModuleSyntax": true,
+		"declaration": true,
+		"emitDeclarationOnly": true,
+		"rootDir": "src",
+		"outDir": "dist",
+		"jsx": "react-jsx",
+		"types": ["vite/client"]
+	},
+	"include": ["src/index.ts", "src/theme.ts"]
+}

packages/ui/vite.config.ts

@@ -0,0 +1,14 @@
+import { defineConfig } from "vite";
+
+export default defineConfig({
+	build: {
+		lib: {
+			entry: { index: "src/index.ts", theme: "src/theme.ts" },
+			formats: ["es"],
+			cssFileName: "styles",
+		},
+		rolldownOptions: {
+			external: /^(react(?:-dom)?|@mantine\/[^/]+|@wealthledger\/tokens)(\/|$)/,
+		},
+	},
+});