Kulcare Platform Style Guide

@kulcare/ui-kit (Single Source of Truth)
    │
    ├── src/styles/globals.css     # Design tokens + @theme inline
    ├── src/components/            # Shared components
    └── src/theme/                 # ThemeProvider, colors
            │
            ▼
    MFEs (shell, cms, growth, reports, connect)

/* ✅ CORRECT - CSS-first configuration */
@theme inline {
  --color-primary: var(--primary);
  --radius: var(--radius);
}

/* ❌ WRONG - No tailwind.config.js in v4 */
module.exports = { theme: { extend: { ... } } }

CSS Variables (:root / .dark)
        │
        ▼
@theme inline mapping
        │
        ▼
Tailwind Utilities (bg-primary, text-foreground, etc.)

// ✅ CORRECT - Use app color tokens
<div className="bg-cms text-white">CMS Context</div>
<div className="bg-growth text-white">Growth Context</div>

// ❌ WRONG - Hardcoded hex values
<div className="bg-[#078DFF] text-white">CMS Context</div>

// ✅ CORRECT - Use Kulcare brand tokens
<div className="bg-kulcare-primary text-white">Brand</div>
<div className="bg-kulcare-primary-light">Light Brand</div>

// ❌ WRONG - Hardcoded hex values
<div className="bg-[#078DFF] text-white">Brand</div>

// ✅ CORRECT - .subtle for accent light variants
<div className="bg-accent-purple-subtle text-accent-purple">Subtle Purple</div>

// ❌ WRONG - /10 pattern for accent colors
<div className="bg-accent-purple/10">Wrong pattern</div>

// ✅ CORRECT - Use Kulcare gray scale
<div className="bg-gray-50 text-gray-900">Light background</div>
<div className="bg-gray-100 text-gray-700">Subtle background</div>

// ❌ WRONG - Tailwind's default gray
<div className="bg-gray-50">Use --color-gray-50 instead</div>

--radius: 0.1875rem                    /* 3px - rounded */
--radius-sm: calc(var(--radius) * 1.067)   /* rounded-sm */
--radius-md: var(--radius)              /* rounded-md */
--radius-lg: calc(var(--radius) * 3.2)    /* rounded-lg */
--radius-xl: 0.5rem                     /* rounded-xl */

/* Light mode - subtle shadows */
--shadow-sm: 0 1px 2px rgba(0, 0, 0, 0.06);
--shadow: 0 2px 8px rgba(0, 0, 0, 0.08);
--shadow-md: 0 2px 8px rgba(0, 0, 0, 0.10);
--shadow-lg: 0 7px 14px rgba(0, 0, 0, 0.12), 0 3px 6px rgba(0, 0, 0, 0.06);
--shadow-xl: 0 5px 25px rgba(0, 0, 0, 0.15);

/* Dark mode - higher opacity for visibility on dark surfaces */
--shadow-sm: 0 1px 2px rgba(0, 0, 0, 0.15);
--shadow: 0 2px 8px rgba(0, 0, 0, 0.20);
--shadow-md: 0 2px 8px rgba(0, 0, 0, 0.25);
--shadow-lg: 0 7px 14px rgba(0, 0, 0, 0.30), 0 3px 6px rgba(0, 0, 0, 0.15);
--shadow-xl: 0 5px 25px rgba(0, 0, 0, 0.15);

<div className="shadow-sm" />   {/* Subtle card hover */}
<div className="shadow" />       {/* Card default */}
<div className="shadow-md" />     {/* Modal, popover */}
<div className="shadow-lg" />     {/* Dropdown menus */}
<div className="shadow-xl" />     {/* Full-page overlays */}

<ResponsiveContainer width="100%" height={300}>
  <LineChart data={data}>
    <Line type="monotone" stroke="var(--color-chart-1)" dataKey="revenue" />
    <Line type="monotone" stroke="var(--color-chart-2)" dataKey="appointments" />
  </LineChart>
</ResponsiveContainer>

<p className="leading-tight">Tight text for headings</p>
<p className="leading-normal">Normal body text</p>
<p className="leading-relaxed">Relaxed text for reading</p>

/* Light mode sidebar */
--sidebar: hsl(220 10% 94%);           /* Light gray - distinguishable from background */
--sidebar-foreground: hsl(228 14% 24%);  /* Dark text on light sidebar */
--sidebar-primary: hsl(211 100% 52%);    /* Primary blue accent */
--sidebar-primary-foreground: hsl(0 0% 100%);
--sidebar-accent: hsl(211 100% 52% / 0.1); /* 10% opacity primary */
--sidebar-accent-foreground: hsl(211 100% 52%);
--sidebar-border: hsl(210 18% 92%);
--sidebar-ring: hsl(211 100% 52%);

