@kenpan/zds-r8f3v1 0.2.0 → 0.3.0

package/guidelines/design-tokens/typography.md

@@ -0,0 +1,146 @@
+# ZDS Typography Design Tokens
+
+ZDS uses a comprehensive typography system based on the Inter font family with consistent sizing, weights, and line heights.
+
+## Font Family
+
+```tsx
+theme.typography.fontFamily // 'Inter', -apple-system, sans-serif
+```
+
+## Typography Scale
+
+ZDS provides typography variants organized by purpose and size:
+
+### Display Text
+For large headlines and hero sections.
+
+| Variant | Font Size | Line Height | Weight | Usage |
+|---------|-----------|-------------|--------|-------|
+| `display-2xl` | 72px | 90px | 600 | Hero headlines |
+| `display-xl` | 60px | 72px | 600 | Page titles |
+| `display-lg` | 48px | 60px | 600 | Section headers |
+| `display-md` | 36px | 44px | 600 | Card headers |
+| `display-sm` | 30px | 38px | 600 | Subsections |
+| `display-xs` | 24px | 32px | 600 | Small headers |
+
+### Text (Body)
+For body text and UI elements.
+
+| Variant | Font Size | Line Height | Weight | Usage |
+|---------|-----------|-------------|--------|-------|
+| `text-xl` | 20px | 30px | 400/500 | Large body text |
+| `text-lg` | 18px | 28px | 400/500 | Body text |
+| `text-md` | 16px | 24px | 400/500 | **Default body** |
+| `text-sm` | 14px | 20px | 400/500 | Small text, labels |
+| `text-xs` | 12px | 18px | 400/500 | Captions, badges |
+
+### Weight Variants
+
+Each text size has regular and medium variants:
+- `text-sm` (400 weight) - Regular
+- `text-sm-medium` (500 weight) - Medium/emphasized
+
+## Usage Examples
+
+### Using Typography Variants
+
+```tsx
+import Typography from '@mui/material/Typography'
+
+// Display text
+<Typography variant="display-lg">Welcome</Typography>
+
+// Body text with custom weight
+<Typography sx={(theme) => ({
+  fontSize: theme.typography['text-sm-medium'].fontSize,
+  fontWeight: theme.typography['text-sm-medium'].fontWeight,
+  lineHeight: theme.typography['text-sm-medium'].lineHeight,
+})}>
+  Label Text
+</Typography>
+```
+
+### Common Text Styles
+
+```tsx
+// Page title
+<Typography
+  variant="h1"
+  sx={(theme) => ({
+    fontSize: 30,
+    fontWeight: 600,
+    lineHeight: '38px',
+  })}
+>
+  Page Title
+</Typography>
+
+// Body text
+<Typography
+  sx={(theme) => ({
+    fontSize: 14,
+    fontWeight: 400,
+    lineHeight: '20px',
+    color: theme.palette.ds?.onsurface ?? '#364152',
+  })}
+>
+  Body content here
+</Typography>
+
+// Caption/small text
+<Typography
+  sx={(theme) => ({
+    fontSize: 12,
+    fontWeight: 400,
+    lineHeight: '18px',
+    color: theme.palette.ds?.onsurfacevariant ?? '#697586',
+  })}
+>
+  Caption text
+</Typography>
+```
+
+## Font Weights
+
+| Weight | Value | Usage |
+|--------|-------|-------|
+| Regular | 400 | Body text |
+| Medium | 500 | Labels, emphasized text |
+| Semibold | 600 | Headings, buttons |
+| Bold | 700 | Strong emphasis |
+
+## Line Heights
+
+ZDS uses consistent line height ratios:
+
+| Text Size | Line Height | Ratio |
+|-----------|-------------|-------|
+| 12px | 18px | 1.5 |
+| 14px | 20px | 1.43 |
+| 16px | 24px | 1.5 |
+| 18px | 28px | 1.56 |
+| 20px | 30px | 1.5 |
+| 24px | 32px | 1.33 |
+
+## Best Practices
+
+1. **Use text-sm for UI elements**: Buttons, labels, table cells use 14px
+2. **Use text-md for body content**: Main content uses 16px
+3. **Use text-xs sparingly**: Only for badges, captions, metadata
+4. **Maintain hierarchy**: Use different sizes to create visual hierarchy
+5. **Consistent weights**: Use 400 for body, 500 for labels, 600 for headings
+6. **Don't mix fonts**: Stick to Inter for all UI text
+
+## Recommended Text Sizes
+
+| Element | Size | Weight |
+|---------|------|--------|
+| Page title | 30px | 600 |
+| Section header | 18-20px | 600 |
+| Card title | 16px | 600 |
+| Body text | 14-16px | 400 |
+| Button text | 14px | 500 |
+| Label | 14px | 500 |
+| Caption | 12px | 400 |
+| Badge | 12px | 500 |

