Card body content...
\nThis is body text.
\nSome smaller text.\n```\n\n## Troubleshooting\n\n### File Case Sensitivity Issues (macOS/Windows Teams)\n\n**Problem:** Component imports break inconsistently across team members, with errors like:\n- `Cannot resolve module './checked.svelte'` vs `'./Checked.svelte'`\n- Barrel file exports pointing to wrong case filenames\n- One developer's changes cause import errors for others\n\n**Root Cause:** Different operating systems handle file case differently:\n- **macOS/Windows:** Case-insensitive but case-preserving file systems\n- **Linux:** Case-sensitive file system\n- **Git:** May not properly sync case-only file renames between different systems\n\n**Solutions:**\n\n1. **Quick Setup (Recommended):** Run the install script which includes Git configuration:\n ```bash\n npm run i # Installs dependencies and configures Git automatically\n ```\n\n2. **Git Only:** If you just need to configure Git case sensitivity:\n ```bash\n npm run set-git\n ```\n\n3. **Manual Setup:** Configure Git to be case-sensitive in your local repository:\n ```bash\n git config core.ignorecase false\n ```\n\n4. **Team Setup:** After the above configuration, if you encounter existing case conflicts:\n ```bash\n git pull # Get latest changes\n npm run dev # Auto-fixes any remaining case issues via Vite plugin\n ```\n\n**Prevention:** \n- All team members should run `npm run i` when first working with the design system\n- Always use PascalCase for `.svelte` component files (e.g., `MyComponent.svelte`)\n- The development server automatically renames files to follow PascalCase convention\n\n### Cursor IDE: TypeScript Parser Not Recognizing Svelte Files\n\n**Problem:** After updating Cursor IDE, you may see TypeScript parsing errors in `.svelte` files that use design system components, such as:\n- `Cannot find name 'script'`\n- `'>': expected`\n- `Cannot find name 'lang'`\n- Other syntax errors in valid Svelte code\n\n**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.\n\n**Solution:**\n1. Select the file showing the error\n2. In the bottom-right corner of Cursor IDE, click the \"TypeScript\" box\n3. When you hover over it, it shows \"Select Language Mode\"\n4. Select **\"Svelte\"** from the dropdown\n5. The file should now be parsed correctly as a Svelte component\n\n**Prevention:** Ensure your project has proper Svelte language support configured:\n- Install the Svelte extension for Cursor/VS Code\n- Check that `svelte.config.js` is properly configured\n- Ensure consistent indentation (spaces vs tabs) in your `.svelte` files\n\n### Design System Import Errors\n\n**Problem:** Cannot import components or getting module resolution errors.\n\n**Solutions:**\n1. **Check peer dependencies:** Ensure all required peer dependencies are installed with compatible versions\n2. **Restart development server:** After installing the design system or updating dependencies\n3. **Clear caches:** Run your project's cache clearing commands (e.g., `npm run clean-svelte-cache`)\n4. **Verify Tailwind config:** Ensure the design system preset is properly imported in your `tailwind.config.ts`\n\n### Styling Issues\n\n**Problem:** Components appear unstyled or with incorrect styling.\n\n**Solutions:**\n1. **Import global styles:** Ensure you've imported `@widgetic/design-system/styles/global.css` in your root layout\n2. **Check Tailwind setup:** Verify your `tailwind.config.ts` includes the design system preset\n3. **PostCSS configuration:** Ensure `postcss.config.js` is set up for Tailwind v4\n4. **Content paths:** Make sure your Tailwind config includes the design system in content paths:\n ```js\n content: [\n \"./src/**/*.{html,js,svelte,ts}\",\n \"./node_modules/@widgetic/*/dist/**/*.{html,js,svelte,ts}\"\n ]\n ```\n\n### Version Compatibility Issues\n\n**Problem:** Getting errors after updating Svelte, SvelteKit, or other dependencies.\n\n**Solutions:**\n1. **Check compatibility:** Ensure your project's Svelte/SvelteKit versions are compatible with the design system\n2. **Update together:** Consider updating both the design system and your project dependencies together\n3. **Check breaking changes:** Review changelogs for any breaking changes\n4. **Use exact versions:** For critical projects, consider pinning exact versions instead of ranges\n\n### Performance Issues\n\n**Problem:** Slow build times or large bundle sizes.\n\n**Solutions:**\n1. **Tree shaking:** Import only the components you need:\n ```js\n // Good: Import specific components\n import { Button } from '@widgetic/design-system/components';\n \n // Avoid: Importing everything\n import * as DS from '@widgetic/design-system';\n ```\n2. **Check Tailwind purging:** Ensure Tailwind is properly purging unused styles\n3. **Optimize imports:** Use direct imports when possible to improve tree shaking\n\n### Getting Help\n\nIf you continue to experience issues:\n1. Check the latest documentation in this README\n2. Review the `__docs/how-to-link-ds.md` guide for setup instructions\n3. Check for updates to the design system package\n4. Report persistent issues to the development team with:\n - Your project's `package.json` dependencies\n - Complete error messages\n - Steps to reproduce the issue","readmeFilename":"README.md"}