/* Dark mode sidebar - Ant Design dark sider #001529 */
--sidebar: hsl(220 27% 8%);             /* Deep dark blue-gray */
--sidebar-foreground: hsl(0 0% 65%);     /* Light gray text */
--sidebar-primary: hsl(211 100% 52%);    /* Primary blue accent */
--sidebar-primary-foreground: hsl(0 0% 100%);
--sidebar-accent: hsl(220 13% 14%);
--sidebar-accent-foreground: hsl(211 100% 52%);
--sidebar-border: hsl(220 27% 12%);
--sidebar-ring: hsl(211 100% 52%);

// ✅ CORRECT - Single import from ui-kit
import { Button, Card, Input, PageHeader } from "@kulcare/ui-kit"

// ❌ WRONG - Direct imports from component paths
import { Button } from "@kulcare/ui-kit/src/components/ui/button"
import { Card } from "@kulcare/ui-kit/src/components/ui/card"

// ✅ CORRECT - Using variant prop
<Button variant="default">Primary Action</Button>
<Button variant="destructive">Delete</Button>
<Button variant="outline">Cancel</Button>
<Button variant="secondary">Secondary</Button>
<Button variant="ghost">Subtle</Button>
<Button variant="link">Text Link</Button>

// ✅ CORRECT - Using size prop
<Button size="default">Default</Button>
<Button size="sm">Small</Button>
<Button size="lg">Large</Button>
<Button size="icon">Icon</Button>

// ❌ WRONG - className for colors
<Button className="bg-blue-600 hover:bg-blue-700">Primary</Button>

// ❌ WRONG - variant with className override
<Button variant="default" className="bg-red-500">Confusing</Button>

// ✅ CORRECT - Composition pattern
import { Card, CardHeader, CardTitle, CardContent } from "@kulcare/ui-kit"

<Card>
  <CardHeader>
    <CardTitle>Patient Details</CardTitle>
  </CardHeader>
  <CardContent>
    <p>Patient information here</p>
  </CardContent>
</Card>

// ❌ WRONG - Div with border classes
<div className="rounded-lg border bg-card p-6">
  <h3 className="text-lg font-semibold">Patient Details</h3>
  <p>Patient information here</p>
</div>

// ✅ CORRECT - Using PageHeader
import { PageHeader, Button } from "@kulcare/ui-kit"
import { Plus, Download } from "lucide-react"

<PageHeader
  icon={<Users className="h-6 w-6" />}
  title="Patients"
  description="Manage patient records"
  actions={
    <div className="flex gap-2">
      <Button variant="outline" size="sm">
        <Download className="h-4 w-4 mr-2" />
        Export
      </Button>
      <Button size="sm">
        <Plus className="h-4 w-4 mr-2" />
        Add Patient
      </Button>
    </div>
  }
/>

import { type } from "@kulcare/ui-kit/lib/typography"

// Page structure
<span className={type.pageTitle}>Page Title</span>
<span className={type.sectionHeading}>Section</span>
<span className={type.subsectionHeading}>Subsection</span>
<span className={type.cardTitle}>Card Title</span>

// Body content
<span className={type.bodyText}>Body text</span>
<span className={type.bodyTextLarge}>Large body</span>
<span className={type.caption}>Caption</span>

// Forms
<span className={type.formLabel}>Label</span>
<span className={type.formError}>Error message</span>

// Medical data (use monospace)
<span className={type.medicalValue}>120/80 mmHg</span>
<span className={type.vitalSign}>98 bpm</span>
<span className={type.patientId}>MRN: 12345678</span>
<span className={type.prescription}>Amoxicillin 500mg</span>

// Status
<span className={type.statusSuccess}>Normal</span>
<span className={type.statusWarning}>Warning</span>
<span className={type.statusError}>Critical</span>

import { tableHeaderStyles, tableCellStyles } from "@kulcare/ui-kit"

<TableHead className={tableHeaderStyles.currency}>Amount</TableHead>
<TableCell className={tableCellStyles.currency}>₹12,500</TableCell>
<TableHead className={tableHeaderStyles.status}>Status</TableHead>
<TableCell className={tableCellStyles.status}>
  <span className="status-normal">Active</span>
</TableCell>

// ✅ CORRECT - Status classes
<span className="status-normal">Normal (green)</span>
<span className="status-warning">Warning (amber)</span>
<span className="status-critical">Critical (red)</span>

// ❌ WRONG - Hardcoded status colors
<span className="text-green-500">Normal</span>
<span className="text-amber-500">Warning</span>
<span className="text-red-500">Critical</span>

import { ThemeProvider } from "@kulcare/ui-kit"

function App() {
  return (
    <ThemeProvider defaultTheme="system" storageKey="kulcare-ui-theme">
      {children}
    </ThemeProvider>
  )
}

