mbt-ui-kit 0.1.14 → 0.1.18

package/.ai/agent-examples/README.md

@@ -0,0 +1,185 @@
+# Agent Examples
+
+Use these examples when a consumer app needs package-level usage patterns for `mbt-ui-kit`.
+
+## App Shell Setup
+
+```tsx
+import { Button, Heading, Input, Text } from 'mbt-ui-kit';
+import 'mbt-ui-kit/styles';
+
+function SettingsPanel() {
+  return (
+    <div>
+      <Heading level={2}>Settings</Heading>
+      <Text muted>Configure your account preferences.</Text>
+      <Input label="Email" placeholder="name@example.com" fullWidth />
+      <Button type="button">Save changes</Button>
+    </div>
+  );
+}
+```
+
+## Font Loading
+
+Default consumer setup:
+
+```tsx
+import 'mbt-ui-kit/styles';
+```
+
+Advanced consumer preload setup:
+
+```tsx
+import 'mbt-ui-kit/styles';
+import plexSansRegularUrl from 'mbt-ui-kit/fonts/ibm-plex-sans-v23-latin-regular.woff2';
+import plexSansMediumUrl from 'mbt-ui-kit/fonts/ibm-plex-sans-v23-latin-500.woff2';
+import interVariableUrl from 'mbt-ui-kit/fonts/Inter-VariableFont_opsz,wght.ttf';
+
+const preloadFonts = [plexSansRegularUrl, plexSansMediumUrl, interVariableUrl];
+```
+
+- Use `mbt-ui-kit/styles` as the default package entrypoint.
+- Preload `mbt-ui-kit/fonts/*` only when the consumer app wants better first paint for fonts already used above the fold.
+- Do not import both `mbt-ui-kit/styles` and `mbt-ui-kit/fonts.css` unless the app intentionally needs separate early font-face loading.
+
+## Buttons
+
+```tsx
+<Button>Start</Button>
+
+<Button disabled>Coming Soon</Button>
+
+<Button fullWidth onClick={handleSubmit}>
+  Confirm
+</Button>
+
+<Button type="button" onClick={handleOpenSettings}>
+  <SettingsIcon /> Settings
+</Button>
+```
+
+## Inputs
+
+```tsx
+<Input label="Search" placeholder="Find champion" showSearchIcon />
+
+<Input label="Email" fullWidth value={email} onChange={(e) => setEmail(e.target.value)} />
+
+<Input placeholder="Custom icon" icon={<CustomIcon />} />
+
+<Input label="Disabled field" muted disabled />
+```
+
+## Typography
+
+```tsx
+<Heading level={1}>Dashboard</Heading>
+<Heading level={3}>Recent Matches</Heading>
+
+<Text>Regular body copy.</Text>
+<Text strong>Highlighted text.</Text>
+<Text small muted>Secondary caption.</Text>
+<Text label>Role</Text>
+
+<Metric>1,234</Metric>
+<Metric large>42,500</Metric>
+<Metric as="span" muted>
+  99
+</Metric>
+```
+
+## Menu Buttons
+
+```tsx
+<MenuButton>Training</MenuButton>
+
+<MenuButton selected icon={<SettingsIcon />}>
+  Settings
+</MenuButton>
+
+<MenuButton small>Inventory</MenuButton>
+
+<MenuButton disabled>Coming Soon</MenuButton>
+```
+
+## Loader
+
+```tsx
+<Loader size="sm" />
+<Loader size="md" />
+<Loader size="lg" />
+
+<Button loading>Saving</Button>
+```
+
+## Icons
+
+```tsx
+<SearchIcon />
+
+<MenuButton icon={<GraduationCapIcon />}>Training</MenuButton>
+```
+
+## Tokens In Styled Components
+
+```tsx
+import styled from 'styled-components';
+import { colors, fontSizes, radius, spacing } from 'mbt-ui-kit/tokens';
+
+export const Card = styled.div`
+  display: grid;
+  gap: ${spacing[3]};
+  padding: ${spacing[5]};
+  border-radius: ${radius.md};
+  background: ${colors.surface};
+  color: ${colors.textPrimary};
+  font-size: ${fontSizes[3]};
+`;
+```
+
+## Token-Only Import
+
+```tsx
+import { colors, spacing, transitions } from 'mbt-ui-kit/tokens';
+
+const panelStyle = {
+  backgroundColor: colors.surfaceRaised,
+  padding: spacing[4],
+  transition: `opacity ${transitions.fast}`,
+};
+```
+
+## CSS Custom Properties
+
+```tsx
+import 'mbt-ui-kit/tokens.css';
+```
+
+```css
+.panel {
+  background-color: var(--mbt-color-surface);
+  color: var(--mbt-color-text-primary);
+  padding: var(--mbt-space-4);
+  border-radius: var(--mbt-radius-sm);
+}
+```
+
+## Sass Tokens
+
+```scss
+@use 'mbt-ui-kit/src/styles/tokens' as *;
+
+.panel {
+  background-color: $surface;
+  color: $text-primary;
+  padding: $space-4;
+  border-radius: $radius-sm;
+}
+```
+
+## Guidance
+
+- Prefer nearby consumer-app usage before inventing a new composition pattern.
+- Prefer public package entrypoints over deep imports, except for the published Sass token path.
+- Keep app-specific layout decisions in the consumer app; keep package examples focused on reusable component and token usage.

