@kenpan/zds-r8f3v1 0.2.0 → 0.3.0

package/guidelines/components/table.md

@@ -1,150 +1,284 @@
 # Table Component
 
-The Table component displays data in a structured grid format with sorting, pagination, and cell customization.
+**Purpose**: Display tabular data with sorting, pagination, and row actions.
+
+**Import**:
+```tsx
+import { Table, TableCell } from '@kenpan/zds-r8f3v1'
+```
+
+## Props
+
+### Table Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `columns` | `TableColumnDef[]` | - | **Required**. Column definitions |
+| `data` | `any[]` | - | **Required**. Row data array |
+| `loading` | `boolean` | `false` | Show loading state |
+| `emptyMessage` | `string` | `'No data'` | Empty state message |
+| `onRowClick` | `(row) => void` | - | Row click handler |
+| `pagination` | `object` | - | Pagination config |
+| `sorting` | `object` | - | Sorting config |
+
+### TableColumnDef
+
+| Prop | Type | Description |
+|------|------|-------------|
+| `field` | `string` | Data field key |
+| `headerName` | `string` | Column header text |
+| `width` | `number \| string` | Column width |
+| `align` | `'left' \| 'center' \| 'right'` | Text alignment |
+| `sortable` | `boolean` | Enable sorting |
+| `renderCell` | `(params) => ReactNode` | Custom cell renderer |
 
 ## Basic Usage
 
 ```tsx
-import { Table } from '@kenpan/zds-r8f3v1'
-
 const columns = [
+  { field: 'id', headerName: 'ID', width: 80 },
   { field: 'name', headerName: 'Name', width: 200 },
-  { field: 'email', headerName: 'Email', width: 250 },
+  { field: 'email', headerName: 'Email', flex: 1 },
   { field: 'status', headerName: 'Status', width: 120 },
 ]
 
-const rows = [
+const data = [
   { id: 1, name: 'John Doe', email: 'john@example.com', status: 'Active' },
   { id: 2, name: 'Jane Smith', email: 'jane@example.com', status: 'Pending' },
 ]
 
-<Table columns={columns} rows={rows} />
+<Table columns={columns} data={data} />
 ```
 
-## Column Definitions
+## With Custom Cell Rendering
 
 ```tsx
+import { Badge, Button } from '@kenpan/zds-r8f3v1'
+import { EditOneIcon, TrashOneIcon } from '@kenpan/zds-r8f3v1/icons'
+
 const columns = [
-  // Basic column
   { field: 'name', headerName: 'Name', width: 200 },
-  
-  // Sortable column
-  { field: 'date', headerName: 'Date', width: 150, sortable: true },
-  
-  // Flex column (takes remaining space)
-  { field: 'description', headerName: 'Description', flex: 1 },
-  
-  // With custom cell renderer
   { 
     field: 'status', 
-    headerName: 'Status',
-    renderCell: (params) => <StatusBadge status={params.value} />
+    headerName: 'Status', 
+    width: 120,
+    renderCell: (params) => (
+      <Badge 
+        status={params.value === 'Active' ? 'success' : 'warning'}
+      >
+        {params.value}
+      </Badge>
+    )
   },
-  
-  // Actions column
   {
     field: 'actions',
     headerName: '',
     width: 100,
-    sortable: false,
+    align: 'right',
     renderCell: (params) => (
-      <DropdownMenu>
-        <MenuItem onClick={() => handleEdit(params.row)}>Edit</MenuItem>
-        <MenuItem onClick={() => handleDelete(params.row)}>Delete</MenuItem>
-      </DropdownMenu>
+      <Stack direction="row" spacing={1}>
+        <Button 
+          variant="tertiary-gray" 
+          iconOnly 
+          iconLeading={<EditOneIcon size={16} />}
+          onClick={() => handleEdit(params.row)}
+        />
+        <Button 
+          variant="tertiary-gray" 
+          iconOnly 
+          destructive
+          iconLeading={<TrashOneIcon size={16} />}
+          onClick={() => handleDelete(params.row)}
+        />
+      </Stack>
     )
-  }
+  },
 ]
 ```
 
-## TableCell Customization
+## With Sorting
 
 ```tsx
-import { TableCell } from '@kenpan/zds-r8f3v1'
+const [sortModel, setSortModel] = useState([
+  { field: 'name', sort: 'asc' }
+])
 
-// Cell with badge
-<TableCell
-  styleType="badge"
-  badge={{ label: 'Active', status: 'success' }}
+<Table 
+  columns={columns} 
+  data={data}
+  sorting={{
+    sortModel,
+    onSortModelChange: setSortModel,
+  }}
 />
+```
+
+## With Pagination
+
+```tsx
+const [page, setPage] = useState(0)
+const [pageSize, setPageSize] = useState(10)
 
-// Cell with action buttons
-<TableCell
-  styleType="action"
-  actionButtons={[
-    { icon: <EditIcon />, onClick: handleEdit },
-    { icon: <DeleteIcon />, onClick: handleDelete },
-  ]}
+<Table 
+  columns={columns} 
+  data={data}
+  pagination={{
+    page,
+    pageSize,
+    totalRows: 100,
+    onPageChange: setPage,
+    onPageSizeChange: setPageSize,
+    pageSizeOptions: [10, 25, 50],
+  }}
 />
+```
+
+## With Row Click
 
-// Cell with supporting text
-<TableCell
-  primaryText="John Doe"
-  supportingText="john@example.com"
+```tsx
+<Table 
+  columns={columns} 
+  data={data}
+  onRowClick={(row) => {
+    console.log('Clicked row:', row)
+    navigate(`/details/${row.id}`)
+  }}
 />
 ```
 
-## With Pagination
+## Loading State
 
 ```tsx
-<Table
-  columns={columns}
-  rows={rows}
-  pagination
-  pageSize={10}
-  pageSizeOptions={[10, 25, 50]}
-  onPageChange={handlePageChange}
+<Table 
+  columns={columns} 
+  data={data}
+  loading={isLoading}
 />
 ```
 
-## With Selection
+## Empty State
 
 ```tsx
-<Table
-  columns={columns}
-  rows={rows}
-  checkboxSelection
-  onRowSelectionModelChange={handleSelectionChange}
+<Table 
+  columns={columns} 
+  data={[]}
+  emptyMessage="No items found. Create your first item."
 />
 ```
 
-## With ActionBar
+## TableCell Component
 
-When rows are selected, show an ActionBar for bulk actions:
+For custom cell styling:
 
 ```tsx
-function DataTable() {
-  const [selectedRows, setSelectedRows] = useState([])
-  
-  return (
-    <>
-      {selectedRows.length > 0 && (
-        <ActionBar
-          selectedCount={selectedRows.length}
-          onClose={() => setSelectedRows([])}
-          actions={[
-            { label: 'Delete', onClick: handleBulkDelete, variant: 'destructive' },
-            { label: 'Export', onClick: handleExport },
-          ]}
+import { TableCell } from '@kenpan/zds-r8f3v1'
+
+// In renderCell
+renderCell: (params) => (
+  <TableCell
+    type="text"
+    text={params.value}
+    subText={params.row.subtitle}
+  />
+)
+
+// With badge
+renderCell: (params) => (
+  <TableCell
+    type="badge"
+    badge={{ status: 'success', label: params.value }}
+  />
+)
+
+// With avatar
+renderCell: (params) => (
+  <TableCell
+    type="avatar"
+    avatar={{ src: params.row.avatar, name: params.value }}
+    text={params.value}
+  />
+)
+```
+
+## Full Example
+
+```tsx
+import { useState } from 'react'
+import { Table, Badge, Button, Card, CardHeader } from '@kenpan/zds-r8f3v1'
+import { PlusIcon, EditOneIcon, TrashOneIcon } from '@kenpan/zds-r8f3v1/icons'
+
+function UsersTable() {
+  const [page, setPage] = useState(0)
+  const [users, setUsers] = useState([
+    { id: 1, name: 'John Doe', email: 'john@example.com', role: 'Admin', status: 'Active' },
+    { id: 2, name: 'Jane Smith', email: 'jane@example.com', role: 'User', status: 'Pending' },
+  ])
+
+  const columns = [
+    { field: 'name', headerName: 'Name', width: 200, sortable: true },
+    { field: 'email', headerName: 'Email', flex: 1 },
+    { field: 'role', headerName: 'Role', width: 120 },
+    { 
+      field: 'status', 
+      headerName: 'Status', 
+      width: 120,
+      renderCell: ({ value }) => (
+        <Badge status={value === 'Active' ? 'success' : 'warning'}>
+          {value}
+        </Badge>
+      )
+    },
+    {
+      field: 'actions',
+      headerName: '',
+      width: 80,
+      renderCell: ({ row }) => (
+        <Button 
+          variant="tertiary-gray" 
+          iconOnly 
+          iconLeading={<EditOneIcon size={16} />}
+          onClick={() => handleEdit(row)}
         />
-      )}
-      <Table
-        columns={columns}
-        rows={rows}
-        checkboxSelection
-        rowSelectionModel={selectedRows}
-        onRowSelectionModelChange={setSelectedRows}
+      )
+    },
+  ]
+
+  return (
+    <Card>
+      <CardHeader 
+        title="Users" 
+        actions={
+          <Button variant="primary" iconLeading={<PlusIcon size={20} />}>
+            Add User
+          </Button>
+        }
       />
-    </>
+      <Table 
+        columns={columns} 
+        data={users}
+        pagination={{
+          page,
+          pageSize: 10,
+          totalRows: users.length,
+          onPageChange: setPage,
+        }}
+      />
+    </Card>
   )
 }
 ```
 