package/guidelines/overview-components.md

@@ -0,0 +1,136 @@
+# ZDS Components Overview
+
+Always prefer components from the ZDS package (imported from `@kenpan/zds-r8f3v1`) if they are available. Each component has a guidelines file that contains helpful examples and additional context.
+
+## Available Components
+
+| Component | Overview | Guidelines file |
+|-----------|----------|-----------------|
+| Button | Primary action button with multiple variants | [button.md](components/button.md) |
+| Card | Container component with header support | - |
+| Badge | Status indicators and labels | - |
+| Tag | Removable labels with icons and avatars | - |
+| Tooltip | Contextual information on hover | - |
+| Alert | Feedback messages with different intents | - |
+| Toast | Notification messages | - |
+| Dialog | Modal dialogs | [dialog.md](components/dialog.md) |
+| Table | Data grid with sorting and pagination | [table.md](components/table.md) |
+| InputField | Text input with label and validation | [forms.md](components/forms.md) |
+| Checkbox | Checkbox with label and description | [forms.md](components/forms.md) |
+| Radio | Radio button groups | [forms.md](components/forms.md) |
+| Switch | Toggle switches | [forms.md](components/forms.md) |
+| Slider | Range sliders | [forms.md](components/forms.md) |
+
+## General Component Usage and Best Practices
+
+### Import Pattern
+
+```tsx
+// Import components from the main package
+import { Button, Card, Alert, Badge, Tag } from '@kenpan/zds-r8f3v1'
+
+// Import theme separately
+import { theme } from '@kenpan/zds-r8f3v1/theme'
+
+// Import icons separately
+import { ChevronDownIcon, PlusIcon, SearchSmIcon } from '@kenpan/zds-r8f3v1/icons'
+```
+
+### Theme Provider Required
+
+**IMPORTANT:** All ZDS components must be wrapped in a ThemeProvider with the ZDS theme:
+
+```tsx
+import { ThemeProvider } from '@mui/material/styles'
+import { theme } from '@kenpan/zds-r8f3v1/theme'
+
+function App() {
+  return (
+    <ThemeProvider theme={theme}>
+      {/* Your components here */}
+    </ThemeProvider>
+  )
+}
+```
+
+### Common Props
+
+Most ZDS components accept these common props:
+- `disabled`: Boolean to disable the component
+- `sx`: MUI sx prop for additional styling (use sparingly)
+- `className`: String for additional CSS classes (avoid when possible)
+- `data-*`: data attributes are always allowed
+
+### Sizing
+
+Most components support a `size` prop:
+- `"sm"` or `"small"` - Compact size
+- `"md"` or `"medium"` - Default size (recommended)
+- `"lg"` or `"large"` - Larger size
+
+### Color/Intent Props
+
+Many components support color or intent props:
+- `"primary"` - Primary brand color (blue)
+- `"secondary"` - Secondary color
+- `"success"` - Success state (green)
+- `"warning"` - Warning state (yellow/orange)
+- `"error"` - Error state (red)
+- `"info"` - Informational state (blue)
+- `"gray"` or `"neutral"` - Neutral/gray
+
+### Controlled vs Uncontrolled
+
+- **Controlled**: Component receives `value` and `onChange` props, parent manages state
+- **Uncontrolled**: Component manages own state, use `defaultValue` for initial value
+- Prefer controlled for most cases in modern React
+
+## Component Categories
+
+### Base Components
+- **Button**: Primary action button with multiple variants (primary, secondary, tertiary, link)
+- **Card**: Container component with optional CardHeader
+- **Badge**: Status indicators with color variants
+- **Tag**: Removable labels with dot/avatar/country icons
+- **Tooltip**: Hover tooltips with dark/light themes
+
+### Form Components
+- **InputField**: Text inputs with label, hint, and validation
+- **InputNumber**: Numeric inputs with increment/decrement
+- **InputSearch**: Search input with clear button
+- **InputDropdown**: Dropdown select with search
+- **Checkbox**: Checkboxes with label and description
+- **Radio**: Radio button groups
+- **Switch**: Toggle switches
+- **Slider**: Range sliders
+
+### Feedback Components
+- **Alert**: Inline feedback messages (info, success, warning, error)
+- **Toast**: Floating notifications
+- **EmptyState**: Empty content placeholders with illustrations
+- **Skeleton**: Loading placeholders
+
+### Layout Components
+- **PageHeader**: Page title with breadcrumbs and actions
+- **SectionHeader**: Section titles
+- **ContentDivider**: Horizontal dividers
+- **Card**: Content containers
+
+### Navigation Components
+- **HeaderNavigation**: Top navigation bar
+- **SidebarNavigation**: Vertical sidebar
+- **Breadcrumbs**: Hierarchical navigation
+- **HorizontalTabs**: Tab navigation
+- **SlideoutMenu**: Slide-out panels
+
+### Overlay Components
+- **Dialog**: Modal dialogs with header and footer
+- **Popover**: Contextual overlays
+- **BackgroundOverlay**: Backdrop dimmer
+
+### Data Display
+- **Table**: Data grids with sorting, pagination
+- **Scorecard**: Metric cards with trends
+- **DonutChart**: Circular charts
+- **ActivityFeed**: Activity timelines
+- **Accordion**: Collapsible sections

