Mystified by faces used by swiper

[Addlai]

Trying swiper/counsel/ivy has been a bewildering experience for me. Before I end my experiment, I thought I'd let you know, so you might have an insight into the experience of a new user.

Like most users these days, I have no time to read source code, and can only very selectively skim manuals. I likely have more tha 500 packages and applications of different kinds, considering all the Emacs packages that are loaded, modules for the various programming languages I use, LaTeX packages, etc. If there is something I was supposed to read on page 43 of some document, my apologies; it would be more than a full time job to give that much attention to something like an Emacs package.

First, I find it a bit confusing that there are three different names used by the package. I think I see your rationale, but again, I don't have the bandwidth for following package authors down fanciful rabbit holes. I prefer that people respect the realistic mental bandwidth and time limitations of their users and make everything as simple as possible.

Next, I'm confronted with what appear to me to be very strange choices of faces. For one example, calling counsel-switch-buffer pops up a list of buffers in a variety of different faces which is quite busy, confusing, and, frankly rather grotesque from a typographic perspective.

What's worse, I have no idea what most the faces signify. A quick glance at your manual was not enlightening.

What's even worse, I can't tell which buffer name is selected because typically a lot of the displayed buffer names are in the same face as the current selection. In the customization buffer for Ivy faces, I see that the face is probably ivy-current-match. (I'm not filtering or attempting to match anything, so I don't know why that face is used at all.) It's not clear to me from the face names which of the Ivy faces is intended to show the current selection; whatever it is, I'm not seeing it in my setup.

Unfortunately, these and other problems make Ivy unusable for me, so I won't be attempting to track down the issues, but I thought it would be a courtesy to you to let you know my experience.

[basil-conto]

Trying swiper/counsel/ivy has been a bewildering experience for me. Before I end my experiment, I thought I'd let you know, so you might have an insight into the experience of a new user.

Noted, thank you for the feedback.
Even as a relatively longterm user and contributor to the project, I sometimes find the customisation options overwhelming or hard to pin down.

First, I find it a bit confusing that there are three different names used by the package. I think I see your rationale, but again, I don't have the bandwidth for following package authors down fanciful rabbit holes. I prefer that people respect the realistic mental bandwidth and time limitations of their users and make everything as simple as possible.

That ship has sailed.

Next, I'm confronted with what appear to me to be very strange choices of faces. For one example, calling counsel-switch-buffer pops up a list of buffers in a variety of different faces which is quite busy, confusing, and, frankly rather grotesque from a typographic perspective.

Care to share a screenshot or similar?

As a quick but partial workaround, you could try setting the variable ivy-switch-buffer-faces-alist to nil. By default, Dired and Org buffers get highlighted specially according to this variable. And I think this variable might need to be marked as a user option instead of a plain variable, for better discoverability.

I think the colour palette is also controlled by the following faces, which would need customising if deemed too noisy by default:

• ivy-subdir :: Face used by Ivy for highlighting subdirs in the alternatives.
• ivy-org :: Face used by Ivy for highlighting Org buffers in the alternatives.
• ivy-modified-buffer :: Face used by Ivy for highlighting modified file visiting buffers.
• ivy-modified-outside-buffer :: Face used by Ivy for highlighting file visiting buffers modified outside Emacs.
• ivy-remote :: Face used by Ivy for highlighting remotes in the alternatives.
• ivy-virtual :: Face used by Ivy for matching virtual buffer names.

What's worse, I have no idea what most the faces signify. A quick glance at your manual was not enlightening.

Indeed, the manual is far from optimal or complete. Patches to improve the documentation are always welcome.

What's even worse, I can't tell which buffer name is selected because typically a lot of the displayed buffer names are in the same face as the current selection.

That should not normally happen; the faces that Ivy uses (for submatches, etc.) may by default not always ensure the highest levels of contrast between one another, but they are sufficiently far apart to be able to distinguish a match from a non-match.

Am I correct in assuming you have not customised Ivy faces yourself? Are you by chance using a colour theme which tweaks Ivy faces?
Again, a screenshot would speak volumes.

Personally, I prefer the higher (than default) levels of contrast afforded by Protesilaos Stavrou's Modus themes, which are built-in since Emacs 28. Here's a screenshot:

In the customization buffer for Ivy faces, I see that the face is probably ivy-current-match. (I'm not filtering or attempting to match anything, so I don't know why that face is used at all.)

Ivy's UI conflates two subtly different functions of vanilla Emacs completion: selection vs completion. In every Ivy completion session, the user is presented with a list of candidates and a current selection therein. The user can change the selected candidate by moving up, down, etc. in a drop-down/menu-like fashion, and can also reduce the number of completion candidates by entering text, which is matched against candidates.

It's not clear to me from the face names which of the Ivy faces is intended to show the current selection; whatever it is, I'm not seeing it in my setup.

ivy-current-match is indeed the face with which the currently selected candidate is highlighted.

Beyond that, submatches of the text entered by the user are highlighted with the four faces ivy-minibuffer-match-face-N for N from 1 through 4. As an alternative to customising these individually, you can instead set the user option ivy-minibuffer-faces to a smaller or different list of faces for Ivy to cycle through.

Unfortunately, these and other problems make Ivy unusable for me, so I won't be attempting to track down the issues, but I thought it would be a courtesy to you to let you know my experience.

I'm sorry to hear it was a sufficiently negative experience for you that it warranted writing so much about it.

Ivy has accrued many different features and knobs over the years, most of the time by evolution rather than intelligent design. Documentation was not always kept to the same standard as that of Emacs itself, for example, but even if it had, the manual would today be of nontrivial size (and take proportionally nontrivial time to read).

Unfortunately, without further detail on what exactly goes wrong, what you have tried, what it looks like, or what concretely would improve the experience for you (i.e. the usual appreciated ingredients of a bug report or feature request), or without patches to that effect, it's hard to motivate or deliberate over improvements in this department.