From 964f37bd70a45a9f6b33541567bff2304772262a Mon Sep 17 00:00:00 2001
From: Eden Zimbelman <eden.zimbelman@salesforce.com>
Date: Thu, 10 Sep 2026 15:28:24 -0700
Subject: [PATCH] feat(types): allow mrkdwn descriptions on checkbox and radio
 button options

`OptionDescriptor.description` was typed `PlainTextElement`, so a checkbox
or radio button option could not carry a `mrkdwn` description even though
the option-object docs allow it for those two element types.

Widen the base `description` to `PlainTextElement | MrkdwnElement` and
narrow it back to `PlainTextElement` on `PlainTextOption` (overflow,
select, and multi-select options remain plain_text-only). Add tsd type
tests covering both branches.

Ref: https://docs.slack.dev/reference/block-kit/composition-objects/option-object

Co-Authored-By: Claude <svc-devxp-claude@slack-corp.com>
---
 .changeset/mrkdwn-option-description.md       |  5 ++++
 .../src/block-kit/composition-objects.ts      | 14 ++++++++---
 .../types/test/composition-objects.test-d.ts  | 25 ++++++++++++++++++-
 3 files changed, 40 insertions(+), 4 deletions(-)
 create mode 100644 .changeset/mrkdwn-option-description.md

diff --git a/.changeset/mrkdwn-option-description.md b/.changeset/mrkdwn-option-description.md
new file mode 100644
index 000000000..9b14f0ca0
--- /dev/null
+++ b/.changeset/mrkdwn-option-description.md
@@ -0,0 +1,5 @@
+---
+"@slack/types": minor
+---
+
+feat(types): allow `mrkdwn` descriptions on checkbox and radio button [options](https://docs.slack.dev/reference/block-kit/composition-objects/option-object)
diff --git a/packages/types/src/block-kit/composition-objects.ts b/packages/types/src/block-kit/composition-objects.ts
index b36d1cf50..0644ec38e 100644
--- a/packages/types/src/block-kit/composition-objects.ts
+++ b/packages/types/src/block-kit/composition-objects.ts
@@ -79,10 +79,12 @@ interface OptionDescriptor {
    */
   url?: string;
   /**
-   * @description A {@link PlainTextElement} that defines a line of descriptive text shown below the `text` field.
-   * Maximum length for the `text` within this field is 75 characters.
+   * @description A {@link PlainTextElement} or {@link MrkdwnElement} that defines a line of descriptive text shown
+   * below the `text` field beside a single selectable item in a select menu, multi-select menu, checkbox group,
+   * radio button group, or overflow menu. Only checkbox group and radio button group items can use `mrkdwn`
+   * formatting. Maximum length for the `text` within this field is 75 characters.
    */
-  description?: PlainTextElement;
+  description?: PlainTextElement | MrkdwnElement;
 }
 
 export interface MrkdwnOption extends OptionDescriptor {
@@ -99,6 +101,12 @@ export interface PlainTextOption extends OptionDescriptor {
    * overflow, select and multi-select menus. Maximum length for the `text` in this field is 75 characters.
    */
   text: PlainTextElement;
+  /**
+   * @description A {@link PlainTextElement} that defines a line of descriptive text shown below the `text` field.
+   * Options for overflow, select, and multi-select menus can only use `plain_text` descriptions. Maximum length for
+   * the `text` within this field is 75 characters.
+   */
+  description?: PlainTextElement;
 }
 
 /**
diff --git a/packages/types/test/composition-objects.test-d.ts b/packages/types/test/composition-objects.test-d.ts
index 98a03259b..b51f3dff3 100644
--- a/packages/types/test/composition-objects.test-d.ts
+++ b/packages/types/test/composition-objects.test-d.ts
@@ -1,5 +1,5 @@
 import { expectAssignable, expectError } from 'tsd';
-import type { RawNumberElement, RawTextElement } from '../src/index';
+import type { MrkdwnOption, PlainTextOption, RawNumberElement, RawTextElement } from '../src/index';
 
 // RawNumberElement
 // -- sad path
@@ -17,3 +17,26 @@ expectError<RawTextElement>({}); // missing type and text
 expectError<RawTextElement>({ type: 'raw_text' }); // missing required text
 // -- happy path
 expectAssignable<RawTextElement>({ type: 'raw_text', text: 'Item' });
+
+// MrkdwnOption (checkboxes and radio buttons): description may be plain_text or mrkdwn
+// -- happy path
+expectAssignable<MrkdwnOption>({
+  text: { type: 'mrkdwn', text: '*bold* option' },
+  description: { type: 'plain_text', text: 'plain description' },
+});
+expectAssignable<MrkdwnOption>({
+  text: { type: 'mrkdwn', text: '*bold* option' },
+  description: { type: 'mrkdwn', text: '*bold* description' },
+});
+
+// PlainTextOption (overflow, select, multi-select): description must be plain_text only
+// -- happy path
+expectAssignable<PlainTextOption>({
+  text: { type: 'plain_text', text: 'option' },
+  description: { type: 'plain_text', text: 'plain description' },
+});
+// -- sad path
+expectError<PlainTextOption>({
+  text: { type: 'plain_text', text: 'option' },
+  description: { type: 'mrkdwn', text: '*bold* description' },
+});