-## Best Practices
+## Usage Guidelines
+
+### Do:
+- Define clear, descriptive column headers
+- Use appropriate column widths
+- Provide loading and empty states
+- Use custom cell renderers for complex data
+- Enable sorting for sortable columns
 
-1. **Column widths** - Set appropriate widths to prevent content truncation
-2. **Sortable columns** - Enable sorting for columns users commonly filter by
-3. **Pagination** - Use pagination for tables with more than 25 rows
-4. **Empty state** - Show an EmptyState component when there's no data
-5. **Loading state** - Show a Skeleton while data is loading
-6. **Actions** - Place row actions in the last column
+### Don't:
+- Don't show too many columns (use detail views instead)
+- Don't use tables for simple lists (use List component)
+- Don't hide important data in scroll
+- Don't forget pagination for large datasets

package/guidelines/design-tokens/colors.md

@@ -0,0 +1,181 @@
+# ZDS Color Design Tokens
+
+ZDS uses a comprehensive color system with semantic tokens for consistent theming across components.
+
+## Color Philosophy
+
+- Use semantic color tokens rather than raw color values
+- Colors are organized into scales (50-950) for each color family
+- Semantic tokens provide meaning-based color access
+- State layers provide consistent interaction feedback
+
+## Color Scales
+
+Each color family includes shades from 50 (lightest) to 950 (darkest):
+
+### Primary (Blue)
+The primary brand color used for primary actions and emphasis.
+
+| Token | Value | Usage |
+|-------|-------|-------|
+| `primary.50` | `#EEF3FF` | Lightest background |
+| `primary.100` | `#DEE9FE` | Light background |
+| `primary.200` | `#C4D8FE` | Hover states |
+| `primary.300` | `#9ABAFD` | Borders |
+| `primary.400` | `#5D87FC` | - |
+| `primary.500` | `#376BFD` | **Main primary color** |
+| `primary.600` | `#1D47EF` | Pressed states |
+| `primary.700` | `#1C3ED8` | - |
+| `primary.800` | `#1C35AF` | - |
+| `primary.900` | `#1C3289` | Dark text |
+
+### Gray (Neutral)
+Used for text, borders, backgrounds, and disabled states.
+
+| Token | Value | Usage |
+|-------|-------|-------|
+| `gray.50` | `#F8FAFC` | Page background |
+| `gray.100` | `#EEF2F6` | Container background |
+| `gray.200` | `#E3E8EF` | Borders, dividers |
+| `gray.300` | `#CDD5DF` | Disabled borders |
+| `gray.400` | `#9AA4B2` | Placeholder text |
+| `gray.500` | `#697586` | Secondary text |
+| `gray.600` | `#4B5565` | Body text |
+| `gray.700` | `#364152` | **Primary text** |
+| `gray.800` | `#202939` | Headings |
+| `gray.900` | `#121926` | Darkest text |
+
+### Success (Green)
+Used for success states, confirmations, and positive actions.
+
+| Token | Value | Usage |
+|-------|-------|-------|
+| `success.50` | `#ECFDF3` | Success background |
+| `success.500` | `#17B26A` | **Main success color** |
+| `success.700` | `#079455` | Success text |
+
+### Error (Red)
+Used for errors, destructive actions, and critical alerts.
+
+| Token | Value | Usage |
+|-------|-------|-------|
+| `error.50` | `#FEF3F2` | Error background |
+| `error.500` | `#F04438` | **Main error color** |
+| `error.700` | `#B42318` | Error text |
+
+### Warning (Orange/Yellow)
+Used for warnings and attention-requiring states.
+
+| Token | Value | Usage |
+|-------|-------|-------|
+| `warning.50` | `#FFFAEB` | Warning background |
+| `warning.500` | `#F79009` | **Main warning color** |
+| `warning.700` | `#B54708` | Warning text |
+
+## Semantic Tokens
+
+Semantic tokens provide meaning-based color access through `theme.palette.ds`:
+
+### Surface Colors
+```tsx
+theme.palette.ds.surface              // Default surface (#FFFFFF)
+theme.palette.ds.surfacecontainer     // Container background
+theme.palette.ds.surfacecontainerlow  // Lower elevation
+theme.palette.ds.surfacecontainerhigh // Higher elevation
+theme.palette.ds.surfacecontainerlowest // Lowest (white)
+```
+
+### Text Colors
+```tsx
+theme.palette.ds.onsurface          // Primary text (#364152)
+theme.palette.ds.onsurfacevariant   // Secondary text (#697586)
+```
+
+### Outline Colors
+```tsx
+theme.palette.ds.outline            // Default border (#AFBACA)
+theme.palette.ds.outlinevariant     // Light border (#D4DCE7)
+theme.palette.ds.outlineerror       // Error border
+theme.palette.ds.outlinewarning     // Warning border
+theme.palette.ds.outlinesuccess     // Success border
+```
+
+### Semantic Colors
+```tsx
+theme.palette.ds.onprimary          // Text on primary (#FFFFFF)
+theme.palette.ds.primarycontainer   // Primary container bg
+theme.palette.ds.onerror            // Text on error
+theme.palette.ds.errorcontainer     // Error container bg
+theme.palette.ds.onsuccess          // Text on success
+theme.palette.ds.successcontainer   // Success container bg
+theme.palette.ds.onwarning          // Text on warning
+theme.palette.ds.warningcontainer   // Warning container bg
+```
+
+## State Layers
+
+State layers provide consistent hover/pressed/focus visual feedback:
+
+```tsx
+// Hover states (8% opacity)
+theme.palette.dsTokens.stateLayers['state-layers-onsurface-opacity-8']
+theme.palette.dsTokens.stateLayers['state-layers-primary-opacity-8']
+
+// Pressed states (10% opacity)
+theme.palette.dsTokens.stateLayers['state-layers-onsurface-opacity-10']
+
+// Disabled states (38% opacity)
+theme.palette.dsTokens.stateLayers['state-layers-onsurface-opacity-38']
+```
+
+## Usage Examples
+
+### Background Colors
+
+```tsx
+// Default page background
+<Box sx={{ bgcolor: 'background.default' }}>
+
+// Container background
+<Box sx={(theme) => ({ bgcolor: theme.palette.ds.surfacecontainer })}>
+
+// Primary accent background
+<Box sx={{ bgcolor: 'primary.50' }}>
+```
+
+### Text Colors
+
+```tsx
+// Primary text
+<Typography sx={(theme) => ({ color: theme.palette.ds.onsurface })}>
+
+// Secondary text
+<Typography sx={(theme) => ({ color: theme.palette.ds.onsurfacevariant })}>
+
+// Error text
+<Typography color="error.main">
+```
+
+### Interactive States
+
+```tsx
+<Box
+  sx={(theme) => ({
+    bgcolor: 'transparent',
+    '&:hover': {
+      bgcolor: theme.palette.dsTokens?.stateLayers?.['state-layers-onsurface-opacity-8'] ?? 'rgba(54, 65, 82, 0.08)',
+    },
+    '&:active': {
+      bgcolor: theme.palette.dsTokens?.stateLayers?.['state-layers-onsurface-opacity-10'] ?? 'rgba(54, 65, 82, 0.10)',
+    },
+  })}
+>
+```
+
+## Best Practices
+
+1. **Use semantic tokens**: Prefer `theme.palette.ds.onsurface` over `gray.700`
+2. **Contrast matters**: Ensure sufficient contrast between text and backgrounds
+3. **Use state layers**: Apply consistent hover/pressed effects with state layers
+4. **Don't hardcode colors**: Always use theme tokens for maintainability
+5. **Fallback values**: When accessing custom tokens, provide fallback values for compatibility

