Best practices

Guidelines for creating high-quality, maintainable BetterDiscord themes

Follow these best practices to create themes that are performant, maintainable, and user-friendly.

Performance

Minimize CSS selectors

Use efficient selectors to reduce rendering overhead:

/* ❌ Bad - overly specific */
html body div.theme-dark div[class*="app_"] div[class*="container_"] div[class*="message_"] {
  background: red;
}

/* ✅ Good - concise and efficient */
[class*="message_"] {
  background: red;
}

Avoid universal selectors

/* ❌ Bad - affects everything */
* {
  border-radius: 10px;
}

/* ✅ Good - target specific elements */
[class*="container_"],
[class*="wrapper_"],
[class*="card_"] {
  border-radius: 10px;
}

Use CSS variables for repeated values

/* ❌ Bad - repeated values */
.element1 { background: #7289da; }
.element2 { border-color: #7289da; }
.element3 { color: #7289da; }

/* ✅ Good - reusable variable */
:root {
  --accent-color: #7289da;
}

.element1 { background: var(--accent-color); }
.element2 { border-color: var(--accent-color); }
.element3 { color: var(--accent-color); }

Optimize animations

Use transform and opacity for smooth animations:

/* ❌ Bad - causes layout recalculation */
[class*="message_"] {
  transition: width 0.3s, height 0.3s, margin 0.3s;
}

/* ✅ Good - GPU-accelerated */
[class*="message_"] {
  transition: transform 0.3s, opacity 0.3s;
}

[class*="message_"]:hover {
  transform: scale(1.02);
}

Maintainability

Organize your code

Use comments to create clear sections:

/**
 * @name Organized Theme
 * @author YourName
 * @version 1.0.0
 * @description A well-organized theme
 */

/* ==================== Variables ==================== */
:root {
  --primary-color: #7289da;
  --secondary-color: #5865f2;
}

/* ==================== Layout ==================== */
/* Sidebar */
[class*="sidebar_"] {
  background: var(--background-secondary);
}

/* Main content */
[class*="content_"] {
  background: var(--background-primary);
}

/* ==================== Components ==================== */
/* Messages */
[class*="message_"] {
  /* styles */
}

/* Buttons */
[class*="button_"] {
  /* styles */
}

/* ==================== Utilities ==================== */
/* Scrollbars */
::-webkit-scrollbar {
  /* styles */
}

Use consistent naming

/* ✅ Good - consistent variable naming */
:root {
  /* Colors */
  --accent-primary: #7289da;
  --accent-secondary: #5865f2;
  --accent-tertiary: #3ba55c;
  
  /* Spacing */
  --spacing-xs: 4px;
  --spacing-sm: 8px;
  --spacing-md: 16px;
  --spacing-lg: 24px;
  
  /* Borders */
  --border-radius-sm: 4px;
  --border-radius-md: 8px;
  --border-radius-lg: 12px;
}

Document complex code

/* Target the message list container for custom scrollbar styling
   This affects all message scrolling areas in channels */
[class*="messagesWrapper_"] [class*="scroller_"] {
  scrollbar-width: thin;
  scrollbar-color: var(--scrollbar-thin-thumb) var(--scrollbar-thin-track);
}

/* Fix for overlapping elements in compact mode
   Applies additional padding when compact message density is enabled */
[class*="compact_"] [class*="message_"] {
  padding-top: 2px;
  padding-bottom: 2px;
}

Compatibility

Test both themes

Always test your theme in both light and dark modes:

/* Style both themes appropriately */
.theme-dark {
  --custom-bg: #1a1a1a;
  --custom-text: #ffffff;
}

.theme-light {
  --custom-bg: #f5f5f5;
  --custom-text: #000000;
}

[class*="container_"] {
  background: var(--custom-bg);
  color: var(--custom-text);
}

Use fallback values

/* ✅ Good - fallback for unsupported variables */
.element {
  background: var(--custom-variable, #7289da);
  font-family: var(--custom-font, 'Arial', sans-serif);
}

Avoid breaking core functionality

/* ❌ Bad - hides important elements */
[class*="toolbar_"] {
  display: none !important;
}

/* ✅ Good - style without hiding */
[class*="toolbar_"] {
  opacity: 0.7;
  transition: opacity 0.2s;
}

[class*="toolbar_"]:hover {
  opacity: 1;
}

User experience

Maintain readability

Ensure text is always readable:

/* ❌ Bad - poor contrast */
.theme-dark {
  --text-default: #333333;
  --background-primary: #2f3136;
}

/* ✅ Good - WCAG compliant contrast */
.theme-dark {
  --text-default: #dcddde;
  --background-primary: #2f3136;
}

Provide visual feedback

Elements should respond to user interaction:

/* Interactive elements should have hover states */
[class*="button_"] {
  background: var(--brand-experiment);
  transition: all 0.17s ease;
}

[class*="button_"]:hover {
  background: var(--brand-experiment-560);
  transform: translateY(-1px);
  box-shadow: 0 4px 8px rgba(0, 0, 0, 0.2);
}

[class*="button_"]:active {
  transform: translateY(0);
  box-shadow: none;
}

Respect user preferences

/* Respect reduced motion preference */
@media (prefers-reduced-motion: reduce) {
  *,
  *::before,
  *::after {
    animation-duration: 0.01ms !important;
    animation-iteration-count: 1 !important;
    transition-duration: 0.01ms !important;
  }
}

/* Respect color scheme preference */
@media (prefers-color-scheme: dark) {
  :root {
    --custom-text: #ffffff;
  }
}

@media (prefers-color-scheme: light) {
  :root {
    --custom-text: #000000;
  }
}

Code quality

Use !important sparingly

/* ❌ Bad - overusing !important */
.element {
  color: red !important;
  background: blue !important;
  font-size: 14px !important;
}

/* ✅ Good - only when absolutely necessary */
.element {
  color: red;
  background: blue;
  font-size: 14px;
}

/* Only use !important to override inline styles or ensure critical overrides */
[class*="message_"][style] {
  background: transparent !important;
}

Avoid redundant code

/* ❌ Bad - repetitive */
.element1 {
  background: #7289da;
  border-radius: 8px;
  padding: 16px;
}

.element2 {
  background: #7289da;
  border-radius: 8px;
  padding: 16px;
}

/* ✅ Good - grouped selectors */
.element1,
.element2 {
  background: #7289da;
  border-radius: 8px;
  padding: 16px;
}

Validate your CSS

Use proper CSS syntax:

/* ❌ Bad - invalid syntax */
.element {
  background: ;
  color: red
  font-size: 14px;
}

/* ✅ Good - valid syntax */
.element {
  background: transparent;
  color: red;
  font-size: 14px;
}

Distribution

Complete metadata

Provide comprehensive theme information:

/**
 * @name Complete Theme Name
 * @author Your Name
 * @version 1.0.0
 * @description A detailed description of what your theme does and its unique features
 * @source https://github.com/yourusername/your-theme
 * @website https://yourwebsite.com/theme-documentation
 * @invite discordserver
 * @donate https://ko-fi.com/yourusername
 * @authorId 123456789012345678
 * @authorLink https://yourwebsite.com
 */

Semantic versioning

Follow semantic versioning (MAJOR.MINOR.PATCH):

• MAJOR - Breaking changes or complete redesign (1.0.0 → 2.0.0)
• MINOR - New features, non-breaking changes (1.0.0 → 1.1.0)
• PATCH - Bug fixes and small improvements (1.0.0 → 1.0.1)

Provide documentation

Create a README or documentation page that includes:

• Theme preview screenshots
• Installation instructions
• Customization guide
• Known issues
• Changelog
• Support information

License your work

Include a license in your repository:

/**
 * @name Licensed Theme
 * @author Your Name
 * @version 1.0.0
 * @description Theme with proper licensing
 * @source https://github.com/yourusername/your-theme
 * @license MIT
 */

/*
 * MIT License
 * 
 * Copyright (c) 2026 Your Name
 * 
 * Permission is hereby granted, free of charge, to any person obtaining a copy
 * of this software and associated documentation files (the "Software"), to deal
 * in the Software without restriction...
 */

Testing checklist

Before releasing your theme, verify:

• Theme loads without errors
• All metadata fields are complete
• Works in both light and dark mode
• Text is readable everywhere
• No broken layouts
• Buttons and interactive elements work
• Modals and popups display correctly
• Settings panels are accessible
• Scrollbars are styled appropriately
• Animations are smooth
• No console errors
• Compatible with popular plugins
• Tested on multiple servers
• Documentation is complete

Resources

Getting started

Create your first BetterDiscord theme

Styling guide

Learn Discord’s CSS structure

Theme structure

Understand theme file organization

Custom CSS

Test CSS snippets quickly