@elsahafy/ux-mcp-server 2.0.0

package/knowledge/design-tokens.json

@@ -0,0 +1,286 @@
+{
+  "name": "Design System Principles & Tokens",
+  "description": "Foundational design system concepts and token structure",
+  "principles": {
+    "atomic_design": {
+      "name": "Atomic Design Methodology",
+      "levels": [
+        {
+          "name": "Atoms",
+          "description": "Basic building blocks (buttons, inputs, labels, icons)",
+          "examples": ["Button", "Input", "Label", "Icon", "Badge", "Avatar"],
+          "characteristics": [
+            "Cannot be broken down further",
+            "Highly reusable",
+            "Minimal logic"
+          ]
+        },
+        {
+          "name": "Molecules",
+          "description": "Simple combinations of atoms",
+          "examples": ["Search bar (input + button + icon)", "Form field (label + input + helper text)", "Card header (avatar + name + timestamp)"],
+          "characteristics": [
+            "Single responsibility",
+            "Reusable combinations",
+            "Simple interactions"
+          ]
+        },
+        {
+          "name": "Organisms",
+          "description": "Complex components made of molecules/atoms",
+          "examples": ["Navigation bar", "Product card", "Data table", "Form section"],
+          "characteristics": [
+            "Distinct section of interface",
+            "May contain business logic",
+            "More specific use cases"
+          ]
+        },
+        {
+          "name": "Templates",
+          "description": "Page-level layouts",
+          "examples": ["Dashboard layout", "Landing page template", "Admin panel"],
+          "characteristics": [
+            "Define page structure",
+            "Show content placement",
+            "No actual content yet"
+          ]
+        },
+        {
+          "name": "Pages",
+          "description": "Specific instances of templates with real content",
+          "examples": ["User dashboard", "Product listing", "Profile page"],
+          "characteristics": [
+            "Real data and content",
+            "Test components in context",
+            "End-user facing"
+          ]
+        }
+      ]
+    },
+    "design_tokens": {
+      "description": "Named design decisions that maintain consistency",
+      "categories": {
+        "color": {
+          "structure": {
+            "primitive": "Raw values (hex codes)",
+            "semantic": "Purpose-based names",
+            "component": "Component-specific tokens"
+          },
+          "example_structure": {
+            "primitive": {
+              "blue-50": "#eff6ff",
+              "blue-500": "#3b82f6",
+              "blue-900": "#1e3a8a"
+            },
+            "semantic": {
+              "color-primary": "var(--blue-500)",
+              "color-background": "var(--gray-50)",
+              "color-text": "var(--gray-900)",
+              "color-success": "var(--green-500)",
+              "color-error": "var(--red-500)"
+            },
+            "component": {
+              "button-primary-bg": "var(--color-primary)",
+              "button-primary-text": "white",
+              "input-border": "var(--gray-300)"
+            }
+          },
+          "best_practices": [
+            "Use semantic naming (not color names in app code)",
+            "Define light/dark mode variants",
+            "Maintain WCAG AA contrast ratios",
+            "Limit palette to 5-7 primary colors"
+          ]
+        },
+        "spacing": {
+          "description": "Consistent spacing scale for margins, padding, gaps",
+          "scale": {
+            "concept": "Base unit multiplied by scale factor",
+            "example": {
+              "base_unit": "4px or 8px",
+              "scale": {
+                "space-1": "4px",
+                "space-2": "8px",
+                "space-3": "12px",
+                "space-4": "16px",
+                "space-6": "24px",
+                "space-8": "32px",
+                "space-12": "48px",
+                "space-16": "64px"
+              }
+            }
+          },
+          "best_practices": [
+            "Use scale values only (no arbitrary values)",
+            "4px or 8px base unit most common",
+            "Consistent spacing creates visual rhythm",
+            "Larger spacing for grouping, smaller within groups"
+          ]
+        },
+        "typography": {
+          "scales": {
+            "modular_scale": {
+              "description": "Mathematically related font sizes",
+              "ratios": {
+                "minor_third": "1.200",
+                "major_third": "1.250",
+                "perfect_fourth": "1.333",
+                "golden_ratio": "1.618"
+              }
+            }
+          },
+          "structure": {
+            "font_family": {
+              "font-sans": "system-ui, -apple-system, sans-serif",
+              "font-serif": "Georgia, Cambria, serif",
+              "font-mono": "Menlo, Monaco, Courier, monospace"
+            },
+            "font_size": {
+              "text-xs": "0.75rem",
+              "text-sm": "0.875rem",
+              "text-base": "1rem",
+              "text-lg": "1.125rem",
+              "text-xl": "1.25rem",
+              "text-2xl": "1.5rem",
+              "text-3xl": "1.875rem",
+              "text-4xl": "2.25rem"
+            },
+            "font_weight": {
+              "font-normal": "400",
+              "font-medium": "500",
+              "font-semibold": "600",
+              "font-bold": "700"
+            },
+            "line_height": {
+              "leading-tight": "1.25",
+              "leading-normal": "1.5",
+              "leading-relaxed": "1.75"
+            }
+          },
+          "best_practices": [
+            "Limit to 2-3 font families maximum",
+            "Use system fonts for performance",
+            "Minimum 16px base font size",
+            "1.5 line-height for body text",
+            "Scale sizes proportionally"
+          ]
+        },
+        "shadows": {
+          "description": "Elevation and depth",
+          "levels": {
+            "shadow-sm": "0 1px 2px 0 rgba(0, 0, 0, 0.05)",
+            "shadow": "0 1px 3px 0 rgba(0, 0, 0, 0.1)",
+            "shadow-md": "0 4px 6px -1px rgba(0, 0, 0, 0.1)",
+            "shadow-lg": "0 10px 15px -3px rgba(0, 0, 0, 0.1)",
+            "shadow-xl": "0 20px 25px -5px rgba(0, 0, 0, 0.1)"
+          },
+          "usage": {
+            "shadow-sm": "Subtle card separation",
+            "shadow": "Cards, buttons",
+            "shadow-md": "Dropdowns, tooltips",
+            "shadow-lg": "Modals, popovers",
+            "shadow-xl": "Full-screen overlays"
+          }
+        },
+        "border_radius": {
+          "scale": {
+            "rounded-none": "0",
+            "rounded-sm": "2px",
+            "rounded": "4px",
+            "rounded-md": "6px",
+            "rounded-lg": "8px",
+            "rounded-xl": "12px",
+            "rounded-full": "9999px"
+          },
+          "usage": {
+            "rounded": "Buttons, inputs",
+            "rounded-lg": "Cards, panels",
+            "rounded-xl": "Modals, large containers",
+            "rounded-full": "Pills, avatars, icon buttons"
+          }
+        },
+        "animation": {
+          "durations": {
+            "duration-fast": "150ms",
+            "duration-base": "200ms",
+            "duration-slow": "300ms",
+            "duration-slower": "500ms"
+          },
+          "easing": {
+            "ease-in": "cubic-bezier(0.4, 0, 1, 1)",
+            "ease-out": "cubic-bezier(0, 0, 0.2, 1)",
+            "ease-in-out": "cubic-bezier(0.4, 0, 0.2, 1)"
+          },
+          "best_practices": [
+            "Use ease-out for entrances",
+            "Use ease-in for exits",
+            "Keep durations under 300ms",
+            "Provide prefers-reduced-motion support"
+          ]
+        }
+      }
+    },
+    "component_api_design": {
+      "description": "Principles for designing component interfaces",
+      "guidelines": [
+        {
+          "principle": "Composition over Configuration",
+          "description": "Favor composable components over complex prop APIs",
+          "example": {
+            "good": "<Card>\n  <CardHeader>Title</CardHeader>\n  <CardContent>Body</CardContent>\n</Card>",
+            "bad": "<Card title='Title' content='Body' />"
+          }
+        },
+        {
+          "principle": "Sensible Defaults",
+          "description": "Components work well out-of-box without configuration",
+          "example": {
+            "good": "<Button>Click me</Button> // works without props",
+            "bad": "<Button type='button' color='primary' size='medium'>Click</Button> // requires many props"
+          }
+        },
+        {
+          "principle": "Progressive Enhancement",
+          "description": "Start simple, add features as needed",
+          "layers": [
+            "Basic functionality works with no props",
+            "Common customizations via props",
+            "Advanced use cases via composition/slots"
+          ]
+        },
+        {
+          "principle": "Consistent Naming",
+          "description": "Use consistent prop names across components",
+          "examples": [
+            "size: 'sm' | 'md' | 'lg' (not small/medium/large)",
+            "variant: 'primary' | 'secondary' | 'ghost'",
+            "disabled, loading, error (boolean props)",
+            "onX pattern for events: onClick, onChange, onSubmit"
+          ]
+        }
+      ]
+    }
+  },
+  "implementation_checklist": [
+    "Define color palette with semantic naming",
+    "Create spacing scale (base 4px or 8px)",
+    "Establish typography scale and weights",
+    "Define shadow levels for elevation",
+    "Set border-radius values",
+    "Create animation durations and easing",
+    "Build atomic components (buttons, inputs)",
+    "Compose molecules from atoms",
+    "Document component APIs",
+    "Provide usage examples",
+    "Test dark mode support",
+    "Ensure accessibility (WCAG AA)",
+    "Create component playground/storybook"
+  ],
+  "tools": [
+    "Figma Variables for design tokens",
+    "Style Dictionary for code generation",
+    "Storybook for component documentation",
+    "Chromatic for visual testing",
+    "Axe DevTools for accessibility"
+  ]
+}