package/guidelines/overview-icons.md

@@ -0,0 +1,144 @@
+# ZDS Icons Overview
+
+ZDS provides 1,194 pre-built React icon components. All icons are available as individual React components that can be imported from `@kenpan/zds-r8f3v1/icons`.
+
+## Icon Import Pattern
+
+```tsx
+import { 
+  ChevronDownIcon,
+  ChevronRightIcon,
+  PlusIcon,
+  SearchSmIcon,
+  XCloseIcon,
+  CheckIcon,
+  AlertCircleIcon,
+  HelpCircleIcon
+} from '@kenpan/zds-r8f3v1/icons'
+```
+
+## Icon Usage
+
+### Basic Usage
+
+```tsx
+import { PlusIcon, SearchSmIcon } from '@kenpan/zds-r8f3v1/icons'
+
+// Icons accept size prop (default: 24)
+<PlusIcon size={24} />
+<SearchSmIcon size={16} />
+
+// Icons inherit currentColor for fill
+<div style={{ color: '#376BFD' }}>
+  <PlusIcon /> {/* Will be blue */}
+</div>
+```
+
+### With Icon Component Wrapper
+
+For dynamic icon loading or when you need the icon name as a string:
+
+```tsx
+import { Icon } from '@kenpan/zds-r8f3v1'
+
+// Use name or iconId prop
+<Icon name="Plus" size={24} />
+<Icon iconId="ChevronDown" size={16} color="#376BFD" />
+<Icon name="Search" rotate={90} />
+```
+
+### Icon Props
+
+All icon components accept these props:
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `size` | `number \| string` | `24` | Width and height of the icon |
+| `color` | `string` | `currentColor` | Fill color (inherits from parent) |
+| Standard SVG props | - | - | All standard SVG props are supported |
+
+## Common Icons
+
+### Navigation Icons
+- `ChevronDownIcon`, `ChevronUpIcon`, `ChevronLeftIcon`, `ChevronRightIcon`
+- `ChevronDownDoubleIcon`, `ChevronUpDoubleIcon`
+- `ArrowLeftIcon`, `ArrowRightIcon`, `ArrowUpIcon`, `ArrowDownIcon`
+- `MenuOneIcon`, `DotsVerticalIcon`, `DotsHorizontalIcon`
+
+### Action Icons
+- `PlusIcon`, `MinusIcon`
+- `XCloseIcon`, `CheckIcon`
+- `EditOneIcon`, `TrashOneIcon`
+- `CopyThreeIcon`, `DownloadOneIcon`, `UploadOneIcon`
+- `SearchSmIcon`, `SearchMdIcon`, `SearchLgIcon`
+- `RefreshCwOneIcon`, `RefreshCcwOneIcon`
+
+### Status Icons
+- `CheckCircleIcon` - Success
+- `AlertCircleIcon` - Warning/Error
+- `InfoCircleIcon` - Information
+- `HelpCircleIcon` - Help
+- `AlertTriangleIcon` - Warning
+
+### UI Icons
+- `HomeLineIcon`, `Home01Icon`
+- `SettingsOneIcon`, `SettingsTwoIcon`
+- `UserOneIcon`, `UsersOneIcon`
+- `BellOneIcon`, `MailOneIcon`
+- `CalendarIcon`, `ClockIcon`
+- `FilterFunnelOneIcon`, `SortAscAZIcon`, `SortDescAZIcon`
+- `EyeIcon`, `EyeOffIcon`
+- `LockOneIcon`, `LockUnlockedOneIcon`
+
+### File/Document Icons
+- `FileOneIcon`, `FolderIcon`
+- `ClipboardIcon`, `DocumentIcon`
+- `ImageOneIcon`, `VideoRecorderIcon`
+
+### Commerce Icons
+- `ShoppingCartOneIcon`, `ShoppingBagOneIcon`
+- `CreditCardOneIcon`, `BankIcon`
+- `ReceiptIcon`, `TagOneIcon`
+
+## Icon Naming Convention
+
+Icons follow a consistent naming pattern:
+- Base name in PascalCase: `Plus`, `Search`, `Chevron`
+- Direction suffix if applicable: `Up`, `Down`, `Left`, `Right`
+- Numeric variant suffix: `One`, `Two`, `Three` (for alternative designs)
+- Size suffix for search icons: `Sm`, `Md`, `Lg`
+- All end with `Icon`: `PlusIcon`, `ChevronDownIcon`, `SearchSmIcon`
+
+## Finding Icons
+
+**IMPORTANT:** Always verify an icon exists before using it. Check the available icons by:
+
+1. Looking in `node_modules/@kenpan/zds-r8f3v1/dist/icons/`
+2. Using IDE autocomplete when importing from `@kenpan/zds-r8f3v1/icons`
+
+## Icon with Components
+
+Many ZDS components accept icon props:
+
+```tsx
+import { Button, Alert, Badge } from '@kenpan/zds-r8f3v1'
+import { PlusIcon, AlertCircleIcon } from '@kenpan/zds-r8f3v1/icons'
+
+// Button with icon
+<Button variant="primary" iconLeading={<PlusIcon size={20} />}>
+  Add Item
+</Button>
+
+// Alert with custom icon
+<Alert color="warning" icon={<AlertCircleIcon />}>
+  Please review your input
+</Alert>
+```
+
+## Best Practices
+
+1. **Use semantic icons**: Choose icons that clearly represent the action or content
+2. **Consistent sizing**: Use 16px for compact UI, 20px for buttons, 24px for standalone
+3. **Inherit color**: Let icons inherit color from parent elements when possible
+4. **Don't modify strokeWidth**: This will break the visual consistency
+5. **Verify existence**: Always confirm an icon exists before using it

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kenpan/zds-r8f3v1",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "React component library built with MUI and TypeScript",
   "type": "module",
   "main": "./dist/index.js",

