\n \n ))}\n \n );\n}\n```\n\n## š ļø Development\n\n### Prerequisites\n\n- Node.js 16+ \n- npm/yarn/pnpm\n\n### Setup\n\n```bash\n# Clone the repository\ngit clone https://github.com/your-org/unicity-design-system.git\n\n# Install dependencies\nnpm install\n\n# Start Storybook development server\nnpm run storybook\n\n# Build the library\nnpm run build\n\n# Run tests\nnpm test\n```\n\n### Development Scripts\n\n```bash\nnpm run dev # Start development environment\nnpm run build # Build production bundle\nnpm run storybook # Start Storybook server\nnpm run test # Run test suite\nnpm run lint # Lint code\nnpm run type-check # TypeScript type checking\n```\n\n### Project Structure\n\n```\nsrc/\nāāā components/ # All components\nā āāā Button/\nā ā āāā Button.tsx\nā ā āāā Button.stories.tsx\nā āāā ...\nāāā theme/ # Theme system\nā āāā theme.ts\nā āāā ThemeProvider.tsx\nāāā index.ts # Main exports\n\ndist/ # Built library\ndocs/ # Documentation\nstorybook-static/ # Built Storybook\n```\n\n## š Contributing\n\nWe welcome contributions! Please see our [Contributing Guide](CONTRIBUTING.md) for details.\n\n### Component Development Guidelines\n\n1. **TypeScript First** - All components must be written in TypeScript\n2. **Storybook Documentation** - Every component needs comprehensive stories\n3. **Accessibility** - Follow WCAG guidelines and test with screen readers\n4. **Testing** - Include unit tests for component logic\n5. **Theme Integration** - Support all theme modes\n6. **Responsive Design** - Mobile-first approach\n\n### Adding New Components\n\n```bash\n# Create component structure\nmkdir src/components/NewComponent\ntouch src/components/NewComponent/NewComponent.tsx\ntouch src/components/NewComponent/NewComponent.stories.tsx\n\n# Add to main exports\n# Update src/index.ts\n```\n\n## š§ Advanced Usage\n\n### Tree Shaking\n\nImport only what you need for optimal bundle size:\n\n```tsx\n// ā Good - tree shaking friendly\nimport { Button } from '@unicity/design-system';\n\n// ā Avoid - imports entire library\nimport * as DesignSystem from '@unicity/design-system';\n```\n\n### Font Override Service\n\nConfigure comprehensive font scaling that works with any styling method:\n\n```tsx\nimport { fontOverrideService } from '@unicity/design-system';\n\n// Enable font override with custom settings\nfontOverrideService.updateConfig({\n scale: 1.25,\n aggressive: false,\n excludeSelectors: ['code', '.my-special-class'],\n excludeClasses: ['no-scale', 'fixed-size'],\n minFontSize: 12,\n maxFontSize: 40,\n});\n\n// Use CSS variables in styled components\nimport styled from 'styled-components';\n\nconst ResponsiveText = styled.div`\n font-size: clamp(\n var(--unicity-min-font-size, 10px),\n calc(16px * var(--unicity-font-scale, 1)),\n var(--unicity-max-font-size, 32px)\n );\n`;\n\n// Exclude specific elements from scaling\n
Won't be scaled
\n
Also won't be scaled
\n```\n\n### Translation Configuration\n\nConfigure internationalization with external APIs or custom translations:\n\n```tsx\nimport { TranslationProvider } from '@unicity/design-system';\n\n// External API configuration\n\n \n\n\n// Environment-based configuration\n// Set in your .env file:\n// REACT_APP_TRANSLATION_URL=https://cdn.unicity.com/translations/\n// REACT_APP_TRANSLATION_DEBUG=false\n// REACT_APP_TRANSLATION_CACHE=true\n\n\n \n\n\n// Programmatic translation utilities\nimport { translationUtils } from '@unicity/design-system';\n\nconst currentLang = translationUtils.getLanguage();\ntranslationUtils.changeLanguage('es');\nconst languages = translationUtils.getSupportedLanguages();\n```\n\n### Accessibility Integration\n\nCombine accessibility features with your existing theme system:\n\n```tsx\nimport { \n ThemeProvider, \n AccessibilityController, \n useTheme \n} from '@unicity/design-system';\n\nfunction AccessibilityAwareApp() {\n const { settings } = useTheme();\n \n // Access current accessibility settings\n const isHighContrast = settings.accessibilityMode === 'high-contrast';\n const reduceMotion = settings.motion?.reduceMotion;\n const fontSize = settings.fontSize?.scale;\n \n return (\n
\n \n \n
\n );\n}\n\n// Individual accessibility tools\nimport { \n VisualAccessibility,\n TextSize,\n MotionAnimation,\n ColorVisibility \n} from '@unicity/design-system';\n\n\n \n \n \n\n```\n\n### Custom Components\n\nExtend existing components with your own styling:\n\n```tsx\nimport { Button } from '@unicity/design-system';\nimport { styled } from '@mui/material/styles';\n\nconst CustomButton = styled(Button)(({ theme }) => ({\n borderRadius: theme.spacing(3),\n // Your custom styles\n}));\n```\n\n### Theme Customization\n\nCreate custom theme variants with accessibility support:\n\n```tsx\nimport { getTheme } from '@unicity/design-system';\n\nconst brandTheme = getTheme('light', {\n palette: {\n primary: { main: '#1976d2' },\n secondary: { main: '#dc004e' },\n },\n shape: { borderRadius: 8 },\n typography: {\n fontFamily: '\"Roboto\", \"Helvetica\", \"Arial\", sans-serif',\n },\n // Accessibility-aware spacing\n spacing: (factor) => `${0.25 * factor}rem`,\n});\n\n// High contrast theme variant\nconst highContrastTheme = getTheme('high-contrast-light', {\n palette: {\n primary: { main: '#000000' },\n background: { default: '#ffffff', paper: '#ffffff' },\n text: { primary: '#000000', secondary: '#000000' }\n }\n});\n```\n\n## š Bundle Size\n\nThe library is optimized for tree shaking and minimal bundle impact:\n\n- **Core**: ~45KB gzipped (theme system + utilities)\n- **Individual Components**: 2-8KB gzipped each\n- **Complete Library**: ~180KB gzipped\n\n## š Browser Support\n\n### Core Library\n- **Chrome 90+** - Full feature support including accessibility APIs\n- **Firefox 88+** - Complete compatibility with translation and theming\n- **Safari 14+** - All features supported including CSS custom properties\n- **Edge 90+** - Full support for advanced components and services\n\n### Internationalization Features\n- **Intl API Support**: Modern browsers with `Intl.NumberFormat` and `Intl.DateTimeFormat`\n- **Unicode Support**: Full UTF-8 character set support for 11 languages\n- **LocalStorage**: For language preference persistence\n- **Fetch API**: For dynamic translation loading\n\n### Accessibility Features\n- **CSS Custom Properties**: For dynamic theming and font scaling\n- **MutationObserver**: For font override service functionality\n- **Web Audio API**: Optional for sound effect controls\n- **Vibration API**: Optional for haptic feedback (mobile)\n- **Intersection Observer**: For reading guide features\n- **Media Queries**: For `prefers-reduced-motion` and contrast preferences\n\n### Performance Optimization\n- **ES2020 Support**: For optimal bundle size and performance\n- **CSS Grid & Flexbox**: For layout components\n- **CSS Transforms**: For smooth animations and transitions\n\n## š License\n\nMIT License - see [LICENSE](LICENSE) file for details.\n\n## š¤ Support\n\n- š [Documentation](https://your-storybook-url.com)\n- š [Issues](https://github.com/your-org/unicity-design-system/issues)\n- š¬ [Discussions](https://github.com/your-org/unicity-design-system/discussions)\n- š§ [Email Support](mailto:support@unicity.com)\n\n## š Roadmap\n\n- [ ] React 19 support\n- [ ] Additional neumorphism components\n- [ ] Dark mode auto-detection\n- [ ] Advanced animation system\n- [ ] Mobile-specific components\n- [ ] Performance optimizations\n\n---\n\nBuilt with ā¤ļø by the Unicity Design Team ","readmeFilename":"README.md"}