package/.ai/agent-reference/README.md

@@ -0,0 +1,49 @@
+# Agent Reference
+
+This folder holds factual package reference for `mbt-ui-kit`.
+
+## Public Entry Points
+
+- `mbt-ui-kit` - components plus token exports from `src/index.ts`
+- `mbt-ui-kit/styles` - built package stylesheet, including the package font-face declarations
+- `mbt-ui-kit/fonts.css` - standalone font-face stylesheet for advanced consumer setup
+- `mbt-ui-kit/fonts/*` - published font asset files for preload or direct asset access
+- `mbt-ui-kit/tokens` - token-only module surface
+- `mbt-ui-kit/tokens.css` - CSS custom properties surface
+- `mbt-ui-kit/src/styles/tokens` - published Sass token surface for Sass consumers
+
+## Font Contract
+
+- `fonts.primary` maps to `IBM Plex Sans`
+- `fonts.secondary` maps to `Inter`
+- `fonts.mono` maps to `IBM Plex Mono`
+- importing `mbt-ui-kit/styles` is the default way to make those package fonts available in a consumer app
+- importing `mbt-ui-kit/fonts.css` is an advanced alternative for apps that want font-face declarations without the full package stylesheet
+- importing `mbt-ui-kit/fonts/*` is for direct asset access, such as preload tags in the consumer app shell
+
+## Primary Components
+
+- `Button`
+- `Input`
+- `Loader`
+- `Heading`
+- `Text`
+- `Metric`
+- `MenuButton`
+- `GraduationCapIcon`
+- `SearchIcon`
+
+## Primary Token Families
+
+- `tokens`
+- `colors`
+- `fonts`
+- `fontSizes`
+- `fontWeights`
+- `fontFeatures`
+- `spacing`
+- `radius`
+- `zIndex`
+- `transitions`
+
+Reference docs should stay factual. Policy and maintenance rules belong in `.ai/agent-rules/`.

package/.ai/agent-rules/README.md

