This skill provides guidance for working with the @alfalab/core-components React component library. It contains patterns, conventions, and best practices for using components effectively.

Context

Library: @alfalab/core-components
Components: ~100 components available
Structure: Desktop/Mobile responsive variants, theme support, TypeScript

MCP Tools

Always use MCP tools to get component data — never read source files, CHANGELOG.md, package.json, or *.mdx docs directly from the filesystem.
If a tool returns "not found" — do not guess or invent the component API.

For tool reference and workflow: read MCP.md.

Available tools: component_list, component_info, component_demo, component_changelog.

Import Patterns

Installation

# Main library
yarn add @alfalab/core-components

# Required peer dependencies
yarn add @alfalab/core-components-config @alfalab/core-components-stack-context

Both peer packages are mandatory for the library to function correctly.

Note: Starting from @alfalab/core-components@49 the peer package names changed:

@alfalab/core-config → @alfalab/core-components-config

@alfalab/stack-context → @alfalab/core-components-stack-context

If the project uses @alfalab/core-components below v49, install the old package names instead.

@alfalab/core-components-config — provides CoreConfigContext and useCoreConfig for global configuration of responsive components (breakpoint, client type, portal container). See CoreConfig section.
@alfalab/core-components-stack-context — provides StackingContext and stackingOrder constants for z-index management. Used internally by overlay components (Modal, Popover, Toast, etc.). Rarely used directly.

Import Rule

Always import from the root package @alfalab/core-components/<component>:

import { Button } from '@alfalab/core-components/button';

Never use individual packages (@alfalab/core-components-button). Root imports are the required pattern for this library.

Build Variants

Components are shipped in three build variants:

// ES5 (default)
import { Button } from '@alfalab/core-components/button';

// ES5 with CSS Modules
import { Button } from '@alfalab/core-components/button/cssm';

// ES2020
import { Button } from '@alfalab/core-components/button/modern';

Desktop/Mobile Variants

Some components have responsive variants:

Variant	Import path
Responsive (default)	`@alfalab/core-components/button`
Desktop only	`@alfalab/core-components/button/desktop`
Mobile only	`@alfalab/core-components/button/mobile`

// Responsive (auto-detects viewport)
import { Button } from '@alfalab/core-components/button';

// Explicit desktop variant
import { ButtonDesktop } from '@alfalab/core-components/button/desktop';

// Explicit mobile variant
import { ButtonMobile } from '@alfalab/core-components/button/mobile';

Use responsive variant with breakpoint prop for automatic switching, or explicit variants when you need platform-specific behavior.

Common Patterns

Loading States

<Button loading={isLoading} onClick={handleClick}>
    Submit
</Button>

Addons/Slots

<Button leftAddons={<Icon />} rightAddons={<Badge />}>
    Label
</Button>

Typography

// Titles — use Typography package
import { Typography } from '@alfalab/core-components/typography';

<Typography.Title tag="h1" view="xlarge">Page title</Typography.Title>
<Typography.TitleResponsive tag="h2" view="large">Section title</Typography.TitleResponsive>

// Inline/block text — use Text package
import { Text } from '@alfalab/core-components/text';

<Text tag="p" view="primary-medium">Body text</Text>
<Text tag="span" view="secondary-small" rowLimit={2}>Truncated text</Text>

Icons

import { CDNIcon } from '@alfalab/core-components/cdn-icon';

// Mono icon — inherits color from parent
<CDNIcon name="monkey_m" color="#FF5733" />

// Color icon — name contains "_color"
<CDNIcon name="monkey_color_m" />

// With fallback on load error
<CDNIcon name="monkey_m" fallback={<span>?</span>} onError={() => console.warn('Icon failed')} />

Theming

Themes Package

Themes are shipped as separate package @alfalab/core-components-themes:

yarn add @alfalab/core-components-themes

Available Themes

Theme	Package path	Purpose
Mobile	`@alfalab/core-components-themes/mobile.css`	Mobile application styling
Site	`@alfalab/core-components-themes/site.css`	Site/website styling
Corp	`@alfalab/core-components-themes/corp.css`	Corporate styling
Click	`@alfalab/core-components-themes/click.css`	Click banking styling
Intranet	`@alfalab/core-components-themes/intranet.css`	Intranet styling

Dark Mode

@import '@alfalab/core-components-themes/dark.css';

Color Palettes

Default palette is bluetint. Additional palettes available:

Palette	CSS
Bluetint	`@alfalab/core-components/vars/colors-bluetint.css`
Decorative	`@alfalab/core-components/vars/colors-decorative.css`
Qualitative	`@alfalab/core-components/vars/colors-qualitative.css`
Sequential	`@alfalab/core-components/vars/colors-sequential.css`
PFM	`@alfalab/core-components/vars/colors-pfm.css`
Students	`@alfalab/core-components/vars/colors-students.css`

