Краткое описание проекта

Small Design System — это современная React библиотека компонентов, созданная для обеспечения консистентного пользовательского опыта во всех продуктах компании.

$3

Создание единой экосистемы UI компонентов, которая ускоряет разработку и обеспечивает высокие стандарты доступности и качества.

---

Назначение дизайн-системы

$3

| Задача | Решение | Результат |
| ------------------------ | ---------------------------------- | -------------------------------- |
| Единообразие UI | Стандартизированные компоненты | Консистентный опыт пользователей |
| Ускорение разработки | Готовые к использованию компоненты | Сокращение времени на 60% |
| Масштабируемость | Модульная архитектура | Легкое расширение системы |
| Типобезопасность | TypeScript first подход | Меньше багов в продакшене |

$3

- 🎨 Современный дизайн - Минималистичные, чистые компоненты
- 🔧 TypeScript First - Полная типизация всех компонентов
- 🚀 Performance - Оптимизированные компоненты
- 📱 Responsive - Адаптивность на всех устройствах
- 🌙 Dark Mode - Встроенная поддержка тем

---

Локальное развертывание проекта

$3

$3

``bash


1. Клонирование

`

$3

$3

- npm run dev - Development сервер (порт 5173)
- npm run start - Документация компонентов (порт 6006)

$3

- npm run test - Запуск всех тестов
- npm run test --watch - Watch режим
- npm run test --coverage - Покрытие кода

$3

- npm run lint - ESLint проверка
- npm run lint:fix - Автоисправление
- npm run format - Prettier форматирование

$3

- npm run build:lib - Сборка библиотеки
- npm run build:types - Генерация типов

---

Архитектура проекта

`
src/
├── components/ # UI компоненты
│ ├── button/
│ │ ├── button.tsx # Основной компонент
│ │ ├── button.variants.ts # Стили и варианты
│ │ ├── button.stories.tsx # Storybook
│ │ ├── button.test.tsx # Тесты
│ │ └── index.ts # Экспорты
├── core/ # Ядро системы
├── hooks/ # React хуки
├── styles/ # Глобальные стили
├── types/ # TypeScript типы
└── utils/ # Утилиты

`

---

Правила разработки компонентов

$3

`
src/components/my-component/
├── index.ts # Экспорты
├── my-component.tsx # Основной компонент
├── my-component.variants.ts # Стили
├── my-component.stories.tsx # Storybook
├── my-component.test.tsx # Тесты
├── types.ts # TypeScript типы
└── sub-component/ # Подкомпонент

`

$3

$3

- Папки: kebab-case (dropdown-menu, icon-button)
- Компоненты: PascalCase в коде, kebab-case в файлах
- Типы: PascalCase + суффикс (ButtonProps, SelectVariants)

$3

- Props: camelCase (isDisabled, showIcon, onValueChange)
- Variants: kebab-case строки ('primary', 'ghost', 'destructive')
- Boolean props: is, has, should* (isLoading, hasError)
- Callbacks: on* (onClick, onSubmit, onValueChange)

$3

`tsx
// my-component.tsx
import React from "react";
import { createPolymorphicComponent } from "@/core/factory";
import { myComponentVariants } from "./my-component.variants";

const _MyComponent = React.forwardRef(
({ className, variant = "default", size = "md", ...props }, ref) => {
return (
ref={ref}
className={cn(myComponentVariants({ variant, size }), className)}
{...props}
/>
);
}
);

