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:

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:

<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:

 /* 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:

.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:

npm run i-shadcn

At prompt answer like this:

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:

npx shadcn-svelte@next init

c. Add one or more SHADCN UI components:

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".

// 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:

import { Table } from '@widgetic/design-system';

h. If there is a component that looks compound but is not, add the @notCompound marker in the file:

// @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:

// @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.

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.

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:

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'
    ]
  },
  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
}

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:

"dependencies": {
"tailwindcss": "^3.4.16",
"@tailwindcss/postcss": "^4.1.2",
}

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:

"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",

5. Import DS config into the tailwind.config.ts file(of consuming project) and add it in the presets array:

// 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...
		}
	}
};

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:

<!-- +layout.svelte -->
<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:

<!-- +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:

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.

Developing inside this project:

1. Install dependencies with npm install

2. Link the package in the system with npm:

npm link

3. Start the development server with:

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:

/* 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;
  }
}

2. In the project where the design system is imported:

• Import the global styles in the +layout.svelte file:

<script>
  import '@widgetic/design-system/styles';
</script>

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:

<script>
  // Import Button from the SHADCN UI components
  import { Button } from './components/ui';
</script>

<MyButton 
  {type}
  class="btn-primary"
  on:click
>
  <slot />
</MyButton>

Then export the component in the "src/lib/components/index.ts" file:

export {default as MyButton } from './components/MyButton.svelte';

Deployment of Design System

To deploy the design system, run the following command:

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:

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

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

<!-- 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>

Grid Area Classes

The following classes are available to position elements within the grid:

.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) */

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).

DeleteConfirmation Component

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

<script>
  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 on:click={() => showDeleteConfirmation = true}>
  Delete Items
</button>

<DeleteConfirmation
  bind:isOpen={showDeleteConfirmation}
  items={itemsToDelete}
  modalId="my-delete-confirmation"
  on:delete={handleDelete}
  on:cancel={handleCancel}
/>

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 |

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:

<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:

   npm run i  # Installs dependencies and configures Git automatically

2. Git Only: If you just need to configure Git case sensitivity:

   npm run set-git

3. Manual Setup: Configure Git to be case-sensitive in your local repository:

   git config core.ignorecase false

4. Team Setup: After the above configuration, if you encounter existing case conflicts:

   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:

   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:

   // 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