core-components

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

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

1. Use semantic prop names - prefer view, size, status over custom styling
2. Leverage built-in variants - most components have pre-defined views
3. Use breakpoints for responsive - set once at root, components inherit
4. Use dataTestId - for testing automation
5. 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