{"_id":"@boxpasshq/boxkit","name":"@boxpasshq/boxkit","dist-tags":{"latest":"2.4.1"},"versions":{"2.4.1":{"name":"@boxpasshq/boxkit","version":"2.4.1","description":"BoxKit — BoxPass component library with React, TypeScript, Storybook, and design tokens","keywords":["boxkit","boxpass","storybook","design-system","react","typescript","ui-components","vitest","vite","design-tokens","component-library"],"homepage":"https://github.com/boxpasshq/boxkit#readme","bugs":{"url":"https://github.com/boxpasshq/boxkit/issues"},"repository":{"type":"git","url":"git+https://github.com/boxpasshq/boxkit.git"},"publishConfig":{"access":"public"},"license":"MIT","author":{"name":"BoxPass"},"type":"module","exports":{".":{"import":"./dist/index.js","types":"./dist/index.d.ts"},"./styles":"./dist/index.css"},"main":"dist/index.js","module":"dist/index.js","types":"dist/index.d.ts","scripts":{"build":"tsc -b && vite build && tsc --project tsconfig.declarations.json","build-storybook":"storybook build","build:package":"yarn build","build:types":"tsc --project tsconfig.declarations.json","check-all":"yarn lint && yarn type-check && yarn test:run:quiet && yarn build && yarn build-storybook","chromatic":"chromatic --exit-zero-on-changes","chromatic:token":"chromatic --exit-zero-on-changes --project-token","dev":"vite","format":"prettier --write .","format:check":"prettier --check .","format:package":"npx sort-package-json package.json","lint":"eslint .","lint:fix":"eslint . --fix","prepublishOnly":"yarn build:package","preview":"vite preview","release":"semantic-release","release:dry":"semantic-release --dry-run","serve":"npx serve storybook-static -l 8080","start":"storybook dev -p 6006","storybook":"storybook dev -p 80 --no-open --host 0.0.0.0 --port 80","storybook:local":"STORYBOOK_ENV=local storybook dev -p 6006","storybook:restart":"pkill -f storybook || true && yarn storybook:local","test":"vitest --project=unit","test:all":"vitest run","test:ci":"CI=true yarn test:run:quiet","test:coverage":"vitest run --project=unit --coverage","test:run":"vitest run --project=unit","test:run:quiet":"vitest run --project=unit --reporter=default","test:storybook":"vitest run --project=storybook","test:ui":"vitest --ui --project=unit","type-check":"tsc --noEmit","visual-test":"chromatic --exit-zero-on-changes --auto-accept-changes","visual-test:ci":"chromatic --exit-zero-on-changes --exit-once-uploaded"},"dependencies":{"clsx":"^2.1.1","lucide-react":"^0.525.0","react":"^18.0.0","react-dom":"^18.0.0"},"devDependencies":{"@chromatic-com/storybook":"^4.0.1","@eslint/js":"^9.30.1","@semantic-release/changelog":"^6.0.3","@semantic-release/git":"^10.0.1","@semantic-release/github":"^11.0.3","@storybook/addon-a11y":"^9.0.17","@storybook/addon-docs":"^9.0.17","@storybook/addon-vitest":"^9.0.17","@storybook/react-vite":"^9.0.17","@testing-library/dom":"^10.4.0","@testing-library/jest-dom":"^6.6.3","@testing-library/react":"^16.3.0","@testing-library/user-event":"^14.6.1","@types/node":"^24.0.15","@types/qrcode":"^1.5.5","@types/react":"^19.1.8","@types/react-dom":"^19.1.6","@typescript-eslint/eslint-plugin":"^8.37.0","@typescript-eslint/parser":"^8.37.0","@vitejs/plugin-react":"^4.6.0","@vitest/browser":"^3.2.4","@vitest/coverage-v8":"^3.2.4","chromatic":"^13.1.2","eslint":"^9.30.1","eslint-plugin-react-hooks":"^5.2.0","eslint-plugin-react-refresh":"^0.4.20","eslint-plugin-storybook":"^9.0.17","globals":"^16.3.0","jsdom":"^26.1.0","playwright":"^1.54.1","prettier":"^3.6.2","qrcode":"^1.5.4","semantic-release":"^24.2.7","storybook":"^9.0.17","typescript":"~5.8.3","typescript-eslint":"^8.35.1","vite":"^7.0.4","vitest":"^3.2.4"},"peerDependencies":{"react":"^18.0.0","react-dom":"^18.0.0"},"packageManager":"yarn@4.5.1","engines":{"node":">=22.0.0","npm":">=10.0.0"},"_id":"@boxpasshq/boxkit@2.4.1","gitHead":"56662be38048b460be03cd253e8d66f9eb411fa3","_nodeVersion":"22.22.0","_npmVersion":"10.9.3","dist":{"integrity":"sha512-1uU4Xu3HSKSGHN7QqB1PcsF7L/4R6W7pIyE2FGdIV2DITle5Pr0X4NptEY0OOW2MfVyX8Wy4+GK642NzypSQ1A==","shasum":"5b230b9b70e1ff2a939f897b7f0ec0e202b8cea2","tarball":"https://registry.npmjs.org/@boxpasshq/boxkit/-/boxkit-2.4.1.tgz","fileCount":33,"unpackedSize":172800,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCIQDAfk8/eiLQkR8Jr0QiKGWqlGYg2XrYi8/ul++Qk6swrAIgRo+aCRp5sKFBj6E4dkNPjX7IW51mp9xT0PxmzCFhLh8="}]},"_npmUser":{"name":"vladhadzhiyski","email":"vlad@hadzhiyski.com"},"directories":{},"maintainers":[{"name":"vladhadzhiyski","email":"vlad@hadzhiyski.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/boxkit_2.4.1_1773284465198_0.0009230267150495131"},"_hasShrinkwrap":false}},"time":{"created":"2026-03-12T03:01:05.026Z","2.4.1":"2026-03-12T03:01:05.391Z","modified":"2026-03-12T03:01:05.691Z"},"maintainers":[{"name":"vladhadzhiyski","email":"vlad@hadzhiyski.com"}],"description":"BoxKit — BoxPass component library with React, TypeScript, Storybook, and design tokens","homepage":"https://github.com/boxpasshq/boxkit#readme","keywords":["boxkit","boxpass","storybook","design-system","react","typescript","ui-components","vitest","vite","design-tokens","component-library"],"repository":{"type":"git","url":"git+https://github.com/boxpasshq/boxkit.git"},"author":{"name":"BoxPass"},"bugs":{"url":"https://github.com/boxpasshq/boxkit/issues"},"license":"MIT","readme":"# BoxKit\n\nThe official design system and component library for BoxPass, built with React, TypeScript, and Storybook. This system provides reusable UI components, design tokens, and comprehensive documentation for building consistent user experiences across all BoxPass products.\n\n**📚 [Live Storybook Documentation →](https://boxpasshq.github.io/boxkit)**\n_Interactive component library with examples, automatically updated on every main branch merge_\n\n## 🎯 **Production Design System**\n\nThis is the **official design system** for BoxPass. It provides:\n\n- **Modern development stack** (React + TypeScript + Vite + Storybook)\n- **Production-ready components** with proper TypeScript interfaces\n- **Complete testing setup** with Vitest and browser testing\n- **CI/CD configuration** with CircleCI\n- **Design tokens system** for consistent theming\n- **Configurable branding** system for easy customization\n\n### **🚀 Quick Start**\n\n#### Installing the Design System\n\n```bash\n# Install from npm\nnpm install @boxpasshq/boxkit\n\n# Or with yarn\nyarn add @boxpasshq/boxkit\n```\n\n#### Usage in Your Project\n\n```tsx\nimport { Button, Card } from '@boxpasshq/boxkit';\nimport '@boxpasshq/boxkit/styles';\n\nfunction App() {\n  return (\n    <Card>\n      <Button variant=\"primary\">BoxPass</Button>\n    </Card>\n  );\n}\n```\n\n#### Development Setup\n\n```bash\n# Clone the repository\ngit clone https://github.com/boxpasshq/boxkit.git\ncd boxkit\n\n# Install dependencies and start Storybook\nyarn install && yarn storybook:local\n```\n\n#### Live Documentation\n\n**🌐 [Browse Components Online →](https://boxpasshq.github.io/boxkit)**\nExplore all components, view interactive examples, and see usage guidelines in our live Storybook documentation.\n\n---\n\n## 📦 What's Included\n\nThis design system provides:\n\n- **Enhanced UI Components** (Button, Card) with multiple variants\n- **Design Tokens System** for colors, typography, and spacing\n- **Configurable Brand System** for easy customization\n- **Comprehensive Storybook** documentation\n- **Full Testing Suite** with unit and visual tests\n\n## 🎨 **Design System Documentation**\n\nComprehensive guides for using and extending the design system:\n\n- **[Development Guide](./docs/guides/development.md)** - Commands, workflows, and development setup\n- **[Testing NPM Publishing](./docs/guides/testing-npm-publishing.md)** - Test publishing from non-main branches\n- **[Brand Customization Guide](./docs/template/brand-customization.md)** - Customize for your brand requirements\n- **[Setup Guide](./docs/template/setup.md)** - Complete development environment setup\n\n## 🧩 Example Components\n\n### Button Component\n\n```typescript\nimport { Button } from './components/Button';\n\n<Button variant=\"primary\" size=\"large\">\n  Get Started\n</Button>\n```\n\n### Card Component\n\n```typescript\nimport { Card } from './components/Card';\n\n<Card\n  variant=\"elevated\"\n  header={<h3>Card Title</h3>}\n  footer={<Button>Action</Button>}\n>\n  Card content goes here\n</Card>\n```\n\n### Design Tokens\n\n```typescript\nimport { colors, typography, spacing, brandConfig } from './tokens';\n\n// Use design tokens in your components\nconst myComponent = {\n  color: colors.primary.blue500,\n  fontSize: typography.fontSize.lg,\n  padding: spacing.md,\n  // Brand-specific values\n  companyName: brandConfig.company.name,\n};\n```\n\n## 🎨 **Interactive Development**\n\nView and test all components locally:\n\n```bash\nyarn storybook:local  # Local development (localhost:6006)\nyarn storybook       # Container development (port 80)\n```\n\nVisit Storybook to see:\n\n- Interactive component playground\n- Design token documentation\n- Component API documentation\n- Real-world usage examples\n\n### **📚 Live Documentation**\n\n- **Storybook Demo**: [Live Preview](https://boxpasshq.github.io/boxkit/)\n- **Template Users**: Your Storybook will auto-deploy to `https://yourusername.github.io/your-repo-name/`\n\n## 🧪 **Testing**\n\n```bash\nyarn test               # Run tests in watch mode\nyarn test:run           # Run unit tests once\nyarn test:coverage      # Run with coverage report\nyarn check-all          # Full verification (lint + test + build)\n```\n\n📖 **[Complete Development Guide →](./docs/guides/development.md)** - All commands, workflows, and troubleshooting\n\n## 🚀 **Build & Deploy**\n\n```bash\nyarn build              # Build package for distribution\nyarn build:package      # Build complete package for NPM\nyarn build-storybook    # Build static Storybook documentation\n```\n\n## 📦 **Releases & Contributing**\n\nThis project uses **[semantic-release](https://semantic-release.gitbook.io/)** for fully automated version management and package publishing. All releases are triggered automatically based on conventional commit messages.\n\n### **🚀 How Releases Work**\n\n1. **Commit with conventional format** → Push to any branch\n2. **Create Pull Request** → Review and merge to main\n3. **Automatic release** → semantic-release analyzes commits and publishes\n\n**✨ No manual version bumping required!** The release type is determined automatically from your commit messages.\n\n### **📝 Conventional Commit Format**\n\nUse this format for all commits to enable automatic releases:\n\n```\n<type>[optional scope]: <description>\n\n[optional body]\n\n[optional footer(s)]\n```\n\n### **🎯 Release Types & Examples**\n\n#### **🔧 PATCH Release** (1.0.0 → 1.0.1)\n*Bug fixes that don't change the API*\n\n```bash\ngit commit -m \"fix: resolve button hover state issue\"\ngit commit -m \"fix(card): correct padding in mobile view\"\ngit commit -m \"docs: update installation instructions\"\n```\n\n#### **🚀 MINOR Release** (1.0.0 → 1.1.0)\n*New features that are backward compatible*\n\n```bash\ngit commit -m \"feat: add loading state to Button component\"\ngit commit -m \"feat(card): add new 'outlined' variant\"\ngit commit -m \"feat: implement dark mode support\"\n```\n\n#### **💥 MAJOR Release** (1.0.0 → 2.0.0)\n*Breaking changes that affect existing API*\n\n```bash\ngit commit -m \"feat!: redesign Button component API\n\nBREAKING CHANGE: Button 'size' prop renamed to 'variant'.\nUpdate your imports: size='large' → variant='large'\"\n\n# Or using body:\ngit commit -m \"feat: remove deprecated Card props\n\nBREAKING CHANGE: Removed 'elevation' prop. Use 'variant' instead.\"\n```\n\n### **📋 Common Commit Types**\n\n| Type | Description | Release |\n|------|-------------|---------|\n| `fix:` | Bug fixes | PATCH |\n| `feat:` | New features | MINOR |\n| `feat!:` | Breaking changes | MAJOR |\n| `docs:` | Documentation only | PATCH |\n| `style:` | Code style (formatting, etc.) | PATCH |\n| `refactor:` | Code refactoring | PATCH |\n| `test:` | Adding tests | PATCH |\n| `chore:` | Build process, dependencies | PATCH |\n\n### **🔄 Complete Workflow Example**\n\n```bash\n# 1. Create feature branch\ngit checkout -b feat/add-tooltip-component\n\n# 2. Make your changes\n# ... develop new Tooltip component ...\n\n# 3. Commit with conventional format\ngit add .\ngit commit -m \"feat: add Tooltip component with positioning options\n\n- Add Tooltip component with top, bottom, left, right positions\n- Include hover and click trigger modes\n- Add comprehensive Storybook stories and tests\"\n\n# 4. Push and create PR\ngit push origin feat/add-tooltip-component\n# Create PR through GitHub UI\n\n# 5. After PR approval and merge to main:\n# ✨ semantic-release automatically:\n#   - Detects \"feat:\" → MINOR release\n#   - Bumps version: 1.2.0 → 1.3.0\n#   - Publishes to npm\n#   - Creates GitHub release with changelog\n#   - Updates all related PRs\n```\n\n### **🎯 Tips for Great Releases**\n\n- **Be descriptive**: Good commit messages become release notes\n- **Use scopes**: `feat(button):`, `fix(card):` for better organization\n- **Include context**: Explain why the change was needed\n- **Document breaking changes**: Always include `BREAKING CHANGE:` footer\n- **Test before merging**: Use `yarn check-all` to verify everything works\n\n### **📊 Checking Releases**\n\n```bash\n# View published versions\nnpm view @boxpasshq/boxkit versions --json\n\n# Install specific version\nnpm install @boxpasshq/boxkit@2.0.0\n\n# Check what's in latest release\nnpm view @boxpasshq/boxkit\n```\n\n### **🔗 Resources**\n\n- **[GitHub Releases](https://github.com/boxpasshq/boxkit/releases)** - View all releases and changelogs\n- **[npm Package](https://www.npmjs.com/package/@boxpasshq/boxkit)** - Published package versions\n- **[Conventional Commits](https://conventionalcommits.org/)** - Specification for commit format\n- **[semantic-release](https://semantic-release.gitbook.io/)** - Automated release documentation\n\n---\n\n## 🏗️ **Design System Architecture**\n\n```\nBoxKit\n├── 🧩 Components/          # Reusable UI components\n│   ├── Button/             # Enhanced button with variants\n│   └── Card/               # Flexible card component\n├── 🎨 Design Tokens/       # BoxPass brand system\n│   ├── colors.ts           # Color palette & utilities\n│   ├── typography.ts       # Font & text styles\n│   ├── spacing.ts          # Layout & spacing system\n│   └── brand.ts            # BoxPass brand configuration\n├── 📚 Storybook/          # Component documentation\n├── 🧪 Testing/            # Vitest + Browser testing\n└── 🔄 CI/CD/              # CircleCI configuration\n```\n\n## 🚀 **Live Documentation & Deployment**\n\n### **📚 Storybook Documentation**\n\nOur interactive component library is automatically deployed to [**boxpasshq.github.io/boxkit**](https://boxpasshq.github.io/boxkit) via GitHub Pages.\n\n**📈 Auto-Deployment Triggers:**\n\n- ✅ **Main branch merges** - Documentation updates automatically\n- ✅ **Pull requests** - Preview builds for testing\n- ✅ **Manual triggers** - Deploy on-demand when needed\n\n## 📦 **Publishing the Design System**\n\nThis design system includes **automated NPM publishing** via GitHub Actions with two methods:\n\n### **🏷️ GitHub Releases** (Recommended)\n\n1. Go to your repo's **Releases** page\n2. Click **\"Create a new release\"**\n3. Tag: `v1.0.1`, Title: `v1.0.1`\n4. Click **\"Publish release\"**\n5. ✅ **Automatic NPM publishing**!\n\n### **🔄 Quick Publishing**\n\n1. Go to **Actions** → **\"Publish to NPM\"**\n2. Click **\"Run workflow\"**\n3. Select version bump (`patch`/`minor`/`major`)\n4. Click **\"Run workflow\"**\n5. ✅ **Version bumped and published**!\n\n📖 **[Complete NPM Publishing Guide](./docs/template/npm-publishing.md)** - Detailed setup, troubleshooting, and best practices\n\n## 🌐 **Hosting Your Storybook**\n\n### **GitHub Pages** (Automatic - Recommended)\n\nYour Storybook automatically deploys to:\n`https://yourusername.github.io/your-repo-name/`\n\n1. Go to **Settings** → **Pages** in your GitHub repo\n2. Set **Source** to \"GitHub Actions\"\n3. Push to `main` branch - Storybook deploys automatically!\n\n### **Alternative Hosting Options**\n\n```bash\n# Netlify - Add netlify.toml:\n[build]\n  command = \"yarn build-storybook\"\n  publish = \"storybook-static\"\n\n# Vercel - Add vercel.json:\n{\n  \"buildCommand\": \"yarn build-storybook\",\n  \"outputDirectory\": \"storybook-static\"\n}\n\n# Chromatic (with visual testing)\nyarn chromatic --project-token=<your-token>\n```\n\n## 📋 **Requirements**\n\n- **React** 18.0.0+\n- **React DOM** 18.0.0+\n- **Node.js** 22.0.0+\n- **yarn** 4.5.1+ (managed via packageManager)\n\n## 🎯 **What Makes This Design System Special**\n\n✅ **BoxPass Branded** - Official design system with company brand identity\n✅ **Production Ready** - Battle-tested components used in real applications\n✅ **Fully Typed** - Complete TypeScript support with proper interfaces\n✅ **Comprehensive Testing** - Unit tests + Storybook tests + Visual testing\n✅ **CI/CD Ready** - Automated publishing and deployment workflows\n✅ **Design Token System** - Consistent BoxPass brand tokens\n✅ **Modern Stack** - Vite + Vitest + Storybook 9 + React 18\n\n## 📚 **Documentation**\n\n### **🎨 Design System Resources**\n\n- **[Development Guide](./docs/guides/development.md)** - Complete development workflow and commands\n- **[Testing NPM Publishing](./docs/guides/testing-npm-publishing.md)** - Safe testing procedures for releases\n- **[Brand Guidelines](./docs/template/brand-customization.md)** - BoxPass brand specifications\n- **[Setup Guide](./docs/template/setup.md)** - Development environment setup\n- **[Best Practices](./docs/template/best-practices.md)** - Component development standards\n- **[Design Tokens](./docs/template/design-tokens.md)** - Token system and usage guidelines\n- **[NPM Publishing](./docs/template/npm-publishing.md)** - Release management workflows\n\n### **🔧 Troubleshooting**\n\n- **[WebSocket CI Errors](./docs/websocket-ci-issue-documentation.md)** - Fix \"WebSocket closed without opened\" in containerized CI environments\n\n### **📖 Reference**\n\n- **[Recommended Stack](./docs/reference/recommended-stack.md)** - Tool recommendations for design systems\n\n## 📞 **Support**\n\nFor questions or issues:\n\n- **📚 Live Documentation**: [Storybook Components](https://boxpasshq.github.io/boxkit/) - Interactive component library\n- **🐛 Bug Reports**: [GitHub Issues](https://github.com/boxpasshq/boxkit/issues) - Report bugs and request features\n- **💬 Design System Discussions**: Use GitHub Discussions for design system questions\n\n---\n\n**🎉 Happy building! Create amazing experiences with BoxKit.**\n","readmeFilename":"README.md","_rev":"1-2e8af4b87486372ed9df511456d6a026"}