🎨 @kalbii/core-ui Design System

The centralized, production-grade design system, layout primitives, component library, and AI coding agent directives for the Kalbii software suite (billing.frontend, crm.frontend, account.kalbii.frontend, hrm.app).

🌟 Key Architectural Pillars

1. Design Tokens & Theme Sync: Single source of truth for colors, typography scale, spacing, radii, shadows, Tailwind presets, and Ant Design KalbiiProvider.
2. Page-Level Layout Primitives: Structural page wrappers (PageLayout, PageHeader, PageFilterBar, PageContentCard, FormLayout, DetailLayout) guaranteeing 100% layout consistency across all products.
3. Pure UI Components: Zero domain logic; 100% reusable UI building blocks (AppButton, AppSearchInput, StatCard, AppStatusTag, AppTable, AppDrawer, ConfirmDialog, Skeleton).
4. Production-Grade Sonner Toast Engine: Micro-animated notification system (KalbiiToaster & kalbiiToast).
5. AI Agent Integration: Strict rulebook (AGENTS.md) and component blueprint catalog (llms.txt) so AI agents generate 100% compliant code.
6. Visual Testing & Storybook: Full story suite for interactive visual verification.
7. DevOps & Deployment Pipelines: Complete publishing and CI/CD guide (docs/DEVOPS.md).

📦 Package Distribution & Import Structure

// 1. Root Export (Components, Layouts, Tokens, Provider)
import { 
  PageLayout, 
  PageHeader, 
  PageActions, 
  PageFilterBar, 
  AppFilterGroup, 
  PageToolbar, 
  PageContentCard, 
  AppTable, 
  AppPagination, 
  AppButton, 
  AppSearchInput, 
  StatCard, 
  AppStatusTag, 
  KalbiiProvider, 
  KalbiiToaster, 
  kalbiiToast, 
  typography 
} from '@kalbii/core-ui';

// 2. Sub-path Exports
import { kalbiiTokens } from '@kalbii/core-ui/tokens';
import { KalbiiProvider } from '@kalbii/core-ui/provider';

🚀 Quick Start & Integration Guide

Step 1: Install Package Dependency

In your product repository (package.json):

{
  "dependencies": {
    "@kalbii/core-ui": "file:../core-ui"
  }
}

Step 2: Extend Tailwind Configuration

In your product's tailwind.config.cjs:

module.exports = {
  presets: [require('@kalbii/core-ui/tailwind')],
  content: ['./src/**/*.{js,ts,jsx,tsx}'],
};

Step 3: Wrap Main Application Entry Point

In your main App.tsx or main.tsx:

import { KalbiiProvider, KalbiiToaster } from '@kalbii/core-ui';

export default function App() {
  return (
    <KalbiiProvider>
      <KalbiiToaster position="top-right" />
      <YourAppRoutes />
    </KalbiiProvider>
  );
}

📐 Layout Primitives API

1. Standard List Page Pattern

<PageLayout>
  <PageHeader
    title="Invoices"
    subtitle="Manage customer invoices and payments"
    actions={
      <PageActions>
        <AppButton variant="outline">Export CSV</AppButton>
        <AppButton variant="primary">Create Invoice</AppButton>
      </PageActions>
    }
  />

  <PageFilterBar
    left={
      <AppFilterGroup>
        <AppSearchInput placeholder="Search invoice number..." onSearch={handleSearch} />
      </AppFilterGroup>
    }
    right={
      <PageToolbar>
        <AppButton variant="outline">Columns</AppButton>
      </PageToolbar>
    }
  />

  <PageContentCard padding="none">
    <AppTable columns={columns} dataSource={data} />
    <div className="border-t border-slate-100 px-4 py-2">
      <AppPagination current={page} pageSize={pageSize} total={total} onChange={setPage} />
    </div>
  </PageContentCard>
</PageLayout>

2. Create / Edit Form Page Pattern

<FormLayout
  title="Create Organization"
  subtitle="Enter organization details and tax settings"
  maxWidth="md"
  actions={
    <>
      <AppButton variant="outline">Cancel</AppButton>
      <AppButton variant="primary">Save Organization</AppButton>
    </>
  }
