mbt-ui-kit 0.1.15 → 0.1.19

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

@@ -0,0 +1,207 @@
+# 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}`,
+};
+```
+
+## Gradient Tokens
+
+```tsx
+import { colors } from 'mbt-ui-kit/tokens';
+
+const heroStyle = {
+  background: colors.primaryGradient,
+};
+
+const customDiamondStyle = {
+  background: `linear-gradient(90deg, ${colors.diamondStop0} 0%, ${colors.diamondStop1} 25%, ${colors.diamondStop2} 50%, ${colors.diamondStop3} 75%, ${colors.diamondStop4} 100%)`,
+};
+```
+
+## 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);
+}
+
+.hero {
+  background: var(--mbt-color-primary-gradient);
+}
+```
+
+## 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;
+}
+
+.hero {
+  background: $diamond-gradient;
+}
+```
+
+## 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,56 @@
+# 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`
+
+## Color Token Notes
+
+- `colors` includes solid colors, gradient stop tokens, and convenience gradient strings.
+- direct gradient tokens: `colors.primaryGradient` and `colors.diamondGradient`
+- primary gradient stop tokens: `colors.primaryStop0`, `colors.primaryStop1`, `colors.primaryStop2`
+- diamond gradient stop tokens: `colors.diamondStop0`, `colors.diamondStop1`, `colors.diamondStop2`, `colors.diamondStop3`, `colors.diamondStop4`
+
+Reference docs should stay factual. Policy and maintenance rules belong in `.ai/agent-rules/`.

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

@@ -0,0 +1,39 @@
+# 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`.
+- Use `colors.primaryGradient` and `colors.diamondGradient` when the consumer wants the package's default gradient strings directly.
+- Use the exported gradient stop tokens when the consumer needs to compose the same gradients with a different angle or stop layout.
+- 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.