package/knowledge/error-messages.json

@@ -0,0 +1,307 @@
+{
+  "name": "Error Message Library",
+  "description": "User-friendly, accessible error messages for common scenarios",
+  "principles": {
+    "good_error_messages": [
+      "Explain what went wrong in plain language",
+      "Tell the user how to fix it",
+      "Be specific, not generic",
+      "Use positive, helpful tone",
+      "Avoid technical jargon",
+      "Include relevant context",
+      "Provide next steps or alternatives"
+    ],
+    "avoid": [
+      "Generic messages ('An error occurred')",
+      "Technical error codes alone ('Error 500')",
+      "Blaming the user ('You did X wrong')",
+      "Overwhelming details",
+      "Unclear next steps"
+    ]
+  },
+  "categories": {
+    "authentication": {
+      "invalid_credentials": {
+        "bad": "Invalid username or password",
+        "good": "We couldn't find an account with that email and password combination. Please check your credentials and try again.",
+        "extra_help": "Link to password reset",
+        "security_note": "Don't reveal which field is wrong (email vs password) to prevent enumeration attacks"
+      },
+      "account_locked": {
+        "message": "Your account has been temporarily locked for security reasons after multiple failed login attempts.",
+        "action": "Try again in 15 minutes or reset your password to unlock immediately.",
+        "tone": "Reassuring, not alarming"
+      },
+      "password_reset_required": {
+        "message": "For your security, you need to reset your password before continuing.",
+        "action": "Click the button below to reset your password.",
+        "context": "Explain why (policy, breach, etc.)"
+      },
+      "session_expired": {
+        "message": "Your session has expired for security reasons.",
+        "action": "Please log in again to continue.",
+        "helpful": "Save your work before expiration with auto-save"
+      }
+    },
+    "validation": {
+      "required_field": {
+        "generic": "[Field name] is required",
+        "specific_examples": {
+          "email": "Please enter your email address",
+          "password": "Please create a password",
+          "name": "Please enter your name"
+        }
+      },
+      "invalid_format": {
+        "email": {
+          "message": "Please enter a valid email address (e.g., name@example.com)",
+          "trigger": "After @ missing or invalid domain"
+        },
+        "phone": {
+          "message": "Please enter a valid phone number (e.g., (555) 123-4567)",
+          "show_format": "Display expected format in helper text"
+        },
+        "url": {
+          "message": "Please enter a valid URL starting with http:// or https://",
+          "example": "https://www.example.com"
+        },
+        "date": {
+          "message": "Please enter a valid date in MM/DD/YYYY format",
+          "provide_picker": "Use native date picker when possible"
+        }
+      },
+      "length_requirements": {
+        "too_short": {
+          "generic": "[Field] must be at least X characters",
+          "password_example": "Password must be at least 8 characters long",
+          "show_count": "Display character counter"
+        },
+        "too_long": {
+          "message": "[Field] must be less than X characters",
+          "show_count": "Display remaining characters"
+        }
+      },
+      "pattern_requirements": {
+        "password_weak": {
+          "message": "Password must include at least one uppercase letter, one number, and one special character",
+          "realtime": "Show requirements checklist that updates as user types"
+        },
+        "username_invalid": {
+          "message": "Username can only contain letters, numbers, and underscores",
+          "example": "For example: user_name123"
+        }
+      },
+      "value_constraints": {
+        "number_too_low": {
+          "message": "[Field] must be at least X",
+          "example": "Quantity must be at least 1"
+        },
+        "number_too_high": {
+          "message": "[Field] cannot exceed X",
+          "example": "You can order a maximum of 10 items"
+        },
+        "date_in_past": {
+          "message": "Date must be in the future",
+          "context": "For scheduling, bookings, etc."
+        },
+        "date_too_far": {
+          "message": "Date cannot be more than X days/months in the future",
+          "helpful": "Show available date range"
+        }
+      }
+    },
+    "network_errors": {
+      "offline": {
+        "message": "You appear to be offline. Please check your internet connection and try again.",
+        "action": "Automatically retry when connection restored",
+        "helpful": "Show connection status indicator"
+      },
+      "timeout": {
+        "message": "The request is taking longer than expected. This might be due to a slow connection.",
+        "action": "Would you like to keep waiting or try again?",
+        "buttons": ["Keep Waiting", "Try Again"]
+      },
+      "server_error": {
+        "user_facing": "Something went wrong on our end. We're working to fix it.",
+        "action": "Please try again in a few minutes.",
+        "helpful": "Include error ID for support: 'Error ID: ABC123'",
+        "avoid": "Exposing stack traces or technical details"
+      },
+      "rate_limited": {
+        "message": "You're doing that too quickly. Please wait a moment before trying again.",
+        "action": "You can try again in X seconds.",
+        "show_timer": "Display countdown"
+      }
+    },
+    "permissions": {
+      "not_authorized": {
+        "message": "You don't have permission to access this feature.",
+        "action": "Contact your administrator if you believe this is a mistake.",
+        "helpful": "Link to help or support"
+      },
+      "browser_permission": {
+        "camera": {
+          "message": "This feature needs access to your camera.",
+          "action": "Click 'Allow' in the browser prompt to continue.",
+          "alternative": "Or upload a photo instead"
+        },
+        "location": {
+          "message": "We need your location to show nearby results.",
+          "action": "Click 'Allow' when prompted, or enter your location manually.",
+          "privacy": "Explain how location is used"
+        },
+        "notifications": {
+          "message": "Enable notifications to stay updated.",
+          "action": "Click 'Allow' to receive notifications, or adjust this later in settings.",
+          "optional": "Make it clear notifications are optional"
+        }
+      }
+    },
+    "business_logic": {
+      "out_of_stock": {
+        "message": "This item is currently out of stock.",
+        "action": "Get notified when it's back in stock",
+        "alternative": "View similar items"
+      },
+      "promo_expired": {
+        "message": "This promotional code has expired.",
+        "action": "Check our current offers",
+        "helpful": "Show expiration date if known"
+      },
+      "payment_declined": {
+        "message": "Your payment couldn't be processed.",
+        "reasons": [
+          "The card details might be incorrect",
+          "There might be insufficient funds",
+          "Your bank might be blocking the transaction"
+        ],
+        "action": "Please check your payment details or try a different payment method.",
+        "support": "Contact your bank if the problem persists"
+      },
+      "age_restriction": {
+        "message": "You must be 18 or older to access this content.",
+        "action": "Please verify your age to continue.",
+        "comply": "Explain legal requirement"
+      }
+    },
+    "file_upload": {
+      "file_too_large": {
+        "message": "This file is too large. Maximum file size is X MB.",
+        "action": "Please choose a smaller file or compress your image.",
+        "helpful": "Show current file size"
+      },
+      "invalid_file_type": {
+        "message": "This file type isn't supported. Please upload a JPG, PNG, or PDF file.",
+        "show_accepted": "Display accepted formats clearly"
+      },
+      "upload_failed": {
+        "message": "Upload failed. This might be due to a connection issue.",
+        "action": "Please try again or choose a different file.",
+        "preserve": "Don't lose other form data on failure"
+      }
+    },
+    "search_results": {
+      "no_results": {
+        "message": "No results found for '[search term]'",
+        "suggestions": [
+          "Check your spelling",
+          "Try different keywords",
+          "Use fewer or more general terms"
+        ],
+        "alternatives": "Show popular searches or categories"
+      },
+      "too_many_results": {
+        "message": "Your search returned too many results to display.",
+        "action": "Try adding more specific terms to narrow your search.",
+        "helpful": "Suggest filters"
+      }
+    },
+    "system_messages": {
+      "maintenance": {
+        "planned": {
+          "advance_notice": "Scheduled maintenance on [date] from [time] to [time]. Some features may be unavailable.",
+          "during": "We're currently performing scheduled maintenance. We'll be back shortly.",
+          "estimate": "Always provide estimated completion time"
+        },
+        "unexpected": {
+          "message": "We're experiencing technical difficulties and are working to resolve them.",
+          "action": "Please check back shortly.",
+          "updates": "Link to status page for updates"
+        }
+      },
+      "deprecation": {
+        "message": "This feature will be discontinued on [date].",
+        "action": "Please switch to [new feature] before then.",
+        "migration": "Provide migration guide or support"
+      }
+    }
+  },
+  "tone_guidelines": {
+    "do": [
+      "Use conversational language",
+      "Be empathetic and understanding",
+      "Focus on solutions, not problems",
+      "Take responsibility when it's our fault",
+      "Provide clear next steps",
+      "Use 'we' and 'us' (not 'the system')"
+    ],
+    "dont": [
+      "Use jargon or technical terms",
+      "Blame the user",
+      "Be vague or unclear",
+      "Use angry or frustrated tone",
+      "Overwhelm with information",
+      "Make jokes about errors"
+    ]
+  },
+  "formatting": {
+    "structure": {
+      "title": "Brief summary (5-10 words)",
+      "description": "Explanation of what went wrong",
+      "action": "Clear next step(s)",
+      "additional_help": "Links or alternatives (optional)"
+    },
+    "visual_elements": [
+      "Icon to indicate error type (⚠️ warning, ❌ error, ℹ️ info)",
+      "Color coding (red for errors, yellow for warnings)",
+      "Highlight the problematic field in forms",
+      "Use sufficient contrast for readability"
+    ],
+    "placement": {
+      "inline": "Next to field for form validation",
+      "toast": "For non-critical system messages",
+      "modal": "For critical errors requiring acknowledgment",
+      "banner": "For system-wide issues"
+    }
+  },
+  "accessibility": [
+    "Use role='alert' for critical errors",
+    "Announce errors to screen readers with aria-live",
+    "Link error summary to specific fields with aria-describedby",
+    "Don't rely on color alone",
+    "Include text with icons",
+    "Make error messages keyboard accessible",
+    "Move focus to error on form submission"
+  ],
+  "internationalization": {
+    "considerations": [
+      "Write messages that can be easily translated",
+      "Avoid idioms or cultural references",
+      "Account for text expansion (some languages are 30-40% longer)",
+      "Use placeholders for dynamic content: '{fieldName} is required'",
+      "Provide context for translators"
+    ]
+  },
+  "testing": {
+    "checklist": [
+      "Test all error scenarios",
+      "Verify messages are clear to non-technical users",
+      "Check tone is appropriate",
+      "Ensure next steps are actionable",
+      "Test with screen readers",
+      "Verify error recovery flows work",
+      "Check messages in different languages",
+      "Validate character limits for UI"
+    ]
+  }
+}