export const MyComponent = createPolymorphicComponent<"div", MyComponentProps>(
_MyComponent
);
`

---

Рекомендации по стилям

$3

- Tailwind CSS v4 - Основной CSS фреймворк
- Tailwind Variants - Создание вариантов компонентов
- CSS Custom Properties - Токены дизайна
- Inter Font - Variable font для типографики

$3

$3

1. Использовать Tailwind утилиты для 95% стилизации
2. Создавать варианты через tailwind-variants
3. Группировать классы логически
4. Использовать семантические токены

$3

- Inline стили (style атрибут)
- Кастомный CSS вместо Tailwind
- Магические числа
- Дублирование стилей

$3

`tsx
export const buttonVariants = tv({
base: [
"inline-flex items-center justify-center",
"rounded-md font-medium transition-colors",
"focus-visible:outline-none focus-visible:ring-2",
"disabled:pointer-events-none disabled:opacity-50",
],
variants: {
variant: {
primary: "bg-blue-600 text-white hover:bg-blue-700",
secondary: "bg-gray-100 text-gray-900 hover:bg-gray-200",
ghost: "text-gray-600 hover:bg-gray-100",
},
size: {
sm: "h-8 px-3 text-sm",
md: "h-10 px-4",
lg: "h-12 px-6 text-lg",
},
},
defaultVariants: {
variant: "primary",
size: "md",
},
});
`

---

Тестирование компонентов

$3

- Vitest - Test runner
- React Testing Library - Тестирование компонентов
- @testing-library/jest-dom - Дополнительные матчеры
- @testing-library/user-event - Симуляция пользователя
- jsdom - Browser-like окружение

$3

| Категория | Примеры | Приоритет |
| ------------------ | ---------------------- | ------------- |
| Рендеринг | Компонент отображается | 🔴 Критично |
| Props | Все props работают | 🔴 Критично |
| Взаимодействия | Клики, фокус, ввод | 🟡 Важно |
| Accessibility | ARIA, навигация | 🟡 Важно |
| Варианты | Стилевые варианты | 🟢 Желательно |

$3

1. Описательные имена тестов
2. Тестировать поведение, не implementation details
3. Accessibility first - всегда проверять ARIA
4. Один тест = один сценарий
5. AAA pattern: Arrange, Act, Assert

$3

`tsx
describe("Button Component", () => {
it("should render with correct text and role", () => {
render(Click me);

const button = screen.getByRole("button", { name: "Click me" });
expect(button).toBeInTheDocument();
});

it("should call onClick when clicked", async () => {
const user = userEvent.setup();
const handleClick = vi.fn();

render(Click me);
await user.click(screen.getByRole("button"));

expect(handleClick).toHaveBeenCalledTimes(1);
});
});
`

---

Процесс Pull Requests

$3

Перед созданием PR проверьте:

- [ ] npm run lint - проходит без ошибок
- [ ] npm run test - все тесты зеленые
- [ ] npm run build:lib - сборка успешная
- [ ] Storybook stories обновлены (для новых компонентов)
- [ ] Документация обновлена (при необходимости)

$3

Формат: [type]: краткое описание

| Тип | Пример |
| ---------- | -------------------------------------- |
| feat | feat: add Alert component |
| fix | fix: resolve focus issue in Modal |
| refactor | refactor: optimize Input performance |

$3

`markdown


🎯 Что изменено

- Краткое описание изменений

🤔 Зачем

- Причина изменений
- Ссылка на issue: Closes #123

🧪 Как тестировать

1. Клонируйте ветку
2. Запустите npm run storybook
3. Проверьте компонент
4. Запустите тесты

✅ Checklist

- [ ] Линтинг проходит
- [ ] Тесты проходят
- [ ] Сборка работает
- [ ] Тесты добавлены/обновлены
- [ ] Storybook обновлен
- [ ] Accessibility проверена
``

$3

$3

- ✅ Self-review перед созданием PR
- 💬 Быстро отвечать на комментарии
- 🔄 Вносить изменения согласно фидбеку

$3

- 🎯 Проверить функциональность
- 🎨 Соответствие дизайн-системе
- ♿ Accessibility compliance
- 📚 Качество документации
- 🧪 Покрытие тестами
- 📱 Responsive поведение

---

Быстрые ссылки

- 📚 Storybook: https://storybook.small.kz/
- 📚 Storybook(Stage): https://storybook-test.small.kz/
- 🎨 Дизайн Figma: https://www.figma.com/
- 📦 NPM: small-design-system