;
+
+export const Body: Story = {
+ args: {
+ children:
+ 'Акции Московской биржи выросли на 2.3% по итогам торговой сессии. Индекс Мосбиржи обновил исторический максимум, достигнув отметки 4500 пунктов.',
+ },
+};
+
+export const Caption: Story = {
+ args: {
+ variant: 'caption',
+ children: 'Данные предоставлены Московской биржей. Цены указаны в рублях.',
+ },
+};
+
+export const Label: Story = {
+ args: {
+ variant: 'label',
+ children: 'Объём торгов',
+ },
+};
+
+export const Numeric: Story = {
+ args: {
+ variant: 'numeric',
+ children: '1 234 567.89 ₽',
+ },
+};
+
+export const PositiveTone: Story = {
+ args: {
+ tone: 'positive',
+ children: '+5.23%',
+ },
+};
+
+export const NegativeTone: Story = {
+ args: {
+ tone: 'negative',
+ children: '-2.15%',
+ },
+};
+
+export const SecondaryTone: Story = {
+ args: {
+ tone: 'secondary',
+ children: 'Дополнительная информация о ценной бумаге',
+ },
+};
+
+export const MutedTone: Story = {
+ args: {
+ tone: 'muted',
+ children: 'Обновлено 5 минут назад',
+ },
+};
+
+export const AllVariants: Story = {
+ render: () => (
+
+ Body: основной текст страницы
+ Caption: вспомогательный текст
+ Label: подпись к полю или метрике
+ Numeric: 1 234.56
+
+ ),
+};
+
+export const AllTones: Story = {
+ render: () => (
+
+ Default — основной текст
+ Secondary — второстепенный текст
+ Positive — рост, прибыль
+ Negative — падение, убыток
+ Muted — неактивный, подсказка
+
+ ),
+};
diff --git a/packages/design-system/src/components/Text/Text.test.tsx b/packages/design-system/src/components/Text/Text.test.tsx
new file mode 100644
index 0000000..5951612
--- /dev/null
+++ b/packages/design-system/src/components/Text/Text.test.tsx
@@ -0,0 +1,53 @@
+import { describe, it, expect } from 'vitest';
+import { render, screen } from '@testing-library/react';
+import { Text } from './Text';
+import { MoexVibeThemeProvider } from '../../theme';
+
+function renderWithTheme(element: React.ReactElement) {
+ return render({element});
+}
+
+describe('Text', () => {
+ it('renders children', () => {
+ renderWithTheme(Hello);
+ expect(screen.getByText('Hello')).toBeInTheDocument();
+ });
+
+ it('renders with body variant by default', () => {
+ renderWithTheme(Body);
+ const el = screen.getByText('Body');
+ expect(el.tagName).toBe('P');
+ });
+
+ it('renders caption variant as MUI caption', () => {
+ renderWithTheme(Caption);
+ const el = screen.getByText('Caption');
+ expect(el.classList.contains('MuiTypography-caption')).toBe(true);
+ });
+
+ it('renders label variant', () => {
+ renderWithTheme(Label);
+ expect(screen.getByText('Label')).toBeInTheDocument();
+ });
+
+ it('renders numeric variant', () => {
+ renderWithTheme(123);
+ expect(screen.getByText('123')).toBeInTheDocument();
+ });
+
+ it('applies default tone by default', () => {
+ renderWithTheme(Default);
+ const el = screen.getByText('Default');
+ expect(el.classList.contains('MuiTypography-body1')).toBe(true);
+ });
+
+ it('accepts className and style props', () => {
+ renderWithTheme(
+
+ Hello
+ ,
+ );
+ const el = screen.getByText('Hello');
+ expect(el.classList.contains('custom')).toBe(true);
+ });
+});
diff --git a/packages/design-system/src/components/Text/Text.tsx b/packages/design-system/src/components/Text/Text.tsx
new file mode 100644
index 0000000..ded9fee
--- /dev/null
+++ b/packages/design-system/src/components/Text/Text.tsx
@@ -0,0 +1,35 @@
+import { Typography, type TypographyProps } from '@mui/material';
+import type { ReactNode } from 'react';
+
+type Tone = 'default' | 'secondary' | 'positive' | 'negative' | 'muted';
+
+type TextVariant = 'body' | 'caption' | 'label' | 'numeric';
+
+export interface TextProps extends Omit {
+ variant?: TextVariant;
+ tone?: Tone;
+ children: ReactNode;
+}
+
+const VARIANT_MAP: Record = {
+ body: 'body1',
+ caption: 'caption',
+ label: 'subtitle2',
+ numeric: 'body1',
+};
+
+const TONE_MAP: Record = {
+ default: 'text.primary',
+ secondary: 'text.secondary',
+ positive: 'success.main',
+ negative: 'error.main',
+ muted: 'text.disabled',
+};
+
+export function Text({ variant = 'body', tone = 'default', children, ...props }: TextProps) {
+ return (
+
+ {children}
+
+ );
+}
diff --git a/packages/design-system/src/components/Text/index.ts b/packages/design-system/src/components/Text/index.ts
new file mode 100644
index 0000000..3e79f02
--- /dev/null
+++ b/packages/design-system/src/components/Text/index.ts
@@ -0,0 +1,2 @@
+export { Text } from './Text';
+export type { TextProps } from './Text';
diff --git a/packages/design-system/src/components/TextField/TextField.stories.tsx b/packages/design-system/src/components/TextField/TextField.stories.tsx
new file mode 100644
index 0000000..a44e40e
--- /dev/null
+++ b/packages/design-system/src/components/TextField/TextField.stories.tsx
@@ -0,0 +1,56 @@
+import type { Meta, StoryObj } from '@storybook/react';
+import { TextField } from './TextField';
+
+const meta: Meta = {
+ title: 'Inputs/TextField',
+ component: TextField,
+ argTypes: {
+ label: { control: 'text' },
+ helperText: { control: 'text' },
+ error: { control: 'boolean' },
+ disabled: { control: 'boolean' },
+ },
+};
+
+export default meta;
+type Story = StoryObj;
+
+export const Default: Story = {
+ args: {
+ label: 'Название',
+ placeholder: 'Введите название',
+ },
+};
+
+export const WithHelperText: Story = {
+ args: {
+ label: 'Email',
+ helperText: 'Введите ваш email адрес',
+ placeholder: 'user@example.com',
+ },
+};
+
+export const Error: Story = {
+ args: {
+ label: 'Пароль',
+ error: true,
+ helperText: 'Обязательное поле',
+ placeholder: 'Введите пароль',
+ },
+};
+
+export const Disabled: Story = {
+ args: {
+ label: 'Заблокировано',
+ disabled: true,
+ value: 'Недоступно для редактирования',
+ },
+};
+
+export const LongRussianText: Story = {
+ args: {
+ label: 'Описание инвестиционной стратегии',
+ helperText: 'Максимальная длина — 1000 символов',
+ placeholder: 'Опишите вашу инвестиционную стратегию максимально подробно...',
+ },
+};
diff --git a/packages/design-system/src/components/TextField/TextField.test.tsx b/packages/design-system/src/components/TextField/TextField.test.tsx
new file mode 100644
index 0000000..99daeb3
--- /dev/null
+++ b/packages/design-system/src/components/TextField/TextField.test.tsx
@@ -0,0 +1,44 @@
+import { describe, it, expect } from 'vitest';
+import { render, screen } from '@testing-library/react';
+import { TextField } from './TextField';
+import { MoexVibeThemeProvider } from '../../theme';
+
+function renderWithTheme(element: React.ReactElement) {
+ return render({element});
+}
+
+describe('TextField', () => {
+ it('renders label and associates with input', () => {
+ renderWithTheme();
+ const input = screen.getByLabelText('Name');
+ expect(input).toBeInTheDocument();
+ });
+
+ it('renders helper text', () => {
+ renderWithTheme();
+ expect(screen.getByText('Enter your name')).toBeInTheDocument();
+ });
+
+ it('shows error state', () => {
+ renderWithTheme();
+ const input = screen.getByLabelText('Name');
+ expect(input).toHaveAttribute('aria-invalid', 'true');
+ });
+
+ it('renders helper text with error', () => {
+ renderWithTheme();
+ expect(screen.getByText('Required')).toBeInTheDocument();
+ });
+
+ it('does not pass color, variant, size or sx to DOM', () => {
+ renderWithTheme();
+ const input = screen.getByLabelText('Name');
+ expect(input).not.toHaveAttribute('color');
+ });
+
+ it('accepts className and style props', () => {
+ renderWithTheme();
+ const wrapper = screen.getByLabelText('Name').closest('.MuiTextField-root')!;
+ expect(wrapper.classList.contains('custom')).toBe(true);
+ });
+});
diff --git a/packages/design-system/src/components/TextField/TextField.tsx b/packages/design-system/src/components/TextField/TextField.tsx
new file mode 100644
index 0000000..ad07999
--- /dev/null
+++ b/packages/design-system/src/components/TextField/TextField.tsx
@@ -0,0 +1,22 @@
+import { TextField as MuiTextField, type TextFieldProps as MuiTextFieldProps } from '@mui/material';
+
+export interface TextFieldProps extends Omit<
+ MuiTextFieldProps,
+ 'variant' | 'color' | 'size' | 'sx'
+> {
+ label: string;
+ helperText?: string;
+}
+
+export function TextField({ label, helperText, error, ...props }: TextFieldProps) {
+ return (
+
+ );
+}
diff --git a/packages/design-system/src/components/TextField/index.ts b/packages/design-system/src/components/TextField/index.ts
new file mode 100644
index 0000000..132aad0
--- /dev/null
+++ b/packages/design-system/src/components/TextField/index.ts
@@ -0,0 +1,2 @@
+export { TextField } from './TextField';
+export type { TextFieldProps } from './TextField';
diff --git a/packages/design-system/src/components/index.ts b/packages/design-system/src/components/index.ts
new file mode 100644
index 0000000..9f98132
--- /dev/null
+++ b/packages/design-system/src/components/index.ts
@@ -0,0 +1,74 @@
+export { Text } from './Text';
+export type { TextProps } from './Text';
+
+export { Heading } from './Heading';
+export type { HeadingProps } from './Heading';
+
+export { Link } from './Link';
+export type { LinkProps } from './Link';
+
+export { Button } from './Button';
+export type { ButtonProps } from './Button';
+
+export { IconButton } from './IconButton';
+export type { IconButtonProps } from './IconButton';
+
+export { TextField } from './TextField';
+export type { TextFieldProps } from './TextField';
+
+export { Select } from './Select';
+export type { SelectProps, SelectOption } from './Select';
+
+export { Checkbox } from './Checkbox';
+export type { CheckboxProps } from './Checkbox';
+
+export { Surface } from './Surface';
+export type { SurfaceProps } from './Surface';
+
+export { Card } from './Card';
+export type { CardProps } from './Card';
+
+export { Chip } from './Chip';
+export type { ChipProps } from './Chip';
+
+export { Badge } from './Badge';
+export type { BadgeProps } from './Badge';
+
+export { Alert } from './Alert';
+export type { AlertProps } from './Alert';
+
+export { Dialog } from './Dialog';
+export type { DialogProps } from './Dialog';
+
+export { Skeleton } from './Skeleton';
+export type { SkeletonProps } from './Skeleton';
+
+export { Progress } from './Progress';
+export type { ProgressProps } from './Progress';
+
+export { DataTable } from './DataTable';
+export type { DataTableProps, Density } from './DataTable';
+
+export { Metric } from './Metric';
+export type { MetricProps } from './Metric';
+
+export { Money } from './Money';
+export type { MoneyProps } from './Money';
+
+export { PriceChange } from './PriceChange';
+export type { PriceChangeProps } from './PriceChange';
+
+export { FormField } from './FormField';
+export type { FormFieldProps } from './FormField';
+
+export { FilterBar } from './FilterBar';
+export type { FilterBarProps } from './FilterBar';
+
+export { EmptyState } from './EmptyState';
+export type { EmptyStateProps } from './EmptyState';
+
+export { ErrorState } from './ErrorState';
+export type { ErrorStateProps } from './ErrorState';
+
+export { LoadingState } from './LoadingState';
+export type { LoadingStateProps } from './LoadingState';
diff --git a/packages/design-system/src/index.ts b/packages/design-system/src/index.ts
new file mode 100644
index 0000000..07635cb
--- /dev/null
+++ b/packages/design-system/src/index.ts
@@ -0,0 +1 @@
+export * from './components';
diff --git a/packages/design-system/src/test/setup.ts b/packages/design-system/src/test/setup.ts
new file mode 100644
index 0000000..13b015b
--- /dev/null
+++ b/packages/design-system/src/test/setup.ts
@@ -0,0 +1,15 @@
+import '@testing-library/jest-dom';
+
+Object.defineProperty(window, 'matchMedia', {
+ writable: true,
+ value: (query: string) => ({
+ matches: false,
+ media: query,
+ onchange: null,
+ addListener: () => {},
+ removeListener: () => {},
+ addEventListener: () => {},
+ removeEventListener: () => {},
+ dispatchEvent: () => false,
+ }),
+});
diff --git a/packages/design-system/src/theme/MoexVibeThemeProvider.tsx b/packages/design-system/src/theme/MoexVibeThemeProvider.tsx
new file mode 100644
index 0000000..7ec21a0
--- /dev/null
+++ b/packages/design-system/src/theme/MoexVibeThemeProvider.tsx
@@ -0,0 +1,19 @@
+import { type ReactNode } from 'react';
+import { ThemeProvider } from '@mui/material/styles';
+import CssBaseline from '@mui/material/CssBaseline';
+import { createMoexVibeTheme } from './createMoexVibeTheme';
+
+const theme = createMoexVibeTheme();
+
+export interface MoexVibeThemeProviderProps {
+ children: ReactNode;
+}
+
+export function MoexVibeThemeProvider({ children }: MoexVibeThemeProviderProps) {
+ return (
+
+
+ {children}
+
+ );
+}
diff --git a/packages/design-system/src/theme/createMoexVibeTheme.test.ts b/packages/design-system/src/theme/createMoexVibeTheme.test.ts
new file mode 100644
index 0000000..2975a00
--- /dev/null
+++ b/packages/design-system/src/theme/createMoexVibeTheme.test.ts
@@ -0,0 +1,29 @@
+import { describe, it, expect } from 'vitest';
+import { createMoexVibeTheme } from './createMoexVibeTheme';
+
+describe('createMoexVibeTheme', () => {
+ it('sets cssVarPrefix to mv', () => {
+ const theme = createMoexVibeTheme();
+ expect(theme.cssVarPrefix).toBe('mv');
+ });
+
+ it('maps color.action.primary to MUI primary main', () => {
+ const theme = createMoexVibeTheme();
+ expect(theme.colorSchemes.light.palette.primary.main).toBe('#176747');
+ });
+
+ it('uses Inter in typography', () => {
+ const theme = createMoexVibeTheme();
+ expect(theme.typography.body1.fontFamily).toContain('Inter');
+ });
+
+ it('maps radius.md to shape border radius', () => {
+ const theme = createMoexVibeTheme();
+ expect(theme.shape.borderRadius).toBe(8);
+ });
+
+ it('disables elevation on MuiButton by default', () => {
+ const theme = createMoexVibeTheme();
+ expect(theme.components?.MuiButton?.defaultProps).toMatchObject({ disableElevation: true });
+ });
+});
diff --git a/packages/design-system/src/theme/createMoexVibeTheme.ts b/packages/design-system/src/theme/createMoexVibeTheme.ts
new file mode 100644
index 0000000..a341a27
--- /dev/null
+++ b/packages/design-system/src/theme/createMoexVibeTheme.ts
@@ -0,0 +1,55 @@
+import { createTheme } from '@mui/material/styles';
+import { primitiveTokens, semanticLightTokens, componentTokens, resolveToken } from '../tokens';
+
+const allTokens = {
+ ...primitiveTokens,
+ ...semanticLightTokens,
+ ...componentTokens,
+} as const;
+
+function resolveValue(name: string): string | number | readonly number[] | readonly string[] {
+ return resolveToken(allTokens, name).value;
+}
+
+export function createMoexVibeTheme() {
+ return createTheme({
+ cssVariables: { cssVarPrefix: 'mv' },
+ colorSchemes: {
+ light: {
+ palette: {
+ primary: { main: resolveValue('color.action.primary') as string },
+ secondary: { main: resolveValue('color.action.secondary') as string },
+ error: { main: resolveValue('color.feedback.error') as string },
+ warning: { main: resolveValue('color.feedback.warning') as string },
+ info: { main: resolveValue('color.feedback.info') as string },
+ success: { main: resolveValue('color.finance.positive') as string },
+ background: {
+ default: resolveValue('color.canvas') as string,
+ paper: resolveValue('color.surface.default') as string,
+ },
+ text: {
+ primary: resolveValue('color.text.primary') as string,
+ secondary: resolveValue('color.text.secondary') as string,
+ disabled: resolveValue('color.text.disabled') as string,
+ },
+ divider: resolveValue('color.border.default') as string,
+ },
+ },
+ },
+ typography: {
+ fontFamily: (resolveValue('font.family.sans') as readonly string[]).join(', '),
+ body1: { fontFamily: (resolveValue('font.family.body') as readonly string[]).join(', ') },
+ fontWeightRegular: resolveValue('font.weight.regular') as number,
+ fontWeightMedium: resolveValue('font.weight.medium') as number,
+ fontWeightBold: resolveValue('font.weight.bold') as number,
+ },
+ shape: {
+ borderRadius: parseInt(resolveValue('radius.md') as string, 10),
+ },
+ components: {
+ MuiButton: {
+ defaultProps: { disableElevation: true },
+ },
+ },
+ });
+}
diff --git a/packages/design-system/src/theme/index.ts b/packages/design-system/src/theme/index.ts
new file mode 100644
index 0000000..c328165
--- /dev/null
+++ b/packages/design-system/src/theme/index.ts
@@ -0,0 +1,2 @@
+export { createMoexVibeTheme } from './createMoexVibeTheme';
+export { MoexVibeThemeProvider } from './MoexVibeThemeProvider';
diff --git a/packages/design-system/src/theme/mui.d.ts b/packages/design-system/src/theme/mui.d.ts
new file mode 100644
index 0000000..8bd3daf
--- /dev/null
+++ b/packages/design-system/src/theme/mui.d.ts
@@ -0,0 +1,18 @@
+import type {} from '@mui/material/themeCssVarsAugmentation';
+
+declare module '@mui/material/styles' {
+ interface Palette {
+ finance: {
+ positive: string;
+ negative: string;
+ neutral: string;
+ };
+ }
+ interface PaletteOptions {
+ finance?: {
+ positive: string;
+ negative: string;
+ neutral: string;
+ };
+ }
+}
diff --git a/packages/design-system/src/tokens/components.ts b/packages/design-system/src/tokens/components.ts
new file mode 100644
index 0000000..da03e0e
--- /dev/null
+++ b/packages/design-system/src/tokens/components.ts
@@ -0,0 +1,88 @@
+import type { TokenCollection } from './types';
+
+export const componentTokens = {
+ // Button
+ 'button.font.weight': { $type: 'fontWeight' as const, $value: '{font.weight.semibold}' },
+ 'button.radius': { $type: 'dimension' as const, $value: '{radius.md}' },
+ 'button.padding.x': { $type: 'dimension' as const, $value: '{space.inset.lg}' },
+ 'button.padding.y': { $type: 'dimension' as const, $value: '{space.inset.sm}' },
+ 'button.primary.bg': { $type: 'color' as const, $value: '{color.action.primary}' },
+ 'button.primary.text': { $type: 'color' as const, $value: '{color.text.inverse}' },
+ 'button.primary.hover.bg': { $type: 'color' as const, $value: '{color.action.primaryHover}' },
+ 'button.secondary.bg': { $type: 'color' as const, $value: '{color.surface.default}' },
+ 'button.secondary.text': { $type: 'color' as const, $value: '{color.text.primary}' },
+ 'button.secondary.border': { $type: 'color' as const, $value: '{color.border.default}' },
+ 'button.danger.bg': { $type: 'color' as const, $value: '{color.action.danger}' },
+ 'button.danger.text': { $type: 'color' as const, $value: '{color.text.inverse}' },
+
+ // IconButton
+ 'iconButton.size.sm': { $type: 'dimension' as const, $value: '{size.control.sm}' },
+ 'iconButton.size.md': { $type: 'dimension' as const, $value: '{size.control.md}' },
+
+ // Field
+ 'field.radius': { $type: 'dimension' as const, $value: '{radius.md}' },
+ 'field.border': { $type: 'color' as const, $value: '{color.border.default}' },
+ 'field.border.focus': { $type: 'color' as const, $value: '{color.border.focus}' },
+ 'field.border.error': { $type: 'color' as const, $value: '{color.feedback.error}' },
+ 'field.label.weight': { $type: 'fontWeight' as const, $value: '{font.weight.medium}' },
+
+ // Checkbox
+ 'checkbox.radius': { $type: 'dimension' as const, $value: '{radius.sm}' },
+
+ // Surface
+ 'surface.radius': { $type: 'dimension' as const, $value: '{radius.lg}' },
+ 'surface.padding': { $type: 'dimension' as const, $value: '{space.inset.lg}' },
+
+ // Card
+ 'card.radius': { $type: 'dimension' as const, $value: '{radius.lg}' },
+ 'card.shadow': { $type: 'shadow' as const, $value: '{shadow.sm}' },
+ 'card.padding': { $type: 'dimension' as const, $value: '{space.inset.lg}' },
+
+ // Chip
+ 'chip.radius': { $type: 'dimension' as const, $value: '{radius.pill}' },
+ 'chip.height': { $type: 'dimension' as const, $value: '{size.control.sm}' },
+
+ // Badge
+ 'badge.radius': { $type: 'dimension' as const, $value: '{radius.pill}' },
+ 'badge.font.size': { $type: 'dimension' as const, $value: '{font.size.200}' },
+
+ // Alert
+ 'alert.radius': { $type: 'dimension' as const, $value: '{radius.md}' },
+ 'alert.info.bg': { $type: 'color' as const, $value: '{color.blue.50}' },
+ 'alert.info.border': { $type: 'color' as const, $value: '{color.feedback.info}' },
+ 'alert.success.bg': { $type: 'color' as const, $value: '{color.green.50}' },
+ 'alert.success.border': { $type: 'color' as const, $value: '{color.feedback.success}' },
+ 'alert.warning.bg': { $type: 'color' as const, $value: '{color.amber.50}' },
+ 'alert.warning.border': { $type: 'color' as const, $value: '{color.feedback.warning}' },
+ 'alert.error.bg': { $type: 'color' as const, $value: '{color.red.50}' },
+ 'alert.error.border': { $type: 'color' as const, $value: '{color.feedback.error}' },
+
+ // Dialog
+ 'dialog.radius': { $type: 'dimension' as const, $value: '{radius.lg}' },
+ 'dialog.shadow': { $type: 'shadow' as const, $value: '{shadow.md}' },
+ 'dialog.padding': { $type: 'dimension' as const, $value: '{space.6}' },
+
+ // Skeleton
+ 'skeleton.radius': { $type: 'dimension' as const, $value: '{radius.sm}' },
+
+ // Progress
+ 'progress.height': { $type: 'dimension' as const, $value: '{space.1}' },
+ 'progress.radius': { $type: 'dimension' as const, $value: '{radius.pill}' },
+ 'progress.bg': { $type: 'color' as const, $value: '{color.neutral.100}' },
+ 'progress.fill': { $type: 'color' as const, $value: '{color.action.primary}' },
+
+ // Table
+ 'table.header.weight': { $type: 'fontWeight' as const, $value: '{font.weight.semibold}' },
+ 'table.cell.padding': { $type: 'dimension' as const, $value: '{space.inset.sm}' },
+ 'table.row.hover.bg': { $type: 'color' as const, $value: '{color.surface.subtle}' },
+
+ // Metric
+ 'metric.label.size': { $type: 'dimension' as const, $value: '{font.size.200}' },
+ 'metric.label.weight': { $type: 'fontWeight' as const, $value: '{font.weight.medium}' },
+ 'metric.value.weight': { $type: 'fontWeight' as const, $value: '{font.weight.bold}' },
+ 'metric.gap': { $type: 'dimension' as const, $value: '{space.1}' },
+
+ // PageState
+ 'pageState.icon.size': { $type: 'dimension' as const, $value: '{space.12}' },
+ 'pageState.title.gap': { $type: 'dimension' as const, $value: '{space.4}' },
+} as const satisfies TokenCollection;
diff --git a/packages/design-system/src/tokens/index.ts b/packages/design-system/src/tokens/index.ts
new file mode 100644
index 0000000..40b3e8c
--- /dev/null
+++ b/packages/design-system/src/tokens/index.ts
@@ -0,0 +1,11 @@
+export { primitiveTokens } from './primitives';
+export { semanticLightTokens } from './semantic.light';
+export { componentTokens } from './components';
+export { resolveToken } from './resolveToken';
+export type {
+ TokenType,
+ TokenValue,
+ TokenDefinition,
+ TokenCollection,
+ ResolvedToken,
+} from './types';
diff --git a/packages/design-system/src/tokens/primitives.ts b/packages/design-system/src/tokens/primitives.ts
new file mode 100644
index 0000000..987c84e
--- /dev/null
+++ b/packages/design-system/src/tokens/primitives.ts
@@ -0,0 +1,103 @@
+import type { TokenCollection } from './types';
+
+export const primitiveTokens = {
+ // Colors — neutral
+ 'color.neutral.0': { $type: 'color' as const, $value: '#ffffff' },
+ 'color.neutral.50': { $type: 'color' as const, $value: '#f5f5f5' },
+ 'color.neutral.100': { $type: 'color' as const, $value: '#e8e8e8' },
+ 'color.neutral.200': { $type: 'color' as const, $value: '#d1d1d1' },
+ 'color.neutral.400': { $type: 'color' as const, $value: '#a3a3a3' },
+ 'color.neutral.600': { $type: 'color' as const, $value: '#666666' },
+ 'color.neutral.800': { $type: 'color' as const, $value: '#333333' },
+ 'color.neutral.900': { $type: 'color' as const, $value: '#1a1a1a' },
+
+ // Colors — green (positive)
+ 'color.green.50': { $type: 'color' as const, $value: '#e8f5e9' },
+ 'color.green.100': { $type: 'color' as const, $value: '#c8e6c9' },
+ 'color.green.600': { $type: 'color' as const, $value: '#2e7d32' },
+ 'color.green.700': { $type: 'color' as const, $value: '#176747' },
+ 'color.green.800': { $type: 'color' as const, $value: '#1b5e20' },
+
+ // Colors — red (negative)
+ 'color.red.50': { $type: 'color' as const, $value: '#ffebee' },
+ 'color.red.600': { $type: 'color' as const, $value: '#e53935' },
+ 'color.red.700': { $type: 'color' as const, $value: '#c62828' },
+
+ // Colors — amber (warning)
+ 'color.amber.50': { $type: 'color' as const, $value: '#fff8e1' },
+ 'color.amber.600': { $type: 'color' as const, $value: '#ffb300' },
+
+ // Colors — blue (info)
+ 'color.blue.50': { $type: 'color' as const, $value: '#e3f2fd' },
+ 'color.blue.600': { $type: 'color' as const, $value: '#1e88e5' },
+
+ // Spacing (4px grid)
+ 'space.0': { $type: 'dimension' as const, $value: '0px' },
+ 'space.1': { $type: 'dimension' as const, $value: '4px' },
+ 'space.2': { $type: 'dimension' as const, $value: '8px' },
+ 'space.3': { $type: 'dimension' as const, $value: '12px' },
+ 'space.4': { $type: 'dimension' as const, $value: '16px' },
+ 'space.5': { $type: 'dimension' as const, $value: '20px' },
+ 'space.6': { $type: 'dimension' as const, $value: '24px' },
+ 'space.8': { $type: 'dimension' as const, $value: '32px' },
+ 'space.10': { $type: 'dimension' as const, $value: '40px' },
+ 'space.12': { $type: 'dimension' as const, $value: '48px' },
+
+ // Border radius
+ 'radius.none': { $type: 'dimension' as const, $value: '0px' },
+ 'radius.sm': { $type: 'dimension' as const, $value: '4px' },
+ 'radius.md': { $type: 'dimension' as const, $value: '8px' },
+ 'radius.lg': { $type: 'dimension' as const, $value: '12px' },
+ 'radius.pill': { $type: 'dimension' as const, $value: '9999px' },
+
+ // Font family
+ 'font.family.sans': {
+ $type: 'fontFamily' as const,
+ $value: ['Inter', 'system-ui', '-apple-system', 'sans-serif'],
+ },
+ 'font.family.mono': {
+ $type: 'fontFamily' as const,
+ $value: ['SFMono-Regular', 'Menlo', 'Monaco', 'Consolas', 'monospace'],
+ },
+
+ // Font size (100 = 10px, 700 = 48px scale)
+ 'font.size.100': { $type: 'dimension' as const, $value: '10px' },
+ 'font.size.200': { $type: 'dimension' as const, $value: '12px' },
+ 'font.size.300': { $type: 'dimension' as const, $value: '14px' },
+ 'font.size.400': { $type: 'dimension' as const, $value: '16px' },
+ 'font.size.500': { $type: 'dimension' as const, $value: '20px' },
+ 'font.size.600': { $type: 'dimension' as const, $value: '24px' },
+ 'font.size.700': { $type: 'dimension' as const, $value: '32px' },
+
+ // Font weight
+ 'font.weight.regular': { $type: 'fontWeight' as const, $value: 400 },
+ 'font.weight.medium': { $type: 'fontWeight' as const, $value: 500 },
+ 'font.weight.semibold': { $type: 'fontWeight' as const, $value: 600 },
+ 'font.weight.bold': { $type: 'fontWeight' as const, $value: 700 },
+
+ // Line height
+ 'lineHeight.tight': { $type: 'dimension' as const, $value: '1.25' },
+ 'lineHeight.normal': { $type: 'dimension' as const, $value: '1.5' },
+ 'lineHeight.relaxed': { $type: 'dimension' as const, $value: '1.75' },
+
+ // Shadows
+ 'shadow.none': { $type: 'shadow' as const, $value: 'none' },
+ 'shadow.sm': { $type: 'shadow' as const, $value: '0px 1px 2px 0px rgba(0,0,0,0.08)' },
+ 'shadow.md': { $type: 'shadow' as const, $value: '0px 4px 8px 0px rgba(0,0,0,0.12)' },
+
+ // Duration
+ 'duration.instant': { $type: 'duration' as const, $value: 0 },
+ 'duration.fast': { $type: 'duration' as const, $value: 150 },
+ 'duration.normal': { $type: 'duration' as const, $value: 250 },
+
+ // Easing
+ 'easing.standard': { $type: 'cubicBezier' as const, $value: [0.4, 0, 0.2, 1] as const },
+
+ // Control sizes
+ 'size.control.sm': { $type: 'dimension' as const, $value: '32px' },
+ 'size.control.md': { $type: 'dimension' as const, $value: '40px' },
+
+ // Focus ring
+ 'size.focus.ring': { $type: 'dimension' as const, $value: '2px' },
+ 'size.focus.offset': { $type: 'dimension' as const, $value: '2px' },
+} as const satisfies TokenCollection;
diff --git a/packages/design-system/src/tokens/resolveToken.test.ts b/packages/design-system/src/tokens/resolveToken.test.ts
new file mode 100644
index 0000000..14844d1
--- /dev/null
+++ b/packages/design-system/src/tokens/resolveToken.test.ts
@@ -0,0 +1,30 @@
+import { describe, it, expect } from 'vitest';
+import { resolveToken } from './resolveToken';
+import type { TokenCollection } from './types';
+
+describe('resolveToken', () => {
+ it('resolves an alias chain and preserves the declared type', () => {
+ const tokens = {
+ base: { $type: 'color' as const, $value: '#176747' },
+ semantic: { $type: 'color' as const, $value: '{base}' },
+ component: { $type: 'color' as const, $value: '{semantic}' },
+ } satisfies TokenCollection;
+ expect(resolveToken(tokens, 'component')).toEqual({ type: 'color', value: '#176747' });
+ });
+
+ it.each([
+ ['missing alias', { a: { $type: 'color', $value: '{missing}' } }, /Unknown token/],
+ [
+ 'cycle',
+ { a: { $type: 'color', $value: '{b}' }, b: { $type: 'color', $value: '{a}' } },
+ /cycle/i,
+ ],
+ [
+ 'type mismatch',
+ { a: { $type: 'color', $value: '#fff' }, b: { $type: 'dimension', $value: '{a}' } },
+ /type/i,
+ ],
+ ] as const)('rejects %s', (_name, tokens, error) => {
+ expect(() => resolveToken(tokens, 'b')).toThrow(error);
+ });
+});
diff --git a/packages/design-system/src/tokens/resolveToken.ts b/packages/design-system/src/tokens/resolveToken.ts
new file mode 100644
index 0000000..7089f11
--- /dev/null
+++ b/packages/design-system/src/tokens/resolveToken.ts
@@ -0,0 +1,35 @@
+import type { TokenCollection, ResolvedToken } from './types';
+
+const aliasPattern = /^\{([^}]+)\}$/;
+
+export function resolveToken(
+ tokens: TokenCollection,
+ name: string,
+ visited = new Set(),
+): ResolvedToken {
+ if (visited.has(name)) {
+ throw new Error(`Cycle detected: ${name} has already been visited in this chain`);
+ }
+
+ const def = tokens[name];
+ if (!def) {
+ throw new Error(`Unknown token: ${name}`);
+ }
+
+ const match = aliasPattern.exec(String(def.$value));
+ if (!match) {
+ return { type: def.$type, value: def.$value };
+ }
+
+ const targetName = match[1];
+ visited.add(name);
+ const resolved = resolveToken(tokens, targetName, visited);
+
+ if (resolved.type !== def.$type) {
+ throw new Error(
+ `Type mismatch: token "${name}" has type "${def.$type}" but alias target "${targetName}" has type "${resolved.type}"`,
+ );
+ }
+
+ return resolved;
+}
diff --git a/packages/design-system/src/tokens/semantic.light.ts b/packages/design-system/src/tokens/semantic.light.ts
new file mode 100644
index 0000000..0cca2c9
--- /dev/null
+++ b/packages/design-system/src/tokens/semantic.light.ts
@@ -0,0 +1,61 @@
+import type { TokenCollection } from './types';
+
+export const semanticLightTokens = {
+ // Canvas
+ 'color.canvas': { $type: 'color' as const, $value: '{color.neutral.50}' },
+
+ // Surface
+ 'color.surface.default': { $type: 'color' as const, $value: '{color.neutral.0}' },
+ 'color.surface.subtle': { $type: 'color' as const, $value: '{color.neutral.50}' },
+ 'color.surface.raised': { $type: 'color' as const, $value: '{color.neutral.0}' },
+
+ // Text
+ 'color.text.primary': { $type: 'color' as const, $value: '{color.neutral.900}' },
+ 'color.text.secondary': { $type: 'color' as const, $value: '{color.neutral.600}' },
+ 'color.text.disabled': { $type: 'color' as const, $value: '{color.neutral.400}' },
+ 'color.text.inverse': { $type: 'color' as const, $value: '{color.neutral.0}' },
+
+ // Border
+ 'color.border.subtle': { $type: 'color' as const, $value: '{color.neutral.100}' },
+ 'color.border.default': { $type: 'color' as const, $value: '{color.neutral.200}' },
+ 'color.border.strong': { $type: 'color' as const, $value: '{color.neutral.400}' },
+ 'color.border.focus': { $type: 'color' as const, $value: '{color.blue.600}' },
+
+ // Action
+ 'color.action.primary': { $type: 'color' as const, $value: '{color.green.700}' },
+ 'color.action.primaryHover': { $type: 'color' as const, $value: '{color.green.800}' },
+ 'color.action.secondary': { $type: 'color' as const, $value: '{color.neutral.600}' },
+ 'color.action.danger': { $type: 'color' as const, $value: '{color.red.600}' },
+
+ // Feedback
+ 'color.feedback.info': { $type: 'color' as const, $value: '{color.blue.600}' },
+ 'color.feedback.success': { $type: 'color' as const, $value: '{color.green.600}' },
+ 'color.feedback.warning': { $type: 'color' as const, $value: '{color.amber.600}' },
+ 'color.feedback.error': { $type: 'color' as const, $value: '{color.red.600}' },
+
+ // Finance
+ 'color.finance.positive': { $type: 'color' as const, $value: '{color.green.700}' },
+ 'color.finance.negative': { $type: 'color' as const, $value: '{color.red.700}' },
+ 'color.finance.neutral': { $type: 'color' as const, $value: '{color.neutral.600}' },
+
+ // Typography
+ 'font.family.body': { $type: 'fontFamily' as const, $value: '{font.family.sans}' },
+ 'font.weight.body': { $type: 'fontWeight' as const, $value: '{font.weight.regular}' },
+ 'font.weight.heading': { $type: 'fontWeight' as const, $value: '{font.weight.semibold}' },
+ 'font.weight.strong': { $type: 'fontWeight' as const, $value: '{font.weight.bold}' },
+ // Spacing
+ 'space.inset.sm': { $type: 'dimension' as const, $value: '{space.2}' },
+ 'space.inset.md': { $type: 'dimension' as const, $value: '{space.3}' },
+ 'space.inset.lg': { $type: 'dimension' as const, $value: '{space.4}' },
+ 'space.stack.sm': { $type: 'dimension' as const, $value: '{space.1}' },
+ 'space.stack.md': { $type: 'dimension' as const, $value: '{space.2}' },
+ 'space.stack.lg': { $type: 'dimension' as const, $value: '{space.4}' },
+ 'space.inline.sm': { $type: 'dimension' as const, $value: '{space.1}' },
+ 'space.inline.md': { $type: 'dimension' as const, $value: '{space.2}' },
+ 'space.inline.lg': { $type: 'dimension' as const, $value: '{space.3}' },
+
+ // Focus ring
+ 'focus.ring.width': { $type: 'dimension' as const, $value: '{size.focus.ring}' },
+ 'focus.ring.offset': { $type: 'dimension' as const, $value: '{size.focus.offset}' },
+ 'focus.ring.color': { $type: 'color' as const, $value: '{color.blue.600}' },
+} as const satisfies TokenCollection;
diff --git a/packages/design-system/src/tokens/tokens.test.ts b/packages/design-system/src/tokens/tokens.test.ts
new file mode 100644
index 0000000..a473d6d
--- /dev/null
+++ b/packages/design-system/src/tokens/tokens.test.ts
@@ -0,0 +1,72 @@
+import { describe, it, expect } from 'vitest';
+import { primitiveTokens } from './primitives';
+import { semanticLightTokens } from './semantic.light';
+import { componentTokens } from './components';
+import { resolveToken } from './resolveToken';
+
+const aliasPattern = /^\{([^}]+)\}$/;
+const isAlias = (value: string | number | readonly number[] | readonly string[]): boolean =>
+ typeof value === 'string' && aliasPattern.test(value);
+
+const allTokens = {
+ ...primitiveTokens,
+ ...semanticLightTokens,
+ ...componentTokens,
+} as const;
+
+describe('token integrity', () => {
+ it('primitives contain no aliases', () => {
+ for (const [name, def] of Object.entries(primitiveTokens)) {
+ expect(isAlias(def.$value), `${name} should not be an alias`).toBe(false);
+ }
+ });
+
+ it('semantic tokens only use aliases', () => {
+ for (const [name, def] of Object.entries(semanticLightTokens)) {
+ expect(isAlias(def.$value), `${name} should be an alias`).toBe(true);
+ }
+ });
+
+ it('component tokens only use aliases', () => {
+ for (const [name, def] of Object.entries(componentTokens)) {
+ expect(isAlias(def.$value), `${name} should be an alias`).toBe(true);
+ }
+ });
+
+ it('all tokens resolve without errors', () => {
+ for (const name of Object.keys(allTokens)) {
+ expect(() => resolveToken(allTokens, name), `Failed to resolve ${name}`).not.toThrow();
+ }
+ });
+
+ it('has unique names across all collections', () => {
+ const allNames = [
+ ...Object.keys(primitiveTokens),
+ ...Object.keys(semanticLightTokens),
+ ...Object.keys(componentTokens),
+ ];
+ const uniqueNames = new Set(allNames);
+ expect(uniqueNames.size).toBe(allNames.length);
+ });
+
+ it('semantic tokens reference only primitive tokens', () => {
+ const primitiveNames = new Set(Object.keys(primitiveTokens));
+ for (const [name, def] of Object.entries(semanticLightTokens)) {
+ if (typeof def.$value === 'string' && aliasPattern.test(def.$value)) {
+ const target = def.$value.match(aliasPattern)![1];
+ expect(primitiveNames.has(target), `${name} references non-primitive "${target}"`).toBe(
+ true,
+ );
+ }
+ }
+ });
+
+ it('component tokens avoid direct primitive value literals', () => {
+ const literalPattern = /(px|#|rgba|rgb)/;
+ for (const [name, def] of Object.entries(componentTokens)) {
+ if (typeof def.$value === 'string') {
+ expect(literalPattern.test(def.$value), `${name} contains a literal value`).toBe(false);
+ }
+ }
+ });
+});
diff --git a/packages/design-system/src/tokens/types.ts b/packages/design-system/src/tokens/types.ts
new file mode 100644
index 0000000..59ea70f
--- /dev/null
+++ b/packages/design-system/src/tokens/types.ts
@@ -0,0 +1,12 @@
+export type TokenType =
+ | 'color'
+ | 'dimension'
+ | 'fontFamily'
+ | 'fontWeight'
+ | 'duration'
+ | 'cubicBezier'
+ | 'shadow';
+export type TokenValue = string | number | readonly number[] | readonly string[];
+export type TokenDefinition = { readonly $type: TokenType; readonly $value: TokenValue };
+export type TokenCollection = Readonly>;
+export type ResolvedToken = { readonly type: TokenType; readonly value: TokenValue };
diff --git a/packages/design-system/tsconfig.json b/packages/design-system/tsconfig.json
new file mode 100644
index 0000000..4f47406
--- /dev/null
+++ b/packages/design-system/tsconfig.json
@@ -0,0 +1,25 @@
+{
+ "compilerOptions": {
+ "target": "ES2020",
+ "lib": ["ES2020", "DOM", "DOM.Iterable"],
+ "module": "ESNext",
+ "moduleResolution": "bundler",
+ "declaration": true,
+ "declarationMap": true,
+ "sourceMap": true,
+ "outDir": "dist",
+ "rootDir": "src",
+ "jsx": "react-jsx",
+ "strict": true,
+ "skipLibCheck": true,
+ "isolatedModules": true,
+ "moduleDetection": "force",
+ "allowImportingTsExtensions": false,
+ "noEmit": false,
+ "noUnusedLocals": false,
+ "noUnusedParameters": false,
+ "noFallthroughCasesInSwitch": true
+ },
+ "include": ["src"],
+ "exclude": ["src/**/*.test.ts", "src/**/*.test.tsx", "src/**/*.stories.ts", "src/**/*.stories.tsx"]
+}
diff --git a/packages/design-system/vitest.config.ts b/packages/design-system/vitest.config.ts
new file mode 100644
index 0000000..928229c
--- /dev/null
+++ b/packages/design-system/vitest.config.ts
@@ -0,0 +1,13 @@
+import { defineConfig } from 'vitest/config';
+
+export default defineConfig({
+ test: {
+ name: 'unit',
+ environment: 'jsdom',
+ setupFiles: ['./src/test/setup.ts'],
+ include: ['src/**/*.test.{ts,tsx}'],
+ exclude: ['src/**/*.stories.test.{ts,tsx}'],
+ globals: true,
+ passWithNoTests: true,
+ },
+});
diff --git a/packages/design-system/vitest.workspace.ts b/packages/design-system/vitest.workspace.ts
new file mode 100644
index 0000000..4cc23c2
--- /dev/null
+++ b/packages/design-system/vitest.workspace.ts
@@ -0,0 +1,19 @@
+import { defineWorkspace } from 'vitest/config';
+
+export default defineWorkspace([
+ 'vitest.config.ts',
+ {
+ test: {
+ name: 'storybook',
+ browser: {
+ enabled: true,
+ name: 'chromium',
+ provider: 'playwright',
+ headless: true,
+ },
+ setupFiles: ['./.storybook/vitest.setup.ts'],
+ include: ['src/**/*.stories.test.{ts,tsx}'],
+ passWithNoTests: true,
+ },
+ },
+]);