Skip to content

docs: cover unspoken rules - #2005

Draft
uncenter wants to merge 1 commit into
mainfrom
docs/unspoken-rules
Draft

docs: cover unspoken rules#2005
uncenter wants to merge 1 commit into
mainfrom
docs/unspoken-rules

Conversation

@uncenter

@uncenter uncenter commented Nov 28, 2025

Copy link
Copy Markdown
Member
  • Links
  • System elements

@uncenter uncenter changed the title docs: add section on reviewing userstyles docs: cover unspoken rules Nov 28, 2025
@WalkQuackBack WalkQuackBack self-assigned this Nov 28, 2025
@WalkQuackBack WalkQuackBack added the 0.kind: meta Repository-wide issues label Nov 28, 2025
@uncenter

Copy link
Copy Markdown
Member Author

@WalkQuackBack's "list of things that should probably be clarified":

  1. How to handle shadows (e.g. text shadows, box shadows). This seems to be inconsistent across the board.
  2. When is it appropriate to use !important vs having a more specific selector for code clarity?
  3. Hover, active and focus states. How much should they be lightened or darkened by? Should these be standardized into the library? In theory, tints and shades should help with this, but a solution should be had in the meantime.
  4. Faded backgrounds such as diff code added/removed. Should the fade or mix amount on this be standardized?
  5. Application of mixin: way it should be applied. As an example, some userstyles do body:not(.dark) and body.dark or [data-theme=鈥渓ight鈥漖 and [data-theme=鈥渄ark鈥漖 while others do body and body.dark or mroot and &[data-theme=鈥渄ark鈥漖.
  6. Encourage using mixins for repetitive code
  7. Specify how apps with colour ramps should be bound to Catppuccin. Atp, this is all over the place.
  8. How should semi-transparent backgrounds be handled?
  9. Userstyles should prefer using attribute selectors over generated classes. I am personally not a fan of using localization specific selectors though.
  10. Usage of vendor prefixes and experimental/not baseline features should be mentioned.

@WalkQuackBack WalkQuackBack added the 0.kind: documentation Documentation content or website label Jan 3, 2026
@uncenter

uncenter commented Jan 7, 2026

Copy link
Copy Markdown
Member Author

Related: #2046.

@uncenter uncenter mentioned this pull request Jan 8, 2026
16 tasks
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

0.kind: documentation Documentation content or website 0.kind: meta Repository-wide issues

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants