@andreaswissel/uiflow

# UIFlow Configuration Guide Comprehensive guide to UIFlow's declarative JSON configuration system for scalable UX management. ## Table of Contents - [Overview](#overview) - [Basic Configuration](#basic-configuration) - [Element Dependencies](#element-dependencies) - [A/B Testing](#ab-testing) - [Flow Rules](#flow-rules) - [Real-World Examples](#real-world-examples) - [Best Practices](#best-practices) ## Overview UIFlow's configuration system allows you to define complex adaptive UX behaviors using declarative JSON, making it perfect for: - **SaaS Applications**: Progressive feature disclosure - **Content Management**: Workflow-based unlocking - **E-commerce**: Skill-based seller tools - **Social Media**: Engagement-driven features ## Basic Configuration ### Minimal Setup ```json { "name": "My App Configuration", "version": "1.0.0", "areas": { "toolbar": { "defaultDensity": 0.3, "elements": [ { "id": "save-btn", "selector": "#save-btn", "category": "basic", "helpText": "Save your work" }, { "id": "export-btn", "selector": "#export-btn", "category": "advanced", "helpText": "Export to various formats" } ] } } } ``` ### Configuration Schema | Property | Type | Required | Description | |----------|------|----------|-------------| | `name` | string | ✅ | Configuration identifier | | `version` | string | ✅ | Configuration version | | `areas` | object | ✅ | UI areas definition | | `rules` | array | ❌ | Advanced behavior rules | | `templates` | array | ❌ | Reusable rule templates | | `abTest` | object | ❌ | A/B testing configuration | ### Area Configuration ```json { "areas": { "editor": { "defaultDensity": 0.4, "learningRate": 0.15, "elements": [...], "metadata": { "description": "Text editing interface", "owner": "content-team" } } } } ``` ## Element Dependencies Define logical relationships between UI elements to create progressive disclosure patterns. ### Usage Count Dependencies Unlock features after repeated use: ```json { "id": "advanced-editor", "category": "advanced", "dependencies": [ { "type": "usage_count", "elementId": "basic-editor", "threshold": 5, "description": "Use basic editor 5 times to unlock advanced features" } ] } ``` **Use Cases:** - Text editor: Basic formatting → Advanced styling - Photo editor: Crop/resize → Filters and effects - Dashboard: View reports → Create custom reports ### Sequence Dependencies Create workflows that must be completed in order: ```json { "id": "publish-scheduler", "category": "expert", "dependencies": [ { "type": "sequence", "elements": ["create-post", "add-media", "preview-post"], "description": "Complete content creation workflow first" } ] } ``` **Use Cases:** - Social media: Create → Edit → Preview → Schedule - E-commerce: Add product → Set pricing → Upload images → Publish - CRM: Add contact → Qualify lead → Create opportunity → Close deal ### Time-Based Dependencies Unlock based on consistent usage over time: ```json { "id": "automation-tools", "category": "expert", "dependencies": [ { "type": "time_based", "elementId": "manual-actions", "timeWindow": "7d", "minUsage": 10, "description": "Use manual tools 10+ times in a week to unlock automation" } ] } ``` **Use Cases:** - Marketing tools: Manual campaigns → Automated workflows - Analytics: Manual reports → Scheduled reports - Customer support: Manual tickets → Auto-routing ### Logical AND Dependencies Require mastery of multiple features: ```json { "id": "power-user-dashboard", "category": "expert", "dependencies": [ { "type": "logical_and", "elements": ["advanced-filters", "custom-charts", "data-exports"], "description": "Master all analysis tools to unlock power dashboard" } ] } ``` **Use Cases:** - Analytics: Multiple chart types → Executive dashboard - Design tools: Basic shapes + colors + effects → Templates - Project management: Tasks + time tracking + reporting → Advanced PM ## A/B Testing Built-in experimentation framework for optimizing progressive disclosure. ### Basic A/B Test ```json { "abTest": { "name": "Feature Unlock Speed Test", "description": "Test aggressive vs conservative unlock patterns", "variants": [ { "id": "control", "weight": 0.5, "name": "Standard Progression" }, { "id": "aggressive", "weight": 0.3, "name": "Fast Unlock", "modifications": { "thresholdMultiplier": 0.5 } }, { "id": "conservative", "weight": 0.2, "name": "Gradual Unlock", "modifications": { "thresholdMultiplier": 1.5 } } ] } } ``` ### Variant-Specific Configuration ```json { "areas": { "toolbar": { "elements": [ { "id": "advanced-tools", "category": "advanced", "dependencies": [ { "type": "usage_count", "elementId": "basic-tools", "threshold": 5, "variants": { "aggressive": { "threshold": 2 }, "conservative": { "threshold": 8 } } } ] } ] } } } ``` ### Metrics Tracking Track success metrics automatically: ```javascript // In your application code uiflow.trackABTestMetric('feature_adoption'); uiflow.trackABTestMetric('user_retention_7d'); uiflow.trackABTestMetric('conversion_rate', 0.12); // Get results const results = uiflow.getABTestResults(); // { variant: "aggressive", metrics: { feature_adoption: 15, ... } } ``` ## Flow Rules Advanced behavioral rules that trigger based on user patterns. ### Usage Pattern Rules ```json { "rules": [ { "name": "Content Creator Journey", "description": "Unlock advanced tools for active creators", "trigger": { "type": "usage_pattern", "elements": ["create-post", "add-media"], "frequency": "daily", "duration": "3d", "threshold": 2 }, "action": { "type": "unlock_category", "category": "advanced", "area": "content-tools" } } ] } ``` ### Element Interaction Rules ```json { "rules": [ { "name": "First Media Upload Tutorial", "trigger": { "type": "element_interaction", "elements": ["media-upload"], "firstTime": true }, "action": { "type": "show_tutorial", "data": { "tutorial": "media-best-practices", "autoStart": true, "message": "🎉 Great! Visual content gets 2.3x more engagement!" } } } ] } ``` ### Time-Based Rules ```json { "rules": [ { "name": "Power User Recognition", "trigger": { "type": "time_based", "threshold": 30, "unit": "interactions" }, "action": { "type": "send_event", "data": { "event": "power_user_achieved", "badge": "Expert User 🏆" } } } ] } ``` ## Real-World Examples ### Social Media Management Platform Complete SocialFlow configuration: ```json { "name": "SocialFlow - Social Media Creator", "version": "1.0.0", "areas": { "composer": { "defaultDensity": 0.8, "elements": [ { "id": "instagram-platform", "selector": "#instagram-platform", "category": "advanced", "helpText": "Share visual content on Instagram", "dependencies": [ { "type": "usage_count", "elementId": "publish-btn", "threshold": 2, "description": "Create 2 posts before accessing Instagram" } ] } ] }, "media": { "defaultDensity": 0.3, "elements": [ { "id": "media-upload", "selector": "#media-upload", "category": "advanced", "helpText": "Add photos and videos", "dependencies": [ { "type": "usage_count", "elementId": "publish-btn", "threshold": 2 } ] } ] }, "scheduling": { "defaultDensity": 0.2, "elements": [ { "id": "post-scheduler", "selector": "#post-scheduler", "category": "expert", "helpText": "Schedule posts for optimal engagement", "dependencies": [ { "type": "logical_and", "elements": ["media-upload", "publish-btn"], "description": "Use media uploads and create posts first" }, { "type": "usage_count", "elementId": "publish-btn", "threshold": 3 } ] } ] }, "analytics": { "defaultDensity": 0.1, "elements": [ { "id": "analytics-dashboard", "selector": "#analytics-dashboard", "category": "expert", "helpText": "Track performance and optimize strategy", "dependencies": [ { "type": "sequence", "elements": ["publish-btn", "media-upload", "post-scheduler"], "description": "Complete the content workflow: post → media → schedule" }, { "type": "usage_count", "elementId": "post-scheduler", "threshold": 3 } ] } ] } }, "rules": [ { "name": "Content Creator Recognition", "trigger": { "type": "usage_pattern", "elements": ["publish-btn", "media-upload"], "frequency": "daily", "duration": "3d" }, "action": { "type": "unlock_category", "category": "advanced", "area": "analytics" } } ], "abTest": { "name": "Progressive Disclosure Speed", "variants": [ { "id": "standard", "weight": 0.6 }, { "id": "fast", "weight": 0.4 } ] } } ``` ### E-commerce Seller Tools Progressive seller capabilities: ```json { "name": "Seller Tools Progressive Disclosure", "areas": { "product-management": { "elements": [ { "id": "basic-listing", "category": "basic", "helpText": "Create product listings" }, { "id": "seo-optimization", "category": "advanced", "dependencies": [ { "type": "usage_count", "elementId": "basic-listing", "threshold": 5, "description": "Create 5 listings to unlock SEO tools" } ] }, { "id": "bulk-operations", "category": "expert", "dependencies": [ { "type": "logical_and", "elements": ["basic-listing", "seo-optimization"], "description": "Master individual listings and SEO first" }, { "type": "usage_count", "elementId": "basic-listing", "threshold": 20, "description": "Create 20+ listings to unlock bulk tools" } ] } ] }, "marketing": { "elements": [ { "id": "promotion-creator", "category": "advanced", "dependencies": [ { "type": "sequence", "elements": ["basic-listing", "first-sale"], "description": "Create listings and make first sale" } ] }, { "id": "ad-automation", "category": "expert", "dependencies": [ { "type": "time_based", "elementId": "promotion-creator", "timeWindow": "14d", "minUsage": 5, "description": "Run 5+ promotions in 2 weeks" } ] } ] } } } ``` ## Best Practices ### 1. Start Simple Begin with basic usage_count dependencies: ```json { "dependencies": [ { "type": "usage_count", "elementId": "basic-feature", "threshold": 3, "description": "Clear, actionable unlock requirement" } ] } ``` ### 2. Logical Progressions Design dependencies that feel natural: ```javascript // ✅ Good: Logical workflow create-post → add-media → schedule-post → analytics // ❌ Bad: Arbitrary requirements create-post → analytics → add-media ``` ### 3. Clear Descriptions Always include helpful descriptions: ```json { "description": "Create 3 posts to understand scheduling value" } ``` ### 4. Reasonable Thresholds Don't make users wait too long: ```javascript // ✅ Good: Quick wins (2-5 uses) { "threshold": 3 } // ❌ Bad: Frustrating delays (20+ uses) { "threshold": 25 } ``` ### 5. A/B Testing Test different unlock speeds: ```json { "variants": [ { "id": "standard", "weight": 0.7 }, { "id": "aggressive", "weight": 0.3, "thresholdMultiplier": 0.5 } ] } ``` ### 6. Progressive Complexity Layer dependencies for advanced features: ```json { "expert-feature": { "dependencies": [ { "type": "logical_and", "elements": ["basic-mastery", "advanced-usage"] }, { "type": "time_based", "timeWindow": "7d", "minUsage": 10 } ] } } ``` ### 7. User Feedback Provide unlock hints and progress indicators: ```json { "dependencies": [ { "type": "usage_count", "threshold": 5, "description": "📊 Use reports 5 times to unlock advanced analytics", "progressHint": "Progress: {current}/{total} reports viewed" } ] } ``` ## Configuration Validation UIFlow automatically validates your configuration and provides helpful error messages: ```javascript try { await uiflow.loadConfiguration(config); } catch (error) { console.error('Configuration Error:', error.message); // "Element 'advanced-btn' depends on non-existent element 'missing-btn'" // "Circular dependency detected: a → b → c → a" // "Invalid dependency type 'custom_type' for element 'test-btn'" } ``` ## Next Steps - 📖 [API Reference](./api.md) - Complete method documentation - 🎮 [SocialFlow Demo](../demo/social-media-demo.html) - See configuration in action - 🛠️ [Best Practices](./best-practices.md) - Advanced patterns and optimization - 📊 [Analytics Integration](./analytics.md) - Track configuration effectiveness