baseline-ds 0.1.4

package/README.md

@@ -0,0 +1,330 @@
+# Baseline Design System
+
+A comprehensive design system with tokens, components, icons, and Storybook documentation.
+
+## Features
+
+- 🎨 **Design Tokens** - Multi-brand token system with primitives, brand overrides, and semantic tokens
+- 🧩 **React Components** - Reusable, accessible components built with TypeScript
+- 🎯 **Icon System** - 50+ SVG icons as React components
+- 🎭 **Multi-Brand Support** - Switch between Baseline, Baseline Pro, and Offset themes
+- 📚 **Storybook Documentation** - Interactive component documentation and examples
+
+## Installation
+
+```bash
+npm install @baseline/design-system
+```
+
+## Design Tokens
+
+The design system uses a cascading token architecture:
+
+1. **Primitive Core** (`0000PrimitiveCore_Mode1.json`) - Base values (colors, spacing, typography)
+2. **Brand Overrides** (`0001PrimitiveBrand_*.json`) - Brand-specific customizations
+3. **Semantic Layer** (`0100SemanticCore_Mode1.json`) - Contextual tokens that reference primitives and brands
+
+### Using Tokens
+
+#### CSS Variables
+
+```css
+/* Import primitives, brand, and semantic tokens */
+@import '@baseline/design-system/tokens/css';
+
+/* Use in your CSS */
+.button {
+  background-color: var(--brand-color-brand-100);
+  padding: var(--spacing-scale-050) var(--spacing-scale-070);
+  border-radius: var(--brand-sizing-radius-small);
+  font-family: var(--brand-typography-font-family-body);
+  font-size: var(--brand-sizing-typography-font-size-paragraph-medium);
+}
+```
+
+#### JavaScript/TypeScript
+
+```typescript
+import tokens from '@baseline/design-system/tokens/json';
+
+const primaryColor = tokens.color.brand[100];
+const spacing = tokens.spacing.scale[50];
+```
+
+#### SCSS
+
+```scss
+@import '@baseline/design-system/tokens/scss';
+
+.button {
+  background-color: $brand-color-brand-100;
+  padding: $spacing-scale-050 $spacing-scale-070;
+}
+```
+
+### Available Token Formats
+
+- `@baseline/design-system/tokens/css` - CSS variables
+- `@baseline/design-system/tokens/scss` - SCSS variables
+- `@baseline/design-system/tokens/js` - JavaScript/ES modules
+- `@baseline/design-system/tokens/json` - JSON format
+
+### Brand-Specific Tokens
+
+You can also import brand-specific token files:
+
+- `@baseline/design-system/tokens/css/baseline`
+- `@baseline/design-system/tokens/css/baseline-pro`
+- `@baseline/design-system/tokens/css/offset`
+
+## Components
+
+### Button
+
+A flexible button component with multiple variants, states, and shapes.
+
+```typescript
+import { Button } from '@baseline/design-system';
+
+// Basic usage
+<Button label="Click me" />
+
+// With icon
+<Button 
+  label="Download" 
+  leadingIcon 
+  icon={<IconDownload size={12} />} 
+/>
+
+// Different variants
+<Button 
+  label="Button" 
+  hierarchy="Primary" 
+  shape="Pill" 
+  state="Default" 
+/>
+```
+
+#### Button Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `label` | `string` | `"Button"` | Button text |
+| `leadingIcon` | `boolean` | `false` | Show icon before text |
+| `icon` | `React.ReactNode` | `null` | Custom icon component |
+| `chevron` | `boolean` | `false` | Show chevron on the right |
+| `shape` | `'Rectangle' \| 'Pill' \| 'Circle'` | `'Rectangle'` | Button shape |
+| `state` | `'Default' \| 'Hover' \| 'Active' \| 'Focus' \| 'Disabled'` | `'Default'` | Button state |
+| `hierarchy` | `'Primary' \| 'Secondary' \| 'Tertiary'` | `'Primary'` | Button importance |
+| `disabled` | `boolean` | `false` | Disable the button |
+| `onClick` | `() => void` | - | Click handler |
+| `className` | `string` | `''` | Additional CSS classes |
+
+## Icons
+
+The design system includes 50+ icons as React components. All icons are tree-shakeable and customizable.
+
+### Available Icons
+
+- `IconArrowRight`, `IconArrowLeft`
+- `IconChevronDown`, `IconChevronUp`, `IconChevronLeft`, `IconChevronRight`
+- `IconSettings`, `IconDownload`, `IconPlus`, `IconMinus`
+- `IconAlert`, `IconError`, `IconWarning`, `IconSuccess`
+- `IconChat`, `IconCamera`, `IconVideo`, `IconMicrophone`
+- And 40+ more...
+
+### Using Icons
+
+```typescript
+import { IconArrowRight, IconDownload, IconSettings } from '@baseline/design-system';
+
+// Basic usage
+<IconArrowRight size={24} />
+
+// Custom size and color
+<IconSettings 
+  size={16} 
+  color="var(--brand-color-brand-100)" 
+/>
+
+// With accessibility
+<IconDownload 
+  size={20} 
+  aria-label="Download file" 
+/>
+
+// In a Button
+<Button 
+  label="Download" 
+  leadingIcon 
+  icon={<IconDownload size={12} />} 
+/>
+```
+
+### Icon Props
+
+All icons accept the same props:
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `size` | `number \| string` | `24` | Icon size (width and height) |
+| `color` | `string` | `'currentColor'` | Icon color (inherits text color by default) |
+| `className` | `string` | - | Additional CSS classes |
+| `aria-label` | `string` | - | Accessibility label |
+| `aria-hidden` | `boolean` | - | Hide from screen readers (auto-set if no aria-label) |
+
+Icons use `currentColor` by default, so they automatically inherit the text color from their parent element, making them theme-aware.
+
+### Generating Icons
+
+Icons are generated from SVG files in `src/assets/icons`. To regenerate icons after adding new SVGs:
+
+```bash
+npm run generate-icons
+```
+
+## Brand Themes
+
+The design system supports three brand themes:
+
+- **Baseline** (default)
+- **Baseline Pro**
+- **Offset**
+
+### Switching Themes in Storybook
+
+Use the "Brand Theme" dropdown in the Storybook toolbar to switch between themes. All components and tokens will update automatically.
+
+### Using Themes in Your Application
+
+```css
+/* Import the brand-specific CSS */
+@import '@baseline/design-system/tokens/css/baseline';
+/* or */
+@import '@baseline/design-system/tokens/css/baseline-pro';
+/* or */
+@import '@baseline/design-system/tokens/css/offset';
+```
+
+## Development
+
+### Prerequisites
+
+- Node.js 18+
+- npm or yarn
+
+### Setup
+
+```bash
+# Install dependencies
+npm install
+
+# Build tokens
+npm run build:tokens
+
+# Start Storybook
+npm run storybook
+```
+
+### Available Scripts
+
+| Script | Description |
+|--------|-------------|
+| `npm run build` | Build tokens and components |
+| `npm run build:tokens` | Build all token files for all brands |
+| `npm run build:components` | Build React components |
+| `npm run generate-icons` | Generate icon components from SVG files |
+| `npm run storybook` | Start Storybook development server |
+| `npm run build-storybook` | Build static Storybook site |
+| `npm run fetch-tokens` | Fetch latest tokens from Zeroheight API |
+
+### Project Structure
+
+```
+baseline-design-system/
+├── src/
+│   ├── assets/
+│   │   └── icons/          # SVG icon files
+│   ├── components/         # React components
+│   ├── icons/              # Generated icon components
+│   └── tokens/             # Token exports
+├── tokens/                 # Source token files (from Zeroheight)
+├── dist/                   # Built output
+├── scripts/                # Build and utility scripts
+└── .storybook/             # Storybook configuration
+```
+
+### Token Architecture
+
+Tokens follow a cascading structure:
+
+1. **Primitives** (`0000PrimitiveCore_Mode1.json`)
+   - Base color palettes (azure, blue, brick, emerald, etc.)
+   - Base spacing and sizing scales
+   - Base typography values
+
+2. **Brand Overrides** (`0001PrimitiveBrand_*.json`)
+   - Brand-specific color mappings
+   - Brand-specific sizing overrides
+   - References primitive tokens where values match
+
+3. **Semantic Layer** (`0100SemanticCore_Mode1.json`)
+   - Contextual tokens (e.g., `color.typography.primary.default`)
+   - References both primitives and brand tokens
+   - Provides meaning-based naming
+
+### Token Transformations
+
+The build process applies several transformations:
+
+- **Sizing**: Pixels → rems (base 16px, 3 decimal places)
+- **Typography**: Points → rems (base 12pt, 3 decimal places)
+- **Line Height**: Raw value → unitless (divided by 100)
+- **Font Families**: Adds `sans-serif` fallback
+- **Font Weight**: Used as-is (no transformation)
+
+## Building for Production
+
+```bash
+# Build everything
+npm run build
+
+# The dist/ folder will contain:
+# - Built components (CJS and ESM)
+# - TypeScript declarations
+# - Token files (CSS, SCSS, JS, JSON)
+```
+
+## Publishing
+
+The package is configured for private npm publishing. See [PRIVATE_NPM_SETUP.md](./PRIVATE_NPM_SETUP.md) for detailed instructions on:
+
+- Setting up private npm registry (GitHub Packages, private registry, etc.)
+- Publishing the package
+- Configuring consuming repositories
+- CI/CD setup
+- Authentication and troubleshooting
+
+### Quick Start
+
+1. Configure your registry in `.npmrc`
+2. Build: `npm run build`
+3. Update version: `npm version patch|minor|major`
+4. Publish: `npm publish`
+
+## License
+
+MIT
+
+## Contributing
+
+This design system is synced with Zeroheight. Token files are automatically updated via GitHub integration.
+
+To add new components or icons:
+
+1. Add component files to `src/components/`
+2. Add SVG icons to `src/assets/icons/`
+3. Run `npm run generate-icons` to regenerate icon components
+4. Update exports in `src/index.ts`
+5. Add Storybook stories in `.storybook/`
+