@@ -0,0 +1,37 @@
+# Agent Rules
+
+These files are the canonical package-owned rules for `mbt-ui-kit`.
+
+## Rule Map
+
+- `.ai/agent-rules/README.md` - normative usage rules for imports, components, styling, and tokens.
+- `.ai/agent-rules/maintenance.md` - required rule for keeping package guidance in sync with public changes.
+
+## Usage Rules
+
+- Import components and tokens from public package entrypoints only.
+- Prefer an existing `mbt-ui-kit` component before creating a new primitive in a consumer app.
+- Prefer exported design tokens over hardcoded near-duplicate values.
+- Use kebab-case for file names and folder names across this repo.
+- Use `pnpm` as the package manager for this repo and keep a single lockfile.
+- Use `mbt-ui-kit/styles` once at the app shell when the consumer app wants the package styles loaded globally.
+- Treat `mbt-ui-kit/styles` as the default entrypoint for package styles and font-face declarations.
+- Use `mbt-ui-kit/fonts.css` only when the consumer intentionally wants the package font-face declarations without the full styles bundle.
+- Use `mbt-ui-kit/fonts/*` only when the consumer intentionally wants direct font-file access for preload or asset orchestration.
+- Use `mbt-ui-kit/tokens` for token access when the consumer wants the token module surface.
+- Use `mbt-ui-kit/tokens.css` when the consumer explicitly wants only the CSS custom properties stylesheet.
+- Use `mbt-ui-kit/src/styles/tokens` for Sass extension workflows that intentionally depend on the published Sass token surface.
+- Keep examples and rules package-focused; app-specific composition rules belong in the consuming app, not here.
+
+## Component Guidance
+
+- Use `Button` for shared button behavior instead of recreating button primitives.
+- Use `Input` for labeled text inputs and search-style input affordances.
+- Use `Heading`, `Text`, and `Metric` for typography when the consumer wants the package typography primitives.
+- Use `MenuButton` for sidebar or navigation-style button treatments, not as a generic replacement for every button.
+- Use `Loader` for package-consistent loading states.
+
+## Token Guidance
+
+- Preferred token families are `colors`, `fonts`, `fontSizes`, `fontWeights`, `fontFeatures`, `spacing`, `radius`, `zIndex`, and `transitions`.
+- When a consumer needs a custom value outside the token system, keep the exception local to that consumer instead of expanding package docs with app-only design rules.

package/.ai/agent-rules/maintenance.md

@@ -0,0 +1,22 @@
+# Maintenance Rule
+
+Agents working in `mbt-ui-kit` must review and update package guidance whenever a change affects public behavior.
+
+## Update The Docs When
+
+- component props or defaults change
+- exported components are added, removed, or renamed
+- token names or token values change in a way that affects usage
+- package entrypoints or import paths change
+- style-loading expectations change
+- font asset paths, exported font entrypoints, or font-loading expectations change
+- canonical examples need to change to stay correct
+
+## Required Files To Review
+
+- `AGENTS.md`
+- `.ai/agent-rules/README.md`
+- `.ai/agent-reference/README.md`
+- `.ai/agent-examples/README.md`
+
+Do not finish public package work without reviewing these files.

package/AGENTS.md

@@ -0,0 +1,41 @@
+# AGENTS.md
+
+## Purpose
+
+- `mbt-ui-kit` is the shared React design-system package for MBT apps.
+- This repo owns the canonical agent guidance for how to use the package.
+- Consumer apps should read the installed package docs from `node_modules/mbt-ui-kit/...`.
+
+## Package Name
+
+- npm package: `mbt-ui-kit`
+- public entrypoints: `mbt-ui-kit`, `mbt-ui-kit/styles`, `mbt-ui-kit/fonts.css`, `mbt-ui-kit/fonts/*`, `mbt-ui-kit/tokens`, `mbt-ui-kit/tokens.css`
+- published Sass token path: `mbt-ui-kit/src/styles/tokens`
+
+## Read This First
+
+1. `.ai/agent-rules/README.md`
+2. `.ai/agent-rules/maintenance.md`
+3. `.ai/agent-reference/README.md`
+4. `.ai/agent-examples/README.md`
+
+## Guidance Map
+
+- `.ai/agent-rules/README.md` - package-owned usage rules, imports, styling boundaries, and token expectations.
+- `.ai/agent-rules/maintenance.md` - required doc-sync rule when public usage changes.
+- `.ai/agent-reference/README.md` - exported surfaces and lookup map.
+- `.ai/agent-examples/README.md` - short canonical examples for common components and tokens.
+
+## Maintenance Rule
+
+- If a change affects public components, props, tokens, styles, font assets, exports, or expected usage, update the guidance docs before considering the work complete.
+
+## Guardrails
+
+- Document only public package behavior here.
+- Prefer public entrypoints over deep source imports in examples, except for the published Sass token path.
+- Treat `mbt-ui-kit/styles` as the default consumer entrypoint for loading package styles and font-face declarations.
+- Treat `mbt-ui-kit/fonts.css` and `mbt-ui-kit/fonts/*` as advanced consumer entrypoints for apps that intentionally preload or separately stage package fonts.
+- Use kebab-case for file names and folder names across this repo.
+- Use `pnpm` as the package manager for this repo.
+- Keep Storybook as maintainer reference material, not the canonical consumer contract.

