From ce76562af1ba9d4f775dc0ffe3fb16c84a63251e Mon Sep 17 00:00:00 2001
From: DA-344 <108473820+DA-344@users.noreply.github.com>
Date: Fri, 9 May 2025 16:43:33 +0200
Subject: [PATCH 01/12] feat: document role gradient colors
---
docs/resources/guild.mdx | 43 ++++++++++++++++++++++----------------
docs/topics/permissions.md | 26 +++++++++++++++++++++++
2 files changed, 51 insertions(+), 18 deletions(-)
diff --git a/docs/resources/guild.mdx b/docs/resources/guild.mdx
index 182dca781f..fbc1a94424 100644
--- a/docs/resources/guild.mdx
+++ b/docs/resources/guild.mdx
@@ -824,6 +824,11 @@ Returns the [guild](/docs/resources/guild#guild-object) object for the given id.
"permissions": "49794752",
"position": 0,
"color": 0,
+ "colors": {
+ "primary_color": 0,
+ "secondary_color": null,
+ "tertiary_color": null,
+ },
"hoist": false,
"managed": false,
"mentionable": false
@@ -1225,15 +1230,16 @@ This endpoint supports the `X-Audit-Log-Reason` header.
###### JSON Params
-| Field | Type | Description | Default |
-|---------------|-------------------------------------------|--------------------------------------------------------------------------------------------------------------------------------|--------------------------------|
-| name | string | name of the role, max 100 characters | "new role" |
-| permissions | string | bitwise value of the enabled/disabled permissions | @everyone permissions in guild |
-| color | integer | RGB color value | 0 |
-| hoist | boolean | whether the role should be displayed separately in the sidebar | false |
-| icon | ?[image data](/docs/reference#image-data) | the role's icon image (if the guild has the `ROLE_ICONS` feature) | null |
-| unicode_emoji | ?string | the role's unicode emoji as a [standard emoji](/docs/reference#message-formatting) (if the guild has the `ROLE_ICONS` feature) | null |
-| mentionable | boolean | whether the role should be mentionable | false |
+| Field | Type | Description | Default |
+|---------------|-----------------------------------------------------------------------|--------------------------------------------------------------------------------------------------------------------------------|--------------------------------------------------------------------------------------|
+| name | string | name of the role, max 100 characters | "new role" |
+| permissions | string | bitwise value of the enabled/disabled permissions | @everyone permissions in guild |
+| color | integer | RGB color value | 0 |
+| colors | [role colors object](/docs/topics/permissions#role-colors-object) | the role's colors (if the guild has bought gradient colors) | [default role colors object](/docs/topics/permissions#default-role-colors-object) |
+| hoist | boolean | whether the role should be displayed separately in the sidebar | false |
+| icon | ?[image data](/docs/reference#image-data) | the role's icon image (if the guild has the `ROLE_ICONS` feature) | null |
+| unicode_emoji | ?string | the role's unicode emoji as a [standard emoji](/docs/reference#message-formatting) (if the guild has the `ROLE_ICONS` feature) | null |
+| mentionable | boolean | whether the role should be mentionable | false |
## Modify Guild Role Positions
/guilds/[\{guild.id\}](/docs/resources/guild#guild-object)/roles
@@ -1268,15 +1274,16 @@ This endpoint supports the `X-Audit-Log-Reason` header.
###### JSON Params
-| Field | Type | Description |
-|---------------|------------------------------------------|--------------------------------------------------------------------------------------------------------------------------------|
-| name | string | name of the role, max 100 characters |
-| permissions | string | bitwise value of the enabled/disabled permissions |
-| color | integer | RGB color value |
-| hoist | boolean | whether the role should be displayed separately in the sidebar |
-| icon | [image data](/docs/reference#image-data) | the role's icon image (if the guild has the `ROLE_ICONS` feature) |
-| unicode_emoji | string | the role's unicode emoji as a [standard emoji](/docs/reference#message-formatting) (if the guild has the `ROLE_ICONS` feature) |
-| mentionable | boolean | whether the role should be mentionable |
+| Field | Type | Description |
+|---------------|----------------------------------------------------------------------|--------------------------------------------------------------------------------------------------------------------------------|
+| name | string | name of the role, max 100 characters |
+| permissions | string | bitwise value of the enabled/disabled permissions |
+| color | integer | RGB color value |
+| colors | [role colors object](/docs/topics/permissions#role-colors-object) | the role's gradient colors (if the guild has bought gradient colors) |
+| hoist | boolean | whether the role should be displayed separately in the sidebar |
+| icon | [image data](/docs/reference#image-data) | the role's icon image (if the guild has the `ROLE_ICONS` feature) |
+| unicode_emoji | string | the role's unicode emoji as a [standard emoji](/docs/reference#message-formatting) (if the guild has the `ROLE_ICONS` feature) |
+| mentionable | boolean | whether the role should be mentionable |
## Modify Guild MFA Level
/guilds/[\{guild.id\}](/docs/resources/guild#guild-object)/mfa
diff --git a/docs/topics/permissions.md b/docs/topics/permissions.md
index e648a30b84..82e81f686f 100644
--- a/docs/topics/permissions.md
+++ b/docs/topics/permissions.md
@@ -208,6 +208,7 @@ Roles represent a set of permissions attached to a group of users. Roles have na
| id | snowflake | role id |
| name | string | role name |
| color | integer | integer representation of hexadecimal color code |
+| colors | [role colors](/docs/topics/permissions#role-colors-structure) object | the role colors |
| hoist | boolean | if this role is pinned in the user listing |
| icon? | ?string | role [icon hash](/docs/reference#image-formatting) |
| unicode_emoji? | ?string | role unicode emoji |
@@ -233,6 +234,26 @@ Tags with type `null` represent booleans. They will be present and set to `null`
| available_for_purchase? | null | whether this role is available for purchase |
| guild_connections? | null | whether this role is a guild's linked role |
+###### Role Colors Structure
+
+This object will always be filled with `primary_color` being the role's `color`. The other fields cannot be filled if the guild does not have the gradient colors feature.
+
+| Field | Type | Description |
+|------------------|----------|----------------------------------------------------------------------------------------------|
+| primary_color | integer | the role primary color, this is always the same as the role's `color` |
+| secondary_color | ?integer | the role secondary color, this will make the role gradient between the other provided colors |
+| tertiary_color | ?integer | the role tertiary color, this will make the role gradient between the other provided colors |
+
+###### Default Role Colors Object
+
+```json
+"colors": {
+ "primary_color": 0,
+ "secondary_color": null,
+ "tertiary_color": null
+}
+```
+
###### Example Role
```json
@@ -240,6 +261,11 @@ Tags with type `null` represent booleans. They will be present and set to `null`
"id": "41771983423143936",
"name": "WE DEM BOYZZ!!!!!!",
"color": 3447003,
+ "colors": {
+ "primary_color": 3447003,
+ "secondary_color": null,
+ "tertiary_color": null
+ },
"hoist": true,
"icon": "cf3ced8600b777c9486c6d8d84fb4327",
"unicode_emoji": null,
From 84bc5af9b2bc80f65f8cc54277aaa23de3cd0bf9 Mon Sep 17 00:00:00 2001
From: DA-344 <108473820+DA-344@users.noreply.github.com>
Date: Fri, 9 May 2025 16:45:41 +0200
Subject: [PATCH 02/12] object
---
docs/topics/permissions.md | 4 ++--
1 file changed, 2 insertions(+), 2 deletions(-)
diff --git a/docs/topics/permissions.md b/docs/topics/permissions.md
index 82e81f686f..56de4cbe9d 100644
--- a/docs/topics/permissions.md
+++ b/docs/topics/permissions.md
@@ -208,7 +208,7 @@ Roles represent a set of permissions attached to a group of users. Roles have na
| id | snowflake | role id |
| name | string | role name |
| color | integer | integer representation of hexadecimal color code |
-| colors | [role colors](/docs/topics/permissions#role-colors-structure) object | the role colors |
+| colors | [role colors](/docs/topics/permissions#role-colors-object) object | the role colors |
| hoist | boolean | if this role is pinned in the user listing |
| icon? | ?string | role [icon hash](/docs/reference#image-formatting) |
| unicode_emoji? | ?string | role unicode emoji |
@@ -234,7 +234,7 @@ Tags with type `null` represent booleans. They will be present and set to `null`
| available_for_purchase? | null | whether this role is available for purchase |
| guild_connections? | null | whether this role is a guild's linked role |
-###### Role Colors Structure
+###### Role Colors Object
This object will always be filled with `primary_color` being the role's `color`. The other fields cannot be filled if the guild does not have the gradient colors feature.
From 5dba1a65ea08eb6b566f761d6e39370973724a1f Mon Sep 17 00:00:00 2001
From: DA-344 <108473820+DA-344@users.noreply.github.com>
Date: Fri, 9 May 2025 16:46:01 +0200
Subject: [PATCH 03/12] comma
---
docs/resources/guild.mdx | 2 +-
1 file changed, 1 insertion(+), 1 deletion(-)
diff --git a/docs/resources/guild.mdx b/docs/resources/guild.mdx
index fbc1a94424..f7f26d5b74 100644
--- a/docs/resources/guild.mdx
+++ b/docs/resources/guild.mdx
@@ -827,7 +827,7 @@ Returns the [guild](/docs/resources/guild#guild-object) object for the given id.
"colors": {
"primary_color": 0,
"secondary_color": null,
- "tertiary_color": null,
+ "tertiary_color": null
},
"hoist": false,
"managed": false,
From 36185b944cf4effe9197403c659cb204a3de5aac Mon Sep 17 00:00:00 2001
From: DA-344 <108473820+DA-344@users.noreply.github.com>
Date: Fri, 9 May 2025 16:50:44 +0200
Subject: [PATCH 04/12] features and more clear docs
---
docs/resources/guild.mdx | 5 +++--
docs/topics/permissions.md | 2 +-
2 files changed, 4 insertions(+), 3 deletions(-)
diff --git a/docs/resources/guild.mdx b/docs/resources/guild.mdx
index f7f26d5b74..ee7d626d50 100644
--- a/docs/resources/guild.mdx
+++ b/docs/resources/guild.mdx
@@ -159,6 +159,7 @@ Fields specific to the `GUILD_CREATE` event are listed in the [Gateway Events do
| VERIFIED | guild is verified |
| VIP_REGIONS | guild has access to set 384kbps bitrate in voice (previously VIP voice servers) |
| WELCOME_SCREEN_ENABLED | guild has enabled the welcome screen |
+| ENHANCED_ROLE_COLORS | guild is able to set gradient colors to roles |
###### Mutable Guild Features
@@ -1235,7 +1236,7 @@ This endpoint supports the `X-Audit-Log-Reason` header.
| name | string | name of the role, max 100 characters | "new role" |
| permissions | string | bitwise value of the enabled/disabled permissions | @everyone permissions in guild |
| color | integer | RGB color value | 0 |
-| colors | [role colors object](/docs/topics/permissions#role-colors-object) | the role's colors (if the guild has bought gradient colors) | [default role colors object](/docs/topics/permissions#default-role-colors-object) |
+| colors | [role colors object](/docs/topics/permissions#role-colors-object) | the role colors | [default role colors object](/docs/topics/permissions#default-role-colors-object) |
| hoist | boolean | whether the role should be displayed separately in the sidebar | false |
| icon | ?[image data](/docs/reference#image-data) | the role's icon image (if the guild has the `ROLE_ICONS` feature) | null |
| unicode_emoji | ?string | the role's unicode emoji as a [standard emoji](/docs/reference#message-formatting) (if the guild has the `ROLE_ICONS` feature) | null |
@@ -1279,7 +1280,7 @@ This endpoint supports the `X-Audit-Log-Reason` header.
| name | string | name of the role, max 100 characters |
| permissions | string | bitwise value of the enabled/disabled permissions |
| color | integer | RGB color value |
-| colors | [role colors object](/docs/topics/permissions#role-colors-object) | the role's gradient colors (if the guild has bought gradient colors) |
+| colors | [role colors object](/docs/topics/permissions#role-colors-object) | the role's colors |
| hoist | boolean | whether the role should be displayed separately in the sidebar |
| icon | [image data](/docs/reference#image-data) | the role's icon image (if the guild has the `ROLE_ICONS` feature) |
| unicode_emoji | string | the role's unicode emoji as a [standard emoji](/docs/reference#message-formatting) (if the guild has the `ROLE_ICONS` feature) |
diff --git a/docs/topics/permissions.md b/docs/topics/permissions.md
index 56de4cbe9d..d502681678 100644
--- a/docs/topics/permissions.md
+++ b/docs/topics/permissions.md
@@ -236,7 +236,7 @@ Tags with type `null` represent booleans. They will be present and set to `null`
###### Role Colors Object
-This object will always be filled with `primary_color` being the role's `color`. The other fields cannot be filled if the guild does not have the gradient colors feature.
+This object will always be filled with `primary_color` being the role's `color`. Other fileds can only be set to a non-null value if the guild has the `ENHANCED_ROLE_COLORS` [guild feature](/docs/resources/guild#guild-object-guild-features).
| Field | Type | Description |
|------------------|----------|----------------------------------------------------------------------------------------------|
From b751c60355f6eaf8cf58e8e218fb96da9cf353f4 Mon Sep 17 00:00:00 2001
From: DA-344 <108473820+DA-344@users.noreply.github.com>
Date: Fri, 9 May 2025 16:53:57 +0200
Subject: [PATCH 05/12] tables
---
docs/resources/guild.mdx | 4 ++--
docs/topics/permissions.md | 2 +-
2 files changed, 3 insertions(+), 3 deletions(-)
diff --git a/docs/resources/guild.mdx b/docs/resources/guild.mdx
index ee7d626d50..197baebbea 100644
--- a/docs/resources/guild.mdx
+++ b/docs/resources/guild.mdx
@@ -1236,7 +1236,7 @@ This endpoint supports the `X-Audit-Log-Reason` header.
| name | string | name of the role, max 100 characters | "new role" |
| permissions | string | bitwise value of the enabled/disabled permissions | @everyone permissions in guild |
| color | integer | RGB color value | 0 |
-| colors | [role colors object](/docs/topics/permissions#role-colors-object) | the role colors | [default role colors object](/docs/topics/permissions#default-role-colors-object) |
+| colors | [role colors](/docs/topics/permissions#role-colors-object) object | the role colors | [default role colors object](/docs/topics/permissions#default-role-colors-object) |
| hoist | boolean | whether the role should be displayed separately in the sidebar | false |
| icon | ?[image data](/docs/reference#image-data) | the role's icon image (if the guild has the `ROLE_ICONS` feature) | null |
| unicode_emoji | ?string | the role's unicode emoji as a [standard emoji](/docs/reference#message-formatting) (if the guild has the `ROLE_ICONS` feature) | null |
@@ -1280,7 +1280,7 @@ This endpoint supports the `X-Audit-Log-Reason` header.
| name | string | name of the role, max 100 characters |
| permissions | string | bitwise value of the enabled/disabled permissions |
| color | integer | RGB color value |
-| colors | [role colors object](/docs/topics/permissions#role-colors-object) | the role's colors |
+| colors | [role colors](/docs/topics/permissions#role-colors-object) object | the role's colors |
| hoist | boolean | whether the role should be displayed separately in the sidebar |
| icon | [image data](/docs/reference#image-data) | the role's icon image (if the guild has the `ROLE_ICONS` feature) |
| unicode_emoji | string | the role's unicode emoji as a [standard emoji](/docs/reference#message-formatting) (if the guild has the `ROLE_ICONS` feature) |
diff --git a/docs/topics/permissions.md b/docs/topics/permissions.md
index d502681678..74856cc9fd 100644
--- a/docs/topics/permissions.md
+++ b/docs/topics/permissions.md
@@ -208,7 +208,7 @@ Roles represent a set of permissions attached to a group of users. Roles have na
| id | snowflake | role id |
| name | string | role name |
| color | integer | integer representation of hexadecimal color code |
-| colors | [role colors](/docs/topics/permissions#role-colors-object) object | the role colors |
+| colors | [role colors](/docs/topics/permissions#role-colors-object) object | the role colors |
| hoist | boolean | if this role is pinned in the user listing |
| icon? | ?string | role [icon hash](/docs/reference#image-formatting) |
| unicode_emoji? | ?string | role unicode emoji |
From 99b2a5054a96f93daad774800f90e6e375dc1b1b Mon Sep 17 00:00:00 2001
From: DA344 <108473820+DA-344@users.noreply.github.com>
Date: Fri, 9 May 2025 17:04:16 +0200
Subject: [PATCH 06/12] typo on permissions.md
Co-authored-by: Suspense <64612795+AlmostSuspense@users.noreply.github.com>
---
docs/topics/permissions.md | 2 +-
1 file changed, 1 insertion(+), 1 deletion(-)
diff --git a/docs/topics/permissions.md b/docs/topics/permissions.md
index 74856cc9fd..73514302f7 100644
--- a/docs/topics/permissions.md
+++ b/docs/topics/permissions.md
@@ -236,7 +236,7 @@ Tags with type `null` represent booleans. They will be present and set to `null`
###### Role Colors Object
-This object will always be filled with `primary_color` being the role's `color`. Other fileds can only be set to a non-null value if the guild has the `ENHANCED_ROLE_COLORS` [guild feature](/docs/resources/guild#guild-object-guild-features).
+This object will always be filled with `primary_color` being the role's `color`. Other fields can only be set to a non-null value if the guild has the `ENHANCED_ROLE_COLORS` [guild feature](/docs/resources/guild#guild-object-guild-features).
| Field | Type | Description |
|------------------|----------|----------------------------------------------------------------------------------------------|
From 1c3d89d7ca75a159c503d70ba8a2e321bba88a9d Mon Sep 17 00:00:00 2001
From: DA-344 <108473820+DA-344@users.noreply.github.com>
Date: Tue, 24 Jun 2025 09:52:21 +0200
Subject: [PATCH 07/12] add note about holographic style
---
docs/topics/permissions.md | 5 +++++
1 file changed, 5 insertions(+)
diff --git a/docs/topics/permissions.md b/docs/topics/permissions.md
index 74856cc9fd..209ac94f9d 100644
--- a/docs/topics/permissions.md
+++ b/docs/topics/permissions.md
@@ -244,6 +244,11 @@ This object will always be filled with `primary_color` being the role's `color`.
| secondary_color | ?integer | the role secondary color, this will make the role gradient between the other provided colors |
| tertiary_color | ?integer | the role tertiary color, this will make the role gradient between the other provided colors |
+:::info
+If you provide a `tertiary_color`, you must follow the holographic style preset. Which is:
+`primary_color = 11127295`, `secondary_color = 16759788`, and `tertiary_color = 16761760`.
+:::
+
###### Default Role Colors Object
```json
From 44fbc457c19aff740a33a1ee4a2cf349d2e3d10d Mon Sep 17 00:00:00 2001
From: DA344 <108473820+DA-344@users.noreply.github.com>
Date: Wed, 25 Jun 2025 09:14:20 +0200
Subject: [PATCH 08/12] Reword info block on RoleColors
Co-authored-by: Anthony
---
docs/topics/permissions.md | 2 +-
1 file changed, 1 insertion(+), 1 deletion(-)
diff --git a/docs/topics/permissions.md b/docs/topics/permissions.md
index 0c489f0893..51e4e4b7f3 100644
--- a/docs/topics/permissions.md
+++ b/docs/topics/permissions.md
@@ -245,7 +245,7 @@ This object will always be filled with `primary_color` being the role's `color`.
| tertiary_color | ?integer | the role tertiary color, this will make the role gradient between the other provided colors |
:::info
-If you provide a `tertiary_color`, you must follow the holographic style preset. Which is:
+When sending `tertiary_color` the API enforces the role color to be a holographic style with values of:
`primary_color = 11127295`, `secondary_color = 16759788`, and `tertiary_color = 16761760`.
:::
From d393bd64f0971225b3a242ff4d45e378fe2f208e Mon Sep 17 00:00:00 2001
From: DA344 <108473820+DA-344@users.noreply.github.com>
Date: Wed, 25 Jun 2025 09:14:53 +0200
Subject: [PATCH 09/12] 's
Co-authored-by: Anthony
---
docs/topics/permissions.md | 2 +-
1 file changed, 1 insertion(+), 1 deletion(-)
diff --git a/docs/topics/permissions.md b/docs/topics/permissions.md
index 51e4e4b7f3..90eb034aa6 100644
--- a/docs/topics/permissions.md
+++ b/docs/topics/permissions.md
@@ -208,7 +208,7 @@ Roles represent a set of permissions attached to a group of users. Roles have na
| id | snowflake | role id |
| name | string | role name |
| color | integer | integer representation of hexadecimal color code |
-| colors | [role colors](/docs/topics/permissions#role-colors-object) object | the role colors |
+| colors | [role colors](/docs/topics/permissions#role-colors-object) object | the role's colors |
| hoist | boolean | if this role is pinned in the user listing |
| icon? | ?string | role [icon hash](/docs/reference#image-formatting) |
| unicode_emoji? | ?string | role unicode emoji |
From 4697b9e4411b31b1a8e5207f64da3ea04979b93e Mon Sep 17 00:00:00 2001
From: DA-344 <108473820+DA-344@users.noreply.github.com>
Date: Wed, 25 Jun 2025 09:24:07 +0200
Subject: [PATCH 10/12] Update based on the review
---
docs/resources/guild.mdx | 22 +++++++++++---------
docs/topics/permissions.md | 42 ++++++++++++++++++++------------------
2 files changed, 34 insertions(+), 30 deletions(-)
diff --git a/docs/resources/guild.mdx b/docs/resources/guild.mdx
index 197baebbea..b8d26f97a5 100644
--- a/docs/resources/guild.mdx
+++ b/docs/resources/guild.mdx
@@ -1275,16 +1275,18 @@ This endpoint supports the `X-Audit-Log-Reason` header.
###### JSON Params
-| Field | Type | Description |
-|---------------|----------------------------------------------------------------------|--------------------------------------------------------------------------------------------------------------------------------|
-| name | string | name of the role, max 100 characters |
-| permissions | string | bitwise value of the enabled/disabled permissions |
-| color | integer | RGB color value |
-| colors | [role colors](/docs/topics/permissions#role-colors-object) object | the role's colors |
-| hoist | boolean | whether the role should be displayed separately in the sidebar |
-| icon | [image data](/docs/reference#image-data) | the role's icon image (if the guild has the `ROLE_ICONS` feature) |
-| unicode_emoji | string | the role's unicode emoji as a [standard emoji](/docs/reference#message-formatting) (if the guild has the `ROLE_ICONS` feature) |
-| mentionable | boolean | whether the role should be mentionable |
+| Field | Type | Description |
+|----------------|----------------------------------------------------------------------|--------------------------------------------------------------------------------------------------------------------------------|
+| name | string | name of the role, max 100 characters |
+| permissions | string | bitwise value of the enabled/disabled permissions |
+| color* | integer | RGB color value |
+| colors | [role colors](/docs/topics/permissions#role-colors-object) object | the role's colors |
+| hoist | boolean | whether the role should be displayed separately in the sidebar |
+| icon | [image data](/docs/reference#image-data) | the role's icon image (if the guild has the `ROLE_ICONS` feature) |
+| unicode_emoji | string | the role's unicode emoji as a [standard emoji](/docs/reference#message-formatting) (if the guild has the `ROLE_ICONS` feature) |
+| mentionable | boolean | whether the role should be mentionable |
+
+\* `color` will still be returned by the API, but using the `colors` field is recommended when doing requests.
## Modify Guild MFA Level
/guilds/[\{guild.id\}](/docs/resources/guild#guild-object)/mfa
diff --git a/docs/topics/permissions.md b/docs/topics/permissions.md
index 90eb034aa6..94a00a807c 100644
--- a/docs/topics/permissions.md
+++ b/docs/topics/permissions.md
@@ -203,24 +203,26 @@ Roles represent a set of permissions attached to a group of users. Roles have na
###### Role Structure
-| Field | Type | Description |
-|----------------|------------------------------------------------------------------------------|---------------------------------------------------------------------------------------------------------------------------------|
-| id | snowflake | role id |
-| name | string | role name |
-| color | integer | integer representation of hexadecimal color code |
-| colors | [role colors](/docs/topics/permissions#role-colors-object) object | the role's colors |
-| hoist | boolean | if this role is pinned in the user listing |
-| icon? | ?string | role [icon hash](/docs/reference#image-formatting) |
-| unicode_emoji? | ?string | role unicode emoji |
-| position | integer | position of this role (roles with the same position are sorted by id) |
-| permissions | string | permission bit set |
-| managed | boolean | whether this role is managed by an integration |
-| mentionable | boolean | whether this role is mentionable |
-| tags? | [role tags](/docs/topics/permissions#role-object-role-tags-structure) object | the tags this role has |
-| flags | integer | [role flags](/docs/topics/permissions#role-object-role-flags) combined as a [bitfield](https://en.wikipedia.org/wiki/Bit_field) |
+| Field | Type | Description |
+|-----------------|------------------------------------------------------------------------------|---------------------------------------------------------------------------------------------------------------------------------|
+| id | snowflake | role id |
+| name | string | role name |
+| color* | integer | integer representation of hexadecimal color code |
+| colors | [role colors](/docs/topics/permissions#role-colors-object) object | the role's colors |
+| hoist | boolean | if this role is pinned in the user listing |
+| icon? | ?string | role [icon hash](/docs/reference#image-formatting) |
+| unicode_emoji? | ?string | role unicode emoji |
+| position | integer | position of this role (roles with the same position are sorted by id) |
+| permissions | string | permission bit set |
+| managed | boolean | whether this role is managed by an integration |
+| mentionable | boolean | whether this role is mentionable |
+| tags? | [role tags](/docs/topics/permissions#role-object-role-tags-structure) object | the tags this role has |
+| flags | integer | [role flags](/docs/topics/permissions#role-object-role-flags) combined as a [bitfield](https://en.wikipedia.org/wiki/Bit_field) |
Roles without colors (`color == 0`) do not count towards the final computed color in the user list.
+\* `color` will still be returned by the API, but using the `colors` field is recommended when doing requests.
+
###### Role Tags Structure
Tags with type `null` represent booleans. They will be present and set to `null` if they are "true", and will be not present if they are "false".
@@ -238,11 +240,11 @@ Tags with type `null` represent booleans. They will be present and set to `null`
This object will always be filled with `primary_color` being the role's `color`. Other fields can only be set to a non-null value if the guild has the `ENHANCED_ROLE_COLORS` [guild feature](/docs/resources/guild#guild-object-guild-features).
-| Field | Type | Description |
-|------------------|----------|----------------------------------------------------------------------------------------------|
-| primary_color | integer | the role primary color, this is always the same as the role's `color` |
-| secondary_color | ?integer | the role secondary color, this will make the role gradient between the other provided colors |
-| tertiary_color | ?integer | the role tertiary color, this will make the role gradient between the other provided colors |
+| Field | Type | Description |
+|------------------|----------|--------------------------------------------------------------------------------------------------------|
+| primary_color | integer | the primary color for the role |
+| secondary_color | ?integer | the secondary color for the role, this will make the role a gradient between the other provided colors |
+| tertiary_color | ?integer | the tertiary color for the role, this will turn the gradient into a holographic style |
:::info
When sending `tertiary_color` the API enforces the role color to be a holographic style with values of:
From dc32e77e35b8cf62269fdbd85117713b3ab978fc Mon Sep 17 00:00:00 2001
From: DA344 <108473820+DA-344@users.noreply.github.com>
Date: Wed, 25 Jun 2025 23:46:14 +0200
Subject: [PATCH 11/12] 's
Co-authored-by: Anthony
---
docs/resources/guild.mdx | 2 +-
1 file changed, 1 insertion(+), 1 deletion(-)
diff --git a/docs/resources/guild.mdx b/docs/resources/guild.mdx
index b8d26f97a5..a88ee9e70c 100644
--- a/docs/resources/guild.mdx
+++ b/docs/resources/guild.mdx
@@ -1236,7 +1236,7 @@ This endpoint supports the `X-Audit-Log-Reason` header.
| name | string | name of the role, max 100 characters | "new role" |
| permissions | string | bitwise value of the enabled/disabled permissions | @everyone permissions in guild |
| color | integer | RGB color value | 0 |
-| colors | [role colors](/docs/topics/permissions#role-colors-object) object | the role colors | [default role colors object](/docs/topics/permissions#default-role-colors-object) |
+| colors | [role colors](/docs/topics/permissions#role-colors-object) object | the role's colors | [default role colors object](/docs/topics/permissions#default-role-colors-object) |
| hoist | boolean | whether the role should be displayed separately in the sidebar | false |
| icon | ?[image data](/docs/reference#image-data) | the role's icon image (if the guild has the `ROLE_ICONS` feature) | null |
| unicode_emoji | ?string | the role's unicode emoji as a [standard emoji](/docs/reference#message-formatting) (if the guild has the `ROLE_ICONS` feature) | null |
From ff1b4f3343b677996daa5ed31fbbdd31d69cea05 Mon Sep 17 00:00:00 2001
From: DA-344 <108473820+DA-344@users.noreply.github.com>
Date: Thu, 26 Jun 2025 09:57:21 +0200
Subject: [PATCH 12/12] apply suggestions and fix tables
---
docs/resources/guild.mdx | 42 ++++++++++++++++++++------------------
docs/topics/permissions.md | 40 ++++++++++++++++++------------------
2 files changed, 42 insertions(+), 40 deletions(-)
diff --git a/docs/resources/guild.mdx b/docs/resources/guild.mdx
index a88ee9e70c..79cd23b419 100644
--- a/docs/resources/guild.mdx
+++ b/docs/resources/guild.mdx
@@ -1231,16 +1231,18 @@ This endpoint supports the `X-Audit-Log-Reason` header.
###### JSON Params
-| Field | Type | Description | Default |
-|---------------|-----------------------------------------------------------------------|--------------------------------------------------------------------------------------------------------------------------------|--------------------------------------------------------------------------------------|
-| name | string | name of the role, max 100 characters | "new role" |
-| permissions | string | bitwise value of the enabled/disabled permissions | @everyone permissions in guild |
-| color | integer | RGB color value | 0 |
-| colors | [role colors](/docs/topics/permissions#role-colors-object) object | the role's colors | [default role colors object](/docs/topics/permissions#default-role-colors-object) |
-| hoist | boolean | whether the role should be displayed separately in the sidebar | false |
-| icon | ?[image data](/docs/reference#image-data) | the role's icon image (if the guild has the `ROLE_ICONS` feature) | null |
-| unicode_emoji | ?string | the role's unicode emoji as a [standard emoji](/docs/reference#message-formatting) (if the guild has the `ROLE_ICONS` feature) | null |
-| mentionable | boolean | whether the role should be mentionable | false |
+| Field | Type | Description | Default |
+|---------------|-------------------------------------------------------------------------------|--------------------------------------------------------------------------------------------------------------------------------|-----------------------------------------------------------------------------------------------|
+| name | string | name of the role, max 100 characters | "new role" |
+| permissions | string | bitwise value of the enabled/disabled permissions | @everyone permissions in guild |
+| color* | integer | RGB color value | 0 |
+| colors | [role colors](/docs/topics/permissions#role-object-role-colors-object) object | the role's colors | [default role colors object](/docs/topics/permissions#role-object-default-role-colors-object) |
+| hoist | boolean | whether the role should be displayed separately in the sidebar | false |
+| icon | ?[image data](/docs/reference#image-data) | the role's icon image (if the guild has the `ROLE_ICONS` feature) | null |
+| unicode_emoji | ?string | the role's unicode emoji as a [standard emoji](/docs/reference#message-formatting) (if the guild has the `ROLE_ICONS` feature) | null |
+| mentionable | boolean | whether the role should be mentionable | false |
+
+\* `color` will still be returned by the API, but using the `colors` field is recommended when doing requests.
## Modify Guild Role Positions
/guilds/[\{guild.id\}](/docs/resources/guild#guild-object)/roles
@@ -1275,16 +1277,16 @@ This endpoint supports the `X-Audit-Log-Reason` header.
###### JSON Params
-| Field | Type | Description |
-|----------------|----------------------------------------------------------------------|--------------------------------------------------------------------------------------------------------------------------------|
-| name | string | name of the role, max 100 characters |
-| permissions | string | bitwise value of the enabled/disabled permissions |
-| color* | integer | RGB color value |
-| colors | [role colors](/docs/topics/permissions#role-colors-object) object | the role's colors |
-| hoist | boolean | whether the role should be displayed separately in the sidebar |
-| icon | [image data](/docs/reference#image-data) | the role's icon image (if the guild has the `ROLE_ICONS` feature) |
-| unicode_emoji | string | the role's unicode emoji as a [standard emoji](/docs/reference#message-formatting) (if the guild has the `ROLE_ICONS` feature) |
-| mentionable | boolean | whether the role should be mentionable |
+| Field | Type | Description |
+|---------------|-------------------------------------------------------------------------------|--------------------------------------------------------------------------------------------------------------------------------|
+| name | string | name of the role, max 100 characters |
+| permissions | string | bitwise value of the enabled/disabled permissions |
+| color* | integer | RGB color value |
+| colors | [role colors](/docs/topics/permissions#role-object-role-colors-object) object | the role's colors |
+| hoist | boolean | whether the role should be displayed separately in the sidebar |
+| icon | [image data](/docs/reference#image-data) | the role's icon image (if the guild has the `ROLE_ICONS` feature) |
+| unicode_emoji | string | the role's unicode emoji as a [standard emoji](/docs/reference#message-formatting) (if the guild has the `ROLE_ICONS` feature) |
+| mentionable | boolean | whether the role should be mentionable |
\* `color` will still be returned by the API, but using the `colors` field is recommended when doing requests.
diff --git a/docs/topics/permissions.md b/docs/topics/permissions.md
index 94a00a807c..d48c11c93b 100644
--- a/docs/topics/permissions.md
+++ b/docs/topics/permissions.md
@@ -203,21 +203,21 @@ Roles represent a set of permissions attached to a group of users. Roles have na
###### Role Structure
-| Field | Type | Description |
-|-----------------|------------------------------------------------------------------------------|---------------------------------------------------------------------------------------------------------------------------------|
-| id | snowflake | role id |
-| name | string | role name |
-| color* | integer | integer representation of hexadecimal color code |
-| colors | [role colors](/docs/topics/permissions#role-colors-object) object | the role's colors |
-| hoist | boolean | if this role is pinned in the user listing |
-| icon? | ?string | role [icon hash](/docs/reference#image-formatting) |
-| unicode_emoji? | ?string | role unicode emoji |
-| position | integer | position of this role (roles with the same position are sorted by id) |
-| permissions | string | permission bit set |
-| managed | boolean | whether this role is managed by an integration |
-| mentionable | boolean | whether this role is mentionable |
-| tags? | [role tags](/docs/topics/permissions#role-object-role-tags-structure) object | the tags this role has |
-| flags | integer | [role flags](/docs/topics/permissions#role-object-role-flags) combined as a [bitfield](https://en.wikipedia.org/wiki/Bit_field) |
+| Field | Type | Description |
+|----------------|-------------------------------------------------------------------------------|---------------------------------------------------------------------------------------------------------------------------------|
+| id | snowflake | role id |
+| name | string | role name |
+| color* | integer | integer representation of hexadecimal color code |
+| colors | [role colors](/docs/topics/permissions#role-object-role-colors-object) object | the role's colors |
+| hoist | boolean | if this role is pinned in the user listing |
+| icon? | ?string | role [icon hash](/docs/reference#image-formatting) |
+| unicode_emoji? | ?string | role unicode emoji |
+| position | integer | position of this role (roles with the same position are sorted by id) |
+| permissions | string | permission bit set |
+| managed | boolean | whether this role is managed by an integration |
+| mentionable | boolean | whether this role is mentionable |
+| tags? | [role tags](/docs/topics/permissions#role-object-role-tags-structure) object | the tags this role has |
+| flags | integer | [role flags](/docs/topics/permissions#role-object-role-flags) combined as a [bitfield](https://en.wikipedia.org/wiki/Bit_field) |
Roles without colors (`color == 0`) do not count towards the final computed color in the user list.
@@ -240,11 +240,11 @@ Tags with type `null` represent booleans. They will be present and set to `null`
This object will always be filled with `primary_color` being the role's `color`. Other fields can only be set to a non-null value if the guild has the `ENHANCED_ROLE_COLORS` [guild feature](/docs/resources/guild#guild-object-guild-features).
-| Field | Type | Description |
-|------------------|----------|--------------------------------------------------------------------------------------------------------|
-| primary_color | integer | the primary color for the role |
-| secondary_color | ?integer | the secondary color for the role, this will make the role a gradient between the other provided colors |
-| tertiary_color | ?integer | the tertiary color for the role, this will turn the gradient into a holographic style |
+| Field | Type | Description |
+|-----------------|----------|--------------------------------------------------------------------------------------------------------|
+| primary_color | integer | the primary color for the role |
+| secondary_color | ?integer | the secondary color for the role, this will make the role a gradient between the other provided colors |
+| tertiary_color | ?integer | the tertiary color for the role, this will turn the gradient into a holographic style |
:::info
When sending `tertiary_color` the API enforces the role color to be a holographic style with values of: