Skip to main content
Version: 1.4

Contributing to the Registry

██████╗ ███████╗ ██████╗ ██╗███████╗████████╗██████╗ ██╗   ██╗
██╔══██╗██╔════╝██╔════╝ ██║██╔════╝╚══██╔══╝██╔══██╗╚██╗ ██╔╝
██████╔╝█████╗  ██║  ███╗██║███████╗   ██║   ██████╔╝ ╚████╔╝
██╔══██╗██╔══╝  ██║   ██║██║╚════██║   ██║   ██╔══██╗  ╚██╔╝
██║  ██║███████╗╚██████╔╝██║███████║   ██║   ██║  ██║   ██║
╚═╝  ╚═╝╚══════╝ ╚═════╝ ╚═╝╚══════╝   ╚═╝   ╚═╝  ╚═╝   ╚═╝

Thank you for contributing to the DankMaterialShell registry! This guide covers how to submit plugins and themes to the dms-plugin-registry repository.

Contributing a Plugin​

How to Add Your Plugin​

  1. Fork the repository

  2. Create a new JSON file in the plugins/ directory:

    plugins/{github-username}-{plugin-name}.json

  3. Fill in your plugin information using this schema:

{
    "id": "pluginId",
    "name": "PluginName",
    "capabilities": ["dankbar-widget"],
    "category": "monitoring",
    "repo": "https://github.com/yourusername/your-plugin-repo",
    "path": "optional/path/in/monorepo",
    "author": "Your Name",
    "description": "Brief description of what your plugin does",
    "dependencies": ["dependency1", "dependency2"],
    "compositors": ["niri", "hyprland"],
    "distro": ["any"],
    "screenshot": "https://url/to/screenshot.png"
}

Plugin Field Descriptions​

FieldRequiredDescriptionidYesUnique identifier in camelCase (e.g., worldClock). Must match your plugin.jsonnameYesDisplay name. Must match your plugin.jsoncapabilitiesYesArray like ["dankbar-widget"]categoryYesOne of: monitoring, utilities, appearance, system, etc.repoYesFull GitHub URL to your plugin repositorypathNoSubdirectory path if plugin is in a monorepoauthorYesYour name or GitHub usernamedescriptionYesClear, concise description of the plugin's purposedependenciesYesArray of dependencies, use [] if nonecompositorsYesSupported compositors: ["niri", "hyprland"], ["any"]distroYesSupported distributions: ["any"], ["fedora"], ["arch"], etc.screenshotNoDirect URL to a screenshot image

:::warning Important The id and name fields must exactly match the corresponding fields in your plugin repository's plugin.json file. :::

  1. Validate your plugin locally:
python3 .github/generate.py --validate
python3 .github/validate_links.py
  1. Submit a Pull Request

Contributing a Theme​

How to Add Your Theme​

  1. Fork the repository

  2. Create a new folder in the themes/ directory:

    themes/{theme-id}/theme.json

  3. Create your theme.json with this schema:

{
  "id": "themeId",
  "name": "Theme Name",
  "version": "1.0.0",
  "author": "Your Name",
  "description": "Brief description of your theme",
  "dark": {
    "primary": "#7aa2f7",
    "primaryText": "#16161e",
    "primaryContainer": "#7dcfff",
    "secondary": "#bb9af7",
    "surface": "#1a1b26",
    "surfaceText": "#73daca",
    "surfaceVariant": "#2f3549",
    "surfaceVariantText": "#cbccd1",
    "surfaceTint": "#7aa2f7",
    "background": "#16161e",
    "backgroundText": "#d5d6db",
    "outline": "#787c99",
    "surfaceContainer": "#2f3549",
    "surfaceContainerHigh": "#444b6a",
    "error": "#f7768e",
    "warning": "#ff9e64",
    "info": "#7dcfff"
  },
  "light": {
    "primary": "#2e7de9",
    "primaryText": "#d0d5e3",
    "primaryContainer": "#007197",
    "secondary": "#9854f1",
    "surface": "#e1e2e7",
    "surfaceText": "#387068",
    "surfaceVariant": "#c4c8da",
    "surfaceVariantText": "#1a1b26",
    "surfaceTint": "#2e7de9",
    "background": "#cbccd1",
    "backgroundText": "#1a1b26",
    "outline": "#4c505e",
    "surfaceContainer": "#dfe0e5",
    "surfaceContainerHigh": "#9699a3",
    "error": "#f52a65",
    "warning": "#b15c00",
    "info": "#007197"
  }
}

Theme Metadata Fields​

FieldRequiredDescriptionidYesUnique identifier in camelCase (e.g., tokyoNight, gruvboxDark)nameYesDisplay name of your themeversionYesSemver version (e.g., 1.0.0)authorYesYour name or usernamedescriptionYesBrief description of the theme

Theme Color Fields​

Both dark and light objects require these color properties:

FieldDescriptionprimaryPrimary accent colorprimaryTextText color on primary backgroundsprimaryContainerContainer using primary colorsecondarySecondary accent colorsurfaceMain surface/card backgroundsurfaceTextText on surfacessurfaceVariantAlternative surface colorsurfaceVariantTextText on variant surfacessurfaceTintTint overlay colorbackgroundApp background colorbackgroundTextText on backgroundoutlineBorder/divider colorsurfaceContainerContainer backgroundsurfaceContainerHighElevated container backgrounderrorError state colorwarningWarning state colorinfoInfo state color

For more details on how these colors are used, see Custom Themes.

  1. Validate your theme locally:
python3 .github/validate_themes.py
python3 .github/generate.py --validate
  1. Submit a Pull Request

Guidelines​

For Plugins​

For Themes​

Questions?​

If you have questions about the contribution process, please open an issue in the registry repository.