Developer & Contributor Guide

Everything you need to submit a theme, understand the project structure, and work with the tooling.

Quick Start

Follow these steps in order. Each one links to the relevant detail section if you need more.

Fork and clone the repo — fork on GitHub, then git clone https://github.com/YOUR_USERNAME/discord-themes.git
Create your contributor folder — must be named Your Name Themes (plural, space before Themes). See Folder Structure.
Create a theme subfolder and CSS file — CSS goes inside a named subfolder, never directly in your contributor folder. Use .\themecmd.cmd new-theme to scaffold it, or create it manually with the required metadata header.
Host your images here — if your theme uses background images, they must be uploaded to this repo. External hosts are blocked. See Image Hosting.
Optionally add AUTHOR.md — a short profile in your contributor folder root. See AUTHOR.md — Your Profile Page.
Open a Pull Request against main — the bot validates automatically. If anything fails it posts a comment explaining the fix. Fill out the PR template to introduce yourself. The repo owner will see it and review it — no issue needed.

Requirements

A GitHub account
Basic knowledge of CSS
Discord with BetterDiscord or Vencord installed for testing
Git installed locally (recommended)

Your first PR will be reviewed by the repo owner — just open it and fill out the PR template. Once you're registered, future PRs auto-merge as long as validation passes.

PR template

Every PR includes a template with a checklist and an optional introduction section for first-time contributors. Fill out the intro section so the repo owner knows who you are and what you're submitting — it only takes a minute and makes the review faster.

Content Policy

All themes must follow these rules. Violations can result in theme removal and contributor access being revoked.

NSFW content

Themes containing NSFW content (nudity, sexually explicit imagery, graphic violence, or other mature content) must be clearly labeled in the theme's @name and @description fields:

/**
 * @name My Theme [NSFW]
 * @description A dark theme with mature artwork. Contains NSFW imagery.
 */

Unlabeled NSFW content is grounds for immediate removal and termination from the repo. If you are unsure whether your content qualifies as NSFW, label it anyway — it is always better to over-label than to be removed.

General rules

No malicious CSS (keyloggers, crash-on-load exploits, or anything intentionally harmful)
No spam, placeholder themes, or clearly unfinished work submitted as complete
No impersonating other contributors or theme authors
Keep your AUTHOR.md relevant to Discord theming — no unrelated promotions

The repo owner reserves the right to remove any content and revoke contributor access at any time.

Folder Structure

Each contributor owns exactly one top-level folder. All your themes and your optional profile file live inside it.

The one-folder-per-contributor rule makes ownership unambiguous — every file in the repo has a clear owner and the automation knows exactly who is allowed to touch what. The X Themes naming convention keeps the repo browsable and is how the README generator identifies contributor folders. CSS lives inside a named theme subfolder rather than at your folder root so you can have multiple themes without files colliding and so each theme has its own isolated space for assets.

discord-themes/
├── Silver Themes/              ← contributor folder (Your Name Themes)
│   ├── AUTHOR.md               ← optional profile file (must be this exact name)
│   ├── assists/                ← optional shared CSS (importable by your own themes only)
│   │   └── clear-bg.css        ← no metadata header required
│   └── My Theme/               ← theme subfolder (one per theme)
│       ├── my-theme.css        ← theme CSS (required)
│       ├── preview.png         ← preview image (optional)
│       └── preview.gif         ← animated preview (optional)
└── Your Name Themes/
    ├── AUTHOR.md
    └── Cool Theme/
        └── cool-theme.css

Rules at a glance:

File	Where it goes	Notes
`.css`	Inside a theme subfolder	Never directly in your contributor folder root
`.css` in `assists/`	`Your Name Themes/assists/`	No metadata header required; only importable by your own themes
`AUTHOR.md`	Directly in your contributor folder root	Must be this exact name, one per folder
`.png` `.gif` `.jpg` `.webp` `.svg`	Inside a theme subfolder or `assists/`	Not at your contributor folder root
Any other type	Not allowed	Contact the repo owner if you need an exception

Do not edit README.md, theme-authors.json, scripts/, or .github/ — these are managed automatically and your changes will be overwritten or blocked.

Theme File Format

Every theme must be a .css file with a metadata header block at the top. All four fields are required.

/**
 * @name Theme Name
 * @author Your Name
 * @version 1.0.0
 * @description A short description of your theme.
 */

