PayloadCMS Admin Theme: Spacing & Branding (Phase 1)

Overview

This article outlines the first phase of implementing basic theming for the PayloadCMS admin panel. Our primary focus is to enhance the user experience through improved spacing, larger click targets, and the subtle integration of We Meditate branding. This is a conservative, iterative approach to customizing the admin panel, ensuring stability and maintainability.

Goals

• Improve visual comfort and spaciousness throughout the admin interface.
• Increase usability with larger click targets for buttons and dropdowns.
• Introduce We Meditate coral accent color for brand consistency.
• Ensure all changes work seamlessly in both light and dark modes.
• Use minimal code with maximum visual impact.
• Avoid dramatic changes that could break the UI.

Implementation Approach

CSS Variable Overrides Only

Rationale: PayloadCMS 3.0 offers comprehensive CSS custom properties specifically designed for theming. By limiting ourselves to CSS variable overrides, we achieve several key benefits:

• Minimize code complexity.
• Reduce maintenance burden.
• Ensure compatibility with future Payload updates.
• Avoid specificity conflicts.
• Maintain consistent behavior across the admin panel.

File Location: All modifications will reside in src/app/(payload)/custom.scss

Phase 1: Focused Changes

This initial phase concentrates on four key areas to deliver a polished and user-friendly admin experience.

1. Spacing & Comfort

In this section, we focus on enhancing the visual comfort and spaciousness of the admin interface by adjusting various spacing parameters. The goal is to reduce visual crowding and create a more relaxed user experience. We'll be working with list/table row spacing, form field spacing, overall page padding and margins, and line height for improved readability. Achieving the right balance in spacing is crucial for making the admin panel feel less cluttered and more inviting, ultimately boosting user satisfaction and productivity. Implementing these changes thoughtfully can significantly improve the overall aesthetic and functionality of the admin panel. The modifications we make in this area are designed to complement each other, creating a harmonious and visually appealing workspace. This is not just about aesthetics; it's about creating an environment where users can work efficiently and comfortably. A well-spaced interface reduces eye strain and makes it easier for users to focus on the task at hand. By addressing the density of information on the screen, we can provide a more pleasant and user-friendly experience. Remember, these adjustments are part of a larger strategy to enhance the overall usability and appeal of the admin panel, setting the stage for future improvements and customizations. By focusing on spacing and comfort in this initial phase, we are laying a strong foundation for a more intuitive and user-centric design. The goal is to create an environment where users can navigate and interact with the admin panel effortlessly, making their experience as smooth and efficient as possible.

Increase spacing in high-density areas to reduce visual crowding:

• List/table row spacing (vertical padding)
• Form field spacing (margins between fields)
• Overall page padding and margins
• Line height for improved readability

CSS Variables to Override:

:root {
  // Base spacing unit (default is typically 20px, we'll increase slightly)
  --gutter-h: 24px;
  
  // Base unit for consistent spacing (default ~20px)
  --base: 24px;
  
  // Increase base font size slightly for readability
  --base-body-size: 14px; // Up from 13px default
}

2. Click Target Improvements

In this phase, we are focusing on improving the usability of interactive elements within the admin panel by increasing the size of click targets. This is a crucial step in enhancing the overall user experience, particularly for those using touch devices or those who may have dexterity challenges. By making buttons, dropdown triggers, checkbox/radio button touch targets, and icon buttons larger, we reduce the likelihood of misclicks and make the interface more accessible and user-friendly. Larger click targets provide a more forgiving interaction experience, allowing users to engage with the admin panel more confidently and efficiently. This is not just about making things bigger; it's about making them easier to use. A well-designed interface takes into account the physical limitations and preferences of its users, and adjusting click target sizes is a simple yet effective way to achieve this. Furthermore, these improvements contribute to a more professional and polished feel, enhancing the perceived quality of the admin panel. This is part of a broader effort to make the admin panel more intuitive and enjoyable to use. By focusing on small details like click target sizes, we can make a significant impact on the overall user experience, creating a more seamless and user-centric environment. These changes are designed to work in harmony with other improvements, such as spacing adjustments and color enhancements, to create a cohesive and user-friendly interface. The goal is to make the admin panel feel responsive and easy to interact with, regardless of the device or input method being used. This attention to detail is essential for creating a positive and productive user experience, ultimately contributing to the success of the overall project. We want our users to feel comfortable and confident while navigating and interacting with the admin panel, and these click target improvements are a crucial step in achieving that goal.

Increase the size of interactive elements for better usability:

• Button minimum height
• Dropdown trigger areas
• Checkbox/radio button touch targets
• Icon button sizes

CSS Variables to Override:

:root {
  // Border radius (also helps make click areas feel larger)
  --style-radius-s: 6px;  // Up from 3px
  --style-radius-m: 8px;  // Up from 5px
  --style-radius-l: 12px; // Up from 8px
}

Additional CSS (minimal direct styling if needed):

@layer payload {
  // Increase button padding for larger click targets
  button, .btn {
    padding: 0.625rem 1rem; // ~10px 16px
    min-height: 38px;
  }
  
  // Larger dropdown triggers
  select, .dropdown-trigger {
    min-height: 38px;
    padding: 0.5rem 0.75rem;
  }
}

3. We Meditate Branding (Subtle Coral Accents)

