@widgetic/design-system 0.3.79 → 0.3.81

package/README.md

@@ -1,163 +1,868 @@
-# Widgetic Design System (`@widgetic/design-system`)
-
-This is the official design system package for the Widgetic platform.
-
-Built with SvelteKit and Tailwind CSS (using shadcn-svelte components as a base), it provides reusable UI components, global styles, design tokens, icons, and fonts for building consistent interfaces across Widgetic projects.
-
-## Features
-
-*   **Styles:** Exports global CSS styles, including CSS variables for design tokens (colors, spacing, etc.) and utility classes based on Tailwind CSS v4.
-*   **UI Components:** A library of Svelte components built upon [shadcn-svelte](https://shadcn-svelte.com/), providing elements like Buttons, Cards, Dialogs, Input fields, Accordions, etc. Includes both base shadcn components and custom Widgetic components.
-*   **Icons:** Exports icons from [Lucide Svelte](https://lucide.dev/) and potentially [Tabler Icons](https://tabler-icons.io/), accessible via named imports.
-*   **Fonts:** Includes specific font families used across the Widgetic platform. Font files themselves are exported, but consuming projects need to ensure they are loaded correctly (e.g., via CSS `@import` or `<link>`).
-
-## Installation
-
-1.  **Install the package:**
-    ```bash
-    npm install @widgetic/design-system
-    ```
-
-2.  **Install Peer Dependencies:** This package relies on several peer dependencies that you need to install in your project if you haven't already. Ensure your `package.json` includes compatible versions:
-    ```json
-    "devDependencies": {
-      // Required by Tailwind v4 setup
-      "postcss": "^8.x.x",
-      "@tailwindcss/postcss": "^4.x.x", 
-      "tailwindcss": "^4.x.x", 
-      // Required by SvelteKit/Svelte 5
-      "svelte": "^5.x.x",
-      "@sveltejs/kit": "^2.x.x",
-      // Required by shadcn-svelte components used internally
-      "bits-ui": "^1.x.x",
-      "clsx": "^2.x.x",
-      "tailwind-merge": "^2.x.x",
-      "tailwind-variants": "^0.x.x",
-      "svelte-sonner": "^0.x.x",
-      // Required by specific components if used
-      "@internationalized/date": "^3.x.x",
-      "lucide-svelte": "^0.x.x",
-      "@tabler/icons-svelte": "^3.x.x",
-      "vaul-svelte": "^1.x.x-next.x"
-      // ... other project devDependencies
-    }
-    ```
-    *Note: Replace `x.x` with appropriate version numbers compatible with the design system's requirements (check its `package.json` `peerDependencies` for specifics).* Make sure you have `postcss.config.js` (or `.mjs`) set up.
-
-## Setup
-
-### 1. Tailwind Configuration
-
-To ensure Tailwind processes the design system's classes and applies your project's customizations correctly, configure your project's `tailwind.config.ts` (or `.js`) to use the design system's configuration as a preset:
+# Widgetic Design System
 
+This is the design system package for the Widgetic platform.
+
+It is built with SvelteKit and TailwindCSS and exports styles(with tailwind), ui components(with shadcn), icons and fonts for the entire platform.
+
+## Initial Setup (Required for Team Development)
+
+After cloning the repository, run the install script which handles dependencies and Git configuration:
+
+```bash
+npm run i
+```
+
+This script installs dependencies, links the package, and automatically configures Git for proper case sensitivity. This prevents file case conflicts between different operating systems (macOS, Windows, Linux). **All team members should run this** when first working with the design system.
+
+0. Styles: it uses tailwindcss and exports global styles and design tokens that are imported in the project where the design system is imported:
+
+```svelte
+<script>
+  import '@widgetic/design-system/styles';
+</script>
+```
+
+0.1. To add new fonts: 
+- Add the font in the fonts folder.
+- Add the font-face rule and the class in the fonts.css file and then the class can be used anywhere in the projects that import the design system's styles:
+```css
+ /* First font-face rule */
+  @font-face {
+    font-family: 'BL Melody';
+    src: url('@widgetic/design-system/fonts/BLMelody/BLMelody-ExtraLight.woff2') format('woff2');
+    font-weight: 200;
+    font-style: normal;
+    font-display: swap;
+  }
+  
+  /* Second fonte class(can be any custom name) */
+  .font-bl-melody-extra-light {
+    font-family: 'BL Melody';
+    font-weight: 200;
+  }
+```
+
+- Use the font-family in any class in the global.css file if needed like this:
+```css
+.my-button-class {
+  /* other CSS properties */
+  background-color: red;
+
+  /* font-family properties here */
+  font-family: 'BL Melody', sans-serif;
+  font-weight: 200;
+  font-style: normal;
+}
+```
+
+1.1. Components: It uses the SHADCN UI components for basic ui components and custom components for the Widgetic platform.
+
+a. (Re)Install latest all shadcn components:
+
+```bash
+npm run i-shadcn
+```
+
+At prompt answer like this:
+```bash
+Which style would you like to use?
+│  Default
+│
+◇  Which base color would you like to use?
+│  Slate
+│
+◇  Where is your global CSS file? (this file will be overwritten)
+│  src/app.css (!!! add local project's css file as we don't want to overwrite our project's global styles)
+│
+◇  Where is your Tailwind config located? (this file will be overwritten)
+│  tailwind.config.ts
+│
+◇  Configure the import alias for components:
+│  $lib/components
+│
+◆  Configure the import alias for utils:
+│  $lib/utils
+│
+◆  Configure the import alias for hooks:
+│  $lib/hooks
+│
+◆  Configure the import alias for ui:
+│  $lib/components/ui
+
+
+Components to install:
+│  accordion, badge, button, calendar, range-calendar, card, checkbox, collapsible, dialog,
+│  drawer, dropdown-menu, input, input-otp, label, popover, progress, radio-group, scroll-area,
+│  select, separator, slider, switch, table, tabs, textarea, tooltip
+│
+◆  Ready to install components and dependencies?
+│  ● Yes / ○ No
+...
+tooltip installed at src/lib/components/ui/tooltip
+│
+◇  Dependencies installed with npm
+│
+◇  Config file components.json updated
+│
+└  Success! Component installation completed.
+
+!!! On commit the change uncheck the grouped components(Table, Select, etc.) baerel file.
+```
+
+b. Installing the shadcn-svelte package:
+
+```bash
+npx shadcn-svelte@next init
+```
+
+c. Add one or more SHADCN UI components:
+
+```bash
+npx shadcn-svelte@next add <component-name component-name2>
+```
+
+d. Check tailwind.config.ts file to see if you didn't lose any of the project's config.
+
+e. Check /src/lib/utils/utils.ts file to see if you didn't lose any of the project's utils.
+
+f. Check /src/lib/hooks/hooks.ts file to see if you didn't lose any of the project's hooks.
+
+g. Check SHADCN UI Grouped components(eg. Table or Select) barel file to export a constant with the subcomponents.
+We do that just be wrapping the first part of the export statement with a constant named as the component ("Table" here) and replace the exported subcomponent: "Table" in this case with "TableRoot".
 ```ts
-// tailwind.config.ts
-import type { Config } from 'tailwindcss';
-import designSystemPreset from '@widgetic/design-system/tailwind.config'; // Import the preset
+// src/lib/components/ui/table/index.ts
+const Table = {
+	Root,
+	Body,
+	Caption,
+	Cell,
+	Footer,
+	Head,
+	Header,
+	Row
+};
+
+export {
+	Table, // add the constant name "Table" that will be the namespace for the grouped components
+	Root as TableRoot, // Change the name of the Root component from "Table" to "TableRoot"
+	Body as TableBody,
+	Caption as TableCaption,
+	Cell as TableCell,
+	Footer as TableFooter,
+	Head as TableHead,
+	Header as TableHeader,
+	Row as TableRow,
+};
+```
+Then you can import and use the namespace in the project:
+```svelte
+import { Table } from '@widgetic/design-system';
+```
 
-const config = {
-    // Use the design system preset
-    presets: [designSystemPreset],
-
-    // Add your project's paths AND the design system's path to the content array
-    content: [
-        './src/**/*.{html,js,svelte,ts}', // Your project files
-        './node_modules/@widgetic/design-system/dist/**/*.{html,js,svelte,ts}' // Design system package files
-    ],
-
-    // You can optionally extend the theme further here
-    theme: {
-        extend: {
-            // Your project-specific theme extensions
-        }
-    },
-
-    plugins: [
-        // Your project-specific plugins (if any)
+h. If there is a component that looks compound but is not, add the @notCompound marker in the file:
+```ts
+// @notCompound
+export {
+	Root,
+	Scrollbar,
+	//,
+	Root as ScrollArea,
+	Scrollbar as ScrollAreaScrollbar,
+};
+```
+ScrollArea is not a compound component but it looks like one.
+
+h. If you want to export only the main component and not the subcomponents, add the @noSubcomponents marker in the file:
+```ts
+// @noSubcomponents
+export {
+	Day,
+	Cell,
+	Grid,
+	Header,
+	Months,
+	GridRow,
+	Heading,
+	GridBody,
+	GridHead,
+	HeadCell,
+	NextButton,
+	PrevButton,
+	//
+	Root as RangeCalendar,
+};
+```
+RangeCalendar share the same subcomponents with Calendar so we don't want to export them.
+
+1.2. In general we should follow the shadcn-svelte approach to export the components with more subcomponents or compound components.
+
+2. Icons: It also uses the Lucide and Tabler icons or custom icons for the platform.
+
+```svelte
+import { IconName } from '@widgetic/design-system/icons';
+```
+
+
+3. Fonts: The design system uses Google Fonts that we need to import in the project where the design system is imported.
+
+```svelte
+import { FontName } from '@widgetic/design-system/fonts';
+```
+
+
+## Performance Optimization for Linked Design System
+
+When using the linked design system in development mode, you may experience slow initial load times and delayed navigation. This is because Vite's default file watching behavior can create performance issues when working with linked packages.
+
+### Common Issues:
+- Long initial loading time (>1 minute)
+- "Pending" status on network requests when navigating between pages
+- High CPU usage during development
+
+### Solution:
+
+#### 1. For consuming projects (like site, context-chat, etc.):
+
+Optimize your `vite.config.ts` with these settings:
+
+```ts
+server: {
+  watch: {
+    // Don't use polling (which causes high CPU usage)
+    // Remove the following if present:
+    // usePolling: true,
+    // interval: 2000,
+    // binaryInterval: 2000,
+    
+    // Ignore all node_modules EXCEPT the design system dist folder if needed
+    ignored: [
+      '**/node_modules/**',
+      '**/*.map',
+      '**/*.d.ts',
+      '**/*.log'
     ]
-} satisfies Config;
+  },
+  hmr: {
+    // Reduce timeout for faster updates
+    timeout: 2000
+  }
+},
+optimizeDeps: {
+  // Don't include the design system in optimizeDeps
+  // Remove this if present:
+  // include: ['@widgetic/design-system']
+  
+  // Keep other settings
+  exclude: ['@sveltejs/kit']
+},
+build: {
+  // Add these for faster builds
+  sourcemap: false,
+  reportCompressedSize: false
+}
+```
 
-export default config;
+#### 2. For production deployments:
+
+When deploying to production, you'll use the published npm package instead of the linked development version. No special configuration is needed beyond the optimizations above.
+
+#### 3. Development vs. Production Mode:
+
+The design system's `vite.config.ts` already includes development-specific optimizations. When publishing the package to npm, the built version will be used, and these configurations won't affect end users.
+
+**Note:** These optimizations are only needed during development with linked packages and won't affect the published npm package performance.
+
+
+## How to link DS into another project and develop it(first time)
+
+0. Go into the DS project and link it in the system and start it with: `cd Frontend/design-system && npm link && npm run dev`
+
+1. Go into the consuming project and make sure you have installed tailwindcss and postcss by checking in package.json if it has these dependencies:
+
+```json
+"dependencies": {
+"tailwindcss": "^3.4.16",
+"@tailwindcss/postcss": "^4.1.2",
+}
 ```
 
-*   **Presets:** The `presets` array applies the design system's base configuration (colors, fonts, plugins like `tailwindcss-animate`).
-*   **Content:** It's crucial to include the path to the installed design system package (`./node_modules/@widgetic/design-system/dist/...`) in your `content` array. This allows Tailwind to scan the design system's components and generate the necessary utility classes.
+Also make sure you have a 'tailwind.config.ts'(if there is a '.js' version rename it to '.ts') and a 'postcss.config.js' file.
+(optional)If not already in the project follow the install guide at: https://tailwindcss.com/docs/installation/using-postcss.
+
+
+2. Also add these dependencies and overrides(that are needed for DS) with these exact versions into the package.json file of the consuming project:
+```json package.json
+"dependencies": {
+    "@sveltejs/kit": "^2.20.2",
+		"svelte": "^5.25.6",
+		"@tabler/icons-svelte": "^3.24.0",
+		"lucide-svelte": "^0.468.0",
+		"bits-ui": "^1.3.0",
+    "svelte-sonner": "^0.3.28",
+
+    "tailwind-merge": "^2.5.2",
+		"tailwind-variants": "^0.2.1",
+		"tailwindcss-animate": "^1.0.7",
+}
+
+"overrides": {
+		"bits-ui": {
+			"@melt-ui/svelte": "^0.86.3"
+		},
+		"vaul-svelte": {
+			"bits-ui": {
+				"@melt-ui/svelte": "^0.86.3"
+			}
+		},
+    "svelte": "^5.25.6"
+	},
+```
+
+Also keep the exact versions mentioned above and check and remove these dependencies from devDependencies or peerDependencies in the package.json of the consuming project.
+
+3. Also add this "i"(install) and "lds"(link) scripts into the package.json file exactly as following:
+"i": "rm -rf node_modules && npm i && npm run lds",
+"lds": "volta run npm link @widgetic/design-system",
+Then run it with: `npm run i`
+
+4. Also add these "dev" scripts into the package.json file for usual start of the consuming project:
+"dev": "npm run dev-sv -- --open",
+"dev-sv": "NODE_ENV=development vite dev",
 
-### 2. Global Styles
+5. Import DS config into the tailwind.config.ts file(of consuming project) and add it in the presets array:
+```ts
+// tailwind.config.ts
+
+import designSystemPreset from '@widgetic/design-system/tailwind.config';
+
+const config = {
+  // add here the DS preset
+	presets: [
+		designSystemPreset
+	],
+  // add here the '@widgetic/*/dist/...' to scan also the DS package files
+	content: [
+		"./src/**/*.{html,js,svelte,ts}",
+		// Include all @widgetic packages from node_modules(for development only) to be sure Tailwind scans all the files
+		"./node_modules/@widgetic/*/dist/**/*.{html,js,svelte,ts}"
+	],
+  // the rest of the config properties
+	theme: {
+		extend: {
+      // current extend config...
+		}
+	}
+};
 
-Import the design system's global CSS file into your main layout file (e.g., `src/routes/+layout.svelte`). This file includes base styles, CSS variables (design tokens), and imports necessary fonts.
+export default config;
+```
+Also make sure you remove the type of the config to avoid conflicts with the DS config.
+Then leave the rest of the config as it is.
 
+6. Import styles and a test component from DS in the consuming project:
+a. In the root layout of the project import the global styles:
 ```svelte
-<!-- src/routes/+layout.svelte -->
+<!-- +layout.svelte -->
 <script>
-  import '@widgetic/design-system/styles'; // Import global styles
-
-  // Your layout script...
+  import '@widgetic/design-system/styles';
 </script>
+```
+b. In the root page of the consuming project import any component(e.g. Button) and use it:
+```svelte
+<!-- +page.svelte -->
+<script>
+  import { Button } from '@widgetic/design-system/';
+</script>
+
+<!-- HTML zone -->
+<Button>Click me</Button>
+```
+
+7. Finally: go into the in the consuming project's folder and start the development server with:
+```bash
+npm run dev
+```
+
+This automatically opens the http://localhost:5173 (default port) for the consuming project and you can see how DS components work in it.
+
+
 
-<slot />
+## Developing inside this project:
+
+1. Install dependencies with `npm install`
+
+2. Link the package in the system with npm:
+```bash
+npm link
+```
+
+3. Start the development server with:
+```bash
+npm run dev
+```
+
+3. Test the design system in action:
+- In the root layout of the DS project there is a global styles import to test the design system's global styles.
+- In the root page of the project there is a button component import to test the design system's components.
+
+Open in new tab in browser with address: http://localhost:5173/ to see the design system in action.
+
+
+
+### Global Tailwind CSS and Design Tokens:
+
+```css
+/* src/lib/styles/global.css */
+@tailwind base;
+@tailwind components;
+@tailwind utilities;
+
+/* CUSTOM GLOBAL STYLES */
+/* ADD HERE CLASSES AND CSS VARIABLES that are used in the projects where the design system is imported */
+
+/* Base styles */
+@layer base {
+  :root {
+    /* Design tokens */
+    --color-primary: 30 158 210; /* RGB values for easier theming */
+    --color-secondary: 46 204 113;
+    --radius: 0.5rem;
+  }
+
+  /* Dark mode tokens */
+  .dark {
+    --color-primary: 100 200 255;
+    --color-secondary: 100 255 150;
+  }
+}
+
+/* Reusable component classes */
+@layer components {
+  .btn-primary {
+    @apply bg-[rgb(var(--color-primary))] text-white rounded-[var(--radius)];
+  }
+
+  .card {
+    @apply shadow-md rounded-lg p-4 bg-white dark:bg-gray-800;
+  }
+}
+
+/* Custom utility classes */
+@layer utilities {
+  .text-balance {
+    text-wrap: balance;
+  }
+}
 ```
 
-## Usage
+2. In the project where the design system is imported:
+- Import the global styles in the +layout.svelte file:
+```svelte
+<script>
+  import '@widgetic/design-system/styles';
+</script>
+```
 
-### Components
 
-Import components directly from the package:
+### Create a Custom Shared Component in the Design System project using a SHADCN UI component and classes from the global styles:
 
+src/lib/components/MyButton.svelte:
 ```svelte
 <script>
-  import { Button, Card, CardHeader, CardTitle, CardContent } from '@widgetic/design-system';
-  // For grouped components (like Table, Accordion), use the namespace
-  import { Table } from '@widgetic/design-system';
+  // Import Button from the SHADCN UI components
+  import { Button } from './components/ui';
 </script>
 
-<Button>Click Me</Button>
+<MyButton 
+  {type}
+  class="btn-primary"
+  on:click
+>
+  <slot />
+</MyButton>
+```
+Then export the component in the "src/lib/components/index.ts" file:
+```ts
+export {default as MyButton } from './components/MyButton.svelte';
+```
+
+
+## Deployment of Design System
+
+To deploy the design system, run the following command:
+```bash
+npm run prepublishOnly
+```
+This will create a `dist` folder with the production build of the design system.
+
+To publish the design system to the npm registry, run the following command:
+```bash
+npm run publish-package
+```
+
+## Grid System
+
+The design system implements three distinct responsive grid layouts:
+
+1. Site Grid
+2. Dashboard Grid
+3. App Grid
+
+### Grid Breakpoints
+- Desktop: > 744px
+- Tablet: 393px - 744px
+- Mobile: ≤ 393px
+
+### 1. Site Grid
+
+**Desktop (>744px)**
+- 12 columns
+- 144px margins
+- 24px gutters
+- Stretching columns with auto width
+
+**Tablet (≤744px)**
+- 8 columns
+- 32px margins
+- 16px gutters
+- Stretching columns with auto width
+
+**Mobile (≤393px)**
+- 4 columns
+- 16px margins
+- 16px gutters
+- Stretching columns with auto width
+
+### 2. Dashboard Grid
+
+**Desktop (>744px)**
+- Header: 12 columns, 24px margins, 20px gutters
+- Sidebar: 240px fixed width
+- Main Content: 12 columns, 24px margins, 20px gutters
+- 56px header height
 
-<Card.Root>
-  <Card.Header>
-    <Card.Title>Card Title</Card.Title>
-  </Card.Header>
-  <Card.Content>
-    <p>Card body content...</p>
-  </Card.Content>
-</Card.Root>
+**Tablet (≤744px)**
+- Header: 8 columns
+- Sidebar: 200px fixed width
+- Main Content: 8 columns
+- 16px margins and gutters
+
+**Mobile (≤393px)**
+- Header: 4 columns
+- Sidebar replaced with menu component
+- Main Content: 4 columns
+- 16px margins and gutters
+
+### 3. App Grid
+
+**Desktop (>744px)**
+- Header: 12 columns, 24px margins, 20px gutters
+- Main Content: 12 columns, 144px margins, 20px gutters
+- 56px header height
+
+**Tablet (≤744px)**
+- Header: 8 columns
+- Main Content: 8 columns, 32px margins
+- 16px gutters
+
+**Mobile (≤393px)**
+- Header: 4 columns
+- Menu component added below header
+- Main Content: 4 columns
+- 16px margins and gutters
+
+### Usage Example
+
+```svelte
+<!-- Site Grid -->
+<div class="site-grid">
+  <div class="grid-margin-left"></div>
+  <header class="grid-header">Header Content</header>
+  <main class="grid-main">Main Content</main>
+  <footer class="grid-footer">Footer Content</footer>
+  <div class="grid-margin-right"></div>
+</div>
+
+<!-- Dashboard Grid -->
+<div class="dashboard-grid">
+  <div class="grid-margin-left"></div>
+  <header class="dashboard-header-grid">
+    <!-- Header content with 12/8/4 columns based on viewport -->
+  </header>
+  <nav class="grid-sidebar">
+    <!-- Sidebar content (hidden on mobile) -->
+  </nav>
+  <main class="dashboard-main-grid">
+    <!-- Main content with 12/8/4 columns based on viewport -->
+  </main>
+  <div class="grid-margin-right"></div>
+  <!-- Mobile menu appears automatically on small screens -->
+  <div class="grid-menu">
+    <!-- Mobile menu content -->
+  </div>
+</div>
+
+<!-- App Grid -->
+<div class="app-grid">
+  <div class="grid-margin-left"></div>
+  <header class="app-header-grid">
+    <!-- Header content with 12/8/4 columns based on viewport -->
+  </header>
+  <main class="app-main-grid">
+    <!-- Main content with 12/8/4 columns based on viewport -->
+  </main>
+  <div class="grid-margin-right"></div>
+  <!-- Mobile menu appears automatically on small screens -->
+  <div class="grid-menu">
+    <!-- Mobile menu content -->
+  </div>
+</div>
+```
 
-<Table.Root>
-  <Table.Header>
-    <Table.Row>
-      <Table.Head>Header 1</Table.Head>
-    </Table.Row>
-  </Table.Header>
-  <Table.Body>
-    <Table.Row>
-      <Table.Cell>Cell 1</Table.Cell>
-    </Table.Row>
-  </Table.Body>
-</Table.Root>
+### Grid Area Classes
+The following classes are available to position elements within the grid:
+```css
+.grid-header      /* Header area */
+.grid-main        /* Main content area */
+.grid-sidebar     /* Sidebar area (dashboard only) */
+.grid-footer      /* Footer area (site only) */
+.grid-toolbar     /* Toolbar area (app only) */
+.grid-margin-left /* Left margin area */
+.grid-margin-right/* Right margin area */
+.grid-menu        /* Mobile menu area */
+.grid-gap         /* Gap area (dashboard only) */
 ```
 
-Refer to the specific component documentation or source code for available props and variants.
+The grid system is designed to maintain consistent spacing and layout across different viewport sizes while adapting to the specific needs of each layout type (site, dashboard, and app).
 
-### Icons
+## DeleteConfirmation Component
 
-Import required icons by name:
+The `DeleteConfirmation` component is a reusable confirmation dialog that can be used across different parts of the project for confirming deletion actions.
+
+### Features
+
+- Independent of any specific store or state management system
+- Customizable title, message, and button labels
+- Works with any type of items to be deleted
+- Dispatches events for both confirmation and cancellation
+
+### Usage
 
 ```svelte
 <script>
-  import { ChevronUp, IconSettings } from '@widgetic/design-system/icons'; // Example names
+  import { DeleteConfirmation } from '@widgetic/design-system/components';
+  
+  let showDeleteConfirmation = false;
+  let itemsToDelete = [
+    { id: '1', name: 'Document.pdf', type: 'file' },
+    { id: '2', name: 'Images', type: 'folder' }
+  ];
+  
+  function handleDelete(event) {
+    const deletedItems = event.detail.items;
+    console.log('Items to delete:', deletedItems);
+    // Perform deletion logic here
+  }
+  
+  function handleCancel() {
+    showDeleteConfirmation = false;
+    console.log('Deletion cancelled');
+  }
 </script>
 
-<button>
-  <ChevronUp class="size-4" /> Settings <IconSettings class="size-4" />
+<button on:click={() => showDeleteConfirmation = true}>
+  Delete Items
 </button>
+
+<DeleteConfirmation
+  bind:isOpen={showDeleteConfirmation}
+  items={itemsToDelete}
+  modalId="my-delete-confirmation"
+  on:delete={handleDelete}
+  on:cancel={handleCancel}
+/>
 ```
 
-### Fonts & Typography
+### Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `isOpen` | boolean | `false` | Controls the visibility of the modal |
+| `items` | array | `[]` | Array of items to be deleted |
+| `title` | string | `''` | Custom title for the modal (autogenerated if empty) |
+| `message` | string | `''` | Custom message for the modal (autogenerated if empty) |
+| `confirmLabel` | string | `'Confirm'` | Label for the confirm button |
+| `cancelLabel` | string | `'Cancel'` | Label for the cancel button |
+| `width` | string | `'410px'` | Width of the modal |
+| `height` | string | `'168px'` | Height of the modal |
+| `modalId` | string | `'delete-confirmation-modal'` | ID for targeting the modal |
 
-The global styles load the necessary `@font-face` rules. You can apply typography using standard Tailwind utility classes (e.g., `text-lg`, `font-semibold`) or the custom typography utility classes exported by the design system (defined in `fonts.css`, like `h1`, `body-medium`, `subtext`).
+### Events
+
+- `delete` - Dispatched when the user confirms deletion, with `items` in the event detail
+- `cancel` - Dispatched when the user cancels deletion
+
+### Custom Title and Message Example
+
+You can provide custom title and message for specific contexts:
 
 ```svelte
-<h1 class="h1">Main Title</h1>
-<p class="body-medium">This is body text.</p>
-<span class="subtext">Some smaller text.</span>
-```
+<script>
+  import { DeleteConfirmation } from '@widgetic/design-system/components';
+  
+  let showDeleteConfirmation = false;
+  let selectedItems = [
+    { id: '1', name: 'Document.pdf', type: 'file' },
+    { id: '2', name: 'Images', type: 'folder' }
+  ];
+  
+  function handleDelete(event) {
+    const deletedItems = event.detail.items;
+    console.log('Items to delete:', deletedItems);
+    // Perform deletion logic here
+  }
+  
+  function handleCancel() {
+    showDeleteConfirmation = false;
+    console.log('Deletion cancelled');
+  }
+</script>
+
+<DeleteConfirmation 
+  bind:isOpen={showDeleteConfirmation}
+  items={selectedItems}
+  title="Delete Assets"
+  message="These assets will be permanently deleted. This action cannot be undone."
+  confirmLabel="Delete Permanently"
+  on:delete={handleDelete}
+  on:cancel={handleCancel}
+/>
+```
+
+
+## Troubleshooting
+
+### File Case Sensitivity Issues (macOS/Windows Teams)
+
+**Problem:** Component imports break inconsistently across team members, with errors like:
+- `Cannot resolve module './checked.svelte'` vs `'./Checked.svelte'`
+- Barrel file exports pointing to wrong case filenames
+- One developer's changes cause import errors for others
+
+**Root Cause:** Different operating systems handle file case differently:
+- **macOS/Windows:** Case-insensitive but case-preserving file systems
+- **Linux:** Case-sensitive file system
+- **Git:** May not properly sync case-only file renames between different systems
+
+**Solutions:**
+
+1. **Quick Setup (Recommended):** Run the install script which includes Git configuration:
+   ```bash
+   npm run i  # Installs dependencies and configures Git automatically
+   ```
+
+2. **Git Only:** If you just need to configure Git case sensitivity:
+   ```bash
+   npm run set-git
+   ```
+
+3. **Manual Setup:** Configure Git to be case-sensitive in your local repository:
+   ```bash
+   git config core.ignorecase false
+   ```
+
+4. **Team Setup:** After the above configuration, if you encounter existing case conflicts:
+   ```bash
+   git pull  # Get latest changes
+   npm run dev  # Auto-fixes any remaining case issues via Vite plugin
+   ```
+
+**Prevention:** 
+- All team members should run `npm run i` when first working with the design system
+- Always use PascalCase for `.svelte` component files (e.g., `MyComponent.svelte`)
+- The development server automatically renames files to follow PascalCase convention
+
+### Cursor IDE: TypeScript Parser Not Recognizing Svelte Files
+
+**Problem:** After updating Cursor IDE, you may see TypeScript parsing errors in `.svelte` files that use design system components, such as:
+- `Cannot find name 'script'`
+- `'>': expected`
+- `Cannot find name 'lang'`
+- Other syntax errors in valid Svelte code
+
+**Root Cause:** Mixed tabs and spaces in the file can confuse the TypeScript parser, preventing it from properly recognizing the file as a Svelte component. This issue commonly occurs after Cursor IDE updates.
+
+**Solution:**
+1. Select the file showing the error
+2. In the bottom-right corner of Cursor IDE, click the "TypeScript" box
+3. When you hover over it, it shows "Select Language Mode"
+4. Select **"Svelte"** from the dropdown
+5. The file should now be parsed correctly as a Svelte component
+
+**Prevention:** Ensure your project has proper Svelte language support configured:
+- Install the Svelte extension for Cursor/VS Code
+- Check that `svelte.config.js` is properly configured
+- Ensure consistent indentation (spaces vs tabs) in your `.svelte` files
+
+### Design System Import Errors
+
+**Problem:** Cannot import components or getting module resolution errors.
+
+**Solutions:**
+1. **Check peer dependencies:** Ensure all required peer dependencies are installed with compatible versions
+2. **Restart development server:** After installing the design system or updating dependencies
+3. **Clear caches:** Run your project's cache clearing commands (e.g., `npm run clean-svelte-cache`)
+4. **Verify Tailwind config:** Ensure the design system preset is properly imported in your `tailwind.config.ts`
+
+### Styling Issues
+
+**Problem:** Components appear unstyled or with incorrect styling.
+
+**Solutions:**
+1. **Import global styles:** Ensure you've imported `@widgetic/design-system/styles/global.css` in your root layout
+2. **Check Tailwind setup:** Verify your `tailwind.config.ts` includes the design system preset
+3. **PostCSS configuration:** Ensure `postcss.config.js` is set up for Tailwind v4
+4. **Content paths:** Make sure your Tailwind config includes the design system in content paths:
+   ```js
+   content: [
+     "./src/**/*.{html,js,svelte,ts}",
+     "./node_modules/@widgetic/*/dist/**/*.{html,js,svelte,ts}"
+   ]
+   ```
+
+### Version Compatibility Issues
+
+**Problem:** Getting errors after updating Svelte, SvelteKit, or other dependencies.
+
+**Solutions:**
+1. **Check compatibility:** Ensure your project's Svelte/SvelteKit versions are compatible with the design system
+2. **Update together:** Consider updating both the design system and your project dependencies together
+3. **Check breaking changes:** Review changelogs for any breaking changes
+4. **Use exact versions:** For critical projects, consider pinning exact versions instead of ranges
+
+### Performance Issues
+
+**Problem:** Slow build times or large bundle sizes.
+
+**Solutions:**
+1. **Tree shaking:** Import only the components you need:
+   ```js
+   // Good: Import specific components
+   import { Button } from '@widgetic/design-system/components';
+   
+   // Avoid: Importing everything
+   import * as DS from '@widgetic/design-system';
+   ```
+2. **Check Tailwind purging:** Ensure Tailwind is properly purging unused styles
+3. **Optimize imports:** Use direct imports when possible to improve tree shaking
+
+### Getting Help
+
+If you continue to experience issues:
+1. Check the latest documentation in this README
+2. Review the `__docs/how-to-link-ds.md` guide for setup instructions
+3. Check for updates to the design system package
+4. Report persistent issues to the development team with:
+   - Your project's `package.json` dependencies
+   - Complete error messages
+   - Steps to reproduce the issue