Custom CSS classes

[srt19170]

In this fork, I've added custom CSS classes to most of the CommaFeed page elements. For example, the header of a feed entry is enclosed in an HTML <div> element with the class name cf-FeedEntryHeader. This makes writing custom CSS easier; for example, if you want to make change the background color of the headers, you could add this to the custom CSS code:

.cf-FeedEntryHeader {background-color: lightblue;}

The class names are hierarchical, so a name like cf-FeedEntryHeader-Flex1-Flex-Box refers (reading right to left) to a Box element within a Flex element within another Flex element within the cf-FeedEntryHeader element. The elements within these class names (e.g., Box, Flex, etc.) follow the naming scheme in the CommaFeed source code (and hence, the naming scheme in the Mantine library. The actual HTML elements in the rendered page are often different. For example, a Mantine Box element becomes an HTML <div>.

I've also created a .md file documenting all of the custom class names, and modified README.md to reference that file. The documentation also includes an extended example of custom CSS. I've put that file in the home directory.

[Athou]

Thanks @srt19170 I'll try to review this ASAP!

[Athou]

Thank you for this PR! I've left a few notes below. Please keep in mind that once we introduce custom CSS classes, users will expect them to remain supported in future releases, so we need to balance the benefit of each new class against the cost of maintaining it over time.

• I really like the cf- prefix. It makes it clear which classes are safe to customize.

• Tying class names directly to our internal structure can make refactoring painful. For example, names like cf-FeedEntries-Box or cf-FeedEntries-Box-Group-Link are brittle: changing the code would break users' custom CSS even if the output HTML is the same. Instead, could we consider more semantic names, e.g. cf-entries-wrapper and cf-feed-link that describe the element's role rather than its exact place in the code? Also, because CSS selectors themselves support hierarchy, these elements can be targeted with nested selectors (e.g. .cf-FeedEntries .cf-Box .cf-Group .cf-Link or even .cf-entries-wrapper .cf-feed-link). Do we need to have entire paths in the class names?

• Do we need custom classes on non‑reading pages (home page, about page, etc.)? Would users actually want to style those, or can we limit customization to the main reading interface?

[srt19170]

Thanks for taking a look at this! Obviously this is your project and you get to decide, but here are some thoughts on the issues:

Please keep in mind that once we introduce custom CSS classes, users will expect them to remain supported in future releases, so we need to balance the benefit of each new class against the cost of maintaining it over time.

Initially I intended to only add class-names to "significant" UI elements but I realized that one of my existing rules used an "insignificant" element, so I ended up erring on the side of completeness and gave a name to everything. I wasn't sure there's much of a maintenance issue after the initial change. I don't imagine you'll often change the meaning of a UI element, and everything have a unique name means you can change the structure without breaking most of the custom CSS. But maybe there's something I'm missing.

Tying class names directly to our internal structure can make refactoring painful. For example, names like cf-FeedEntries-Box or cf-FeedEntries-Box-Group-Link are brittle: changing the code would break users' custom CSS even if the output HTML is the same. Instead, could we consider more semantic names, e.g. cf-entries-wrapper and cf-feed-link that describe the element's role rather than its exact place in the code?

Well, the names are really just arbitrary, so if we can come up with semantic names that's fine. I initially started out trying to use semantic names but I ran into things like cf-FeedEntryHeader-Flex1-Flex-Box where it was getting difficult to come up with meaningful names for all the nested elements. The utility of this naming was that I could look at the generated HTML and trace an element name back to the source code where it appeared, but that's probably more useful to creating the class names than to using them.

Also, because CSS selectors themselves support hierarchy, these elements can be targeted with nested selectors (e.g. .cf-FeedEntries .cf-Box .cf-Group .cf-Link or even .cf-entries-wrapper .cf-feed-link). Do we need to have entire paths in the class names?

I thought about this but my concern was that it will make the UI brittle to structural changes, i.e., if for some reason you drop the Box after cf-FeedEntries you will break all the path references under the Box. (In fact, that's what set me down this path in the first place. I had custom CSS that of necessity used a lot of long paths and which broke when something fairly high up in the hierarchy was changed.) So I thought that giving every element a unique name would make custom CSS more resilient to most code changes.

Do we need custom classes on non‑reading pages (home page, about page, etc.)? Would users actually want to style those, or can we limit customization to the main reading interface?

Yeah, as I was slogging through all those pages I had my doubts! Mostly I did them for the sake of completeness. I certainly have no need of them.

[Athou]

Would you willing to share your custom CSS code? It would help me get a better understanding of what kind of customization you're doing 🙂

[srt19170]

My current custom CSS is basically what's in the example in the documentation file. If you have a way to put a call out to people asking for their custom code or for comments on this change that would be good. Maybe people who have opened CSS issues?

[Athou]

I've reviewed your custom CSS and pushed a commit to this branch with changes I'm more comfortable with going forward.
I think that between those changes and the <header>, <nav>, <main> and <article> elements, you should be able to write custom CSS rules to apply the behavior you're looking for.

For example, some of your previous selectors can now be written as such:

.cf-Layout-Box-AppShell-Navbar -> nav
.cf-TreeNode-Box -> .cf-treenode
.cf-Layout-Box-AppShell-Navbar-Section-Box img -> .cf-treenode img
.cf-FeedEntry-Paper-Box-Divider -> article .cf-footer-divider

Let me know what you think!

[srt19170]

Will you be documenting the new .cf classes? I think having some kind of guide to the CSS classes would be helpful to anyone who wants to develop custom CSS.

Tagging a few other custom CSS users: @DarkFox, @Lorentz83, @Crul, @sn0crash

[Athou]

Will you be documenting the new .cf classes? I think having some kind of guide to the CSS classes would be helpful to anyone who wants to develop custom CSS.

I created this branch mainly to get some feedback, I think it strikes a middle ground between the current code and what you proposed in this PR. I wanted to check if you were able to achieve the customization you had in mind with these changes. If it fits your needs, then adding documentation indeed makes sense 😊

[srt19170]

It's a little difficult to recreate my custom CSS without the new class names and a mapping to the old class names or at least the parts of the interface. When I have time I can try to go through the code and the HTML and recreate my changes but it might be a while before I can find the time, sorry! But I'm sure its possible so if you're happy with this version don't wait on my feedback.

[srt19170]

I was thinking about this a bit more from the aspect of "make it easy for the most common changes". To do that, you want to give the custom CSS authors easy anchors for the most common kinds of changes. In that light, I think you want to have simple anchors to the following parts of the main UI page:

• The whole page (body)
• The header bar (header)
  • Icons/buttons within the header bar (?)
• The sidebar (sidebar)
  • The search field in the sidebar (maybe not important enough?)
  • The entire tree (?)
    • Category entries in the tree (.cf-treenode, .cf-treenode-icon)
    • Feed entries in the tree (.cf-treenode, .cf-treenode-icon, .cf-treenode-unread-count)
• The content area (content)
  • The title area within the content area (?)
  • Feed entries (entries)
    • Feed entry (article)
      • Header within feed entry (.cf-header, .cf-header-title, .cf-header-subtitle, .cf-header-details)
      • Body (?)
      • Footer within the feed entry (.cf-footer-divider, .cf-footer)

Notes:

• The missing anchors for me would be the entire tree in the sidebar, the title area in the content area and the feed entry body.
• It would be nice to be easily able to select the div that wraps each of the buttons in the toolbar, e.g., .cf-toolbar-button or somesuch.
  • Aria-label can be used to identify toolbar buttons by function, which is useful. If the buttons aren't getting unique classnames then it would be good to document aria-label and the label names and how to use them instead.
• I think it would be worthwhile to distinguish category entries and feed entries in the tree. (Maybe there's a way to do that already?) I imagine that people might want to style those separately.
• If cf-treenode-icon, cf-treenode-unread-count, cf-header-title, etc. went away I wouldn't be too upset because cf-header and cf-treenode give a good starting point. On the other hand, I imagine the various parts of the feed entry header will be common targets for customization so it's nice to have shortcuts to those items.
• On a miscellaneous note, it seems to me like the feed entry footer divider should be inside of the footer rather than standing on its own between the body and the footer, but maybe that's just me.

I hope this is helpful!

[Athou]

Hi @srt19170, sorry for the delay.
Thanks for the feedback! I've added more classes in this commit that I believe address all your comments.

Let me know if anything's still missing, otherwise I'll go ahead and merge the branch and close this PR.

[srt19170]

Seems great! Let me know if you want me to help create the documentation or anything.

[Athou]

Great! I just merged the branch. If you could update the documentation you wrote in this PR, I’d really appreciate it. Thanks!

[srt19170]

I've updated the documentation to reflect the current code. I've updated my branch, but I'll attach it here since it might be easier just to grab the file here. Note you'll need to link it into the documentation somewhere.
CUSTOMCSS.md

[Athou]

I've updated the documentation to reflect the current code. I've updated my branch, but I'll attach it here since it might be easier just to grab the file here. Note you'll need to link it into the documentation somewhere. CUSTOMCSS.md

The documentation is now available here and there are references to that url in the README and next to the custom CSS editor. Thank you!