package/README.md

@@ -1,160 +1,240 @@
 # MBT UI Kit
 
-React компонентная библиотека со стилями на SCSS для Electron приложений.
+Reusable React UI primitives, typography, and design tokens for MBT applications.
 
-## Установка
+## Installation
 
 ```bash
-npm install mbt-ui-kit
-# или
-bun install mbt-ui-kit
+pnpm add mbt-ui-kit
 ```
 
-## Использование
+## Package Surfaces
+
+- `mbt-ui-kit` - components plus token exports
+- `mbt-ui-kit/styles` - package stylesheet, including package font-face declarations
+- `mbt-ui-kit/fonts.css` - standalone package font-face stylesheet
+- `mbt-ui-kit/fonts/*` - published package font files
+- `mbt-ui-kit/tokens` - token module surface
+- `mbt-ui-kit/tokens.css` - CSS custom properties
+- `mbt-ui-kit/src/styles/tokens` - published Sass token surface
+
+## Agent Guidance
+
+- `AGENTS.md` is the package entrypoint for coding agents.
+- Canonical rules live in `.ai/agent-rules/`.
+- Factual reference lives in `.ai/agent-reference/`.
+- Canonical usage examples live in `.ai/agent-examples/`.
+
+## Quick Start
 
 ```tsx
-import { Button, Input } from "mbt-ui-kit";
-import "mbt-ui-kit/styles";
+import { Button, Heading, Input, Text } from 'mbt-ui-kit';
+import 'mbt-ui-kit/styles';
 
-function App() {
+function ProfileForm() {
   return (
     <div>
-      <Input label="Email" placeholder="Введите email" showSearchIcon />
-      <Button>Отправить</Button>
+      <Heading level={2}>Profile</Heading>
+      <Text muted>Update your account details.</Text>
+      <Input label="Email" placeholder="name@example.com" fullWidth />
+      <Button type="button">Save</Button>
     </div>
   );
 }
 ```
 
-## Компоненты
+### Font loading in consumer app
 
-### Button
-Кнопка с тремя состояниями: default, hover, disabled.
+Default setup: import `mbt-ui-kit/styles` once at the app shell. This already loads the package font-face declarations.
 
 ```tsx
-<Button>Start</Button>
-<Button disabled>Start</Button>
-<Button fullWidth>Start</Button>
+import 'mbt-ui-kit/styles';
 ```
 
-### Input
-Текстовое поле с label и опциональной иконкой.
+Advanced setup: if the consumer app wants better first paint for package fonts used immediately, preload selected files from `mbt-ui-kit/fonts/*` in the app shell.
 
 ```tsx
-<Input label="Label" placeholder="text_input" showSearchIcon />
-<Input label="Label" placeholder="text_input" muted />
-<Input placeholder="text_input" fullWidth />
+import 'mbt-ui-kit/styles';
 ```
 