Import color palette:

@import '@alfalab/core-components/vars/colors-bluetint.css';

Import color in JS:

import { colorLightDecorativeOrange } from '@alfalab/core-components/vars/colors-decorative.module';

CoreConfig

Global configuration for responsive components. Instead of setting breakpoint on each component, use the context provider.

Parameters

Parameter	Type	Default	Description
`breakpoint`	`number`	`1024`	Viewport width for switching mobile/desktop
`client`	`'desktop' \| 'mobile'`	`'desktop'`	Target client for SSR
`getPortalContainer`	`() => Element \| null \| undefined`	-	Custom container for portals

Usage

import { CoreConfigContext } from '@alfalab/core-components/config';

const coreConfig = {
    breakpoint: 1024,
    client: 'desktop',
};

<CoreConfigContext.Provider value={coreConfig}>
    <App />
</CoreConfigContext.Provider>;

Using config in components

import { useCoreConfig } from '@alfalab/core-components/config';

const MyComponent = () => {
    const config = useCoreConfig();

    return <div>Breakpoint: {config.breakpoint}</div>;
};

CSS Variables

The library provides CSS custom properties for styling.

Import All Variables

@import '@alfalab/core-components/vars';

Or import as JS variables:

import * as vars from '@alfalab/core-components/vars';

vars.gap2xl === '32px'; // true

Available Variable Sets

Category	Import path
All variables	`@alfalab/core-components/vars`
Gaps/Spacing	`@alfalab/core-components/vars/gaps.css`
Border radius	`@alfalab/core-components/vars/border-radius.css`
Shadows (bluetint)	`@alfalab/core-components/vars/shadows-bluetint.css`
Typography	`@alfalab/core-components/vars/typography.css`
Mixins	`@alfalab/core-components/vars/mixins.css`

Best Practices

Use semantic prop names - prefer view, size, status over custom styling
Leverage built-in variants - most components have pre-defined views
Use breakpoints for responsive - set once at root, components inherit
Use dataTestId - for testing automation
Check component demos - always verify with official examples

Component Categories

Category	Components
Typography	Title, TitleResponsive, TitleMobile, Text
Icons	CDNIcon
Inputs	Input, Textarea, Checkbox, Radio, Switch, Select, MaskedInput
Buttons	Button, ActionButton, IconButton, CustomButton
Layout	Grid, Gap, Space, Stack, Plate
Navigation	Tabs, SidePanel, NavigationBar, Pagination
Feedback	Toast, Notification, Spinner, ProgressBar
Data Display	Badge, Tag, Amount, Skeleton, Status
Modals	Modal, Drawer, BottomSheet, Popover
Forms	FormControl, Slider, DateInput, FileUploadItem

Troubleshooting

Component not found: Check if desktop/mobile variant is exported
Props not working: Verify correct prop name via component_info
Styling issues: Ensure theme CSS is imported
Type errors: Check prop types via component_info

When to Use This Skill

Creating new UI with core-components
Finding appropriate component for a use case
Understanding component API and props
Looking up demo examples
Migrating from legacy components
Checking what changed between component versions
Migrating from older versions of components to newer ones
Migrating from deprecated components to current ones

Deprecated Components Migration

If the user references a deprecated component, inform them that it is no longer supported and no MCP data is available for it. Then offer to help migrate to the replacement:

ComponentName is deprecated and is not available in the current version of MCP. The recommended replacement is ReplacementName. Would you like me to help migrate to it?

Do not attempt to use the deprecated component's API or guess its props — always redirect to the replacement.

Deprecated	Replacement
`ConfirmationV1`	`Confirmation`
`FileUploadItemV1`	`FileUploadItem`
`PassCodeV1`	`PassCode`
`PatternLockV1`	`PatternLock`
`Alert`	`Plate`
`Badge`	`StatusBadge`
`CalendarInput`	`UniversalDateInput`
`DateInput`	`UniversalDateInput`
`DateRangeInput`	`UniversalDateInput`
`DateTimeInput`	`UniversalDateInput`
`TimeInput`	`UniversalDateInput`
`IntlPhoneInput`	`InternationalPhoneInput`
`Loader`	`Spinner`

Migration workflow

When a user's code uses a deprecated component:

1. Identify the replacement from the table above
2. component_info("ReplacementName")   → check the new API
3. component_demo("ReplacementName")   → find a relevant demo
4. Rewrite usage with the new component API

name	core-components
description	Work with @alfalab/core-components React UI library — imports, theming, MCP tools, and component patterns
license	MIT

Core Components Skill

Description