design-protocol 1.0.0

package/skills/dp-ui/references/b2b-enterprise-patterns.md

@@ -0,0 +1,319 @@
+# B2B & Enterprise UI Patterns
+
+Patterns for data-dense, power-user focused applications.
+
+## Dashboard Design
+
+### Dashboard Anatomy
+```
+┌─────────────────────────────────────────────────────────┐
+│ [Logo] Navigation                    [Search] [Profile] │ ← Global nav
+├─────────────────────────────────────────────────────────┤
+│ Page Title              [Date Range ▼] [Filter] [Export]│ ← Page header
+├───────────────┬───────────────┬───────────────┬─────────┤
+│   KPI Card    │   KPI Card    │   KPI Card    │ KPI Card│ ← Metrics row
+│   $1.2M ↑12%  │   847 ↓3%     │   94.2%       │ 23 New  │
+├───────────────┴───────────────┴───────────────┴─────────┤
+│                                                         │
+│           Primary Chart / Visualization                 │ ← Main insight
+│                                                         │
+├─────────────────────────────────┬───────────────────────┤
+│     Secondary Chart             │    Supporting Table   │ ← Detail row
+│                                 │                       │
+└─────────────────────────────────┴───────────────────────┘
+```
+
+### KPI Cards
+**Essential elements**:
+- Metric label (what it measures)
+- Primary value (large, prominent)
+- Comparison/trend (vs. previous period)
+- Sparkline (optional, shows trajectory)
+
+**Layout**:
+```
+┌──────────────────────┐
+│ Total Revenue        │  ← Label
+│ $1,247,392          │  ← Primary value (largest)
+│ ↑ 12.4% vs last mo  │  ← Comparison (green/red)
+│ ▁▂▃▂▄▅▆▅▇           │  ← Sparkline (optional)
+└──────────────────────┘
+```
+
+### Dashboard Best Practices
+- **Above the fold**: Most important metrics visible without scrolling
+- **Progressive disclosure**: Summary → Detail on drill-down
+- **Consistent time periods**: All metrics should reference same period
+- **Comparison context**: Raw numbers need benchmarks to be meaningful
+- **Actionable insights**: Dashboards should answer "what should I do?"
+
+## Data Tables
+
+### Table Anatomy
+```
+┌─────┬──────────────┬────────────┬──────────┬─────────┬────────┐
+│ ☐   │ Name ↕       │ Status     │ Created  │ Value   │ Actions│
+├─────┼──────────────┼────────────┼──────────┼─────────┼────────┤
+│ ☐   │ Vessel Alpha │ ● Active   │ Jan 15   │ $45,200 │ ••• ▼  │
+│ ☐   │ Vessel Beta  │ ○ Pending  │ Jan 12   │ $38,100 │ ••• ▼  │
+│ ☑   │ Vessel Gamma │ ● Active   │ Jan 10   │ $52,800 │ ••• ▼  │
+└─────┴──────────────┴────────────┴──────────┴─────────┴────────┘
+      │              │            │          │         │
+      Multi-select   Sortable     Status     Formatted Actions
+                     indicator    badges     numbers   menu
+```
+
+### Table Features Checklist
+- [ ] **Sorting**: Click header to sort, show direction indicator
+- [ ] **Selection**: Checkbox column, "select all" in header
+- [ ] **Bulk actions**: Appear when items selected
+- [ ] **Pagination**: Or infinite scroll with virtualization
+- [ ] **Column resizing**: Drag handles between columns
+- [ ] **Column visibility**: Toggle columns on/off
+- [ ] **Row actions**: Hover to reveal, or persistent "..." menu
+- [ ] **Empty state**: Helpful message when no data
+- [ ] **Loading state**: Skeleton rows, not spinner
+
+### Table Density Options
+```
+Compact:    32px row height  — Maximum data, power users
+Default:    40px row height  — Balanced
+Comfortable: 48px row height — Easier scanning, touch-friendly
+```
+
+### Number Formatting in Tables
+- Right-align numeric columns
+- Use consistent decimal places
+- Add thousand separators (1,234,567)
+- Abbreviate large numbers (1.2M, 45K)
+- Currency symbols once (in header) or per cell (if mixed)
+
+## Filters & Search
+
+### Filter Bar Pattern
+```
+┌───────────────────────────────────────────────────────────────┐
+│ [🔍 Search...          ] [Status ▼] [Date Range ▼] [+ Filter] │
+├───────────────────────────────────────────────────────────────┤
+│ Active filters: [Status: Active ×] [Date: Last 7 days ×]     │
+└───────────────────────────────────────────────────────────────┘
+```
+
+### Filter Types
+- **Search**: Free text, searches across multiple fields
+- **Dropdown select**: Single value from predefined list
+- **Multi-select**: Multiple values (checkboxes in dropdown)
+- **Date range**: Preset ranges + custom picker
+- **Numeric range**: Min/max inputs or slider
+- **Boolean toggle**: On/off states
+
+### Filter UX Best Practices
+- Show active filters as removable chips
+- "Clear all" option when filters applied
+- Persist filters in URL (shareable, bookmarkable)
+- Show result count updating as filters change
+- Remember recent/saved filter combinations
+
+### Advanced Filter Builder
+For complex queries:
+```
+┌─────────────────────────────────────────────────────────────┐
+│ Where ALL of the following match:                           │
+│ ┌─────────────┬────────────┬─────────────────┬───┐         │
+│ │ Status      │ is         │ Active          │ × │         │
+│ ├─────────────┼────────────┼─────────────────┼───┤         │
+│ │ Created     │ is after   │ Jan 1, 2025     │ × │         │
+│ ├─────────────┼────────────┼─────────────────┼───┤         │
+│ │ Value       │ is greater │ $10,000         │ × │         │
+│ └─────────────┴────────────┴─────────────────┴───┘         │
+│ [+ Add condition]                                           │
+└─────────────────────────────────────────────────────────────┘
+```
+
+## Complex Forms
+
+### Multi-Step Forms
+```
+Step indicator:
+──●────────●────────○────────○──
+  1         2         3         4
+Details   Settings  Review   Complete
+```
+
+- Show progress (steps completed / total)
+- Allow back navigation without data loss
+- Validate each step before proceeding
+- Summary/review step before final submission
+
+### Form Section Organization
+```
+┌─────────────────────────────────────┐
+│ Section Header                      │
+│ Brief description of this section   │
+├─────────────────────────────────────┤
+│                                     │
+│  Label              Label           │
+│  [Input field]      [Input field]   │
+│                                     │
+│  Label                              │
+│  [Wider input field              ]  │
+│                                     │
+└─────────────────────────────────────┘
+```
+
+### Inline Editing
+For settings and configuration:
+```
+Read mode:                    Edit mode:
+┌────────────────────────┐   ┌────────────────────────┐
+│ Company Name           │   │ Company Name           │
+│ Acme Corp        [Edit]│   │ [Acme Corp        ] ✓ ✗│
+└────────────────────────┘   └────────────────────────┘
+```
+
+## Navigation Patterns
+
+### Sidebar Navigation
+```
+┌──────────────┬────────────────────────────────────────┐
+│ [Logo]       │                                        │
+│              │                                        │
+│ ● Dashboard  │         Main Content Area              │
+│ ○ Vessels    │                                        │
+│ ○ Analytics  │                                        │
+│ ○ Reports    │                                        │
+│              │                                        │
+│ ─────────    │                                        │
+│ ○ Settings   │                                        │
+│ ○ Help       │                                        │
+│              │                                        │
+│ [User ▼]     │                                        │
+└──────────────┴────────────────────────────────────────┘
+```
+
+### Collapsible Sidebar
+- Expand: Full labels + icons
+- Collapse: Icons only (with tooltips)
+- Persist user preference
+- Keyboard shortcut to toggle
+
+### Tab Navigation (for sub-sections)
+```
+┌─────────────────────────────────────────────────────┐
+│ Vessel Detail                                       │
+├──────────┬───────────┬────────────┬─────────────────┤
+│ Overview │ Voyages   │ Documents  │ Activity        │
+├──────────┴───────────┴────────────┴─────────────────┤
+│                                                     │
+│              Tab content here                       │
+│                                                     │
+└─────────────────────────────────────────────────────┘
+```
+
+## Detail Views
+
+### Master-Detail Pattern
+```
+┌──────────────────────┬──────────────────────────────────┐
+│ List / Table         │  Detail Panel                    │
+│                      │                                  │
+│ ○ Item 1             │  Item 2 Details                  │
+│ ● Item 2  ←selected  │  ─────────────                   │
+│ ○ Item 3             │  [All properties and actions]    │
+│ ○ Item 4             │                                  │
+│                      │                                  │
+└──────────────────────┴──────────────────────────────────┘
+```
+
+### Side Panel / Drawer
+- Slides in from right (typically)
+- Width: 400-600px for forms, up to 50% for complex detail
+- Overlay with backdrop, or push content
+- Close on Escape, click outside, or explicit close button
+
+### Full-Page Detail
+Use when:
+- Detail view is primary workspace
+- Many tabs/sections of information
+- Users spend significant time on single record
+
+## Bulk Operations
+
+### Selection + Action Bar
+```
+When items selected, show action bar:
+┌─────────────────────────────────────────────────────────────┐
+│ ☑ 3 items selected    [Archive] [Delete] [More ▼]   [× Clear]│
+└─────────────────────────────────────────────────────────────┘
+```
+
+### Bulk Action Best Practices
+- Show count of selected items
+- Disable invalid actions for selection
+- Confirmation for destructive bulk actions
+- Progress indicator for long operations
+- Allow cancel mid-operation when possible
+- Report results (success/failures) after completion
+
+## Real-Time Updates
+
+### Live Data Indicators
+```
+● Live    — Green dot, real-time updates active
+◐ Syncing — Animated, sync in progress  
+○ Paused  — Gray, updates paused
+⚠ Stale   — Warning, data may be outdated
+```
+
+### Update Patterns
+- **Silent updates**: Data refreshes without visual indication
+- **Highlight updates**: Flash/highlight changed values briefly
+- **Toast notification**: "3 new items available" [Refresh]
+- **Inline indicator**: Show "Updated 2s ago" timestamp
+
+### Handling Conflicts
+When data changes while user is editing:
+- Show notification: "This item was updated by another user"
+- Options: [Keep my changes] [Load their changes] [Compare]
+
+## Productivity Patterns
+
+### Command Palette (Cmd+K)
+Centrally accessed modal for navigation and actions.
+- **Trigger**: `Cmd+K` / `Ctrl+K`.
+- **Search Mode**: Find pages, vessels, data.
+- **Action Mode**: "Create new...", "Change status to...", "Switch tenant".
+- **Anatomy**:
+  - Input field (autofocused)
+  - Recent items list
+  - Results grouped by type (Navigation, Actions, Data)
+  - Keyboard navigation hints (↑ ↓ ↵)
+
+### Keyboard First Design
+Power users rely on keyboard efficiency.
+- **Global Shortcuts**:
+  - `/`: Focus search
+  - `?`: Show keyboard shortcuts dialog
+  - `Esc`: Close modal/clear selection
+  - `j` / `k`: Next/previous item (Gmail style)
+- **Focus Management**:
+  - Focus trapping in modals.
+  - Logical tab order (top-left to bottom-right).
+  - Visual focus indicators at all times.
+
+## Empty States
+
+### First Use (Onboarding)
+- **Goal**: Teach value and drive first action.
+- **Content**:
+  - Illustration (welcoming)
+  - "No [items] yet"
+  - Description of benefit
+  - [Primary Action Button]
+
+### No Results (Search/Filter)
+- **Goal**: Help user recover.
+- **Content**:
+  - "No results found for 'xyz'"
+  - "Try adjusting filters or search term"
+  - [Clear Filters] button