package/guidelines/overview.md

@@ -1,81 +0,0 @@
-# ZDS - Design System Overview
-
-ZDS is a comprehensive React component library built with MUI (Material-UI) and TypeScript. It provides production-ready components with consistent styling, accessibility, and theming support.
-
-## Getting Started
-
-### Installation
-
-```bash
-npm install @kenpan/zds-r8f3v1 @mui/material @emotion/react @emotion/styled
-```
-
-### Basic Setup
-
-Wrap your application with the theme provider:
-
-```tsx
-import { ThemeProvider } from '@mui/material/styles'
-import { theme } from '@kenpan/zds-r8f3v1/theme'
-
-function App() {
-  return (
-    <ThemeProvider theme={theme}>
-      {/* Your app content */}
-    </ThemeProvider>
-  )
-}
-```
-
-## Component Categories
-
-### Base Components
-- **Button** - Primary action button with multiple variants (primary, secondary, tertiary, link)
-- **Card** - Container component with header support
-- **Badge** - Status indicators and labels
-- **Tag** - Removable labels with icons and avatars
-- **Tooltip** - Contextual information on hover
-
-### Form Components
-- **InputField** - Text input with label and validation
-- **Checkbox** - Checkbox with label and description
-- **Radio** - Radio button groups
-- **Switch** - Toggle switches
-- **Slider** - Range sliders
-- **DatePicker** - Date selection component
-
-### Layout Components
-- **PageHeader** - Page title with breadcrumbs and actions
-- **SectionHeader** - Section titles and labels
-- **FooterNavigation** - Footer with navigation links
-
-### Navigation Components
-- **HeaderNavigation** - Top navigation bar
-- **SidebarNavigation** - Vertical sidebar navigation
-- **Breadcrumbs** - Hierarchical navigation
-- **HorizontalTabs** - Tab navigation
-- **SlideoutMenu** - Slide-out panel
-
-### Overlay Components
-- **Dialog** - Modal dialogs
-- **Popover** - Contextual overlays
-- **Toast** - Notification messages
-- **BackgroundOverlay** - Backdrop dimmer
-
-### Data Display Components
-- **Table** - Data grid with sorting and pagination
-- **Skeleton** - Loading placeholders
-- **EmptyState** - Empty content placeholders
-- **ProgressIndicator** - Progress bars and spinners
-- **Scorecard** - Metric cards with trends
-
-## Design Tokens
-
-The theme includes comprehensive design tokens:
-
-- **Colors**: Primary, secondary, success, error, warning scales
-- **Typography**: Font sizes, weights, line heights
-- **Spacing**: Consistent spacing scale
-- **Shadows**: Elevation shadows
-- **Border Radius**: Rounded corners
-- **Focus Rings**: Accessibility focus states

