Skip to content

Themes 3.0 / Pleroma ISS (Interface Style Sheets) [Side A]

HJ requested to merge themes3 into develop

This is a massive themes rework. There's a paradigm shift - previously we just had "slots" that were loosely tied to each other in a confusing way, which was an increasing pain in the ass to maintain - we had to add a new color slot for each possible placement/state/variant combination and things often weren't consistent, as a result the text color automation would often mistakenly assign wrong color.

New approach closely resembles CSS - now we have "rules" that consist of "selectors" and "directives", however selectors work on developer-defined "components" instead of HTML elements and directives are quite different from CSS. Just like CSS rules "cascade", i.e. more specific rules inherit from less specific rules. Right now specificity is only defined by amount of nesting of the components + some hard-coded inheritance between variants/states. All of this is computed into set of actual CSS rules.

Components are defined by the developer and consist of:

  • CSS selector
  • Variants definitions - let you have different variants of same component, i.e. "danger" button, "submit" button etc. Mutually exclusive
  • States definitions - primarily used for stateful components (buttons, inputs, etc.) those are not mutually exclusive (for now, limitations are planned) and all possible combinations are calculated, even those that possibly don't make sense.
  • Default rules - serve as "default theme"
  • List of valid inner components - this is similar to how LAYERS were in themes 2.0 - it lets developer define which components can contain other components, and framework will generate all possible combinations of all placements and states.

This gives following advantages:

  • Less messy code, no need to write color slots for every occasion.
  • More consistent application style - every component placement, state and variant is automatically accounted for.
  • Cleaner and more consistent CSS (mostly) - you only need to define colors, radii, shadows etc once where they are actually used in CSS without writing all of the state/variant stuff again.
  • More powerful and easier style definitions:
    • Themes can override cases which original theme didn't account for, including different styles for themes
      • For instance Windows 95 (Redmond XX) theme can add style to the "unstyled" buttons in panel headers.
    • Theme makers can use same tools as developers, instead of using color functions in JS those are now declared as text, so it's very much possible to have separate color scheme and interface style (think Breezy themes with different colors except for every theme)
    • Some basic color slots will remain and will be used as "palette", with planned ability to add custom style-specific slots to palette for user to adjust.
  • Easier visual tweaks - we could add commonly used "tweaks" like making underlay transparent or forcing certain roundness by adding or removing extra rule to the ruleset, no need to write extra code.
  • More coherent and less busy editor (eventually)


  • Themes 3.0 are way more complex internally (i'm literally accidentally reinventing CSS) and maintaining the "core" might prove difficult.
  • Despite it being "CSS-like" there might be a learning curve to it.
    • and i mean, i'm probably weird that I like and understand CSS, but for most people something being "like CSS" might be more of a downside than an upside
  • The sheer number of all possible cases - all placements, states, variants is a formidable number, so computing takes some time, even if computing the most simplest element of it takes 1ms it is multiplied by thousands.
    • can be optimized



  • Button
    • Add "floating button" for mobile button
  • Input
    • Fix issues with checkboxes/radios
  • Panel
  • PanelHeader
  • Status
    • Add "selected status" support
  • Notification
  • RichContent
  • Underlay
  • Popovers
  • Modals (layer)
  • Menu item
  • TopBar
  • Avatar
  • Badge
  • Alert
  • Tabs
  • Chat messages
  • Mobile stuff (?)
  • Scrollbars (?)
  • Attachments
  • Polls
  • Dynamic slots


  • text color (via virtual components)
  • background
    • Make it non-mandatory (assume transparent)
  • shadows
  • fonts
  • radii/roundness


  • cascading
  • Backward compat

Moved to Side B:

  • gradients (probably just gonna be custom directives like fonts are)
  • PISS syntax (too much hassle right now)

Known bugs:

  • Global notices looks weird and have badly styled close buttons
  • Video attachments somehow for whatever reason have button-unstyled class, giving them background of the buttons
  • Some of the "Replies:" links have incorrect color
  • Un-collapsed notifications still have faint links (should probably retire the .faint class in general)
  • Counter on "show new" in mobile view isn't styled
  • Chats list has fallback backgrounds on hover
  • Panel footer has fallback background
  • Chat list counters broken
  • Dropdown menus are inconsistent and autosuggest is even more so (2.0?)
  • Toggled buttons have bad hover effect/color and bad text color (2.0)
  • Settings modal "Settings saved" notice has a scrollbar
  • No Firefox scrollbar color (is it even needed? use --bg fallback?)
  • Scrollbar background color should be different
  • No wallpaper color
  • Scrollbar has white corner when scrolling is allowed in both dimensions
  • Polls radios (and checkboxes?) borked
  • Lists have hover effect even if they are not directly actionable (followers list; mutes/blocks should (de)select item)
  • Active (scope selector, nav pins) unstyled buttons are not getting active text color (unstyled buttons don't have "active" state?)
  • Breezy themes have broken sticky panel headers
  • Unicode emoji are smol in autocomplete
  • "+N more" in MentionsLine doesn't have the -link
  • Poll options take too much space
  • Tests need updates
  • Post popovers don't look so good
  • Dialog boxxes (delete status) lack styles (on separate layer from popovers AND settings modals)
  • Unstyled buttons active+hover states somewhat broken again
Edited by HJ

Merge request reports