Discourse/discourse
Discourse/discourse
0
0
Fork 0
mirror of https://github.com/discourse/discourse.git synced 2026-08-09 21:45:25 +08:00
Code Packages Activity Actions
discourse/.skills/discourse-writing-html-css
History
Exact
Kris 7f1cff822f
 FEATURE: LLM skills for writing HTML and CSS (#40410) 
This attempts to define some useful rules for LLMs to write better HTML
and CSS for Discourse... the basics covered include:

**Naming (BEM)**
- `block__element` + standalone `.--modifier` (two-dash); `is-`/`has-`
state classes
  - Name by meaning, not appearance (no position/color/size in names)
  - Don't interpolate user input into class names — use data attributes
  - Prefer a state class over `:has()`

  **Color & theming**
- Never hardcode color; use the custom-property palette; no separate
dark-mode block
- `--token-color-*` for standard UI, palette for bespoke; `--d-*` design
vars
  - Don't rely on color alone; WCAG AA contrast; forced-colors awareness

  **CSS authoring**
- Native CSS over compile-time SASS; keep `z()`, `lib/viewport`, `&`
nesting
  - Low specificity; avoid `!important` (comment when unavoidable)
  - `em`/`rem` + flexible sizing + `overflow-wrap`; `gap` over margins
- Local custom properties for reuse/`calc()`; mobile-first, intrinsic
layout
  - RTL via logical properties
  - Shared mixins (`ellipsis`, `line-clamp`, `d-animation`)
  - Style with restraint — minimal styling, leave aesthetics to themes

  **Accessibility**
  - Semantic/landmark markup; heading levels by outline
- Icon-only labels; `.sr-only` (not `display:none`); live regions via
the `a11y` service
- `:focus-visible`; `prefers-reduced-motion`; animate
`transform`/`opacity`
  - Design to work without hover

  **Templates**
- Escape by default (XSS); `dIcon` with valid sprite icons; translatable
strings
- `<DButton>` variants; FormKit for forms; `...attributes` on root;
`dConcatClass`
- `<PluginOutlet>` (don't add speculatively); avoid div-itis & empty
containers

  **Stylesheet placement**
- `common/` responsive stylesheets (`desktop/`/`mobile/` deprecated);
plugin/theme registration
  - Lint with `bin/lint --fix`
  
Also fixed an issue with two docs having the same index and cleaned up
some references to align better.
2026-06-01 11:08:46 -04:00
..
references FEATURE: LLM skills for writing HTML and CSS (#40410) 2026-06-01 11:08:46 -04:00
SKILL.md FEATURE: LLM skills for writing HTML and CSS (#40410) 2026-06-01 11:08:46 -04:00