import { useTheme } from "@kulcare/ui-kit"

function ThemeToggle() {
  const { theme, setTheme, resolvedTheme } = useTheme()

  return (
    <Button
      variant="ghost"
      onClick={() => setTheme(resolvedTheme === "light" ? "dark" : "light")}
    >
      {resolvedTheme === "light" ? "🌙" : "☀️"}
    </Button>
  )
}

/* Light mode - :root defaults */
:root {
  --background: hsl(210 20% 98%);
  --primary: hsl(211 100% 52%);
}

/* Dark mode - .dark overrides */
.dark {
  --background: hsl(220 10% 8%);
  --primary: hsl(211 90% 56%);
}

--primary: hsl(211 100% 52%);

@theme inline {
  --color-primary: var(--primary);
}

<div className="bg-primary text-primary-foreground">Content</div>

import { getThemeScriptTag } from "@kulcare/ui-kit"

const html = `
  <head>
    ${getThemeScriptTag()}
    <!-- other head content -->
  </head>
`

/* globals.css */
@theme inline {
  --color-primary: var(--primary);
  --radius: var(--radius);
}

/* ✅ CORRECT - v4 pattern */
@import "tailwindcss";
@import "tw-animate-css";

/* ❌ WRONG - v3 pattern */
@tailwind base;
@tailwind components;
@tailwind utilities;

@custom-variant dark (&:where(.dark, .dark *));

@utility scrollbar-hide {
  -ms-overflow-style: none;
  scrollbar-width: none;
}
.scrollbar-hide::-webkit-scrollbar {
  display: none;
}

@source "../**/*.{ts,tsx}";

// vite.config.ts
import tailwindcss from "@tailwindcss/vite"
import react from "@vitejs/plugin-react"

export default defineConfig({
  plugins: [react(), tailwindcss()],
})

// ❌ WRONG - Hardcoded colors
<div className="bg-blue-500 text-white" />
<div className="text-[#078DFF]" />
<div style={{ backgroundColor: "#ffffff" }} />

// ✅ CORRECT - Use design tokens
<div className="bg-primary text-primary-foreground" />
<div className="text-primary" />
<div className="bg-background" />

// ❌ WRONG - Custom button with hardcoded styles
function CustomButton({ children, variant }) {
  return (
    <button className={`
      ${variant === "primary" ? "bg-blue-600" : "bg-gray-200"}
      px-4 py-2 rounded-md
    `}>
      {children}
    </button>
  )
}

// ✅ CORRECT - Use ui-kit Button
import { Button } from "@kulcare/ui-kit"
<Button variant="default">Primary</Button>

// ❌ WRONG - v3 tailwind.config.js
module.exports = {
  theme: {
    extend: {
      colors: { primary: "#078DFF" }
    }
  }
}

// ✅ CORRECT - CSS-first via @theme inline

// ❌ WRONG - Mixed patterns
import { Button } from "@kulcare/ui-kit"
<Button className="hsl(var(--primary))" />  // v3 pattern

// ✅ CORRECT - v4 pattern
<Button variant="default" />  // Using variant prop

// ❌ WRONG - Hardcoded radius
<div className="rounded-[12px]" />

// ✅ CORRECT - Use radius tokens
<div className="rounded-xl" />  /* Uses --radius-xl */

// ❌ WRONG - Non-existent shadow
<div className="shadow-xs" />

// ✅ CORRECT - Use defined shadow tokens
<div className="shadow-sm" />   /* --shadow-sm: 0 1px 2px rgba(0, 0, 0, 0.06) */
<div className="shadow" />       /* --shadow: 0 2px 8px rgba(0, 0, 0, 0.08) */
<div className="shadow-md" />     /* --shadow-md: 0 2px 8px rgba(0, 0, 0, 0.10) */
<div className="shadow-lg" />     /* --shadow-lg: layered rgba(0, 0, 0, ...) */
<div className="shadow-xl" />     /* --shadow-xl: 0 5px 25px rgba(0, 0, 0, 0.15) */

// tailwind.config.js
module.exports = {
  presets: [require("@kulcare/ui-kit/tailwind-preset")],
  content: ["./src/**/*.{js,jsx}"]
}

/* index.css */
@import "@kulcare/ui-kit/src/styles/globals.css";
@import "tailwindcss";

background-color: hsl(var(--primary));
color: hsl(var(--foreground));

background-color: var(--primary);
color: var(--foreground);

import "@kulcare/ui-kit/src/styles/globals.css"
@import "tailwindcss/base";
@import "tailwindcss/components";
@import "tailwindcss/utilities";

@import "@kulcare/ui-kit/src/styles/globals.css";
@import "tailwindcss";
@import "tw-animate-css";