@windstream/react-shared-components 0.0.10 → 0.0.12

package/README.md

@@ -1,623 +1,623 @@
-# @windstream/react-shared-components
-
-A comprehensive React component library built with TypeScript and Tailwind CSS, designed for Kinetic applications. This library provides a complete set of reusable UI components following the Kinetic design system.
-
-## 🚀 Features
-
-- **TypeScript First**: Full TypeScript support with comprehensive type definitions
-- **Tailwind CSS**: Built with Tailwind CSS for consistent design and easy customization
-- **Modern React**: Built with React 18+ and modern hooks
-- **Accessible**: Components follow accessibility best practices
-- **Customizable**: Easy to customize with CSS variables and Tailwind classes
-- **Tree-shakeable**: Optimized for bundle size with proper exports
-- **Storybook**: Interactive component documentation and development environment
-- **Design System**: Comprehensive design tokens following Kinetic brand guidelines
-- **Material Icons**: Built-in Material Symbols Rounded icon support
-
-## 📦 Installation
-
-```bash
-npm install @windstream/react-shared-components
-# or
-yarn add @windstream/react-shared-components
-# or
-pnpm add @windstream/react-shared-components
-```
-
-## 🔧 Setup
-
-### Prerequisites
-
-- React 18.0.0 or higher
-- React DOM 18.0.0 or higher
-- Tailwind CSS 3.4+ (for styling)
-
-### Tailwind CSS Configuration
-
-This library requires Tailwind CSS to be installed and configured in your project. You can extend the library's Tailwind configuration:
-
-```js
-// tailwind.config.js
-const sharedConfig = require('@windstream/react-shared-components/tailwind.config');
-
-module.exports = {
-  ...sharedConfig,
-  content: [
-    './src/**/*.{js,jsx,ts,tsx}',
-    './node_modules/@windstream/react-shared-components/src/**/*.{js,jsx,ts,tsx}',
-  ],
-};
-```
-
-Or import the Tailwind config directly:
-
-```js
-// tailwind.config.js
-module.exports = {
-  presets: [require('@windstream/react-shared-components/tailwind.config')],
-  content: [
-    './src/**/*.{js,jsx,ts,tsx}',
-    './node_modules/@windstream/react-shared-components/src/**/*.{js,jsx,ts,tsx}',
-  ],
-};
-```
-
-## 🎯 Usage
-
-### Basic Usage
-
-```tsx
-import { Button, Input, Text } from '@windstream/react-shared-components/core';
-
-function MyComponent() {
-  return (
-    <div>
-      <Text className="heading1">Welcome to Kinetic</Text>
-      <Input placeholder="Enter your name" />
-      <Button variant="primary">Submit</Button>
-    </div>
-  );
-}
-```
-
-### Import Paths
-
-The library provides multiple export paths for different use cases:
-
-```tsx
-// Core components (recommended)
-import { Button, Input, Text } from '@windstream/react-shared-components/core';
-
-// Utilities
-import { cx, clsx } from '@windstream/react-shared-components/utils';
-
-// Styles (required - styles are not automatically included)
-import '@windstream/react-shared-components/dist/styles.css';
-// Or in CSS: @import '@windstream/react-shared-components/dist/styles.css';
-
-// Tailwind config
-const tailwindConfig = require('@windstream/react-shared-components/tailwind.config');
-```
-
-### Component Examples
-
-#### Button
-
-```tsx
-import { Button } from '@windstream/react-shared-components/core';
-
-// Different variants
-<Button variant="primary">Primary Button</Button>
-<Button variant="secondary">Secondary Button</Button>
-<Button variant="outline">Outline Button</Button>
-
-// Different sizes
-<Button className="btn-small">Small</Button>
-<Button className="btn-medium">Medium</Button>
-<Button className="btn-large">Large</Button>
-
-// With loading state
-<Button isLoading>Loading...</Button>
-
-// Full width
-<Button fullWidth>Full Width Button</Button>
-```
-
-#### Input
-
-```tsx
-import { Input, InputField, TextInput } from '@windstream/react-shared-components/core';
-
-// Input, InputField, and TextInput are all aliases for the same component
-<Input 
-  placeholder="Enter text"
-  type="text"
-  variant="default"
-  size="medium"
-/>
-
-<InputField 
-  placeholder="Enter text"
-  label="Name"
-/>
-
-<TextInput 
-  placeholder="Enter text"
-/>
-```
-
-#### Text
-
-```tsx
-import { Text } from '@windstream/react-shared-components/core';
-
-<Text className="heading1">Heading 1</Text>
-<Text className="body1">Body text</Text>
-<Text className="caption">Caption text</Text>
-```
-
-### Utilities
-
-The `cx` utility is an enhanced version of `clsx` that intelligently merges Tailwind classes:
-
-```tsx
-import { cx, clsx } from '@windstream/react-shared-components/utils';
-
-// cx automatically merges conflicting Tailwind classes
-const classes = cx('btn', 'btn-primary', condition && 'btn-secondary');
-// If condition is true, btn-secondary will override btn-primary
-
-// clsx is also available for basic class name concatenation
-const basicClasses = clsx('btn', condition && 'active');
-```
-
-### Hooks
-
-```tsx
-import { useBodyScrollLock } from '@windstream/react-shared-components/core';
-
-function Modal({ isOpen }) {
-  // Lock body scroll when modal is open
-  useBodyScrollLock(isOpen, true);
-  
-  return (
-    // Modal content
-  );
-}
-```
-
-## 🎨 Available Components
-
-All components are available from the `/core` export path:
-
-```tsx
-import { 
-  Button, 
-  Input,
-  InputField,
-  TextInput,
-  Link, 
-  List,
-  ListItem,
-  MaterialIcon, 
-  Spinner, 
-  Text,
-  CallButton,
-  Modal,
-  Accordion,
-  Checkbox,
-  Select,
-  AlertCard,
-  BrandButton,
-  Checklist,
-  Collapse,
-  Divider,
-  RadioButton,
-  SeeMore,
-  SelectPlanButton,
-  Skeleton,
-  PageSkeleton,
-  Tooltip,
-  ViewCartButton,
-  useBodyScrollLock
-} from '@windstream/react-shared-components/core';
-```
-
-### Core Components
-
-- **Button** - Versatile button component with multiple variants and sizes
-- **Input / InputField / TextInput** - Form input component with validation states (all are aliases)
-- **Link** - Accessible link component
-- **List / ListItem** - List and list item components
-- **MaterialIcon** - Material Design icon component using Material Symbols Rounded
-- **Spinner** - Loading spinner component
-- **Text** - Typography component with predefined variants (heading1-6, body1-3, etc.)
-- **CallButton** - Button component for call-to-action
-- **Modal** - Modal dialog component with customizable size, shape, and animations
-- **Accordion** - Collapsible accordion component
-- **Checkbox** - Checkbox input component
-- **Select** - Select dropdown component (powered by react-select)
-- **AlertCard** - Alert notification card component
-- **BrandButton** - Branded button variant with responsive sizing
-- **Checklist** - Checklist component
-- **Collapse** - Collapsible content component
-- **Divider** - Divider/separator component
-- **RadioButton** - Radio button input component
-- **SeeMore** - Expandable content component
-- **SelectPlanButton** - Plan selection button
-- **Skeleton / PageSkeleton** - Loading skeleton components
-- **Tooltip** - Tooltip component
-- **ViewCartButton** - Shopping cart button component
-
-### Custom Hooks
-
-- **useBodyScrollLock** - Hook to lock/unlock body scroll (useful for modals)
-
-### Component Variants
-
-Each component comes with multiple variants and sizes to fit different use cases:
-
-- **Variants**: default, primary, secondary, outline, unstyled
-- **Sizes**: small (btn-small), medium (btn-medium), large (btn-large), x-large (btn-x-large)
-- **States**: loading, disabled, error, success
-
-### Typography Variants
-
-The `Text` component supports the following typography variants via className:
-
-- **Headings**: `heading1`, `heading2`, `heading3`, `heading4`, `heading5`, `heading6`
-- **Subheadings**: `subheading1`, `subheading2`, `subheading3`, `subheading4`, `subheading5`, `subheading6`
-- **Body**: `body1`, `body2`, `body3`
-- **Labels**: `label1`, `label2`, `label3`, `label4`, `label5`, `label6`
-- **Other**: `footnote`, `micro`
-
-## 🎨 Design System
-
-This library follows the Kinetic design system with comprehensive design tokens:
-
-### Color System
-
-- **Brand Colors**: Primary brand color (#24A76A) with variants (accent, active, hover, disabled, etc.)
-- **Semantic Colors**: Success, critical (error), info, inverse
-- **Surface Colors**: Background fills, surfaces with states (active, hover, selected, disabled)
-- **Text Colors**: Default, brand, critical, secondary, inverse, disabled
-- **Border Colors**: Default, brand, critical, focus, hover, disabled
-- **Icon Colors**: Brand, critical, default, info, inverse, secondary, success
-
-### Typography
-
-- **Font Families**: 
-  - Sans-serif (configurable via CSS variable `--win-site-font`)
-  - Material Symbols Rounded (for icons)
-  - Figtree (for body text)
-- **Font Sizes**: Comprehensive scale from micro (12px) to heading1 (48px)
-- **Line Heights**: Standardized line heights for optimal readability
-
-### Spacing & Layout
-
-- **Spacing Scale**: Custom spacing values (1.5, 2, 3, 4, 4.5, 6, 7, 13, 15, 17, 18, 26)
-- **Border Radius**: Custom radius values (2.5, 3.5, 2xl, 2.5xl, 4xl)
-- **Shadows**: drop, light, cardDrop, card
-
-### Responsive Breakpoints
-
-- `sm`: 640px
-- `md`: 768px
-- `lg`: 1024px
-- `xl`: 1280px
-- `max`: 1200px
-
-## 🔧 Development
-
-### Prerequisites
-
-- Node.js 16+
-- npm 7+ or yarn 1.22+
-
-### Setup
-
-```bash
-# Clone the repository
-git clone <repository-url>
-cd kinetic-react-shared-components
-
-# Install dependencies
-npm install
-
-# Start development mode (watch mode)
-npm run dev
-
-# Build the library
-npm run build
-
-# Run tests
-npm test
-
-# Run tests in watch mode
-npm run test:watch
-
-# Run linting
-npm run lint
-
-# Fix linting issues
-npm run lint:fix
-
-# Format code
-npm run format
-
-# Check code formatting
-npm run format:check
-
-# Type check
-npm run type-check
-
-# Start Storybook (component documentation)
-npm run storybook
-
-# Build Storybook
-npm run build-storybook
-
-# Clean build artifacts
-npm run clean
-```
-
-### Project Structure
-
-```
-src/
-├── components/          # React components
-│   ├── accordion/      # Accordion component
-│   ├── alert-card/     # AlertCard component
-│   ├── brand-button/   # BrandButton component
-│   ├── button/         # Button component
-│   ├── call-button/    # CallButton component
-│   ├── checkbox/       # Checkbox component
-│   ├── checklist/      # Checklist component
-│   ├── collapse/       # Collapse component
-│   ├── divider/        # Divider component
-│   ├── input/          # Input component
-│   ├── link/           # Link component
-│   ├── list/           # List components
-│   ├── material-icon/  # Icon component
-│   ├── modal/          # Modal component
-│   ├── radio-button/   # RadioButton component
-│   ├── see-more/       # SeeMore component
-│   ├── select/         # Select component
-│   ├── select-plan-button/ # SelectPlanButton component
-│   ├── skeleton/       # Skeleton component
-│   ├── spinner/        # Spinner component
-│   ├── text/           # Text component
-│   ├── tooltip/        # Tooltip component
-│   └── view-cart-button/ # ViewCartButton component
-├── hooks/              # Custom React hooks
-├── styles/             # Global styles and Tailwind config
-├── utils/              # Utility functions
-└── index.ts            # Main export file (exports all components)
-```
-
-### Building
-
-The library is built using Rollup with the following outputs:
-
-- **CommonJS**: `dist/index.js` and `dist/utils/index.js`
-- **ES Modules**: `dist/index.esm.js` and `dist/utils/index.esm.js`
-- **TypeScript declarations**: `dist/index.d.ts`, `dist/core.d.ts`, and `dist/utils/index.d.ts`
-- **Styles**: `dist/styles.css` (extracted and minified)
-
-All components are exported from a single entry point (`src/index.ts`), which allows for:
-- Simplified build process
-- Consistent import path: `@windstream/react-shared-components/core`
-- Tree-shaking support for optimal bundle sizes
-- Separate utils export path for utility-only imports
-
-### Package Exports
-
-The package provides the following export paths:
-
-- `@windstream/react-shared-components/core` - All components and hooks
-- `@windstream/react-shared-components/utils` - Utility functions (cx, clsx)
-- `@windstream/react-shared-components/styles.css` - Compiled CSS styles
-- `@windstream/react-shared-components/tailwind.config` - Tailwind configuration
-
-## 📦 Publishing
-
-### Prerequisites
-
-Before publishing the package, ensure you have:
-
-1. **npm account**: An account on npmjs.com with access to the `@windstream` organization
-2. **Authentication**: Logged in to npm via `npm login` or using an authentication token
-3. **Organization access**: Permission to publish packages under the `@windstream` scope
-
-### Publishing Steps
-
-1. **Ensure you're authenticated**:
-   ```bash
-   npm login
-   # Or verify your authentication
-   npm whoami
-   ```
-
-2. **Update the version** in `package.json`:
-   ```bash
-   # For patch version (0.0.4 -> 0.0.5)
-   npm version patch
-   
-   # For minor version (0.0.4 -> 0.1.0)
-   npm version minor
-   
-   # For major version (0.0.4 -> 1.0.0)
-   npm version major
-   ```
-   
-   Or manually update the `version` field in `package.json` and commit the change.
-
-3. **Build the package**:
-   ```bash
-   npm run build
-   ```
-   
-   This will:
-   - Clean the `dist` directory
-   - Build CommonJS and ES Module outputs
-   - Generate TypeScript declarations
-   - Extract and minify CSS styles
-
-4. **Verify the build**:
-   ```bash
-   # Check that dist directory contains all necessary files
-   ls -la dist/
-   ```
-   
-   Ensure the following files exist:
-   - `dist/index.js` (CommonJS)
-   - `dist/index.esm.js` (ES Modules)
-   - `dist/index.d.ts` (TypeScript declarations)
-   - `dist/core.d.ts` (Core types)
-   - `dist/utils/index.js` (Utils CommonJS)
-   - `dist/utils/index.esm.js` (Utils ES Modules)
-   - `dist/utils/index.d.ts` (Utils types)
-   - `dist/styles.css` (Compiled CSS)
-
-5. **Run tests** (optional but recommended):
-   ```bash
-   npm test
-   npm run type-check
-   ```
-
-6. **Publish to npm**:
-   ```bash
-   # Dry run to see what would be published
-   npm publish --dry-run
-   
-   # Publish to npm
-   npm publish --access public
-   ```
-   
-   Note: The `--access public` flag is required for scoped packages (`@windstream/...`) when publishing to the public npm registry.
-
-7. **Create a git tag** (if you used `npm version`, this is done automatically):
-   ```bash
-   # If you manually updated the version, create and push the tag
-   git tag v0.0.4
-   git push origin v0.0.4
-   ```
-
-8. **Push changes to repository**:
-   ```bash
-   git push origin main
-   ```
-
-### Version Management
-
-Follow [Semantic Versioning](https://semver.org/) (semver):
-
-- **MAJOR** version (1.0.0): Breaking changes
-- **MINOR** version (0.1.0): New features (backward compatible)
-- **PATCH** version (0.0.5): Bug fixes (backward compatible)
-
-### Publishing Checklist
-
-Before publishing, verify:
-
-- [ ] All tests pass (`npm test`)
-- [ ] Type checking passes (`npm run type-check`)
-- [ ] Linting passes (`npm run lint`)
-- [ ] Build completes successfully (`npm run build`)
-- [ ] Version number is updated in `package.json`
-- [ ] README is up to date
-- [ ] All changes are committed
-- [ ] You're logged in to npm (`npm whoami`)
-
-## 🧪 Testing
-
-The library uses Jest and React Testing Library for testing:
-
-```bash
-# Run tests
-npm test
-
-# Run tests in watch mode
-npm run test:watch
-
-# Run tests with coverage
-npm run test:coverage
-```
-
-Test files should be named `*.test.ts` or `*.test.tsx` and placed alongside the components they test.
-
-## 📝 Contributing
-
-1. Fork the repository
-2. Create a feature branch (`git checkout -b feature/amazing-feature`)
-3. Commit your changes (`git commit -m 'Add some amazing feature'`)
-4. Push to the branch (`git push origin feature/amazing-feature`)
-5. Open a Pull Request
-
-### Development Guidelines
-
-- Follow the existing code style and conventions
-- Write tests for new components and features
-- Update documentation for any API changes
-- Ensure all components are accessible
-- Follow the established component structure
-
-## 📄 License
-
-This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
-
-## 🤝 Support
-
-For support and questions:
-
-- Create an issue in the GitHub repository
-- Contact the Kinetic development team
-- Check the documentation and examples
-
-## 🔄 Changelog
-
-### v0.0.4
-- Current version
-- 23+ React components with full TypeScript support
-- Comprehensive design system with Tailwind CSS
-- Material Symbols Rounded icon support
-- Storybook integration for component documentation
-- Custom hooks (useBodyScrollLock)
-- Utility functions (cx, clsx) with Tailwind class merging
-- Multiple export paths (core, utils, styles, tailwind.config)
-- CommonJS and ES Module builds
-- Full type definitions
-
-### Components Included
-- **Form Components**: Button, Input, Checkbox, RadioButton, Select
-- **Layout Components**: List, ListItem, Divider, Collapse, Accordion
-- **Feedback Components**: Spinner, Skeleton, PageSkeleton, AlertCard, Tooltip
-- **Navigation Components**: Link, Modal, SeeMore
-- **Specialized Components**: CallButton, BrandButton, SelectPlanButton, ViewCartButton
-- **Typography**: Text component with comprehensive variant system
-- **Icons**: MaterialIcon component
-
-## 📚 Additional Resources
-
-- [React Documentation](https://reactjs.org/)
-- [Tailwind CSS Documentation](https://tailwindcss.com/)
-- [TypeScript Documentation](https://www.typescriptlang.org/)
-- [Storybook Documentation](https://storybook.js.org/)
-- [Material Symbols](https://fonts.google.com/icons)
-- [React Testing Library](https://testing-library.com/react)
-- [Jest Documentation](https://jestjs.io/)
-
-## 📦 Package Information
-
-- **Package Name**: `@windstream/react-shared-components`
-- **Current Version**: `0.0.4`
-- **License**: MIT
-- **Repository**: [GitHub](https://github.com/kinetic/react-shared-components)
-- **Issues**: [GitHub Issues](https://github.com/kinetic/react-shared-components/issues)
-
-## 🔗 Related Packages
-
-This package is part of the Kinetic ecosystem and works seamlessly with:
-- Kinetic design system tokens
-- Kinetic applications and services
-- Other Windstream/Kinetic React packages
+# @windstream/react-shared-components
+
+A comprehensive React component library built with TypeScript and Tailwind CSS, designed for Kinetic applications. This library provides a complete set of reusable UI components following the Kinetic design system.
+
+## 🚀 Features
+
+- **TypeScript First**: Full TypeScript support with comprehensive type definitions
+- **Tailwind CSS**: Built with Tailwind CSS for consistent design and easy customization
+- **Modern React**: Built with React 18+ and modern hooks
+- **Accessible**: Components follow accessibility best practices
+- **Customizable**: Easy to customize with CSS variables and Tailwind classes
+- **Tree-shakeable**: Optimized for bundle size with proper exports
+- **Storybook**: Interactive component documentation and development environment
+- **Design System**: Comprehensive design tokens following Kinetic brand guidelines
+- **Material Icons**: Built-in Material Symbols Rounded icon support
+
+## 📦 Installation
+
+```bash
+npm install @windstream/react-shared-components
+# or
+yarn add @windstream/react-shared-components
+# or
+pnpm add @windstream/react-shared-components
+```
+
+## 🔧 Setup
+
+### Prerequisites
+
+- React 18.0.0 or higher
+- React DOM 18.0.0 or higher
+- Tailwind CSS 3.4+ (for styling)
+
+### Tailwind CSS Configuration
+
+This library requires Tailwind CSS to be installed and configured in your project. You can extend the library's Tailwind configuration:
+
+```js
+// tailwind.config.js
+const sharedConfig = require('@windstream/react-shared-components/tailwind.config');
+
+module.exports = {
+  ...sharedConfig,
+  content: [
+    './src/**/*.{js,jsx,ts,tsx}',
+    './node_modules/@windstream/react-shared-components/src/**/*.{js,jsx,ts,tsx}',
+  ],
+};
+```
+
+Or import the Tailwind config directly:
+
+```js
+// tailwind.config.js
+module.exports = {
+  presets: [require('@windstream/react-shared-components/tailwind.config')],
+  content: [
+    './src/**/*.{js,jsx,ts,tsx}',
+    './node_modules/@windstream/react-shared-components/src/**/*.{js,jsx,ts,tsx}',
+  ],
+};
+```
+
+## 🎯 Usage
+
+### Basic Usage
+
+```tsx
+import { Button, Input, Text } from '@windstream/react-shared-components/core';
+
+function MyComponent() {
+  return (
+    <div>
+      <Text className="heading1">Welcome to Kinetic</Text>
+      <Input placeholder="Enter your name" />
+      <Button variant="primary">Submit</Button>
+    </div>
+  );
+}
+```
+
+### Import Paths
+
+The library provides multiple export paths for different use cases:
+
+```tsx
+// Core components (recommended)
+import { Button, Input, Text } from '@windstream/react-shared-components/core';
+
+// Utilities
+import { cx, clsx } from '@windstream/react-shared-components/utils';
+
+// Styles (required - styles are not automatically included)
+import '@windstream/react-shared-components/dist/styles.css';
+// Or in CSS: @import '@windstream/react-shared-components/dist/styles.css';
+
+// Tailwind config
+const tailwindConfig = require('@windstream/react-shared-components/tailwind.config');
+```
+
+### Component Examples
+
+#### Button
+
+```tsx
+import { Button } from '@windstream/react-shared-components/core';
+
+// Different variants
+<Button variant="primary">Primary Button</Button>
+<Button variant="secondary">Secondary Button</Button>
+<Button variant="outline">Outline Button</Button>
+
+// Different sizes
+<Button className="btn-small">Small</Button>
+<Button className="btn-medium">Medium</Button>
+<Button className="btn-large">Large</Button>
+
+// With loading state
+<Button isLoading>Loading...</Button>
+
+// Full width
+<Button fullWidth>Full Width Button</Button>
+```
+
+#### Input
+
+```tsx
+import { Input, InputField, TextInput } from '@windstream/react-shared-components/core';
+
+// Input, InputField, and TextInput are all aliases for the same component
+<Input 
+  placeholder="Enter text"
+  type="text"
+  variant="default"
+  size="medium"
+/>
+
+<InputField 
+  placeholder="Enter text"
+  label="Name"
+/>
+
+<TextInput 
+  placeholder="Enter text"
+/>
+```
+
+#### Text
+
+```tsx
+import { Text } from '@windstream/react-shared-components/core';
+
+<Text className="heading1">Heading 1</Text>
+<Text className="body1">Body text</Text>
+<Text className="caption">Caption text</Text>
+```
+
+### Utilities
+
+The `cx` utility is an enhanced version of `clsx` that intelligently merges Tailwind classes:
+
+```tsx
+import { cx, clsx } from '@windstream/react-shared-components/utils';
+
+// cx automatically merges conflicting Tailwind classes
+const classes = cx('btn', 'btn-primary', condition && 'btn-secondary');
+// If condition is true, btn-secondary will override btn-primary
+
+// clsx is also available for basic class name concatenation
+const basicClasses = clsx('btn', condition && 'active');
+```
+
+### Hooks
+
+```tsx
+import { useBodyScrollLock } from '@windstream/react-shared-components/core';
+
+function Modal({ isOpen }) {
+  // Lock body scroll when modal is open
+  useBodyScrollLock(isOpen, true);
+  
+  return (
+    // Modal content
+  );
+}
+```
+
+## 🎨 Available Components
+
+All components are available from the `/core` export path:
+
+```tsx
+import { 
+  Button, 
+  Input,
+  InputField,
+  TextInput,
+  Link, 
+  List,
+  ListItem,
+  MaterialIcon, 
+  Spinner, 
+  Text,
+  CallButton,
+  Modal,
+  Accordion,
+  Checkbox,
+  Select,
+  AlertCard,
+  BrandButton,
+  Checklist,
+  Collapse,
+  Divider,
+  RadioButton,
+  SeeMore,
+  SelectPlanButton,
+  Skeleton,
+  PageSkeleton,
+  Tooltip,
+  ViewCartButton,
+  useBodyScrollLock
+} from '@windstream/react-shared-components/core';
+```
+
+### Core Components
+
+- **Button** - Versatile button component with multiple variants and sizes
+- **Input / InputField / TextInput** - Form input component with validation states (all are aliases)
+- **Link** - Accessible link component
+- **List / ListItem** - List and list item components
+- **MaterialIcon** - Material Design icon component using Material Symbols Rounded
+- **Spinner** - Loading spinner component
+- **Text** - Typography component with predefined variants (heading1-6, body1-3, etc.)
+- **CallButton** - Button component for call-to-action
+- **Modal** - Modal dialog component with customizable size, shape, and animations
+- **Accordion** - Collapsible accordion component
+- **Checkbox** - Checkbox input component
+- **Select** - Select dropdown component (powered by react-select)
+- **AlertCard** - Alert notification card component
+- **BrandButton** - Branded button variant with responsive sizing
+- **Checklist** - Checklist component
+- **Collapse** - Collapsible content component
+- **Divider** - Divider/separator component
+- **RadioButton** - Radio button input component
+- **SeeMore** - Expandable content component
+- **SelectPlanButton** - Plan selection button
+- **Skeleton / PageSkeleton** - Loading skeleton components
+- **Tooltip** - Tooltip component
+- **ViewCartButton** - Shopping cart button component
+
+### Custom Hooks
+
+- **useBodyScrollLock** - Hook to lock/unlock body scroll (useful for modals)
+
+### Component Variants
+
+Each component comes with multiple variants and sizes to fit different use cases:
+
+- **Variants**: default, primary, secondary, outline, unstyled
+- **Sizes**: small (btn-small), medium (btn-medium), large (btn-large), x-large (btn-x-large)
+- **States**: loading, disabled, error, success
+
+### Typography Variants
+
+The `Text` component supports the following typography variants via className:
+
+- **Headings**: `heading1`, `heading2`, `heading3`, `heading4`, `heading5`, `heading6`
+- **Subheadings**: `subheading1`, `subheading2`, `subheading3`, `subheading4`, `subheading5`, `subheading6`
+- **Body**: `body1`, `body2`, `body3`
+- **Labels**: `label1`, `label2`, `label3`, `label4`, `label5`, `label6`
+- **Other**: `footnote`, `micro`
+
+## 🎨 Design System
+
+This library follows the Kinetic design system with comprehensive design tokens:
+
+### Color System
+
+- **Brand Colors**: Primary brand color (#24A76A) with variants (accent, active, hover, disabled, etc.)
+- **Semantic Colors**: Success, critical (error), info, inverse
+- **Surface Colors**: Background fills, surfaces with states (active, hover, selected, disabled)
+- **Text Colors**: Default, brand, critical, secondary, inverse, disabled
+- **Border Colors**: Default, brand, critical, focus, hover, disabled
+- **Icon Colors**: Brand, critical, default, info, inverse, secondary, success
+
+### Typography
+
+- **Font Families**: 
+  - Sans-serif (configurable via CSS variable `--win-site-font`)
+  - Material Symbols Rounded (for icons)
+  - Figtree (for body text)
+- **Font Sizes**: Comprehensive scale from micro (12px) to heading1 (48px)
+- **Line Heights**: Standardized line heights for optimal readability
+
+### Spacing & Layout
+
+- **Spacing Scale**: Custom spacing values (1.5, 2, 3, 4, 4.5, 6, 7, 13, 15, 17, 18, 26)
+- **Border Radius**: Custom radius values (2.5, 3.5, 2xl, 2.5xl, 4xl)
+- **Shadows**: drop, light, cardDrop, card
+
+### Responsive Breakpoints
+
+- `sm`: 640px
+- `md`: 768px
+- `lg`: 1024px
+- `xl`: 1280px
+- `max`: 1200px
+
+## 🔧 Development
+
+### Prerequisites
+
+- Node.js 16+
+- npm 7+ or yarn 1.22+
+
+### Setup
+
+```bash
+# Clone the repository
+git clone <repository-url>
+cd kinetic-react-shared-components
+
+# Install dependencies
+npm install
+
+# Start development mode (watch mode)
+npm run dev
+
+# Build the library
+npm run build
+
+# Run tests
+npm test
+
+# Run tests in watch mode
+npm run test:watch
+
+# Run linting
+npm run lint
+
+# Fix linting issues
+npm run lint:fix
+
+# Format code
+npm run format
+
+# Check code formatting
+npm run format:check
+
+# Type check
+npm run type-check
+
+# Start Storybook (component documentation)
+npm run storybook
+
+# Build Storybook
+npm run build-storybook
+
+# Clean build artifacts
+npm run clean
+```
+
+### Project Structure
+
+```
+src/
+├── components/          # React components
+│   ├── accordion/      # Accordion component
+│   ├── alert-card/     # AlertCard component
+│   ├── brand-button/   # BrandButton component
+│   ├── button/         # Button component
+│   ├── call-button/    # CallButton component
+│   ├── checkbox/       # Checkbox component
+│   ├── checklist/      # Checklist component
+│   ├── collapse/       # Collapse component
+│   ├── divider/        # Divider component
+│   ├── input/          # Input component
+│   ├── link/           # Link component
+│   ├── list/           # List components
+│   ├── material-icon/  # Icon component
+│   ├── modal/          # Modal component
+│   ├── radio-button/   # RadioButton component
+│   ├── see-more/       # SeeMore component
+│   ├── select/         # Select component
+│   ├── select-plan-button/ # SelectPlanButton component
+│   ├── skeleton/       # Skeleton component
+│   ├── spinner/        # Spinner component
+│   ├── text/           # Text component
+│   ├── tooltip/        # Tooltip component
+│   └── view-cart-button/ # ViewCartButton component
+├── hooks/              # Custom React hooks
+├── styles/             # Global styles and Tailwind config
+├── utils/              # Utility functions
+└── index.ts            # Main export file (exports all components)
+```
+
+### Building
+
+The library is built using Rollup with the following outputs:
+
+- **CommonJS**: `dist/index.js` and `dist/utils/index.js`
+- **ES Modules**: `dist/index.esm.js` and `dist/utils/index.esm.js`
+- **TypeScript declarations**: `dist/index.d.ts`, `dist/core.d.ts`, and `dist/utils/index.d.ts`
+- **Styles**: `dist/styles.css` (extracted and minified)
+
+All components are exported from a single entry point (`src/index.ts`), which allows for:
+- Simplified build process
+- Consistent import path: `@windstream/react-shared-components/core`
+- Tree-shaking support for optimal bundle sizes
+- Separate utils export path for utility-only imports
+
+### Package Exports
+
+The package provides the following export paths:
+
+- `@windstream/react-shared-components/core` - All components and hooks
+- `@windstream/react-shared-components/utils` - Utility functions (cx, clsx)
+- `@windstream/react-shared-components/styles.css` - Compiled CSS styles
+- `@windstream/react-shared-components/tailwind.config` - Tailwind configuration
+
+## 📦 Publishing
+
+### Prerequisites
+
+Before publishing the package, ensure you have:
+
+1. **npm account**: An account on npmjs.com with access to the `@windstream` organization
+2. **Authentication**: Logged in to npm via `npm login` or using an authentication token
+3. **Organization access**: Permission to publish packages under the `@windstream` scope
+
+### Publishing Steps
+
+1. **Ensure you're authenticated**:
+   ```bash
+   npm login
+   # Or verify your authentication
+   npm whoami
+   ```
+
+2. **Update the version** in `package.json`:
+   ```bash
+   # For patch version (0.0.4 -> 0.0.5)
+   npm version patch
+   
+   # For minor version (0.0.4 -> 0.1.0)
+   npm version minor
+   
+   # For major version (0.0.4 -> 1.0.0)
+   npm version major
+   ```
+   
+   Or manually update the `version` field in `package.json` and commit the change.
+
+3. **Build the package**:
+   ```bash
+   npm run build
+   ```
+   
+   This will:
+   - Clean the `dist` directory
+   - Build CommonJS and ES Module outputs
+   - Generate TypeScript declarations
+   - Extract and minify CSS styles
+
+4. **Verify the build**:
+   ```bash
+   # Check that dist directory contains all necessary files
+   ls -la dist/
+   ```
+   
+   Ensure the following files exist:
+   - `dist/index.js` (CommonJS)
+   - `dist/index.esm.js` (ES Modules)
+   - `dist/index.d.ts` (TypeScript declarations)
+   - `dist/core.d.ts` (Core types)
+   - `dist/utils/index.js` (Utils CommonJS)
+   - `dist/utils/index.esm.js` (Utils ES Modules)
+   - `dist/utils/index.d.ts` (Utils types)
+   - `dist/styles.css` (Compiled CSS)
+
+5. **Run tests** (optional but recommended):
+   ```bash
+   npm test
+   npm run type-check
+   ```
+
+6. **Publish to npm**:
+   ```bash
+   # Dry run to see what would be published
+   npm publish --dry-run
+   
+   # Publish to npm
+   npm publish --access public
+   ```
+   
+   Note: The `--access public` flag is required for scoped packages (`@windstream/...`) when publishing to the public npm registry.
+
+7. **Create a git tag** (if you used `npm version`, this is done automatically):
+   ```bash
+   # If you manually updated the version, create and push the tag
+   git tag v0.0.4
+   git push origin v0.0.4
+   ```
+
+8. **Push changes to repository**:
+   ```bash
+   git push origin main
+   ```
+
+### Version Management
+
+Follow [Semantic Versioning](https://semver.org/) (semver):
+
+- **MAJOR** version (1.0.0): Breaking changes
+- **MINOR** version (0.1.0): New features (backward compatible)
+- **PATCH** version (0.0.5): Bug fixes (backward compatible)
+
+### Publishing Checklist
+
+Before publishing, verify:
+
+- [ ] All tests pass (`npm test`)
+- [ ] Type checking passes (`npm run type-check`)
+- [ ] Linting passes (`npm run lint`)
+- [ ] Build completes successfully (`npm run build`)
+- [ ] Version number is updated in `package.json`
+- [ ] README is up to date
+- [ ] All changes are committed
+- [ ] You're logged in to npm (`npm whoami`)
+
+## 🧪 Testing
+
+The library uses Jest and React Testing Library for testing:
+
+```bash
+# Run tests
+npm test
+
+# Run tests in watch mode
+npm run test:watch
+
+# Run tests with coverage
+npm run test:coverage
+```
+
+Test files should be named `*.test.ts` or `*.test.tsx` and placed alongside the components they test.
+
+## 📝 Contributing
+
+1. Fork the repository
+2. Create a feature branch (`git checkout -b feature/amazing-feature`)
+3. Commit your changes (`git commit -m 'Add some amazing feature'`)
+4. Push to the branch (`git push origin feature/amazing-feature`)
+5. Open a Pull Request
+
+### Development Guidelines
+
+- Follow the existing code style and conventions
+- Write tests for new components and features
+- Update documentation for any API changes
+- Ensure all components are accessible
+- Follow the established component structure
+
+## 📄 License
+
+This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
+
+## 🤝 Support
+
+For support and questions:
+
+- Create an issue in the GitHub repository
+- Contact the Kinetic development team
+- Check the documentation and examples
+
+## 🔄 Changelog
+
+### v0.0.4
+- Current version
+- 23+ React components with full TypeScript support
+- Comprehensive design system with Tailwind CSS
+- Material Symbols Rounded icon support
+- Storybook integration for component documentation
+- Custom hooks (useBodyScrollLock)
+- Utility functions (cx, clsx) with Tailwind class merging
+- Multiple export paths (core, utils, styles, tailwind.config)
+- CommonJS and ES Module builds
+- Full type definitions
+
+### Components Included
+- **Form Components**: Button, Input, Checkbox, RadioButton, Select
+- **Layout Components**: List, ListItem, Divider, Collapse, Accordion
+- **Feedback Components**: Spinner, Skeleton, PageSkeleton, AlertCard, Tooltip
+- **Navigation Components**: Link, Modal, SeeMore
+- **Specialized Components**: CallButton, BrandButton, SelectPlanButton, ViewCartButton
+- **Typography**: Text component with comprehensive variant system
+- **Icons**: MaterialIcon component
+
+## 📚 Additional Resources
+
+- [React Documentation](https://reactjs.org/)
+- [Tailwind CSS Documentation](https://tailwindcss.com/)
+- [TypeScript Documentation](https://www.typescriptlang.org/)
+- [Storybook Documentation](https://storybook.js.org/)
+- [Material Symbols](https://fonts.google.com/icons)
+- [React Testing Library](https://testing-library.com/react)
+- [Jest Documentation](https://jestjs.io/)
+
+## 📦 Package Information
+
+- **Package Name**: `@windstream/react-shared-components`
+- **Current Version**: `0.0.4`
+- **License**: MIT
+- **Repository**: [GitHub](https://github.com/kinetic/react-shared-components)
+- **Issues**: [GitHub Issues](https://github.com/kinetic/react-shared-components/issues)
+
+## 🔗 Related Packages
+
+This package is part of the Kinetic ecosystem and works seamlessly with:
+- Kinetic design system tokens
+- Kinetic applications and services
+- Other Windstream/Kinetic React packages