Smithery Logo
MCPsSkillsDocsPricing
Login
Smithery Logo

Accelerating the Agent Economy

Resources

DocumentationPrivacy PolicySystem Status

Company

PricingAboutBlog

Connect

© 2026 Smithery. All rights reserved.

    bejranonda

    gui-design-principles

    bejranonda/gui-design-principles
    Design
    15
    1 installs

    About

    SKILL.md

    Install

    Install via Skills CLI

    or add to your agent
    • Claude Code
      Claude Code
    • Codex
      Codex
    • OpenClaw
      OpenClaw
    • Cursor
      Cursor
    • Amp
      Amp
    • GitHub Copilot
      GitHub Copilot
    • Gemini CLI
      Gemini CLI
    • Kilo Code
      Kilo Code
    • Junie
      Junie
    • Replit
      Replit
    • Windsurf
      Windsurf
    • Cline
      Cline
    • Continue
      Continue
    • OpenCode
      OpenCode
    • OpenHands
      OpenHands
    • Roo Code
      Roo Code
    • Augment
      Augment
    • Goose
      Goose
    • Trae
      Trae
    • Zencoder
      Zencoder
    • Antigravity
      Antigravity
    ├─
    ├─
    └─

    About

    Comprehensive design principles and best practices for creating beautiful, functional GUI applications including dashboards, web apps, and mobile apps

    SKILL.md

    Overview

    This skill provides essential design principles, patterns, and guidelines for developing high-quality graphical user interfaces. It encompasses visual design, user experience, accessibility, and modern UI/UX best practices across web, desktop, and mobile platforms.

    Design Foundations

    Core Design Principles

    Visual Hierarchy

    • Establish clear information hierarchy with size, weight, and spacing
    • Use contrast to guide attention to important elements
    • Implement progressive disclosure for complex interfaces
    • Follow the "F-Pattern" and "Z-Pattern" for natural eye movement

    Color Theory

    • Use limited color palettes (3-5 primary colors maximum)
    • Ensure sufficient contrast ratios (WCAG AA: 4.5:1, AAA: 7:1)
    • Implement consistent color meanings across the interface
    • Use color purposefully for branding, actions, and feedback

    Typography

    • Choose readable fonts optimized for screens
    • Establish clear type scale (h1-h6, body, small, caption)
    • Maintain consistent line spacing (1.4-1.6 for body text)
    • Limit font families to 2-3 maximum for consistency

    Spacing & Layout

    • Use consistent spacing units (4px, 8px, 16px grid system)
    • Implement proper visual rhythm with consistent margins/padding
    • Ensure adequate touch targets (44px minimum for mobile)
    • Use white space strategically to reduce cognitive load

    Responsive Design Principles

    Mobile-First Approach

    • Design for smallest screen first, then enhance for larger screens
    • Use flexible grids and layouts that adapt to screen size
    • Optimize touch interactions for mobile devices
    • Consider content prioritization for different screen sizes

    Breakpoint Strategy

    • Mobile: 320px - 768px
    • Tablet: 768px - 1024px
    • Desktop: 1024px - 1440px
    • Large Desktop: 1440px+

    Flexible Components

    • Use relative units (%, rem, em, vh, vw)
    • Implement fluid typography with clamp() function
    • Create adaptive layouts with CSS Grid and Flexbox
    • Design components that work across all screen sizes

    UI Component Design

    Button Design

    • Primary Actions: High contrast, clear call-to-action
    • Secondary Actions: Subtle styling, less emphasis
    • Danger Actions: Red color scheme, clear warnings
    • Disabled States: Clear visual feedback, reduced opacity
    • Loading States: Progress indicators, disabled during action

    Form Design

    • Input Fields: Clear labels, helpful placeholders, validation states
    • Error Handling: Inline error messages, clear error indicators
    • Success States: Confirmation messages, positive feedback
    • Accessibility: Proper labels, ARIA attributes, keyboard navigation

    Navigation Design

    • Consistent Placement: Same location across all pages
    • Clear Labels: Descriptive, concise navigation labels
    • Visual States: Active, hover, and visited states
    • Breadcrumb Navigation: For hierarchical content

    Card & Container Design

    • Consistent Spacing: Uniform padding and margins
    • Visual Separation: Borders, shadows, or background colors
    • Content Hierarchy: Clear title, subtitle, body structure
    • Interactive Elements: Hover states and transitions

    Modern Design Systems

    Design Tokens

    /* Color Tokens */
    --color-primary: #3b82f6;
    --color-secondary: #64748b;
    --color-success: #10b981;
    --color-warning: #f59e0b;
    --color-danger: #ef4444;
    --color-background: #ffffff;
    --color-surface: #f8fafc;
    --color-text: #1e293b;
    --color-text-muted: #64748b;
    
    /* Spacing Tokens */
    --space-xs: 4px;
    --space-sm: 8px;
    --space-md: 16px;
    --space-lg: 24px;
    --space-xl: 32px;
    --space-2xl: 48px;
    
    /* Typography Tokens */
    --font-size-xs: 12px;
    --font-size-sm: 14px;
    --font-size-base: 16px;
    --font-size-lg: 18px;
    --font-size-xl: 20px;
    --font-size-2xl: 24px;
    --font-size-3xl: 30px;
    
    /* Shadow Tokens */
    --shadow-sm: 0 1px 2px 0 rgb(0 0 0 / 0.05);
    --shadow-md: 0 4px 6px -1px rgb(0 0 0 / 0.1);
    --shadow-lg: 0 10px 15px -3px rgb(0 0 0 / 0.1);
    

    Component Library Structure

    • Base Components: Button, Input, Card, Modal
    • Layout Components: Grid, Container, Sidebar, Header
    • Navigation Components: Menu, Breadcrumb, Tabs, Pagination
    • Feedback Components: Alert, Toast, Spinner, Progress
    • Data Display: Table, List, Badge, Avatar

    Dashboard Design Best Practices

    Data Visualization

    • Chart Selection: Choose appropriate chart types for data
      • Line charts: Trends over time
      • Bar charts: Comparisons between categories
      • Pie charts: Parts of a whole (max 5-7 segments)
      • Scatter plots: Correlations and distributions
    • Color Usage: Use color consistently and meaningfully
    • Accessibility: Provide patterns and textures in addition to color
    • Interactivity: Tooltips, zoom, filter capabilities

    Layout Patterns

    • Header: Clear title, key metrics, primary actions
    • Sidebar: Navigation, filters, secondary information
    • Main Content: Primary data visualization and insights
    • Footer: Summary, export options, help links

    Real-time Updates

    • Smooth Transitions: Animate data changes smoothly
    • Loading States: Clear indicators during data updates
    • Error Handling: Graceful degradation when data unavailable
    • Performance: Optimize for frequent updates without lag

    Accessibility Guidelines

    WCAG 2.1 Compliance

    • Perceivable: Information must be presentable in ways users can perceive
    • Operable: Interface components must be operable
    • Understandable: Information and UI operation must be understandable
    • Robust: Content must be robust enough for various assistive technologies

    Keyboard Navigation

    • Tab Order: Logical tab order through interactive elements
    • Focus Indicators: Clear visible focus states
    • Shortcuts: Keyboard shortcuts for common actions
    • Skip Links: Allow skipping to main content

    Screen Reader Support

    • Semantic HTML: Use proper HTML5 semantic elements
    • ARIA Labels: Descriptive labels for complex components
    • Alternative Text: Meaningful alt text for images
    • Announcements: Dynamic content changes announced

    Mobile App Design

    Touch Interactions

    • Touch Targets: Minimum 44px for comfortable tapping
    • Gesture Support: Swipe, pinch, long press interactions
    • Haptic Feedback: Vibration for important actions
    • Thumb-Friendly Design: Place primary actions in easy reach zones

    Platform Guidelines

    • iOS: Human Interface Guidelines compliance
    • Android: Material Design principles
    • Cross-Platform: Consistent experience while respecting platform conventions

    Performance Considerations

    • Optimized Assets: Compressed images, efficient code
    • Offline Support: Critical functionality available offline
    • Battery Optimization: Minimize battery drain
    • Network Awareness: Adapt to connection quality

    CSS Framework Integration

    Tailwind CSS Strategy

    • Utility-First: Rapid development with utility classes
    • Component Abstraction: Create reusable component classes
    • Design System: Consistent design tokens and variants
    • Responsive Design: Mobile-first responsive utilities

    Modern CSS Features

    • CSS Grid: Complex layouts with fewer elements
    • Flexbox: Flexible box layouts for components
    • Custom Properties: CSS variables for theming
    • Container Queries: Component-based responsive design

    Animation & Micro-interactions

    Motion Principles

    • Purposeful Animation: Every animation should have a purpose
    • Natural Movement: Follow physical laws and expectations
    • Performance: Use transform and opacity for smooth 60fps
    • Accessibility: Respect prefers-reduced-motion settings

    Common Animations

    • Page Transitions: Smooth navigation between views
    • Loading States: Engaging waiting experiences
    • Hover Effects: Subtle feedback for interactive elements
    • State Changes: Clear feedback for status updates

    Implementation Guidelines

    File Structure

    src/
    ├── components/          # Reusable UI components
    ├── layouts/            # Layout templates
    ├── styles/             # Global styles and utilities
    ├── assets/             # Images, icons, fonts
    ├── utils/              # Helper functions
    └── types/              # TypeScript definitions
    

    Naming Conventions

    • BEM Methodology: Block__Element--Modifier
    • Consistent Prefixes: Component-specific prefixes
    • Semantic Names: Descriptive, purpose-driven names
    • File Organization: Logical grouping and structure

    Testing Strategy

    • Visual Regression: Catch unintended design changes
    • Accessibility Testing: Automated and manual testing
    • Cross-Browser Testing: Ensure consistency
    • Performance Testing: Load times and animation performance

    Common Design Patterns

    Modal Windows

    • Overlay: Semi-transparent background
    • Focus Management: Trap focus within modal
    • Close Options: X button, overlay click, ESC key
    • Accessibility: Proper ARIA attributes

    Dropdown Menus

    • Trigger: Clear button or link to open menu
    • Positioning: Proper placement relative to trigger
    • Keyboard Navigation: Arrow keys, Enter, Escape
    • Outside Click: Close when clicking outside

    Form Validation

    • Real-time Validation: Immediate feedback on input
    • Error Messaging: Clear, actionable error messages
    • Success States: Positive confirmation of valid input
    • Accessibility: Associate errors with form controls

    Design Review Checklist

    Visual Design

    • Consistent color usage throughout interface
    • Proper typography hierarchy and readability
    • Adequate spacing and visual rhythm
    • Appropriate contrast ratios for accessibility
    • Consistent icon style and usage

    User Experience

    • Clear navigation and information architecture
    • Intuitive interaction patterns
    • Proper feedback for user actions
    • Error prevention and recovery
    • Responsive design across devices

    Accessibility

    • Keyboard navigation support
    • Screen reader compatibility
    • Sufficient color contrast
    • Alternative text for images
    • ARIA labels for complex components

    Performance

    • Optimized images and assets
    • Efficient CSS and JavaScript
    • Smooth animations and transitions
    • Fast loading times
    • Minimal layout shifts

    Tools and Resources

    Design Tools

    • Figma: Collaborative interface design
    • Sketch: Mac-only design tool
    • Adobe XD: Adobe's design platform
    • Framer: Interactive design and prototyping

    Development Tools

    • Chrome DevTools: Device simulation and debugging
    • Lighthouse: Performance and accessibility auditing
    • Axe: Accessibility testing extension
    • Color Contrast Analyzer: Contrast ratio validation

    Inspiration Resources

    • Dribbble: UI/UX design inspiration
    • Behance: Design portfolio platform
    • Awwwards: Website awards and inspiration
    • Mobbin: Mobile app design patterns

    When to Apply

    Use these design principles when:

    • Creating new GUI applications (web, desktop, mobile)
    • Redesigning existing interfaces
    • Building dashboards and data visualization tools
    • Developing interactive components and widgets
    • Implementing responsive design
    • Ensuring accessibility compliance
    • Improving user experience and usability
    • Establishing design systems and component libraries

    These principles ensure professional, accessible, and user-friendly interfaces that work across all platforms and devices.

    Recommended Servers
    tldraw
    tldraw
    InstantDB
    InstantDB
    Miro
    Miro
    Repository
    bejranonda/llm-autonomous-agent-plugin-for-claude
    Files