We have a great theme system, but we don't always make full and proper use of it from the developer side and the themer side is underdocumented. I propose we improve this situation by writing guidelines:
- When to use themable functions; building on How to write themable modules.
- What PHP is allowed in a themable function and what is not. Somewhere between
db_query()there is a hard line to be drawn.
- Notes on accessibility
- What HTML is best, including
- What CSS is best (current convention: as little as possible, but usable without extra CSS)
For every themable function, document:
- What the function does
- What variables go in
- What the expected output should contain, including required and recommended classes and ids for HTML elements
- When it will be used and in what context (for example- block or inline in HTML)
Using these guidelines and documentation we can attack theming annoyances at the root cause and fix the bugs in the default themable functions in Drupal core and contributed modules.