Skip to content

A platform for community discussion. Free, open, simple.

FEATURE: LLM skills for writing HTML and CSS (#40410)

Kris7f1cff822f55
diff --git a/.skills/discourse-writing-html-css/SKILL.md b/.skills/discourse-writing-html-css/SKILL.md
new file mode 100644
index 00000000000..cb821fdcea1
--- /dev/null
+++ b/.skills/discourse-writing-html-css/SKILL.md
@@ -0,0 +1,381 @@
+---
+name: discourse-writing-html-css
+description: Write HTML and CSS/SCSS for Discourse core, plugins, themes, and theme components. Use when authoring or modifying templates (.gjs/.hbs), stylesheets (.scss), component markup, or class names. Covers Discourse's BEM-with-standalone-modifiers naming, the CSS custom-property color palette (theming + dark mode), template/HTML conventions, and where stylesheets live.
+---
+
+# Writing HTML & CSS for Discourse
+
+Discourse styles must survive conditions the author never sees: a **theme** restyling the
+component, **light/dark color schemes**, any **viewport** width, and **screen-reader** users
+navigating the markup. A component is correct only when it holds up across all of them.
+
+Two CSS rules are the most load-bearing — get them right by reflex:
+
+1. **Name classes with BEM** so themes can target and override cleanly.
+2. **Never hardcode color** — pull from the CSS custom-property palette so themes and dark
+ mode work for free.
+
+These rules operationalize Discourse's documented frontend philosophy — **mobile-first,
+progressive enhancement (works without hover or JS), a themeable base layer, and a shared design
+system over bespoke styling.** The two source-of-truth docs are
+[`25-css-guidelines-bem.md`](../../docs/developer-guides/docs/03-code-internals/25-css-guidelines-bem.md)
+(naming) and
+[`27-designing-for-devices.md`](../../docs/developer-guides/docs/03-code-internals/27-designing-for-devices.md)
+(responsive / device adaptation). The canonical real-world example is the chat loading skeleton —
+[`plugins/chat/assets/javascripts/discourse/components/chat-skeleton.gjs`](../../plugins/chat/assets/javascripts/discourse/components/chat-skeleton.gjs)
+and its `.scss`.
+
+**Deeper detail lives in companion files — read the relevant one before working in that area:**
+
+- [references/color-and-theming.md](references/color-and-theming.md) — full palette, semantic
+ tokens, `--d-*` design vars.
+- [references/layout-and-responsive.md](references/layout-and-responsive.md) — intrinsic layout
+ and the `lib/viewport` breakpoint API.
+- [references/css-authoring.md](references/css-authoring.md) — native-CSS-vs-SASS swaps, local
+ custom properties (incl. theme interaction), shared mixins.
+- [references/accessibility.md](references/accessibility.md) — screen-reader-only text, live-region
+ announcements, contrast & forced-colors detail (the short a11y rules stay inline below).
+
+## BEM naming (block / element / modifier)
+
+Discourse uses a **modified BEM**: standard `block__element`, but modifiers are **standalone
+classes**, not `block__element--modifier` suffixes.
+
+| Part | Syntax | Example |
+| --- | --- | --- |
+| Block | `.block` | `.chat-skeleton`, `.d-button` |
+| Element | `.block__element` | `.chat-skeleton__message`, `.header__item` |
+| Modifier | `.--modifier` (standalone) | `.--cancel`, `.--animation`, `.--error` |
+| State | `.is-foo` / `.has-foo` | `.is-open`, `.has-errors` |
+
+- **One block per reusable component.** A distinct block-level class per Ember component, then
+ hang elements and modifiers off it. Blocks may nest inside blocks.
+- **An element** is a part with no meaning outside its block. Elements do **not** chain
+ (`block__el1__el2` is wrong — use `block__el2`); the skeleton uses flat `__message`,
+ `__message-avatar`, `__message-text`.
+- **A modifier** is a standalone `.--modifier` for appearance variants (not the verbose
+ `block__element--modifier`) — they're often reused, and it keeps the DOM readable.
+- **State prefixes** `is-`/`has-` mark a condition driven by JS or interaction (`is-open`,
+ `has-errors`), as opposed to a design variant (`--cancel`).
+- **Prefer adding a class over the CSS `:has()` selector.** If a component already knows its own
+ state, express it with a class (`is-open`, a `--modifier`) rather than `:has()`, which can be
+ costly (re-evaluated on DOM mutations; broad/nested selectors are worst). Reserve `:has()` for
+ when you can't add a class — e.g. styling a parent off cooked/third-party markup — and scope it
+ tightly.
+
+### Dash convention
+
+Use **two dashes**: `.--modifier`. This is the documented standard and dominates the codebase.
+Legacy **single-dash** modifiers exist (`.-animation` in the chat-skeleton predates the
+convention) — don't copy them in new code, and don't mass-rename existing ones unless that's
+the task.
+
+### Name by meaning, not appearance
+
+Class names describe **what a thing is**, never **how it looks** — a presentational name
+becomes a lie the moment a theme, redesign, or responsive reflow changes the appearance, and
+you can't rename it without hunting down every override. Avoid:
+
+- **Position** — `block-right` → `block__sidebar`, `block__actions`.
+- **Color** — `warning-red` / `text-blue` → `block--warning`, `block__link`.
+- **Size** — `box-300px`, `text-large` → `block__panel`, `--prominent`.
+
+Same for modifiers: `.--danger` / `.--compact` (intent), not `.--red` / `.--narrow`
+(appearance).
+
+### Don't build class names from user input
+
+Never interpolate a user-controlled value (group/category/tag name, username, custom field)
+directly into a class — they collide with generic utility/state classes (a group named "hidden"
+emits `class="hidden"` and silently inherits its rules, often `display: none`) and make
+unpredictable selectors. Carry the value in a **data attribute** and target it with an attribute
+selector:
+
+```hbs
+{{! BAD — a group named "hidden" becomes class="hidden" }}
+<span class="group-badge {{@group.name}}">…</span>
+
+{{! GOOD — namespaced in an attribute, can't collide }}
+<span class="group-badge" data-group-name={{@group.name}}>…</span>
+```
+
+```scss
+.group-badge[data-group-name="staff"] { color: var(--tertiary); }
+```
+
+If a class is genuinely required (an existing theme hook), **prefix it** (`group-#{name}`,
+`category-#{slug}`) and prefer slugs over free-text. These values still need normal escaping
+for safety — see the XSS note under HTML conventions.
+
+### Nesting & modifier application
+
+Nest elements under the block with SCSS `&`. A modifier can apply **directly** on an element
+(`&.--modifier`) or **indirectly** from an ancestor (`.--modifier &`) — the latter keeps the
+DOM clean when many children react to one condition (e.g. one `--error` on the block):
+
+```scss
+.composer {
+ &__input {
+ &.--disabled { … } // <input class="composer__input --disabled">
+ .--error & { border-color: var(--danger); } // <div class="composer --error"> … </div>
+ }
+}
+```
+
+## Color & theming — never hardcode
+
+**Do not write hex, `rgb()`, or named colors for UI surfaces, text, or borders.** Use the CSS
+custom-property palette so the result adapts to every theme and color scheme:
+
+```scss
+// BAD — breaks theming and dark mode
+.notice { color: #222; background: #fff; border: 1px solid #ddd; }
+
+// GOOD — adapts to every theme and color scheme
+.notice { color: var(--primary); background: var(--secondary); border: 1px solid var(--primary-low); }
+```
+
+**Do not author a separate dark-mode block.** The palette already inverts; if something looks
+wrong in dark mode you picked the wrong palette variable, not the wrong color.
+
+**Prefer the semantic `--token-color-*` tokens for standard UI** (text, surfaces, borders,
+icons); reach into the raw palette for bespoke components a token doesn't cover. Most-used
+palette vars: `--primary` (text/foreground, with `-low`…`-high` and `-100`…`-900` steps),
+`--secondary` (background), `--tertiary` (accent/links), `--danger`/`--success`, and
+`rgba(var(--x-rgb), …)` for translucency. Full palette, tokens, and `--d-*` design vars:
+[references/color-and-theming.md](references/color-and-theming.md).
+
+**Don't rely on color alone, and mind contrast.** Never signal state or meaning by color by
+itself (a red border for an error, a green dot for "online") — pair it with an icon, text, or
+shape so it's perceivable to colorblind users and in forced-colors mode. Stick to the palette's
+intended foreground/background pairings (text in `--primary` on a `--secondary` surface, etc.),
+which are contrast-tuned per scheme; don't invent low-contrast combinations like `--primary-low`
+text on `--secondary`. WCAG AA targets and forced-colors/WHCM notes:
+[references/accessibility.md](references/accessibility.md).
+
+## Style with restraint
+
+Discourse is a highly themeable platform: core and plugin styles are a **base that theme
+authors build on**, and anything you over-style is something they then have to override or
+undo. Aim for the minimum that makes a component clear and functional, and leave the aesthetics
+to themes.
+
+- **Style for structure and function, not decoration.** Layout, spacing, sizing, and states
+ (hover/focus/disabled) — yes. Decorative flourishes that aren't core to the component's
+ meaning (drop shadows, gradients, custom borders, bespoke typography) are opinions a theme may
+ not share — leave them out.
+- **When a visual choice isn't load-bearing, it probably belongs in a theme, not core.** A
+ plainer component a theme can dress up beats a heavily-styled one a theme must strip down. When
+ in doubt, do less.
+- It's the *why* behind several rules here — palette/tokens over fixed values, low specificity,
+ override hooks (`...attributes`, local `--custom-properties`) — so themes can adjust without
+ fighting your CSS.
+
+## Browser support
+
+Discourse targets the **latest stable releases** of Edge, Chrome, Firefox, and Safari
+(including iOS 16.4+) — no IE, no legacy polyfills. Use modern CSS freely; the practical floor
+is the oldest still-"latest-stable" Safari, so for a very new feature confirm Safari support
+(Baseline "widely available" is a safe bar).
+
+## Native CSS first
+
+Discourse is gradually moving toward native CSS — when a native feature does the job, prefer it
+over a compile-time SASS construct (`var(--…)` over `$variables`, `clamp()` over `sass:math`,
+`light-dark()` over SCSS color functions, `var(--font-up-2)` over the `$font-up-2` alias).
+**But keep the established helpers** — `z("header")`, the `lib/viewport` mixins, `&` nesting.
+Full swap list + rule-of-thumb: [references/css-authoring.md](references/css-authoring.md).
+
+## CSS best practices
+
+- **Keep specificity low.** Target by **one class**, not deep descendant chains
+ (`.card__title`, not `.card .body h2`). Don't style by ID or over-qualify (`div.card` →
+ `.card`). **Avoid `!important`** — it usually signals a specificity fight you can solve by
+ simplifying the selector. When it's genuinely necessary (overriding inline styles or a
+ third-party rule), always add a comment saying why.
+
+- **Units & flexible sizing.** Prefer `em`/`rem` over `px` so the UI scales with the user's
+ adjustable base font size (`px` is fine for hairline borders). Avoid fixed heights/magic
+ dimensions — let content size the box (translated strings and long usernames run longer than
+ English); prefer `min-`/`max-` over hard `height`/`width`. Use **`gap`** for flex/grid spacing,
+ not per-child margins. On user-generated text (titles, usernames, URLs), add
+ `overflow-wrap: anywhere` so a long unbroken string can't force horizontal scroll.
+
+- **Local custom properties.** Hoist a value to a component-scoped `--property` when it's reused
+ or feeds a `calc()` (the name documents the math better than a magic number). Don't promote
+ every value reflexively. Full pattern + theme interaction:
+ [references/css-authoring.md](references/css-authoring.md).
+
+- **Right-to-left: use logical properties.** Write `margin-inline`, `padding-inline`,
+ `inset-inline-start`/`-end`, `border-start-*`, `text-align: start`/`end` — not `left`/`right`
+ or `margin-left`. New code defaults to these and avoids a separate `_rtl.scss`. Legacy code
+ uses physical props + `_rtl.scss`; don't mass-convert, but don't add new physical-direction
+ rules either.
+
+- **Motion & focus (a11y).** Gate non-essential animation behind
+ `@media (prefers-reduced-motion: no-preference)` (the chat-skeleton shimmer does this). Animate
+ **cheap properties** — `transform` and `opacity` are GPU-composited; animating layout
+ properties (`width`, `height`, `top`/`left`, `margin`) triggers reflow and causes jank. Never
+ `outline: none` without a replacement — use **`:focus-visible`** so keyboard users get a clear
+ ring while it stays hidden for mouse clicks.
+
+- **Reuse the shared mixins** (`common/foundation/mixins.scss`): `ellipsis` / `line-clamp($n)`
+ for truncation, `d-animation` (bakes in reduced-motion), `unselectable`. Details and the
+ legacy ones to skip: [references/css-authoring.md](references/css-authoring.md).
+
+## HTML / template conventions
+
+Discourse templates are **`.gjs`** (Glimmer components with inline `<template>`) or `.hbs`.
+
+- **Escape by default.** Use `{{value}}` (escaped). Never `{{{value}}}` / triple-curlies or raw
+ `innerHTML` for user-derived content — that's an XSS hole. Trusted HTML must be explicitly
+ marked (`trustHTML` / `htmlSafe`) and only for content you control.
+- **Icons** come from the `dIcon` helper, never inline SVG or `<i class="fa">`:
+
+ ```gjs
+ import dIcon from "discourse/ui-kit/helpers/d-icon";
+ // …in <template>: {{dIcon "chevron-left"}}
+ ```
+
+ Use a **real icon name** — icons render from Discourse's registered SVG sprite (a subset of
+ Font Awesome), not arbitrary names. Don't guess; if a plugin needs an icon outside the subset,
+ register it (`register_svg_icon` in `plugin.rb`).
+
+- **Icon-only controls need an accessible label.** An icon conveys nothing to a screen reader,
+ so a control with only an icon must carry a label: on `<DButton>` use `@title` (an i18n key —
+ also a tooltip) or `@ariaLabel`, or `@translatedTitle` for pre-translated text; on raw markup,
+ a translated `aria-label`. A button with visible text doesn't need this. (`dIcon` renders the
+ glyph `aria-hidden` by default — the accessible name belongs on the control, not the icon.)
+- **Screen-reader-only text uses `.sr-only`, not `display: none`.** For text that should exist
+ for assistive tech but not show on screen (a label for an icon-only region, a skip target), use
+ the `.sr-only` helper — `display: none`/`visibility: hidden` remove it from the accessibility
+ tree. See [references/accessibility.md](references/accessibility.md).
+- **Announce dynamic content via the `a11y` service — never a hand-rolled `aria-live`.** Content
+ that appears without a page navigation (async results, a toast, inline validation) needs
+ `this.a11y.announce(message, "polite" | "assertive")` to be read out. Live regions only work
+ when **persistent in the DOM before the change** — which is exactly why you route through the
+ service rather than adding an `aria-live` element alongside the new content. Details and the
+ why: [references/accessibility.md](references/accessibility.md).
+- **All display strings are translatable.** Pull copy through `i18n(...)`; never hardcode
+ user-facing English. Use placeholders for interpolation — never concatenate translated
+ fragments. Write strings in **"Sentence case"**.
+- **Semantic, accessible markup.** Reach for the element that describes the content before a
+ generic `<div>`/`<span>`:
+ - **Landmarks & sectioning** — `<nav>`, `<header>`/`<footer>`, `<main>`, `<aside>`,
+ `<section>`/`<article>` expose landmarks and an outline screen-reader users navigate by; a
+ wall of `<div>`s gives them nothing to jump between. `<ul>`/`<ol>` + `<li>` for lists,
+ `<table>` only for tabular data.
+ - **Interactive & form** — real `<button>` for actions (not a clickable `<div>`), `<a>` for
+ navigation, `<label>` tied to its input, `<fieldset>`/`<legend>` for groups.
+ - Add `alt`/`aria-*` only to fill gaps native semantics can't — don't paper over a wrong
+ element with ARIA. And don't add `<section>`/`<nav>` purely as styling hooks where they
+ carry no role; a `<div>` is honest there.
+ - Prefer existing `<DButton>` and other shared components — they get semantics and a11y right.
+- **`<DButton>` style variants — only when it should look like a button.** Use the shared
+ variant via `@class` (`btn-default`, `btn-primary`, `btn-danger`, `btn-flat`/`btn-transparent`,
+ `btn-small`) rather than restyling from scratch. Don't apply them to non-button-looking
+ controls (you'll override more than you saved), and don't fight a `<DButton>` into a shape it
+ resists — a plain semantic `<button class="my-thing">` is cleaner there. Variant when
+ button-shaped, naked button when not.
+- **Use FormKit for forms — don't roll your own.** Build forms with the `<Form>` component
+ (`import Form from "discourse/components/form"`), which yields field/row/submit pieces
+ (`<form.Field>`, `<form.Row>`, `<form.Submit>`) and handles layout, validation, state, and the
+ label/error/a11y wiring for you. Don't hand-assemble a raw `<form>` with manual `<input>`s and
+ bespoke validation. See
+ [`docs/developer-guides/docs/03-code-internals/21-form-kit.md`](../../docs/developer-guides/docs/03-code-internals/21-form-kit.md)
+ (`frontend/discourse/app/form-kit`).
+- **Splat `...attributes` on the component's root element** so a caller can pass a class,
+ `data-*`, `aria-*`, or a `--modifier` through. Without it the component is a closed box. The
+ root is also where the BEM block class lives: `<div class="user-card" ...attributes>`.
+- **Use `dConcatClass` for conditional/computed classes** instead of hand-built strings or
+ stacked inline `{{if}}`s (`import dConcatClass from "discourse/ui-kit/helpers/d-concat-class"`).
+ It drops falsy values cleanly:
+
+ ```gjs
+ <div class={{dConcatClass "card" (if @selected "is-selected") (if @compact "--compact")}}>
+ ```
+
+- **Know `<PluginOutlet>`, but don't add outlets speculatively.** Outlets are named seams where
+ plugins/themes inject content (400+ across the app); you'll work inside them often. Each one is
+ a **public API surface and maintenance commitment** — once it exists, extensions depend on its
+ name and `@outletArgs`, so it can't be moved freely. Add one only for a concrete need; pass
+ data via `lazyHash` (not `hash`) and name it by location (`above-…`, `below-…`). See
+ [`13-plugin-outlet-connectors.md`](../../docs/developer-guides/docs/03-code-internals/13-plugin-outlet-connectors.md).
+- **Heading levels follow the document outline, not type size.** Never pick a level for its
+ default font size — if the right heading looks wrong-sized, style it in CSS
+ (`font-size: var(--font-up-1)`). An `<h1>` styled smaller is fine; an `<h3>` chosen because
+ you wanted smaller text is not.
+- **Avoid "div-itis" — no wrapper without a job.** Pick the right element (`<span>` inline,
+ `<div>` for a block/structural container, a semantic element where one fits), and add one only
+ when it earns its place: its own `max-width`, a positioning context, a scroll area, or a real
+ semantic region. A stray wrapper between a flex/grid parent and its children breaks layout — the
+ items stop being direct children, so `gap`/`flex`/`grid-template` no longer reach them. No
+ style, role, or layout reason → delete it.
+- **Components clean up after themselves — don't render empty containers.** If a container's
+ contents are conditional, put the container inside the condition so it isn't emitted when
+ empty — an empty-but-present element still counts as a flex/grid item and `gap` slot, leaving
+ a phantom gap:
+
+ ```hbs
+ {{! GOOD — nothing emitted when there's nothing to show }}
+ {{#if @actions}}
+ <div class="card__actions">
+ {{#each @actions as |action|}}<DButton @action={{action}} />{{/each}}
+ </div>
+ {{/if}}
+ ```
+
+ Likewise, **don't put `padding`/`margin`/`gap` on a container that can render empty** — that
+ reserves space with no content. And **don't lean on `:empty`** to hide it: Ember leaves
+ whitespace/comment nodes (`<!---->`) that make `:empty` fail to match, so it silently won't
+ apply. The template conditional is the only reliable guard.
+- **No empty backing class** for a template-only component unless explicitly requested.
+- Don't add JSDoc to new code; if editing code that already has it, keep it accurate.
+
+## Where stylesheets live
+
+Core stylesheets are under `app/assets/stylesheets/`. Place a partial by target, then register
+it in the matching `_index.scss` / parent `@import` (partials are underscore-prefixed and
+**not** auto-globbed).
+
+| Path | Applies to |
+| --- | --- |
+| `common/base/` | **Where new styles go** — one responsive stylesheet for all viewports |
+| `common/components/` | Reusable component styles |
+| `desktop/` | **Legacy desktop-only** — don't add new styles here |
+| `mobile/` | **Legacy mobile-only** — don't add new styles here |
+| `*_rtl.scss` | Legacy RTL overrides — new code uses logical properties instead |
+
+- **Write one responsive stylesheet, not desktop + mobile copies.** Discourse designs
+ **mobile-first** and enhances upward (see the philosophy doc,
+ [`27-designing-for-devices.md`](../../docs/developer-guides/docs/03-code-internals/27-designing-for-devices.md)):
+ new styles live in `common/` and adapt with breakpoints. **Prefer intrinsic layout** (e.g.
+ `grid-template-columns: repeat(auto-fill, minmax(14em, 1fr))`) and reach for a breakpoint only
+ to *restructure*; use the `lib/viewport` mixins (`viewport.from`/`until`/`between`). The legacy
+ device split — the `desktop/`/`mobile/` dirs, the `.mobile-view`/`.desktop-view` classes, and
+ `site.mobileView` in JS — is **deprecated**; don't use it. Details, breakpoints, and the
+ `capabilities` service: [references/layout-and-responsive.md](references/layout-and-responsive.md).
+- **Design to work without hover.** Touch users can't hover, so hover is an *enhancement*, not a
+ requirement — nothing essential should be hover-only. When you do add hover styling, scope it
+ to `html.discourse-no-touch` (see the layout reference).
+- `common/foundation/variables.scss` and `mixins.scss` are injected everywhere — that's where
+ layout-width vars and `z()` come from. (Font sizes/line-heights are native custom properties —
+ `var(--font-up-2)`, `var(--line-height-medium)`.)
+
+### Plugins & themes
+
+- **Plugin** styles live in `plugins/<name>/assets/stylesheets/` and are registered in
+ `plugin.rb`: `register_asset "stylesheets/common/my-feature.scss"` (optionally `, :desktop` /
+ `, :admin`).
+- **Themes/components** ship `common/`/`desktop/`/`mobile/` SCSS compiled with the palette
+ injected — the same `var(--…)` and `$…` variables are available, so color, BEM, and native-CSS
+ rules apply identically. The same responsive-first rule holds: put new styles in `common/`.
+
+## Before committing
+
+Lint every changed file (CSS via stylelint, templates via the JS toolchain):
+
+```sh
+bin/lint --fix path/to/file.scss path/to/file.gjs
+bin/lint --fix --recent # all recently changed files
+```
diff --git a/.skills/discourse-writing-html-css/references/accessibility.md b/.skills/discourse-writing-html-css/references/accessibility.md
new file mode 100644
index 00000000000..637095e47a9
--- /dev/null
+++ b/.skills/discourse-writing-html-css/references/accessibility.md
@@ -0,0 +1,78 @@
+# Accessibility reference
+
+Companion to the accessibility rules in `SKILL.md`. The short, point-of-use rules stay inline
+there — semantic/landmark markup, icon labels, focus (`:focus-visible`), motion
+(`prefers-reduced-motion`), and "don't rely on color alone." This file holds the deeper
+mechanics: screen-reader-only text, announcing dynamic changes via live regions, and the
+contrast / forced-colors detail.
+
+## Screen-reader-only text — `.sr-only`
+
+When text should exist for assistive tech but not show on screen — extra context, a label for
+an icon-only region, a skip target — use the `.sr-only` utility (defined in
+[`app/assets/stylesheets/common/foundation/helpers.scss`](../../../app/assets/stylesheets/common/foundation/helpers.scss)).
+It positions the text off-screen and clips it to a 1px box while keeping it in the
+accessibility tree.
+
+Do **not** use `display: none` or `visibility: hidden` for this — both remove the element from
+the accessibility tree, so screen readers never announce it. `.sr-only` is the only correct way
+to hide-visually-but-keep-for-AT.
+
+```hbs
+<button type="button">
+ {{dIcon "trash-can"}}
+ <span class="sr-only">{{i18n "post.controls.delete"}}</span>
+</button>
+```
+
+## Announcing dynamic content — live regions
+
+When content appears or a value changes without a full page navigation (async search results, a
+toast, an inline validation message, a "saved" confirmation), a screen reader won't notice
+unless the change happens inside an ARIA live region it is *already* observing. Discourse handles
+this with a dedicated service plus a persistent set of regions.
+
+**Announce through the `a11y` service** — never hand-roll an `aria-live` element:
+
+```js
+import { service } from "@ember/service";
+// …in the component/service:
+@service a11y;
+// …
+this.a11y.announce(i18n("search.results_count", { count }), "polite");
+this.a11y.announce(i18n("errors.something_failed"), "assertive", 3000);
+```
+
+`announce(message, type = "polite", clearDelay = 2000)`:
+
+- `type` — `"polite"` waits for the screen reader to finish what it's saying (use for most
+ updates); `"assertive"` interrupts (reserve for errors / urgent state).
+- `message` must be a string; the region auto-clears after `clearDelay` ms.
+
+**Why it must go through the service:** a live region only announces changes to a region the
+screen reader was already observing. The regions are mounted app-wide and stay in the DOM — see
+[`components/a11y/live-regions.gjs`](../../../frontend/discourse/app/components/a11y/live-regions.gjs),
+which renders persistent `#a11y-announcements-polite` (`role="status"`) and
+`#a11y-announcements-assertive` (`role="alert"`) containers, and the service just updates their
+text. If you instead add an `aria-live` element to the DOM at the same moment you fill it with
+content, it typically **won't** announce — the region has to exist *before* the change and
+persist. So never create per-message live regions; route everything through the service.
+
+## Color, contrast & forced colors
+
+The inline rule (in `SKILL.md`): don't signal meaning by color alone, and use the palette's
+contrast-tuned pairings. The detail:
+
+- Aim for **WCAG AA** contrast — 4.5:1 for normal text, 3:1 for large text and meaningful
+ UI/graphical boundaries. The palette's intended foreground/background pairings already clear
+ this; you get into trouble by improvising (e.g. `--primary-low` or `--primary-medium` text on
+ a `--secondary` surface).
+- **Don't convey state by color alone** — colorblind users and forced-colors mode won't perceive
+ it. Pair color with an icon, text label, underline, or shape.
+- **Forced colors / Windows High Contrast (WHCM).** Under `@media (forced-colors: active)` the OS
+ replaces your colors with a limited system palette, so don't depend on a background or border
+ color to carry meaning, and don't `outline: none` (the system outline may be the only focus
+ cue). Most components inherit sensible behavior — only reach for `forced-color-adjust` or a
+ `@media (forced-colors: active)` override for genuine breakage. See
+ [`common/whcm.scss`](../../../app/assets/stylesheets/common/whcm.scss) and the forced-colors
+ blocks in `common/components/buttons.scss` for precedent.
diff --git a/.skills/discourse-writing-html-css/references/color-and-theming.md b/.skills/discourse-writing-html-css/references/color-and-theming.md
new file mode 100644
index 00000000000..22ce54b4ba1
--- /dev/null
+++ b/.skills/discourse-writing-html-css/references/color-and-theming.md
@@ -0,0 +1,103 @@
+# Color & theming reference
+
+Companion to the **Color & theming** section of `SKILL.md`. The cardinal rule lives there:
+never hardcode color, and never write a separate dark-mode block — the palette inverts. This
+file is the variable inventory.
+
+All variables are defined in
+[`app/assets/stylesheets/color_definitions.scss`](../../../app/assets/stylesheets/color_definitions.scss)
+and remapped per color scheme, so the same variable is dark in dark mode and matches any
+theme's palette.
+
+## The core palette
+
+Each base color has a graduated scale blending it toward its opposite (`-low` is closest to
+the background, `-high` closest to the foreground), plus numeric steps `-50`…`-900`.
+
+| Variable family | Use for |
+| --- | --- |
+| `--primary` / `--primary-low` … `--primary-high`, `--primary-100`…`--primary-900` | Main text and foreground; low steps for subtle borders/backgrounds |
+| `--secondary` | Main background / surface |
+| `--tertiary` (+ scale) | Accent, links, primary actions |
+| `--quaternary` | Secondary accent for themes |
+| `--danger`, `--success`, `--love`, `--highlight` (each + `-low`/`-medium`/`-hover`) | Semantic states |
+| `--header_background`, `--header_primary` | Header surface and its text |
+| `--d-hover`, `--d-selected` | Hover / selected affordances |
+
+Need a translucent color? Use the `-rgb` triplet variants inside `rgba()`:
+
+```scss
+background: rgba(var(--tertiary-rgb), 0.1);
+```
+
+## Semantic design tokens (preferred for new UI)
+
+[`app/assets/stylesheets/common/tokens.scss`](../../../app/assets/stylesheets/common/tokens.scss)
+layers **semantic tokens** on top of the palette. Prefer these when one fits — they encode
+intent and already handle light/dark via `light-dark()`:
+
+- Text: `--token-color-text-default`, `--token-color-text-subtle`, `--token-color-text-accent`, `--token-color-text-inverse`
+- Icons: `--token-color-icon-default`, `--token-color-icon-subtle`, `--token-color-icon-danger`
+- Borders: `--token-color-border-default`, `--token-color-border-focused`, `--token-color-border-input`
+- Surfaces: `--token-color-surface`, `--token-color-surface-hovered`, `--token-color-surface-selected`
+- Sizing: `--token-radius-small|normal|large|full`, `--token-border-width`
+- Weight: `--token-font-weight-regular|medium|semibold|bold`
+
+## General-purpose `--d-*` design vars
+
+A family of app-wide design constants — `--d-border-radius` (and `--d-border-radius-large`,
+`--d-input-border-radius`), `--d-content-background`, `--d-link-color`, `--d-hover`,
+`--d-selected` — for conventions like the standard corner radius and link color. Prefer these
+over inventing your own constant so a component matches the rest of the UI (and a theme can
+retune them globally).
+
+**Which to reach for:** a raw palette var when no token fits; a token or `--d-*` var when one
+does.
+
+## Theming components via their design vars
+
+Many components expose `--d-*` custom properties as **theming hooks**: override the variable
+(globally in `:root`, or scoped to a wrapper) to retheme the component without rewriting its
+selectors or fighting specificity. Coverage varies by component and is still expanding, so
+treat the listed source file as the authoritative, current set — these are entry points, not
+exhaustive lists.
+
+### Rounded corners
+
+`--d-border-radius` is the standard corner radius used across the UI; `--d-border-radius-large`
+is the larger step. Component radii derive from it — `--d-button-border-radius`,
+`--d-input-border-radius`, `--d-nav-pill-border-radius`, `--d-tag-border-radius`. Override
+`--d-border-radius` to round everything consistently; override a component's own var to change
+just that component. (Semantic-token equivalents: `--token-radius-small|normal|large|full`.)
+
+### Buttons
+
+`common/components/buttons.scss` defines the button hooks in `:root`, by variant:
+
+```scss
+// pattern: --d-button-{variant}-{text-color|bg-color|icon-color|border}[--hover]
+// variants: default, primary, danger, success, flat
+:root {
+ --d-button-primary-bg-color: var(--tertiary);
+ --d-button-primary-bg-color--hover: var(--tertiary-hover);
+}
+```
+
+Plus globals `--d-button-border-radius`, `--d-button-border`, `--d-button-transition`. Override
+these to restyle every button of a variant without touching `.btn` selectors.
+
+### Inputs & form elements
+
+`common/base/discourse.scss` defines input hooks: `--d-input-bg-color`, `--d-input-border`,
+`--d-input-text-color`, `--d-input-focused-color`, `--d-input-border-radius` (each with a
+`--disabled` variant where relevant). For FormKit layout (gutters, input widths), see the
+`--form-kit-*` vars in `common/form-kit/_variables.scss` (`--form-kit-gutter-x/y`,
+`--form-kit-max-input`, `--form-kit-{small,medium,large}-input`).
+
+### Sidebar (and admin sidebar)
+
+`common/base/sidebar.scss` defines the sidebar hooks: `--d-sidebar-background`,
+`--d-sidebar-active-background`, `--d-sidebar-active-color`, `--d-sidebar-active-icon-color`,
+`--d-sidebar-animation-time`/`-ease`, etc. The admin layout's sidebar adds `--d-sidebar-admin-*`
+(e.g. `--d-sidebar-admin-background`) in `admin/sidebar.scss`. Override these to retheme the
+sidebar in either context without overriding its internal selectors.
diff --git a/.skills/discourse-writing-html-css/references/css-authoring.md b/.skills/discourse-writing-html-css/references/css-authoring.md
new file mode 100644
index 00000000000..a84c8455878
--- /dev/null
+++ b/.skills/discourse-writing-html-css/references/css-authoring.md
@@ -0,0 +1,127 @@
+# CSS authoring reference
+
+Companion to the **Native CSS first** and **CSS best practices** sections of `SKILL.md`. The
+rules live there; this file holds the full native-vs-SASS swap list, the local-custom-property
+deep dive (including theme interaction), and the shared-mixin inventory.
+
+## Native CSS vs. SASS — what to swap, what to keep
+
+Discourse is gradually moving toward native CSS. When a native feature does the job, use it
+instead of a SASS construct that only exists at compile time — reduce what the precompiler has to do.
+
+**Don't introduce new SASS machinery** for something CSS now handles natively. Prefer:
+
+- `var(--…)` custom properties over SCSS `$variables` for values that should be themeable or
+ live at runtime.
+- `clamp()` / `min()` / `max()` over SCSS math (`@use "sass:math"`, `math.div`).
+- `light-dark()` and the palette over SCSS color functions (`color.adjust`, `color.scale`,
+ `dark-light-diff`) for new color work.
+- `rgb(var(--x-rgb) / 0.1)` or `rgba(var(--x-rgb), 0.1)` over SASS color manipulation.
+- The **font-size scale** and **line-heights** as custom properties — `var(--font-up-2)`,
+ `var(--font-0)`, `var(--font-down-1)`, `var(--line-height-medium)` (and `-rem` variants like
+ `var(--font-up-2-rem)` for headings). The SCSS `$font-up-2` names are just compile-time
+ aliases to these — use the `var(--…)` form directly.
+
+**But keep using the established SASS helpers** where they're still the tool — don't reinvent
+them in the name of "native":
+
+- **`z("header")`** for z-index — always use the function, never raw z-index integers. It
+ keeps the global stacking order coherent (`$z-layers` in `foundation/variables.scss`).
+- The **`lib/viewport`** mixins (`viewport.from`/`until`/`between`) for responsive rules (see
+ `references/layout-and-responsive.md`).
+- Layout-width vars and other genuinely compile-time SCSS values.
+- SCSS **`&` nesting** for BEM structure is fine and conventional.
+
+**Rule of thumb:** new value that should be themeable/runtime → CSS custom property;
+cross-cutting system already wrapped in a helper (z-index, breakpoints) → use the helper;
+one-off compile-time math/color that native CSS can now express → native CSS.
+
+## Local custom properties for repeated & computed values
+
+Define a component-scoped custom property when a value earns it — it keeps the component DRY
+and self-documenting. (These are local, component-level vars, distinct from the global
+palette/token variables.)
+
+**Reused within the component** — if the same value appears in more than one place, hoist it
+to a `--property` on the block so there's a single source of truth:
+
+```scss
+.user-card {
+ --avatar-size: 3em;
+
+ &__avatar {
+ width: var(--avatar-size);
+ height: var(--avatar-size);
+ }
+ &__body {
+ margin-inline-start: var(--avatar-size); // stays in sync automatically
+ }
+}
+```
+
+**Use custom properties as documentation inside `calc()`.** A named variable explains the math
+far better than a magic number plus a comment:
+
+```scss
+// AVOID — magic number, comment is the only thing explaining it
+width: calc(1em + 20px); // 20px = avatar margin
+
+// PREFER — the name IS the documentation, and it can't drift from a stale comment
+width: calc(1em + var(--avatar-margin));
+```
+
+**Override the variable at a breakpoint instead of redeclaring every rule — when it has
+several consumers.** If a responsive change is "this value is smaller on mobile" and the value
+feeds multiple declarations, retarget the single var and they all update together:
+
+```scss
+.user-card {
+ --avatar-size: 3em;
+ &__avatar { width: var(--avatar-size); height: var(--avatar-size); }
+ &__body { margin-inline-start: calc(var(--avatar-size) + 0.5em); }
+
+ @include viewport.until(sm) {
+ --avatar-size: 2em; // updates the avatar AND the body offset in one line
+ }
+}
+```
+
+But don't reach for this when a value is **used once** — overriding `--avatar-margin` to change
+a single `margin` is more indirection than just redeclaring `margin`. Use the variable-override
+pattern only when it saves repeating several dependent declarations (or recomputing a
+`calc()`); otherwise redeclare the property directly.
+
+### Theme interaction
+
+Local custom properties are the more theme-friendly shape: a theme can retarget `--avatar-size`
+once and every consumer (including breakpoint overrides) updates consistently, instead of
+re-overriding each dependent rule. Two things to keep in mind:
+
+- A theme's **unconditional** override (`.user-card { --avatar-size: 4em }`) loads after core at
+ equal specificity, so it wins everywhere and flattens your responsive shrink. This isn't
+ specific to variables — an unconditional redeclared property does the same — but it means a
+ value you override at breakpoints is also a value a theme can fully take over.
+- Don't promote every value to a variable reflexively; each one reads as a de-facto theming
+ API. Reserve it for values with a real single-source-of-truth or override reason.
+
+## Shared mixins (`common/foundation/mixins.scss`)
+
+A handful of mixins encode patterns that are easy to get subtly wrong. Prefer them over
+reinventing:
+
+- **Text truncation** — `@include ellipsis;` for single-line truncation
+ (`overflow`/`white-space`/`text-overflow`, the most-used helper in the codebase) and
+ `@include line-clamp($lines);` for multi-line.
+- **`@include d-animation($name, $duration, $easing);`** — runs an animation and automatically
+ zeroes its duration under `prefers-reduced-motion`, so you get reduced-motion handling for
+ free.
+- **`@include unselectable;`** — disables text selection on UI chrome (buttons, labels, tab
+ strips) where stray selection is annoying, especially on touch.
+
+Skip the legacy ones: the `user-select` mixin is deprecated (write the native `user-select`
+property — autoprefixer handles the rest), and `clearfix` is rarely needed once you're using
+flex/grid.
+
+For focus rings, prefer native `:focus-visible` (see `SKILL.md`). The `default-focus` mixin is
+an optional shorthand for the standard ring's appearance — pair it inside `:focus-visible` if
+you want the default look, but a hand-written `outline` is equally fine.
diff --git a/.skills/discourse-writing-html-css/references/layout-and-responsive.md b/.skills/discourse-writing-html-css/references/layout-and-responsive.md
new file mode 100644
index 00000000000..0ccf2bd2bbb
--- /dev/null
+++ b/.skills/discourse-writing-html-css/references/layout-and-responsive.md
@@ -0,0 +1,113 @@
+# Layout & responsive reference
+
+Companion to the **Where stylesheets live** section of `SKILL.md`. The rules live there:
+write one responsive stylesheet (not desktop/mobile copies), prefer intrinsic layout, and use
+`lib/viewport` for breakpoints. This file is the detail.
+
+The authoritative philosophy is
+[`docs/developer-guides/docs/03-code-internals/27-designing-for-devices.md`](../../../docs/developer-guides/docs/03-code-internals/27-designing-for-devices.md):
+**design mobile-first, then enhance for larger viewports and richer input** — read it for the
+full picture.
+
+## Prefer intrinsic layout over breakpoints
+
+Reach for a breakpoint only when a layout genuinely needs to *restructure*. For sizing and
+wrapping, prefer **intrinsic, self-adjusting CSS** that responds to available space on its
+own — it adapts at every width, not just at the breakpoints you happened to pick, and it's
+far less code to maintain.
+
+```scss
+// GOOD — one rule, fills and wraps columns to fit any container width
+.card-grid {
+ display: grid;
+ grid-template-columns: repeat(auto-fill, minmax(14em, 1fr));
+ gap: 1em;
+}
+
+// AVOID — redefining the column count at each breakpoint
+.card-grid {
+ grid-template-columns: 1fr;
+ @include viewport.from(sm) { grid-template-columns: repeat(2, 1fr); }
+ @include viewport.from(lg) { grid-template-columns: repeat(3, 1fr); }
+ @include viewport.from(xl) { grid-template-columns: repeat(4, 1fr); }
+}
+```
+
+Other intrinsic tools to favor before media queries: `flex-wrap` with `flex` basis/grow,
+`min()`/`max()`/`clamp()` for fluid sizing, `min-content`/`max-content`/`fit-content`, and
+`auto-fit`/`auto-fill` + `minmax()`. Use `lib/viewport` breakpoints for the cases intrinsic
+layout can't express — e.g. moving a sidebar from beside the content to below it, or swapping
+`flex-direction`.
+
+## Responsive breakpoints — `lib/viewport`
+
+Make a component responsive with the standardized **`lib/viewport`** module rather than ad-hoc
+media queries or the legacy `breakpoint()` mixin. `@use` it at the top of the file, then use
+the `from` / `until` / `between` mixins:
+
+```scss
+@use "lib/viewport";
+
+.my-component {
+ flex-direction: column; // mobile-first default
+
+ @include viewport.from(md) {
+ flex-direction: row; // wider viewports
+ }
+
+ &__sidebar {
+ @include viewport.until(lg) {
+ display: none;
+ }
+ }
+}
+```
+
+Standard breakpoints
+([`app/assets/stylesheets/lib/viewport.scss`](../../../app/assets/stylesheets/lib/viewport.scss)):
+
+| Name | Width |
+| --- | --- |
+| `sm` | 40rem |
+| `md` | 48rem |
+| `lg` | 64rem |
+| `xl` | 80rem |
+| `2xl` | 96rem |
+
+- `viewport.from($bp)` → `width >= $bp` (min-width); `viewport.until($bp)` → `width < $bp`
+ (max-width); `viewport.between($from, $until)` → a bounded range.
+- Prefer a **mobile-first** default with `from()` to scale up. Always use a named breakpoint —
+ never a raw `px`/`rem` media query — so breakpoints stay consistent sitewide.
+
+For viewport-conditional rendering in a component (rather than CSS), use the `capabilities`
+service — `this.capabilities.viewport.lg`, etc. — but SCSS is the recommended way to handle
+layout differences.
+
+## Touch & hover
+
+Some devices have only a touchscreen, some only a pointer, some both — and touch users **cannot
+hover**. So design interfaces to **work entirely without hover**, and add hover only as an
+enhancement. When you do add hover styling, scope it to non-touch devices via the
+`html.discourse-no-touch` class (Discourse adds `.discourse-touch` / `.discourse-no-touch` to
+`<html>` based on `(any-pointer: coarse)`):
+
+```scss
+html.discourse-no-touch .my-component__reveal-on-hover {
+ opacity: 0;
+ &:hover { opacity: 1; }
+}
+```
+
+In components, the same info is on the `capabilities` service (`this.capabilities.touch`).
+
+## Legacy device modes (deprecated)
+
+Discourse historically shipped separate mobile/desktop stylesheets and layouts switched by
+user-agent. **All of these are deprecated** and being removed — don't use them in new code:
+
+- the `desktop/` and `mobile/` stylesheet directories,
+- the `.mobile-view` / `.desktop-view` HTML classes,
+- the `site.mobileView` boolean in JS.
+
+Replace them with the viewport breakpoints and `capabilities` service above. ("Mobile mode"
+will become an alias for "viewport width &lt; `sm`" for backwards compatibility.)
diff --git a/docs/developer-guides/docs/03-code-internals/23-transformers.md b/docs/developer-guides/docs/03-code-internals/23-transformers.md
index 3177dc6e56c..063a7481311 100644
--- a/docs/developer-guides/docs/03-code-internals/23-transformers.md
+++ b/docs/developer-guides/docs/03-code-internals/23-transformers.md
@@ -27,12 +27,13 @@ The `valueCallback` will be passed two named arguments: the original value, and
Callbacks can access the provided context for the current transformer hook, or they can reference other data sources. Many value transformers are executed in autotracking contexts, which means that referencing reactive state will cause the transformer to be automatically re-evaluated when that state changes.
-For example, to modify the link URL of the logo on mobile devices:
+For example, to modify the link URL of the logo on small screen devices:
```js
api.registerValueTransformer("home-logo-href", ({ value, context }) => {
- const site = api.container.lookup("service:site");
- if (site.mobileView) {
+ const capabilities = api.container.lookup("service:capabilities");
+ if (!capabilities.viewport.sm) {
+ // viewport narrower than the `sm` breakpoint
return "/latest";
} else {
return value;
diff --git a/docs/developer-guides/docs/03-code-internals/25-css-guidelines-bem.md b/docs/developer-guides/docs/03-code-internals/25-css-guidelines-bem.md
index b1da0c4c5ab..45e15c48ca3 100644
--- a/docs/developer-guides/docs/03-code-internals/25-css-guidelines-bem.md
+++ b/docs/developer-guides/docs/03-code-internals/25-css-guidelines-bem.md
@@ -62,3 +62,7 @@ Or in an alternate use case, imagine we want to style all of these elements insi
Instead of placing a modifier on each element separately, we can just place it on the block level and use it indirectly via the syntax with `&` at the end. It makes little difference in the CSS file, but it keeps the DOM cleaner by not repeating modifiers.
A great real world example of our CSS classes in use in Discourse is within the chat plugin, in the [loading skeleton component](https://github.com/discourse/discourse/blob/8b9da12bf2ef02cbf913352d861fd031b763f7fd/plugins/chat/assets/javascripts/discourse/components/chat-skeleton.gjs).
+
+## See also
+
+- [Designing for Different Devices](27-designing-for-devices.md) — adapting styles to viewport size, touch vs. hover, and other device characteristics.
diff --git a/docs/developer-guides/docs/03-code-internals/25-designing-for-devices.md b/docs/developer-guides/docs/03-code-internals/27-designing-for-devices.md
similarity index 97%
rename from docs/developer-guides/docs/03-code-internals/25-designing-for-devices.md
rename to docs/developer-guides/docs/03-code-internals/27-designing-for-devices.md
index 0a9b32033e3..d53807903c8 100644
--- a/docs/developer-guides/docs/03-code-internals/25-designing-for-devices.md
+++ b/docs/developer-guides/docs/03-code-internals/27-designing-for-devices.md
@@ -110,3 +110,7 @@ class MyComponent extends Component {
Historically, Discourse shipped two completely different layouts and stylesheets for "mobile" and "desktop" views, based on the browser's user-agent. Developers would target these modes by putting CSS in specific mobile/desktop directories, by using the `.mobile-view`/`.desktop-view` HTML classes, and the `site.mobileView` boolean in JavaScript.
These techniques are now considered deprecated and should be replaced with the viewport and capability-based strategies discussed above. We will be removing the dedicated modes in the near future, making "mobile mode" an alias for "viewport width less than `sm`" for backwards compatibility.
+
+## See also
+
+- [Guidelines for CSS classes using BEM](25-css-guidelines-bem.md) — CSS class naming conventions.