MBT UI Kit

Reusable React UI primitives, typography, and design tokens for MBT applications.

Installation

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

import { Button, Heading, Input, Text } from 'mbt-ui-kit';
import 'mbt-ui-kit/styles';

function ProfileForm() {
  return (
    <div>
      <Heading level={2}>Profile</Heading>
      <Text muted>Update your account details.</Text>
      <Input label="Email" placeholder="[email protected]" fullWidth />
      <Button type="button">Save</Button>
    </div>
  );
}

Font loading in consumer app

Default setup: import mbt-ui-kit/styles once at the app shell. This already loads the package font-face declarations.

import 'mbt-ui-kit/styles';

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.

import 'mbt-ui-kit/styles';

Example with bundler-resolved asset URLs:

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,
];

Example preload tags:

<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.

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.

Components

Primary exports include:

• Button
• Input
• Loader
• Heading
• Text
• Metric
• MenuButton
• SearchIcon
• GraduationCapIcon

For richer package examples, use .ai/agent-examples/README.md.

Design Tokens

TypeScript or JavaScript

Use token exports for inline styles, styled-components, or utility layers.

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],
};

Available token groups:

• tokens
• colors
• fonts
• fontSizes
• fontWeights
• fontFeatures
• spacing
• radius
• zIndex
• transitions

The colors group also includes gradient stop tokens:

• primaryStop0, primaryStop1, primaryStop2
• diamondStop0, diamondStop1, diamondStop2, diamondStop3, diamondStop4

Gradient composition from stop colors:

import { colors } from 'mbt-ui-kit/tokens';

const heroStyle = {
  background: `linear-gradient(45deg, ${colors.primaryStop0} 0%, ${colors.primaryStop1} 40%, ${colors.primaryStop2} 100%)`,
};

Custom angle composition:

import { colors } from 'mbt-ui-kit/tokens';

const accentStyle = {
  background: `linear-gradient(90deg, ${colors.diamondStop0} 0%, ${colors.diamondStop1} 25%, ${colors.diamondStop2} 50%, ${colors.diamondStop3} 75%, ${colors.diamondStop4} 100%)`,
};

CSS Custom Properties

import 'mbt-ui-kit/tokens.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);
  transition: all var(--mbt-transition-fast);
}

.hero {
  background: linear-gradient(
    45deg,
    var(--mbt-color-primary-stop-0) 0%,
    var(--mbt-color-primary-stop-1) 40%,
    var(--mbt-color-primary-stop-2) 100%
  );
}

Sass Tokens

@use 'mbt-ui-kit/src/styles/tokens' as *;

.panel {
  background-color: $surface;
  color: $text-primary;
  padding: $space-4;
  border-radius: $radius-sm;
}

.hero {
  background: linear-gradient(
    45deg,
    $diamond-stop-0 0%,
    $diamond-stop-1 25%,
    $diamond-stop-2 50%,
    $diamond-stop-3 75%,
    $diamond-stop-4 100%
  );
}

Development

pnpm install
pnpm build
pnpm lint
pnpm format
pnpm storybook

This repo standardizes on pnpm only.

Notes

• 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.