package/guidelines/design-tokens/spacing.md

@@ -0,0 +1,135 @@
+# ZDS Spacing Design Tokens
+
+ZDS uses a consistent 4px-based spacing scale for margins, padding, and gaps.
+
+## Spacing Scale
+
+The spacing scale is based on MUI's default 8px multiplier but uses 4px as the base unit:
+
+| Token | Value | Usage |
+|-------|-------|-------|
+| `0` | 0px | No spacing |
+| `0.5` | 2px | Micro spacing |
+| `1` | 4px | Tight spacing |
+| `1.5` | 6px | Compact spacing |
+| `2` | 8px | Small spacing |
+| `2.5` | 10px | - |
+| `3` | 12px | Medium spacing |
+| `4` | 16px | **Standard spacing** |
+| `5` | 20px | Large spacing |
+| `6` | 24px | Section spacing |
+| `8` | 32px | Major section gaps |
+| `10` | 40px | Page section gaps |
+| `12` | 48px | Large gaps |
+| `16` | 64px | Extra large gaps |
+| `20` | 80px | Page-level spacing |
+
+## Usage
+
+### With theme.spacing()
+
+```tsx
+// Single value
+<Box sx={{ p: 4 }}>           // padding: 16px
+<Box sx={{ m: 2 }}>           // margin: 8px
+<Box sx={{ gap: 3 }}>         // gap: 12px
+
+// Using theme.spacing function
+<Box sx={(theme) => ({
+  padding: theme.spacing(4),       // 16px
+  marginBottom: theme.spacing(2),  // 8px
+  gap: theme.spacing(3),           // 12px
+})}>
+```
+
+### Common Patterns
+
+#### Container Padding
+```tsx
+// Card/container padding
+<Card sx={{ p: 4 }}>           // 16px all sides
+<Card sx={{ p: 6 }}>           // 24px for larger cards
+
+// Asymmetric padding
+<Box sx={{ px: 4, py: 3 }}>    // 16px horizontal, 12px vertical
+```
+
+#### Element Spacing
+```tsx
+// Gap between elements
+<Stack spacing={2}>            // 8px gap
+<Stack spacing={3}>            // 12px gap
+<Stack spacing={4}>            // 16px gap (standard)
+
+// Flex gap
+<Box sx={{ display: 'flex', gap: 2 }}>  // 8px gap
+```
+
+#### Margins
+```tsx
+// Section margins
+<Box sx={{ mb: 4 }}>           // margin-bottom: 16px
+<Box sx={{ mt: 6 }}>           // margin-top: 24px
+
+// Component margins
+<Button sx={{ ml: 2 }}>        // margin-left: 8px
+```
+
+## Component Spacing Guidelines
+
+### Buttons
+- Gap between icon and text: 8px (spacing 2)
+- Gap between buttons: 12px (spacing 3)
+- Button padding: 8-16px depending on size
+
+### Cards
+- Card padding: 16-24px (spacing 4-6)
+- Gap between card elements: 12-16px (spacing 3-4)
+- Card header margin-bottom: 16px (spacing 4)
+
+### Forms
+- Gap between form fields: 16-24px (spacing 4-6)
+- Label margin-bottom: 4-8px (spacing 1-2)
+- Hint text margin-top: 4px (spacing 1)
+
+### Lists
+- Gap between list items: 8-12px (spacing 2-3)
+- List item padding: 8-16px (spacing 2-4)
+
+### Tables
+- Cell padding: 12-16px (spacing 3-4)
+- Header padding: 12-16px (spacing 3-4)
+
+### Dialogs
+- Dialog padding: 24px (spacing 6)
+- Gap between dialog sections: 16-24px (spacing 4-6)
+- Dialog actions gap: 12px (spacing 3)
+
+## Best Practices
+
+1. **Use the spacing scale**: Always use theme.spacing() instead of arbitrary px values
+2. **Consistent gaps**: Use spacing(3) (12px) or spacing(4) (16px) for most gaps
+3. **Breathing room**: Larger containers need more padding (24-32px)
+4. **Tight UI**: Compact elements use spacing(1-2) (4-8px)
+5. **Vertical rhythm**: Keep consistent vertical spacing between sections
+
+## Quick Reference
+
+```tsx
+// Most common spacing values
+<Box sx={{ 
+  p: 4,      // 16px - standard padding
+  m: 2,      // 8px - small margin
+  gap: 3,    // 12px - element gap
+  mb: 4,     // 16px - section margin
+}}>
+
+// Form layout
+<Stack spacing={4}>  // 16px between fields
+
+// Button group
+<Stack direction="row" spacing={3}>  // 12px between buttons
+
+// Card content
+<Box sx={{ p: 6 }}>  // 24px padding
+```