package/skills/dp-ui/references/data-visualization.md

@@ -0,0 +1,304 @@
+# Data Visualization
+
+Charts, graphs, and maritime-specific display patterns.
+
+## Chart Selection Guide
+
+### Choose Based on Data Relationship
+
+| Relationship | Best Chart Types |
+|--------------|------------------|
+| **Comparison** (between categories) | Bar chart, grouped bar, radar |
+| **Trend** (over time) | Line chart, area chart |
+| **Part-to-whole** | Pie chart (≤5 segments), stacked bar, treemap |
+| **Distribution** | Histogram, box plot, violin plot |
+| **Correlation** | Scatter plot, bubble chart |
+| **Geographic** | Map, choropleth, connection map |
+| **Flow/Process** | Sankey, funnel |
+| **Hierarchy** | Treemap, sunburst |
+
+### Common Chart Patterns
+
+**Line Chart** — Time series, trends
+```
+│     ╭─────╮
+│    ╱       ╲    ╱
+│   ╱         ╲──╱
+│──╱
+└────────────────────
+  Jan  Feb  Mar  Apr
+```
+- Use for continuous data over time
+- Limit to 5-7 lines before it gets cluttered
+- Zero baseline not required (but be transparent)
+
+**Bar Chart** — Comparison across categories
+```
+│ ████████████████ 87
+│ ██████████████ 76
+│ ████████████ 65
+│ ████████ 43
+└─────────────────────
+```
+- Horizontal bars for long labels
+- Start at zero (truncated bars mislead)
+- Order by value (unless natural order exists)
+
+**Area Chart** — Volume over time, stacked composition
+- Use stacked area for part-to-whole over time
+- Ensure colors have enough contrast
+- Consider 100% stacked for proportions
+
+**Scatter Plot** — Correlation, distribution of two variables
+- Use color/size for third dimension
+- Add trend line to show correlation
+- Handle overplotting (transparency, jitter)
+
+## Chart Design Best Practices
+
+### Visual Hierarchy
+1. **Data** — Most prominent (highest contrast)
+2. **Labels** — Supporting (medium contrast)
+3. **Grid/axes** — Background (low contrast, subtle)
+
+### Color Usage
+```
+Sequential:    Light → Dark (for magnitude)
+              ░▒▓█
+
+Diverging:     Color ← Neutral → Color (for +/-)
+              █▓▒░ ░▒▓█
+
+Categorical:   Distinct, accessible palette
+              █ █ █ █ █ (max 5-7 colors)
+```
+
+### Accessible Palettes
+- **Colorblind Safe**: Avoid Red/Green acting as the only differentiator.
+- **Patterns**: Use dashed lines or textures for series differentiation.
+- **Safe Pairs**: Blue/Orange, Purple/Green.
+- **High Contrast**: Support system preference (thicker borders, distinct fills).
+
+### Labeling
+- **Title**: What is this showing? (not just "Chart")
+- **Axis labels**: Include units
+- **Data labels**: Directly on chart when possible (reduces eye movement)
+- **Legend**: Near relevant data, avoid separate legend when possible
+
+### Reduce Chart Junk
+Remove:
+- 3D effects (distort perception)
+- Decorative gridlines
+- Unnecessary borders
+- Redundant legends
+- Background colors (unless functional)
+
+### Responsiveness
+- Simplify for small screens (fewer data points, larger touch targets)
+- Provide summary stats when chart can't fit
+- Allow expand to full screen
+- Horizontal scroll for time series on mobile
+
+## Real-Time Data Visualization
+
+### Streaming Data Patterns
+
+**Live Line Chart**
+```
+Window approach:
+│    ╱╲   ╱╲  ╱╲   ╱╲
+│╱╲╱    ╲╱  ╲╱  ╲╱  ╲
+└──────────────────────→ time
+[← 5 minutes →] slides right
+```
+- Show rolling time window (last 5 min, last hour)
+- Smooth transitions for new data points
+- Option to pause/resume updates
+- Show "live" indicator
+
+**Real-Time Gauges**
+```
+        ╭──────╮
+      ╱    ▲    ╲
+     │     │     │    Current: 72%
+     │   ╲ │ ╱   │    Target: 80%
+      ╲   ─┴─   ╱
+        ╰──────╯
+         0   100
+```
+- Use for single KPIs with known range
+- Show target/threshold lines
+- Color changes at thresholds
+
+### Update Animation
+- Smooth transitions (300-500ms)
+- Highlight new data briefly
+- Don't animate if updates are too frequent (>1/second)
+
+## Maritime-Specific Visualizations
+
+### Vessel Position Map
+```
+┌─────────────────────────────────────┐
+│                    ▲ Vessel A       │
+│     ○ Port        ╱ (12 kts, N)     │
+│                  ╱                  │
+│                ╱                    │
+│      - - - - ▲ Vessel B (anchored)  │
+│            (predicted path)         │
+│                                     │
+│     ○ Port                          │
+└─────────────────────────────────────┘
+
+Legend:
+▲ Vessel (arrow = heading)
+● AIS position
+○ Port
+─ Historical track
+- - Predicted path
+```
+
+**Map Features**:
+- Vessel icons showing heading direction
+- Historical track (past 24h, configurable)
+- Predicted path based on speed/heading
+- Port markers with names
+- Vessel clusters at zoom levels
+- Click for vessel details popup
+
+### Voyage Timeline
+```
+Load Port        Discharge Port
+   ○─────────────────●
+   │                 │
+   ▼                 ▼
+[Rotterdam]     [Singapore]
+ Jan 5            Jan 28
+ 
+──●────○────○────○────●──────────→
+  Load  Canal Waiting Discharge  Next
+  3d    1d    2d     4d         voyage
+
+Status: ● Complete  ○ In Progress  ◌ Planned
+```
+
+### Fleet Overview Grid
+```
+┌────────────┬────────────┬────────────┐
+│ ▲ ALPHA    │ ▲ BETA     │ ⚓ GAMMA   │
+│ En route   │ En route   │ At port    │
+│ → Singapore│ → Dubai    │ Rotterdam  │
+│ ETA: 3d    │ ETA: 7d    │ Dep: 2d    │
+├────────────┼────────────┼────────────┤
+│ ⚓ DELTA   │ ▲ EPSILON  │ ⚠ ZETA    │
+│ At port    │ En route   │ Delayed    │
+│ Houston    │ → Santos   │ Weather    │
+│ Dep: 1d    │ ETA: 12d   │ +2d        │
+└────────────┴────────────┴────────────┘
+```
+
+### Freight Rate Charts
+```
+Baltic Index (Time Series)
+│2500
+│    ╭──╮
+│   ╱    ╲  ╭──
+│  ╱      ╲╱
+│1500
+└────────────────────────
+ Jan  Feb  Mar  Apr  May
+
+Annotations:
+↑ Market event markers
+─ Moving average (30-day)
+░ Confidence interval / range
+```
+
+### Port Congestion Visualization
+```
+Port Rotterdam
+┌─────────────────────────────────────┐
+│ Vessels waiting: 23 (+5 vs avg)     │
+│ Avg wait time: 2.3 days             │
+├─────────────────────────────────────┤
+│ Wait time distribution:             │
+│ <1d  ████████░░░░░░░ 12             │
+│ 1-3d ██████████░░░░░ 8              │
+│ >3d  ███░░░░░░░░░░░░ 3              │
+└─────────────────────────────────────┘
+```
+
+### Distance/Duration Matrix
+```
+           Rotterdam  Singapore  Houston
+Rotterdam     -          28d       14d
+Singapore    28d          -        35d
+Houston      14d         35d        -
+
+Visual encoding:
+░ Short  ▒ Medium  ▓ Long
+```
+
+### Vessel Performance Dashboard
+```
+┌──────────────────────────────────────────────────┐
+│ MV Pacific Voyager                               │
+├─────────────┬─────────────┬──────────────────────┤
+│ Speed       │ Fuel        │ Efficiency           │
+│   12.4 kts  │  45 MT/day  │   92%               │
+│   ↓ 0.2     │   ↑ 2%      │   ↓ 3%              │
+├─────────────┴─────────────┴──────────────────────┤
+│ Speed vs Consumption (Scatter)                   │
+│      •                                           │
+│    • • •    Optimal zone                         │
+│   •  ●  •  ┌───────────┐                        │
+│     • •    │           │ Current: ●             │
+│            └───────────┘                        │
+└──────────────────────────────────────────────────┘
+```
+
+## Interactive Features
+
+### Tooltips
+```
+Hover on data point:
+┌──────────────────────┐
+│ January 2025         │
+│ Revenue: $1,234,567  │
+│ vs LY: +12.4%        │
+│ [View details →]     │
+└──────────────────────┘
+```
+- Show on hover (desktop), tap (mobile)
+- Formatted values with context
+- Link to drill-down when available
+
+### Zoom & Pan
+- Click-drag to zoom to selection
+- Mousewheel for zoom in/out
+- Reset zoom button always visible
+- Mini-map for context in large datasets
+
+### Cross-Filtering
+When clicking a chart element, filter other charts:
+```
+Click "January" in bar chart → 
+  Line chart highlights January
+  Table filters to January rows
+  Map shows January positions
+```
+
+### Advanced Interactions
+- **Sticky Tooltips**: Tooltip follows mouse vs. snaps to nearest point.
+- **Drill-Down**:
+  - Click bar → Filter dashboard → Show detailed table.
+  - Maintains context (don't lose where you came from).
+- **Brushing**: Drag to select range on one chart → highlights on others.
+
+## Accessibility in Charts
+
+- Don't rely on color alone (use patterns, labels)
+- Provide data table alternative
+- Keyboard navigation for interactive elements
+- Screen reader descriptions for charts
+- Sufficient contrast in all visual elements