ui-lib

UI component library for TopMessage products, built on top of Ant Design with:

• shared design tokens (CSS variables)
• shared Ant Design theme tokens
• shared locale mapping

Core Theme Architecture

The theming entrypoint is TopMessageConfigProvider in src/components/theme/TopMessageConfigProvider.tsx.

It applies three concerns in one place:

1. Design tokens (CSS variables)

   • Imports src/styles/variables.css.
   • Provides palette, spacing, radius, and shared style primitives used by all components.

2. Ant Design locale

   • Maps language (de, fr, it, es, nl, pl, sv, en) through src/components/locale.ts.
   • Passes the matching Ant locale object to Ant Design ConfigProvider.

3. Ant Design theme

   • Uses mergeTopMessageTheme(themeOverrides) from src/components/theme/antdTheme.ts.
   • Merges a shared base + TopMessage component tokens + optional consumer overrides.

Theme Layers

Theme composition in antdTheme.ts is structured as:

• baseToken / baseTheme: foundation-level defaults (primary color, border defaults, base font).
• topMessageTheme: standard component-level tokens (for example Segmented, Slider, InputNumber, Select).
• mergeTopMessageTheme(overrides): safe merge point for app/product-specific overrides.

ConfigProvider Usage Rules

1) Required top-level wrapper

Wrap app roots and Storybook roots with TopMessageConfigProvider.

import { TopMessageConfigProvider } from '@top-message/ui-lib';

<TopMessageConfigProvider language="en">
    <App />
</TopMessageConfigProvider>;

2) Default component behavior

Components should rely on the top-level provider for:

• locale
• standard theme tokens
• global token consistency

Avoid adding local ConfigProvider unless there is a clear scoped requirement.

3) When local ConfigProvider is acceptable

Use a local ConfigProvider only for intentional scoped overrides that must not affect all components.

Example: OTP input styling uses an Input token override (otpInputTheme), and keeping it local prevents global changes to every Input/Password/TextArea.

Practical Notes

• language controls Ant Design locale text.
• locale props in some date/time components are still used for formatting behavior (for example en-US 12h/time formats), even though Ant locale is global.
• themeOverrides on TopMessageConfigProvider is the supported extension point for product-level theming.