From 221680dbd13f7610dc95d39a4527ec39854330b6 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Aldin=20=C4=8Camd=C5=BEi=C4=87?= <acamdzic0@proton.me>
Date: Tue, 26 May 2026 18:38:08 +0200
Subject: [PATCH] fix(RoleManager): allow null in RoleColorsResolvable to clear
 gradient colors (#11536)

* fix(RoleManager): allow null in RoleColorsResolvable to clear gradient colors

* docs(RoleManager): document nullable secondary/tertiary role colors

* refactor: split RoleColorsResolvable for create vs edit

* style: apply prettier formatting

* refactor: deduplicate RoleColors interfaces via inheritance

Co-authored-by: Qjuh <76154676+Qjuh@users.noreply.github.com>

* refactor: move colors out of RoleData

---------

Co-authored-by: Qjuh <76154676+Qjuh@users.noreply.github.com>
Co-authored-by: kodiakhq[bot] <49736102+kodiakhq[bot]@users.noreply.github.com>
---
 packages/discord.js/src/managers/RoleManager.js | 12 ++++++++++++
 packages/discord.js/src/structures/Role.js      |  1 -
 packages/discord.js/typings/index.d.ts          | 13 ++++++++++---
 3 files changed, 22 insertions(+), 4 deletions(-)

diff --git a/packages/discord.js/src/managers/RoleManager.js b/packages/discord.js/src/managers/RoleManager.js
index 734d84fa6..823ef14d1 100644
--- a/packages/discord.js/src/managers/RoleManager.js
+++ b/packages/discord.js/src/managers/RoleManager.js
@@ -125,6 +125,17 @@ class RoleManager extends CachedManager {
    * These values are available as a constant: `Constants.HolographicStyle`
    */
 
+  /**
+   * @typedef {Object} RoleColorsEditResolvable
+   * @property {ColorResolvable} primaryColor The primary color of the role
+   * @property {?ColorResolvable} [secondaryColor] The secondary color of the role. Pass `null` to clear it.
+   * This will make the role a gradient between the other provided colors
+   * @property {?ColorResolvable} [tertiaryColor] The tertiary color of the role. Pass `null` to clear it.
+   * When sending `tertiaryColor` the API enforces the role color to be a holographic style
+   * with values of `primaryColor = 11127295`, `secondaryColor = 16759788`, and `tertiaryColor = 16761760`.
+   * These values are available as a constant: `Constants.HolographicStyle`
+   */
+
   /**
    * Options used to create a new role.
    * @typedef {Object} RoleCreateOptions
@@ -231,6 +242,7 @@ class RoleManager extends CachedManager {
   /**
    * Options for editing a role
    * @typedef {RoleData} RoleEditOptions
+   * @property {RoleColorsEditResolvable} [colors] The colors to set on the role
    * @property {string} [reason] The reason for editing this role
    */
 
diff --git a/packages/discord.js/src/structures/Role.js b/packages/discord.js/src/structures/Role.js
index c148324f6..c97e1226d 100644
--- a/packages/discord.js/src/structures/Role.js
+++ b/packages/discord.js/src/structures/Role.js
@@ -258,7 +258,6 @@ class Role extends Base {
    * @property {string} [name] The name of the role
    * @property {ColorResolvable} [color] The color of the role, either a hex string or a base 10 number
    * <warn>This property is deprecated. Use `colors` instead.</warn>
-   * @property {RoleColorsResolvable} [colors] The colors of the role
    * @property {boolean} [hoist] Whether or not the role should be hoisted
    * @property {number} [position] The position of the role
    * @property {PermissionResolvable} [permissions] The permissions of the role
diff --git a/packages/discord.js/typings/index.d.ts b/packages/discord.js/typings/index.d.ts
index bdc0fc9d5..d35a85044 100644
--- a/packages/discord.js/typings/index.d.ts
+++ b/packages/discord.js/typings/index.d.ts
@@ -3272,12 +3272,18 @@ export interface RoleColors {
   tertiaryColor: number | null;
 }
 
-export interface RoleColorsResolvable {
+export interface RoleColorsResolvable extends RoleColorsEditResolvable {
   primaryColor: ColorResolvable;
   secondaryColor?: ColorResolvable;
   tertiaryColor?: ColorResolvable;
 }
 
+export interface RoleColorsEditResolvable {
+  primaryColor: ColorResolvable;
+  secondaryColor?: ColorResolvable | null;
+  tertiaryColor?: ColorResolvable | null;
+}
+
 export class Role extends Base {
   private constructor(client: Client<true>, data: RawRoleData, guild: Guild);
   /** @deprecated Use {@link Role.colors} instead. */
@@ -6425,10 +6431,12 @@ export interface GuildScheduledEventInviteURLCreateOptions extends InviteCreateO
 }
 
 export interface RoleCreateOptions extends RoleData {
+  colors?: RoleColorsResolvable;
   reason?: string;
 }
 
 export interface RoleEditOptions extends RoleData {
+  colors?: RoleColorsEditResolvable;
   reason?: string;
 }
 
@@ -7736,9 +7744,8 @@ export interface ResolvedOverwriteOptions {
 
 export interface RoleData {
   name?: string;
-  /** @deprecated Use {@link RoleData.colors} instead. */
+  /** @deprecated Use `colors` instead. */
   color?: ColorResolvable;
-  colors?: RoleColorsResolvable;
   hoist?: boolean;
   position?: number;
   permissions?: PermissionResolvable;