/* your CSS below */

Field	Required	Description
`@name`	Yes	Display name shown in the README and Discord
`@author`	Yes	Your name — should match your folder's entry in `theme-authors.json`
`@version`	Yes	Semantic version, start at `1.0.0`
`@description`	Yes	One or two sentences describing the theme

Missing any of these will cause the doctor check to warn.

Raw install URL

Once your theme is merged, users install it via the raw GitHub URL — no downloading required:

https://raw.githubusercontent.com/Silverfox0338/discord-themes/main/Your%20Name%20Themes/Your%20Theme/your-theme.css

Get the exact URL for any file with:

.\themecmd.cmd png-url "Your Name Themes\Your Theme\your-theme.css"

Preview images

Add a .png, .gif, or .jpg inside your theme subfolder to include a preview in the README. Name it anything — the generator picks it up automatically.

AUTHOR.md — Your Profile Page

You can include an AUTHOR.md file directly in your contributor folder root. This is optional but encouraged — it shows up as a Profile link next to your name in the README.

The H1 heading is your display name

The first # heading in your AUTHOR.md is automatically used as your display name in theme-authors.json and the README. This is how the repo knows what name to show next to your themes.

# Silverfox0338

Rules for the H1 heading:

It is required — the tooling pulls it as your display name in theme-authors.json and the README; without it there is nothing to register you under
It must be 24 characters or fewer — keeps the README table readable and display names consistently short
It must be unique across the entire repo — the comparison is case-insensitive to prevent identity spoofing; if 8Bit is registered, 8BIT and 8bit are also taken
It should be your author name or handle, not a sentence or description

If your AUTHOR.md has no H1 heading, your heading is too long, or the name is already taken, your PR will be blocked with an explanation.

What to include

A short bio or introduction
Links to your other Discord themes or related work
Links to your personal site, portfolio, or social profiles (Discord theme related)
Any shoutouts

Template

# Your Name

Discord theme designer. Short bio here.