Introducing the We Meditate branding through subtle coral accents will provide a consistent and recognizable identity within the PayloadCMS admin panel. By incorporating coral as the primary action color, we aim to create a visually appealing and cohesive experience that aligns with the overall brand aesthetic. This includes using coral for primary buttons, active states, focus indicators, and success states, replacing the default green with our brand's signature hue. Subtle branding is key to ensuring that the admin panel feels both professional and personalized without being overwhelming or distracting. The goal is to create a harmonious balance between the functionality of the admin panel and the visual representation of the We Meditate brand. By carefully selecting where and how to apply the coral accents, we can create a memorable and engaging experience for users. This not only enhances the visual appeal of the admin panel but also reinforces brand recognition and loyalty. Furthermore, these branding elements will be implemented in a way that seamlessly integrates with both light and dark modes, ensuring a consistent and visually pleasing experience regardless of the user's preferred theme. This attention to detail is crucial for maintaining a professional and polished appearance across all aspects of the admin panel. By thoughtfully incorporating the We Meditate branding, we can create a unique and memorable experience that sets our admin panel apart from the rest.

Introduce coral accent color for primary actions and interactive elements:

• Primary buttons
• Active states
• Focus indicators
• Success states (using coral instead of default green)

CSS Variables to Override:

:root {
  // We Meditate coral branding
  --coral: #F07855;
  --coral-light: #FF9477;
  --coral-dark: #D86545;
  
  // Override theme success color with coral
  --theme-success-50: #FFF5F2;
  --theme-success-100: #FFE8E1;
  --theme-success-400: #FF9477;
  --theme-success-500: #F07855;
  --theme-success-600: #D86545;
}

// Dark mode overrides
[data-theme='dark'] {
  // Adjust coral for dark mode visibility
  --theme-success-400: #FF9477;
  --theme-success-500: #FF9477; // Lighter in dark mode
}

4. Subtle Polish

To enhance the overall user experience, we will incorporate subtle polish to the admin panel, focusing on minor improvements that contribute to a modern and comfortable feel. This includes softening shadows, smoothing transitions, and enhancing contrast where needed. These enhancements are designed to be subtle yet impactful, creating a more refined and visually appealing environment. By carefully tweaking these elements, we can elevate the overall aesthetic of the admin panel without introducing drastic changes. Smoother transitions make the interface feel more responsive and fluid, while softer shadows add depth and dimension to the elements on the screen. Additionally, improving contrast ensures that text and interactive elements are easily readable and accessible. These changes are part of a larger effort to create a more polished and user-friendly experience, making the admin panel feel more intuitive and enjoyable to use. The goal is to create an environment where users can navigate and interact with the admin panel effortlessly, without being distracted by jarring transitions or difficult-to-read text. By focusing on these subtle details, we can make a significant impact on the overall perceived quality of the admin panel. These refinements are designed to work in harmony with other improvements, such as spacing adjustments and color enhancements, to create a cohesive and visually pleasing interface. We want our users to feel comfortable and confident while navigating and interacting with the admin panel, and these subtle polish improvements are a crucial step in achieving that goal. By paying attention to these small details, we demonstrate our commitment to creating a high-quality and user-centric experience.

Minor improvements for modern, comfortable feel:

• Softer shadows
• Smoother transitions
• Better contrast (if needed)

CSS Variables to Override:

:root {
  // Smooth transitions
  --nav-trans-time: 200ms; // Slightly faster
}

Implementation Steps

1. Create CSS Variable Overrides
   • Add spacing and comfort variables to custom.scss
   • Add We Meditate coral color variables
   • Add dark mode overrides
2. Test Initial Changes
   • Start dev server and review changes in light mode
   • Switch to dark mode and verify
   • Iterate on values if needed
3. Add Minimal Direct Styling (if needed)
   • Only add direct CSS if variables aren't sufficient
   • Use @layer payload for proper specificity
   • Keep it minimal and focused
4. Documentation
   • Update CLAUDE.md with theming approach
   • Document which variables were changed and why
   • Note any direct CSS additions

Success Criteria

• [ ] Admin panel feels more spacious and comfortable
• [ ] Buttons and dropdowns are easier to click/tap
• [ ] We Meditate coral accent is visible but not overwhelming
• [ ] All changes work perfectly in both light and dark modes
• [ ] No UI breaks or visual regressions
• [ ] Code is clean, minimal, and uses CSS variables primarily
• [ ] Changes are documented in CLAUDE.md

Phase 2 Considerations (Future)

If Phase 1 isn't sufficient, consider:

• Further spacing adjustments in specific problem areas
• Typography improvements (font weights, sizes)
• More comprehensive color system overrides
• Custom component styling for high-traffic areas
• Table/list view density options

Constraints & Guidelines

Must Follow

• ✅ CSS Variables First: Always try CSS variable overrides before direct CSS
• ✅ Dark Mode: Test and support dark mode equally
• ✅ Minimal Code: Focus on high-impact, low-code changes
• ✅ No Breaking Changes: UI must remain functional
• ✅ Use @layer payload: If direct CSS is needed, use proper layer

Must Ask First

• ❌ Direct CSS Styling: Confirm with maintainer before adding direct CSS rules
• ❌ Dramatic Changes: No major UI overhauls without approval
• ❌ Component Overrides: Don't replace Payload components in Phase 1

Related Files

• src/app/(payload)/custom.scss - Main theming file (currently empty)
• src/payload.config.ts - Admin configuration
• src/app/(frontend)/styles.css - Frontend coral color definitions (for reference)
• src/components/branding/ - We Meditate logo/icon components

Resources

• PayloadCMS: Customizing CSS
• PayloadCMS: How to Customize Look and Feel
• PayloadCMS GitHub: CSS Variables Source