From 6780e78b0981f52aec9c4ef96356d3fef3742c9a Mon Sep 17 00:00:00 2001
From: Michele Campeotto <micampe@micampe.it>
Date: Wed, 13 May 2026 19:54:34 +0000
Subject: [PATCH] feat(highlights): new Dimmed hl group for de-emphasized text
 #39505

Problem:
Many color schemes assume the Comment hl group is dim text and use it
for secondary text, decorations, or parts of UI. This is true for many
color schemes but not all.

Solution:
Introducing a new highlight group with a more specific meaning, similar
to Underlined or Ignore.

The new group links to Comment by default so the behavior is unchanged
for color schemes that don't define it.
---
 runtime/doc/news.txt                       | 2 +-
 runtime/doc/syntax.txt                     | 1 +
 runtime/lua/vim/_inspector.lua             | 4 ++--
 src/nvim/highlight_group.c                 | 1 +
 test/unit/viml/expressions/parser_spec.lua | 1 +
 5 files changed, 6 insertions(+), 3 deletions(-)

diff --git a/runtime/doc/news.txt b/runtime/doc/news.txt
index 0734709274..546db27ff6 100644
--- a/runtime/doc/news.txt
+++ b/runtime/doc/news.txt
@@ -148,7 +148,7 @@ EVENTS
 
 HIGHLIGHTS
 
-• todo
+• `Dimmed` for text that should be de-emphasized.
 
 LSP
 
diff --git a/runtime/doc/syntax.txt b/runtime/doc/syntax.txt
index 3cd635bfb4..c3fdd8d956 100644
--- a/runtime/doc/syntax.txt
+++ b/runtime/doc/syntax.txt
@@ -234,6 +234,7 @@ SpecialComment	special things inside a comment
 Debug		debugging statements
 
 Underlined	text that stands out, HTML links
+Dimmed		text that is de-emphasized
 
 Ignore		left blank, hidden  |hl-Ignore|
 
diff --git a/runtime/lua/vim/_inspector.lua b/runtime/lua/vim/_inspector.lua
index a7417b9b0b..5a39006e9c 100644
--- a/runtime/lua/vim/_inspector.lua
+++ b/runtime/lua/vim/_inspector.lua
@@ -186,7 +186,7 @@ function vim.show_pos(buf, row, col, filter)
       append('   ')
     end
     if comment then
-      append(comment, 'Comment')
+      append(comment, 'Dimmed')
     end
     nl()
   end
@@ -244,7 +244,7 @@ function vim.show_pos(buf, row, col, filter)
         item(extmark.opts, extmark.ns)
       else
         append('  - ')
-        append(extmark.ns, 'Comment')
+        append(extmark.ns, 'Dimmed')
         nl()
       end
     end
diff --git a/src/nvim/highlight_group.c b/src/nvim/highlight_group.c
index 65e5533d07..0c8f8bf537 100644
--- a/src/nvim/highlight_group.c
+++ b/src/nvim/highlight_group.c
@@ -218,6 +218,7 @@ static const char *highlight_init_both[] = {
   "default link Debug          Special",
   // Used by HLF_8 (very common). None of the HLF_* things use the other Special* groups.
   "default link SpecialKey     Special",
+  "default link Dimmed         Comment",
   "default link Ignore         Normal",
 
   // Built-in LSP
diff --git a/test/unit/viml/expressions/parser_spec.lua b/test/unit/viml/expressions/parser_spec.lua
index 6f18448bd2..1c8a8ebbd8 100644
--- a/test/unit/viml/expressions/parser_spec.lua
+++ b/test/unit/viml/expressions/parser_spec.lua
@@ -78,6 +78,7 @@ local predefined_hl_defs = {
   Delimiter = true,
   SpecialComment = true,
   Debug = true,
+  Dimmed = true,
 
   -- From highlight_init_(dark|light)
   ColorColumn = true,