## My Themes
- [Theme Name](https://raw.githubusercontent.com/Silverfox0338/discord-themes/main/Your%20Name%20Themes/Theme%20Name/theme-name.css)

## Links
- [GitHub](https://github.com/yourusername)

Rules

The file must be named exactly AUTHOR.md — any other name will be flagged and blocked
It must not be empty
The H1 heading is required and must be 24 characters or fewer
Keep it relevant — no unrelated promotions or spam
It goes in your contributor folder root, not inside a theme subfolder

Image Hosting

All images referenced inside your CSS must be hosted in this GitHub repository. External image hosts are not allowed.

Host	Allowed
`raw.githubusercontent.com/Silverfox0338/discord-themes/…`	Yes
Imgur, Discord CDN, personal servers, or any other external host	No

External hosts like Imgur are blocked in parts of the EU (Germany and others), which means your theme's background would just be broken for those users. GitHub raw URLs work everywhere. It also protects against external hosts going down after your theme is merged.

How to host an image here:

Place the image file inside your theme subfolder — e.g. Your Name Themes/Cool Theme/bg.png

Get the raw URL:

.\themecmd.cmd png-url "Your Name Themes\Cool Theme\bg.png"

Use that URL in your CSS:

--background-image: url("https://raw.githubusercontent.com/Silverfox0338/discord-themes/main/Your%20Name%20Themes/Cool%20Theme/bg.png");

PRs containing external image URLs in CSS are automatically blocked and the offending URLs are reported in the PR comment. If you don't use any background images, you don't need to add any image files at all.

CSS Imports

You can use @import in your theme CSS, but only from approved sources. Everything else is automatically blocked in PR validation.

Allowed import sources

Source	Example
Google Fonts	`@import url("https://fonts.googleapis.com/css2?family=Roboto")`
ClearVision	`@import url("https://clearvision.github.io/ClearVision-v7/main.css")`
Your own contributor folder	`@import url("https://raw.githubusercontent.com/Silverfox0338/discord-themes/main/Your%20Name%20Themes/assists/file.css")`

Everything else — other contributors' CSS, third-party CDNs, external URLs — is blocked.

Cross-contributor imports are blocked

You cannot import from another contributor's folder. If 8Bit Themes tries to import a URL pointing into Korone Themes/, it is blocked — even if the URL is technically valid.

The `assists/` subfolder

If a theme depends on shared utility CSS — like a reusable transparent-background base — place it in an assists/ subfolder inside your contributor folder:

Your Name Themes/
├── assists/
│   └── clear-bg.css        ← no metadata header required
└── My Theme/
    └── my-theme.css

Then import it in your theme CSS:

@import url("https://raw.githubusercontent.com/Silverfox0338/discord-themes/main/Your%20Name%20Themes/assists/clear-bg.css");

Rules for assists/:

Allowed file types are the same as everywhere else: .css, .png, .gif, .jpg, .jpeg, .webp, .svg
CSS files in assists/ do not require a metadata header (@name, @author, @version, @description) — they are utility files, not themes
They are never listed in the README
Only your own themes may import from your assists/ folder — cross-contributor imports are blocked regardless of target folder

Auto-Merge Rules

Every pull request is validated automatically.

Every rule in the blocked table below protects one of three things: repo integrity (the README, registry, and config stay consistent and aren't corrupted by manual edits), contributor ownership (no one can touch, overwrite, or delete someone else's work), or theme reliability (themes install and render correctly for every user, everywhere).

What passes

Scenario	Result
Registered contributor adds/edits/deletes files in their own folder	Auto-merged
Registered contributor adds files to a new unregistered folder	Auto-merged, folder registered automatically
GitHub collaborator touches their own folder	Auto-merged

What gets blocked

Scenario	Reason
`README.md` modified	Auto-generated on every merge — manual edits are immediately overwritten
`theme-authors.json`, `scripts/`, `.github/` modified	Managed by the automation pipeline — manual edits cause conflicts or get overwritten on the next run
Editing another contributor's folder	Each contributor is responsible for their own work only — no one can modify, overwrite, or delete another person's themes
One GitHub user opening a PR for two different top-level folders	One folder per GitHub account keeps ownership traceable and prevents namespace sprawl
`.css` file directly in contributor folder root	Each theme needs its own subfolder so multiple themes can coexist and each has isolated space for its assets
`.md` file inside a theme subfolder	Markdown belongs at your contributor root — the only expected file there is your profile page
`.md` file not named `AUTHOR.md`	Strict naming so tooling can reliably find your profile file without guessing
Images or other files at contributor folder root	Files at the root level have no clear theme to belong to — everything needs to live inside a theme or assists subfolder
Folder name doesn't end with `Themes`	How the README generator identifies contributor folders — without this convention it cannot tell your folder from a random directory
Unsupported file type	Prevents executables, scripts, or unexpected content from being committed under the cover of a theme PR
External image URL in CSS	External hosts go down, get blocked in parts of Europe, and can change URLs — repo-hosted images are permanent and work everywhere
`@import` from another contributor's folder	Your theme would silently break if that contributor renames, moves, or deletes the file you're importing
`@import` from an unlisted external source	Unvetted external CSS can change at any time and is a potential injection vector
Not a registered contributor	First PR always requires a manual review — see What to Expect as a New Contributor

When a PR is blocked, a comment explains exactly what went wrong and how to fix it.

What to Expect as a New Contributor

Here is exactly what happens after you open your first PR, so you know what to expect at each stage.

Your first PR

After you open a PR, the bot validates it automatically within a few seconds. Two things can happen:

If validation fails: Your PR is blocked and a comment is posted explaining every issue and how to fix it. Push a new commit to your branch — the check re-runs automatically. You do not need to close and reopen the PR.

If validation passes: You will see a comment:

All checks passed — pending review The repo owner will review it shortly. Once you're registered and trusted, future PRs will auto-merge.

This is expected. Your first PR always requires a manual review. The repo owner has been notified. Just wait — no action needed on your end.

Once your PR is merged, you are registered as a contributor.

Your second PR

After your first PR is merged you are registered, but not yet marked as trusted. Your second PR goes through the same validation, and if it passes you will see:

All checks passed — pending trust approval The repo owner will review and mark you as trusted — after that, future PRs will auto-merge.

Again, just wait. The repo owner reviews and merges it, then marks you as trusted. This is the last time you will ever need to wait for a manual review.

All future PRs

Once you are trusted, every PR that passes validation is merged automatically — usually within seconds of opening it. You will never need to wait for a manual review again.

If a PR is blocked, the comment tells you what to fix. Push the fix and it re-runs.

themecmd Reference

themecmd.cmd is a Windows command-line tool for README generation and health checks. Run it from the repo root.

Note: From PowerShell, prefix commands with .\ — e.g. .\themecmd.cmd. From Command Prompt, the prefix is not needed.

Commands

Generate README (default):

.\themecmd.cmd
.\themecmd.cmd -NoAuthorPrompt
.\themecmd.cmd generatereadme -NoAuthorPrompt
.\themecmd.cmd generatereadme -OutputPath "README.md" -MetadataPath "theme-authors.json"

Run doctor (full repo):

.\themecmd.cmd doctor

Checks all theme folders for valid CSS metadata headers, AUTHOR.md naming, and theme-authors.json consistency. Reports PASS, WARN, or FAIL.

Run doctor (scoped to one folder):

.\themecmd.cmd doctor "Silver Themes"
.\themecmd.cmd doctor "8Bit Themes"

Runs the same checks but only for the specified contributor folder.

Scaffold a new theme (interactive):

.\themecmd.cmd new-theme

Prompts for name, author, version, description, and target folder — generates a complete starter template with color variables, background properties, and font settings.

Scaffold a new theme (non-interactive):

.\themecmd.cmd new-theme -Name "My Theme" -Author "YourName" -Folder "Your Name Themes"
.\themecmd.cmd new-theme -Name "My Theme" -Author "YourName" -Version "1.0.0" -Description "A cool theme" -Folder "Your Name Themes" -FileName "my-theme.css"

Any omitted parameters fall back to interactive prompts.

Note: The generated template includes url("https://i.imgur.com/YOUR_IMAGE.jpg") as a placeholder. You must replace this with a raw GitHub URL before submitting — external image URLs will be blocked in PR validation.

Get raw URL for a file:

.\themecmd.cmd png-url "Silver Themes\Legoshi\legoshi.png"

Returns the raw.githubusercontent.com URL. Works for any file — use it for CSS install URLs too.

Help:

.\themecmd.cmd help

Exit codes

Code	Meaning
`0`	Success
`1`	Failure or invalid command

Common Issues

Error: Path must be inside the repo root Use a path relative to the repo root, not an absolute path:

.\themecmd.cmd png-url "Silver Themes\Legoshi\legoshi.png"

Doctor reports WARN on my theme Your CSS header is missing one or more required fields (@name, @author, @version, @description). Add them and re-run.

Doctor reports WARN about AUTHOR.md Either your file isn't named exactly AUTHOR.md (rename it) or it exists but is empty (add some content).

My PR was blocked for a file structure issue See the Auto-Merge Rules table. Most common causes:

CSS placed directly in your contributor folder instead of a theme subfolder
A .md file named something other than AUTHOR.md
An image placed at your contributor folder root instead of inside a theme subfolder

My PR was blocked for editing README.md Remove README.md from your PR entirely — it regenerates automatically on merge.

My PR was blocked for touching another folder Each contributor owns exactly one folder. If you want to suggest a change to another theme, open an issue and tag the folder owner.

My PR was blocked for an external image URL Replace the external URL with a raw GitHub URL pointing to an image inside this repo. See Image Hosting.

My PR was blocked for a blocked @import URL Your CSS uses an @import pointing to a disallowed source. Only Google Fonts, ClearVision, and raw GitHub URLs within your own contributor folder are permitted. Move shared utility CSS into your assists/ subfolder and import from there — see CSS Imports.

I'm not a registered contributor and my PR is sitting there Expected — the repo owner will review it. No action needed on your end.

Home · Developer & Contributor Guide · Submit a Theme · Report an Issue · GitHub Repo

Developer & Contributor Guide

Developer & Contributor Guide

Table of Contents

Quick Start

Requirements

PR template

Content Policy

NSFW content

General rules

Folder Structure

Theme File Format

Raw install URL

Preview images

AUTHOR.md — Your Profile Page

The H1 heading is your display name

What to include

Template

Rules

Image Hosting

CSS Imports

Allowed import sources

Cross-contributor imports are blocked

The assists/ subfolder

Auto-Merge Rules

What passes

What gets blocked

What to Expect as a New Contributor

Your first PR

Your second PR

All future PRs

themecmd Reference

Commands

Exit codes

Common Issues

Uh oh!

discord-themes

Getting Started

Submitting a Theme

Rules & Automation

Tooling

Clone this wiki locally

The `assists/` subfolder