-### Typography
-Компоненты для заголовков, текста и метрик.
+Example with bundler-resolved asset URLs:
 
 ```tsx
-<Heading level={1}>Main Title</Heading>
-<Text>Regular text</Text>
-<Text strong>Strong text</Text>
-<Metric large>1,234</Metric>
+import plexSansRegularUrl from 'mbt-ui-kit/fonts/ibm-plex-sans-v23-latin-regular.woff2';
+import plexSansMediumUrl from 'mbt-ui-kit/fonts/ibm-plex-sans-v23-latin-500.woff2';
+import plexSansSemiboldUrl from 'mbt-ui-kit/fonts/ibm-plex-sans-v23-latin-600.woff2';
+import interVariableUrl from 'mbt-ui-kit/fonts/Inter-VariableFont_opsz,wght.ttf';
+import interItalicVariableUrl from 'mbt-ui-kit/fonts/Inter-Italic-VariableFont_opsz,wght.ttf';
+import plexMonoRegularUrl from 'mbt-ui-kit/fonts/ibm-plex-mono-v20-latin-regular.woff2';
+import plexMonoMediumUrl from 'mbt-ui-kit/fonts/ibm-plex-mono-v20-latin-500.woff2';
+import plexMonoSemiboldUrl from 'mbt-ui-kit/fonts/ibm-plex-mono-v20-latin-600.woff2';
+
+const preloadFonts = [
+  plexSansRegularUrl,
+  plexSansMediumUrl,
+  plexSansSemiboldUrl,
+  interVariableUrl,
+  interItalicVariableUrl,
+  plexMonoRegularUrl,
+  plexMonoMediumUrl,
+  plexMonoSemiboldUrl,
+];
 ```
 
-### MenuButton
-Кнопка для боковых меню с иконкой и текстом.
-
-```tsx
-<MenuButton>Training</MenuButton>
-<MenuButton selected>Training</MenuButton>
-<MenuButton small>Training</MenuButton>
+Example preload tags:
+
+```html
+<link
+  rel="preload"
+  href="...resolved IBM Plex Sans 400 url..."
+  as="font"
+  type="font/woff2"
+  crossorigin
+/>
+<link
+  rel="preload"
+  href="...resolved IBM Plex Sans 500 url..."
+  as="font"
+  type="font/woff2"
+  crossorigin
+/>
+<link
+  rel="preload"
+  href="...resolved IBM Plex Sans 600 url..."
+  as="font"
+  type="font/woff2"
+  crossorigin
+/>
+<link
+  rel="preload"
+  href="...resolved Inter variable url..."
+  as="font"
+  type="font/ttf"
+  crossorigin
+/>
+<link
+  rel="preload"
+  href="...resolved Inter italic variable url..."
+  as="font"
+  type="font/ttf"
+  crossorigin
+/>
+<link
+  rel="preload"
+  href="...resolved IBM Plex Mono 400 url..."
+  as="font"
+  type="font/woff2"
+  crossorigin
+/>
+<link
+  rel="preload"
+  href="...resolved IBM Plex Mono 500 url..."
+  as="font"
+  type="font/woff2"
+  crossorigin
+/>
+<link
+  rel="preload"
+  href="...resolved IBM Plex Mono 600 url..."
+  as="font"
+  type="font/woff2"
+  crossorigin
+/>
 ```
 
-## Разработка
+The library publishes the font files in `dist/fonts/`, exposes them under `mbt-ui-kit/fonts/*`, and ships matching declarations in both `mbt-ui-kit/styles` and `mbt-ui-kit/fonts.css`, including both normal and italic Inter variable fonts.
 
-```bash
-# Установка зависимостей
-bun install
+Use `mbt-ui-kit/fonts.css` only when the consumer intentionally wants the font-face declarations without the full package stylesheet. Most apps should import `mbt-ui-kit/styles` only.
 
-# Запуск Storybook
-bun storybook
+## Components
 
-# Сборка библиотеки
-bun run build
+Primary exports include:
 
-# Линтинг и форматирование
-bun run lint
-bun run format
-```
+- `Button`
+- `Input`
+- `Loader`
+- `Heading`
+- `Text`
+- `Metric`
+- `MenuButton`
+- `SearchIcon`
+- `GraduationCapIcon`
 
-## Дизайн-токены
+For richer package examples, use `.ai/agent-examples/README.md`.
 
-Токены дизайн-системы доступны в трёх форматах для максимальной гибкости.
+## Design Tokens
 
-### 1. TypeScript/JavaScript
+### TypeScript or JavaScript
 
-Импорт только токенов (без компонентов и стилей):
-```tsx
-import { tokens, colors, spacing, radius } from "mbt-ui-kit/tokens";
-
-const MyComponent = () => (
-  <div style={{ 
-    backgroundColor: colors.primary,
-    padding: spacing[4],
-    borderRadius: radius.sm 
-  }}>
-    Content
-  </div>
-);
-```
+Use token exports for inline styles, styled-components, or utility layers.
 
-Или из основного пакета:
 ```tsx
-import { colors, spacing, fontSizes } from "mbt-ui-kit";
+import { colors, fontSizes, radius, spacing, tokens } from 'mbt-ui-kit/tokens';
+
+const panelStyle = {
+  backgroundColor: colors.surface,
+  color: colors.textPrimary,
+  padding: spacing[5],
+  borderRadius: radius.md,
+  fontSize: fontSizes[3],
+};
 ```
 
-Доступные токены:
-- `colors` — цветовая палитра
-- `fonts` — семейства шрифтов
-- `fontSizes` — размеры текста
-- `fontWeights` — начертания шрифтов
-- `spacing` — отступы и размеры
-- `radius` — радиусы скругления
-- `zIndex` — z-индексы
-- `transitions` — анимации
+Available token groups:
 
-### 2. CSS Custom Properties
+- `tokens`
+- `colors`
+- `fonts`
+- `fontSizes`
+- `fontWeights`
+- `fontFeatures`
+- `spacing`
+- `radius`
+- `zIndex`
+- `transitions`
+
+### CSS Custom Properties
 
-Импорт CSS переменных:
 ```tsx
-import "mbt-ui-kit/tokens.css";
+import 'mbt-ui-kit/tokens.css';
 ```
 
-Использование в CSS/SCSS:
 ```css
-.my-class {
-  background-color: var(--mbt-color-primary);
+.panel {
+  background-color: var(--mbt-color-surface);
+  color: var(--mbt-color-text-primary);
   padding: var(--mbt-space-4);
   border-radius: var(--mbt-radius-sm);
-  font-family: var(--mbt-font-primary);
   transition: all var(--mbt-transition-fast);
 }
 ```
 
-Все переменные имеют префикс `--mbt-` для избежания конфликтов.
-
-### 3. SCSS Variables (для расширения библиотеки)
+### Sass Tokens
 
 ```scss
-@use "mbt-ui-kit/src/styles/tokens" as *;
+@use 'mbt-ui-kit/src/styles/tokens' as *;
 
-.my-class {
-  background-color: $primary;
+.panel {
+  background-color: $surface;
+  color: $text-primary;
   padding: $space-4;
   border-radius: $radius-sm;
-  font-family: $font-ui-primary;
 }
 ```
 
-## TypeScript
+## Development
+
+```bash
+pnpm install
+pnpm build
+pnpm lint
+pnpm format
+pnpm storybook
+```
 
-Библиотека полностью типизирована с подробными JSDoc комментариями.
+This repo standardizes on `pnpm` only.
 
-## Лицензия
+## Notes
 
-MIT
+- Storybook is maintainer-facing visual coverage, not the canonical package contract.
+- Package-owned agent guidance is versioned with the library and published with the package.