>
  {/* Form Fields */}
</FormLayout>

🧩 Core UI Components Summary

| Component | Description & Key Props | | :--- | :--- | | AppButton | Standard button (variant="primary" \| "outline" \| "danger" \| "secondary", loading, disabled) | | AppInput | Standard text input, AppInput.Password, AppInput.OTP, AppInput.TextArea with auto-trim & number guards | | AppSelect | Standard dropdown select wrapper & AppSelectOption | | AppDatePicker | Standard date picker & AppRangePicker defaulting to DD-MM-YYYY | | AppCheckbox | Standard checkbox wrapper & AppCheckboxGroup | | AppSwitch | Standard toggle switch | | AppRadio | Standard radio button, AppRadioGroup, AppRadioButton | | AppForm | Standard form layout (<AppForm>, <AppFormItem>, useAppForm()) | | AppSearchInput | Constrained debounced search bar ($300\text{px}$ – $420\text{px}$) with search icon & clear button | | StatCard | Dashboard KPI metric box (title, value, trend, trendDirection="up" \| "down" \| "neutral", icon) | | AppStatusTag | Intent status tag (intent="success" \| "warning" \| "danger" \| "info" \| "neutral") | | AppTable | Generic table wrapper (<AppTable<T>>) with standard header styling & built-in empty state | | AppPagination | Customized pagination bar with row-per-page selector | | AppDrawer | Slide-over panel (sizePreset="sm" \| "md" \| "lg" \| "xl", sticky header/footer) | | AppModal | Standard pop-up dialog wrapper | | ConfirmDialog | Destructive confirmation modal (intent="danger", title, description, onConfirm) | | KalbiiToaster & kalbiiToast | Sonner toast engine (kalbiiToast.success(), kalbiiToast.error(), kalbiiToast.warning(), kalbiiToast.info()) | | Skeleton | Loading placeholders (TableSkeleton, CardSkeleton) |

🔤 Semantic Typography Class Map (typography)

Instead of component wrappers, developers use native HTML tags with standard typography utility maps:

import { typography } from '@kalbii/core-ui';

<h1 className={typography.h1}>Page Title (30px Bold)</h1>
<h2 className={typography.h2}>Section Title (24px Semibold)</h2>
<h3 className={typography.h3}>Subsection Title (18px Medium)</h3>
<p className={typography.subtitle}>Subtitle / Description Text (14px Slate-600)</p>
<p className={typography.body}>Body Text (14px Slate-800)</p>
<span className={typography.caption}>Caption / Subtext (12px Slate-500)</span>
<label className={typography.label}>Form Field Label (14px Medium)</label>

Directive & Rules (AGENTS.md)

When an AI coding agent builds a new screen, it strictly follows AGENTS.md:

1. Rule 1: ALWAYS use <PageLayout>, <PageHeader>, <PageFilterBar>, and <PageContentCard> for list screens.
2. Rule 2: Use variant="primary" / variant="outline" / variant="danger" for buttons.
3. Rule 3: NEVER write raw div containers, raw hex colors (#FA6018), or raw pixel utility classes (text-[13px]).
4. Rule 4: NEVER import raw antd components directly. Always use @kalbii/core-ui wrappers.
5. Rule 5: Import Lucide icons directly (import { Plus } from 'lucide-react').

📚 Visual Testing & Storybook

Run Storybook locally to visually inspect, test, and document components:

# In c:\Users\admin\Desktop\core-ui
npm run storybook

Access the interactive dashboard at http://localhost:6006 (or 6007).

🔄 Extension Process: How to Add New Components

When introducing a new component to @kalbii/core-ui:

1. Ensure the component is 100% Pure UI (zero business domain types).
2. Place component code in src/components/<ComponentName>.tsx.
3. Export component in src/components/index.ts.
4. Create a Storybook story in src/stories/<ComponentName>.stories.tsx.
5. Run npm run typecheck and npm run build to verify compilation.
6. Update this README.md and docs/ai-component-catalog.md.