package/guidelines/tokens.md

@@ -1,149 +0,0 @@
-# Design Tokens
-
-ZDS uses a comprehensive design token system for consistent styling across all components.
-
-## Colors
-
-### Primary Colors
-Use primary colors for main actions and brand elements.
-
-```tsx
-// Access via theme
-theme.palette.primary.main    // Primary color
-theme.palette.primary.light   // Lighter variant
-theme.palette.primary.dark    // Darker variant
-
-// Access color scales
-theme.palette.primaryScale[100] // Lightest
-theme.palette.primaryScale[500] // Default
-theme.palette.primaryScale[900] // Darkest
-```
-
-### Semantic Colors
-
-```tsx
-// Success - Positive actions and states
-theme.palette.success.main
-
-// Error - Errors, destructive actions
-theme.palette.error.main
-
-// Warning - Caution states
-theme.palette.warning.main
-
-// Gray - Neutral elements
-theme.palette.gray[100]  // Backgrounds
-theme.palette.gray[500]  // Borders
-theme.palette.gray[900]  // Text
-```
-
-### Design System Colors
-
-```tsx
-// Surface colors
-theme.palette.ds.surface              // Default surface
-theme.palette.ds.surfacecontainer     // Container background
-theme.palette.ds.onsurface            // Text on surface
-
-// Primary semantic
-theme.palette.ds.primary.DEFAULT      // Primary action color
-theme.palette.ds.onprimary            // Text on primary
-```
-
-## Typography
-
-### Font Sizes
-
-```tsx
-theme.typography.xs    // 12px - Caption, labels
-theme.typography.sm    // 14px - Body small
-theme.typography.md    // 16px - Body default
-theme.typography.lg    // 18px - Subtitle
-theme.typography.xl    // 20px - Title
-theme.typography.2xl   // 24px - Heading
-theme.typography.3xl   // 30px - Large heading
-```
-
-### Font Weights
-
-```tsx
-theme.typography.fontWeightRegular  // 400
-theme.typography.fontWeightMedium   // 500
-theme.typography.fontWeightSemiBold // 600
-theme.typography.fontWeightBold     // 700
-```
-
-## Spacing
-
-ZDS uses an 8px spacing scale.
-
-```tsx
-theme.spacing(0.5)  // 4px
-theme.spacing(1)    // 8px
-theme.spacing(2)    // 16px
-theme.spacing(3)    // 24px
-theme.spacing(4)    // 32px
-theme.spacing(6)    // 48px
-theme.spacing(8)    // 64px
-```
-
-## Shadows
-
-```tsx
-theme.shadows[0]   // No shadow
-theme.shadows[1]   // Subtle shadow (buttons, cards)
-theme.shadows[2]   // Medium shadow (dropdowns)
-theme.shadows[3]   // Elevated shadow (modals)
-```
-
-## Focus Rings
-
-For accessibility, use focus rings on interactive elements.
-
-```tsx
-theme.focusRings.primary[100]  // Primary focus ring
-theme.focusRings.error[100]    // Error/destructive focus
-theme.focusRings.gray[100]     // Neutral focus
-```
-
-## Breakpoints
-
-```tsx
-theme.breakpoints.values.xs  // 0
-theme.breakpoints.values.sm  // 640px
-theme.breakpoints.values.md  // 768px
-theme.breakpoints.values.lg  // 1024px
-theme.breakpoints.values.xl  // 1280px
-theme.breakpoints.values.2xl // 1536px
-```
-
-## Using Tokens in Components
-
-```tsx
-import { useTheme } from '@mui/material/styles'
-import { Box, Typography } from '@mui/material'
-
-function MyComponent() {
-  const theme = useTheme()
-  
-  return (
-    <Box
-      sx={{
-        backgroundColor: theme.palette.ds.surfacecontainer,
-        padding: theme.spacing(3),
-        borderRadius: '12px',
-        boxShadow: theme.shadows[1],
-      }}
-    >
-      <Typography
-        sx={{
-          color: theme.palette.ds.onsurface,
-          fontWeight: theme.typography.fontWeightSemiBold,
-        }}
-      >
-        Card Title
-      </Typography>
-    </Box>
-  )
-}
-```