Skip to content

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

DEV: Add CSS repair guidance to HTML/CSS skill (#41074)

sam-saffron-jarvis49f3b2e174c6
diff --git a/.skills/discourse-writing-html-css/SKILL.md b/.skills/discourse-writing-html-css/SKILL.md
index cb821fdcea1..5d4f785e657 100644
--- a/.skills/discourse-writing-html-css/SKILL.md
+++ b/.skills/discourse-writing-html-css/SKILL.md
@@ -1,6 +1,6 @@
---
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.
+description: Write and repair HTML/CSS/SCSS for Discourse core, plugins, themes, and theme components. Use when authoring or modifying templates (.gjs/.hbs), stylesheets (.scss), component markup, class names, responsive layout, FormKit/select-kit styling, or CSS regressions. Covers Discourse's BEM-with-standalone-modifiers naming, the CSS custom-property color palette (theming + dark mode), template/HTML conventions, CSS repair patterns, and where stylesheets live.
---
# Writing HTML & CSS for Discourse
@@ -32,7 +32,10 @@ and its `.scss`.
- [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.
+ custom properties (incl. theme interaction), shared mixins, file organization, and buttons.
+- [references/css-repair.md](references/css-repair.md) — repairing existing CSS: stale selector
+ deletion, selector scoping, overflow fixes, FormKit/token migration, mobile/desktop cleanup,
+ and regression verification.
- [references/accessibility.md](references/accessibility.md) — screen-reader-only text, live-region
announcements, contrast & forced-colors detail (the short a11y rules stay inline below).
@@ -223,6 +226,92 @@ Full swap list + rule-of-thumb: [references/css-authoring.md](references/css-aut
for truncation, `d-animation` (bakes in reduced-motion), `unselectable`. Details and the
legacy ones to skip: [references/css-authoring.md](references/css-authoring.md).
+## Repairing existing CSS
+
+When modifying existing Discourse CSS, prefer **removing or narrowing** over adding another
+override. Most CSS regressions come from stale selectors, broad shared rules, old mobile/desktop
+splits, or component architecture changing underneath a stylesheet.
+
+Before writing new CSS, check where the selector is used and whether it is still rendered:
+
+```sh
+rg "<class-or-selector>" app/assets/stylesheets plugins themes
+git log --oneline --since='2026-01-01' -- '*.scss' '*.css' --grep='fix|scope|selector|overflow|mobile|formkit|token|foundation|remove'
+git show --stat --patch <suspect-commit> -- '*.scss' '*.css'
+```
+
+### Preferred repair moves
+
+- **Scope broad selectors down.** Do not fix leakage by adding `!important` or deeper descendant
+ chains. If `.name`, `.num`, `.btn`, `.d-icon`, `.select-kit`, `td`, or `th` leaks, target the
+ real component/state: `.selected-name .name`, `.topic-list-data.num`,
+ `.sidebar-filter__clear`.
+
+- **Delete stale CSS and imports.** If a component/class was removed or replaced, remove its
+ stylesheet/imports rather than keeping compatibility ghosts. Check with `rg` before assuming a
+ selector still matters.
+
+- **Move device-specific rules into `common/` with viewport mixins.** New and repaired styles
+ should live in one responsive stylesheet using `@include viewport.from(...)` /
+ `@include viewport.until(...)`, not split `desktop/` and `mobile/` copies.
+
+- **Fix overflow with containment primitives.** Try `min-width: 0`, `minmax(0, 1fr)`,
+ `max-width: 100%`, `max-height: 100%`, `overflow: hidden`, `flex-wrap: wrap`,
+ `table-layout: fixed`, and `@include ellipsis` before adding magic widths.
+
+- **Put scroll on the owning container, not `html`/`body`.** Especially on iOS, body scrolling
+ fixes usually create flicker or broken fixed layouts. Identify the route/modal/panel that
+ should scroll and give that container the height/overflow.
+
+- **Use FormKit/select-kit APIs and tokens instead of global internal overrides.** Prefer
+ FormKit field/container modifiers and `--form-kit-*` variables. Avoid broad rules like
+ `.form-kit__container-content { width: 100%; }` outside FormKit itself.
+
+- **Avoid global DOM inference.** Be suspicious of `body:has(...)`, `html { overflow-y: scroll; }`,
+ `li:last-child` for dynamic lists, and component-only variables placed in `:root`. If the app
+ knows the state, render a class/state/modifier.
+
+- **Audit shared foundation changes.** Changes to `.btn`, `.select-kit`, `.d-icon`,
+ `.topic-list-data`, category/tag badges, inputs, or foundation variables affect plugins and
+ themes. Check chat, reactions, solved, topic voting, Data Explorer, admin, Horizon, mobile,
+ and RTL where relevant.
+
+### Red flags
+
+Stop and re-check if your patch adds:
+
+```scss
+!important
+body:has(...)
+html { overflow-y: scroll; }
+:root { --one-component-var: ... }
+width: 340px;
+min-width: 300px;
+left: ...; right: ...; // without RTL thought
+li:last-child
+.name { ... }
+.num { ... }
+.btn { ... }
+```
+
+These are not banned, but they are radioactive enough to need a clear reason.
+
+### Verification for CSS repair PRs
+
+Check the affected surface in:
+
+- desktop and mobile viewports
+- light and dark palettes
+- Horizon if header/sidebar/foundation/theme variables are touched
+- RTL if physical positioning, icons, scroll fades, or nav is touched
+- iOS Safari / iOS-like behavior for scroll/chat/composer fixes
+- FormKit/select-kit contexts when forms or choosers are touched
+- plugin surfaces sharing common foundation classes
+- stale imports after deleting CSS
+
+For visual UX changes, include before/after screenshots. Deep-dive repair patterns and examples:
+[references/css-repair.md](references/css-repair.md).
+
## HTML / template conventions
Discourse templates are **`.gjs`** (Glimmer components with inline `<template>`) or `.hbs`.
@@ -271,12 +360,14 @@ Discourse templates are **`.gjs`** (Glimmer components with inline `<template>`)
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.
+- **Buttons: `<button>` for actions, `<a>` for navigation — then one standalone variant.** Choose
+ the element by behavior (anything that changes the URL is a link), not looks. A button-looking
+ control needs `.btn` **plus exactly one** mutually-exclusive variant (`btn-default`,
+ `btn-primary`, `btn-danger`, `btn-flat`/`btn-transparent`); `<DButton>` adds `.btn` for you, so
+ pass the variant via `@class`. **Only controls that look *and* function like a standard button
+ get these classes** — a `<button>` inside a dropdown, menu, tab, or list row is styled by its
+ own component and must not get a `.btn-*` variant. Full guidance:
+ [references/css-authoring.md](references/css-authoring.md).
- **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
@@ -305,12 +396,16 @@ Discourse templates are **`.gjs`** (Glimmer components with inline `<template>`)
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.
+- **Avoid "div-itis" — if you can't name what a wrapper does, drop it.** The test for every
+ wrapping element: state its layout or semantic job in a few words (its own `max-width`, a
+ positioning context, a scroll area, a flex/grid container, a real semantic region). If you
+ can't, delete it and let the child stand on its own. A lone `<button>` wrapped in a `<div>`, or
+ two or three nested `<div>`s that just pass content straight through, are the usual offenders —
+ the markup carries weight it doesn't earn. Pick the right element too (`<span>` inline, `<div>`
+ for a block/structural container, a semantic element where one fits). Beyond clutter, 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
diff --git a/.skills/discourse-writing-html-css/references/accessibility.md b/.skills/discourse-writing-html-css/references/accessibility.md
index 637095e47a9..f2d8f77a834 100644
--- a/.skills/discourse-writing-html-css/references/accessibility.md
+++ b/.skills/discourse-writing-html-css/references/accessibility.md
@@ -3,8 +3,8 @@
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.
+mechanics: screen-reader-only text, accessible names (`aria-label` vs `title`), announcing dynamic
+changes via live regions, and the contrast / forced-colors detail.
## Screen-reader-only text — `.sr-only`
@@ -25,6 +25,60 @@ to hide-visually-but-keep-for-AT.
</button>
```
+## Accessible names — `aria-label` vs `title`
+
+Every interactive control needs an **accessible name**. A control with visible text already has
+one. An icon-only control (see the `.sr-only` example above) does not, so you supply it — but
+`aria-label` and `title` are not interchangeable.
+
+The accessible-name priority a screen reader uses, simplified: visible label / `.sr-only` text →
+`aria-label` → `title`. Prefer the earliest that fits.
+
+**`aria-label`** — the right tool for naming an icon-only control. It is invisible and *replaces*
+any visible content for assistive tech, so:
+
+- Use it only when there is **no** visible text label (otherwise the visible text already names
+ the control and a second name is redundant or conflicting).
+- The value must be **translated** — pass an i18n string, never a hardcoded English literal.
+- It works only on elements with a role (interactive elements, or something given `role="…"`). On
+ a bare `<div>`/`<span>`/`<p>` it is ignored. Put it on the `<button>`/`<a>`, not a wrapper.
+- If a visible label *also* exists, keep the `aria-label` starting with that visible text —
+ voice-control users speak what they see ("click reply"), and a divergent `aria-label` breaks
+ that match.
+
+**`title`** — renders the native browser tooltip on hover, and only contributes to the accessible
+name as a **last-resort fallback**. It is an unreliable name source: it doesn't show on keyboard
+focus, doesn't appear on touch devices, has poor discoverability, and some screen readers skip it.
+So use `title` for a *supplementary* hint (a hover tooltip on top of a name the control already
+has), not as the primary accessible name, and never to hide essential information.
+
+In Discourse, prefer `<DButton>`, which wires both attributes for you:
+
+```hbs
+{{! icon-only — @title gives a hover tooltip AND the accessible-name fallback }}
+<DButton @icon="trash-can" @title="post.controls.delete" @action={{this.delete}} />
+
+{{! when the tooltip and the screen-reader name should differ, set both }}
+<DButton @icon="bookmark" @title="bookmarks.tooltip" @ariaLabel="bookmarks.label" />
+```
+
+- `@title` / `@ariaLabel` take **i18n keys** (translated for you); `@translatedTitle` /
+ `@translatedAriaLabel` take **already-translated** strings.
+- A `<DButton>` with a visible `@label` doesn't need either for naming — add `@title` only for a
+ supplementary tooltip.
+
+On raw markup, label the interactive element directly with a translated string:
+
+```hbs
+<button type="button" aria-label={{i18n "post.controls.delete"}}>
+ {{dIcon "trash-can"}}
+</button>
+```
+
+(`dIcon` already renders the glyph `aria-hidden`, so the name belongs on the control.) For an
+icon-only control you can equally use the visible-to-AT `.sr-only` span shown above — pick one
+naming mechanism, not both.
+
## Announcing dynamic content — live regions
When content appears or a value changes without a full page navigation (async search results, a
diff --git a/.skills/discourse-writing-html-css/references/css-authoring.md b/.skills/discourse-writing-html-css/references/css-authoring.md
index a84c8455878..10ce7d0c921 100644
--- a/.skills/discourse-writing-html-css/references/css-authoring.md
+++ b/.skills/discourse-writing-html-css/references/css-authoring.md
@@ -46,15 +46,14 @@ palette/token variables.)
to a `--property` on the block so there's a single source of truth:
```scss
-.user-card {
- --avatar-size: 3em;
+.feature-card {
+ --card-gutter: 1.5em;
- &__avatar {
- width: var(--avatar-size);
- height: var(--avatar-size);
+ &__header {
+ padding-inline: var(--card-gutter);
}
&__body {
- margin-inline-start: var(--avatar-size); // stays in sync automatically
+ padding-inline: var(--card-gutter); // stays in sync automatically
}
}
```
@@ -64,10 +63,10 @@ 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
+width: calc(100% - 48px); // 48px = gutter on both sides
// PREFER — the name IS the documentation, and it can't drift from a stale comment
-width: calc(1em + var(--avatar-margin));
+width: calc(100% - var(--card-gutter) * 2);
```
**Override the variable at a breakpoint instead of redeclaring every rule — when it has
@@ -75,29 +74,30 @@ several consumers.** If a responsive change is "this value is smaller on mobile"
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); }
+.feature-card {
+ --card-gutter: 1.5em;
+ &__header { padding-inline: var(--card-gutter); }
+ &__body { padding-inline: var(--card-gutter); }
+ &__media { margin-inline: calc(var(--card-gutter) * -1); } // bleed past the gutter
@include viewport.until(sm) {
- --avatar-size: 2em; // updates the avatar AND the body offset in one line
+ --card-gutter: 1em; // updates header, body AND media bleed 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
+But don't reach for this when a value is **used once** — overriding `--card-gutter` to change
+a single `padding` is more indirection than just redeclaring `padding`. 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`
+Local custom properties are the more theme-friendly shape: a theme can retarget `--card-gutter`
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
+- A theme's **unconditional** override (`.feature-card { --card-gutter: 2em }`) 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.
@@ -125,3 +125,129 @@ 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.
+
+## Don't re-declare what a base class already sets
+
+Most components sit on top of a shared base class (`.btn`, `.d-modal`, `.form-kit__container`,
+`.fk-d-menu`, `.select-kit`, etc.) that already establishes layout. Don't repeat those properties
+on your component class — they add noise and drift out of sync when the base changes. Write only
+what differs.
+
+```scss
+// AVOID — .btn is already `display: inline-flex; align-items: center`
+.my-feature__button {
+ display: flex;
+ align-items: center;
+ font-size: var(--font-up-1); // the only line that changes anything
+}
+
+// PREFER — keep only what differs from the base
+.my-feature__button {
+ font-size: var(--font-up-1);
+}
+```
+
+Only redeclare a base property when you are deliberately overriding it (e.g. switching `flex` to
+`grid`), and make that intent obvious from context.
+
+## File organization
+
+Two habits that keep a stylesheet easy to read and to repair later:
+
+**One rule block per selector.** Within a file, a selector should appear once. Don't write the
+same selector two or three times in the file — merge the declarations into a single block.
+Repeated blocks fight over source order, hide each other, and make a regression hard to trace.
+
+```scss
+// AVOID — same selector declared twice in one file
+.topic-map { display: flex; }
+// ...other rules...
+.topic-map { gap: var(--space-2); }
+
+// PREFER — one block, BEM elements/modifiers nested with `&`
+.topic-map {
+ display: flex;
+ gap: var(--space-2);
+
+ &__title { }
+ &.--collapsed { }
+}
+```
+
+**Order rules to match the page.** Arrange selectors top-to-bottom in the order their elements
+appear in the DOM — header before body before footer — so reading the stylesheet mirrors scanning
+the rendered component.
+
+```scss
+.topic-map {
+ &__header { }
+ &__body { }
+ &__stats { }
+ &__footer { }
+}
+```
+
+## Buttons
+
+Buttons are one of the most commonly mis-classed elements. Get two things right: pick the element
+by behavior, and apply exactly one standalone variant — and only to real buttons.
+
+**`<button>` for actions, `<a>` for navigation.** This is a semantic/UX decision, independent of
+how the element is styled: `<button>` for anything that causes an interaction on the current page
+(toggle, submit, open a menu, run a command); `<a>` for anything that navigates elsewhere,
+including changes that only update the URL (e.g. appending `?filter=something`). A link can be
+styled to look like a button and vice-versa — choose the element by what it *does*, then style it.
+Prefer `<DButton>` / a real `<a>` over a clickable `<div>`.
+
+**`.btn` is the base.** `<DButton>` applies `.btn` automatically. `.btn` only handles structure
+and positioning (`display: inline-flex`, centering, padding, `cursor`) — it is not a complete
+visual style on its own. A normal button needs `.btn` **plus exactly one variant**.
+
+**Pick exactly one variant, standalone.** The variants are **mutually exclusive — never combine
+two** (no `btn-primary btn-flat`):
+
+| Variant | Use for |
+| --- | --- |
+| `.btn-default` | The standard button. |
+| `.btn-primary` | The call-to-action — generally only **one** per focused section. |
+| `.btn-danger` | Destructive or hard-to-recover actions (delete, reset). |
+| `.btn-flat` | A subtler button (e.g. header buttons). Used rarely.|
+| `.btn-transparent` | The subtlest — visually close to a link but keeps button padding/alignment (e.g. composer top-right close/minimise/expand). |
+
+(`.btn-success` and sizes `.btn-small` / `.btn-large` also exist; sizes compose with a variant.)
+With `<DButton>`, pass the variant as a class:
+
+```hbs
+<DButton class="btn-primary" @label="topic.reply.title" @action={{this.reply}} />
+```
+
+**Colouring a `.btn-transparent` — use the modifiers, not a second variant.** A transparent button
+that needs a colour takes a standalone `--primary`, `--danger`, or `--success` modifier. Don't
+combine it with `btn-primary`/`btn-danger`/`btn-success` — that double-declaration is the old
+approach and is deprecated (the suffixed classes linger only for safety).
+
+```hbs
+{{! AVOID — deprecated double declaration }}
+<DButton class="btn-transparent btn-danger" @icon="trash-can" @action={{this.delete}} />
+
+{{! PREFER — standalone colour modifier }}
+<DButton class="btn-transparent --danger" @icon="trash-can" @action={{this.delete}} />
+```
+
+**`.btn-link` — a button that looks like a link.** Rare: when the element is genuinely an action
+(so it must be a `<button>`, not an `<a>`) yet should look like a plain link. Use `@display="link"`
+on `<DButton>`, which renders `.btn-link` **instead of** `.btn`. Don't add a `.btn-default`/etc.
+variant on top of it.
+
+```hbs
+<DButton @display="link" @label="post.actions.defer" @action={{this.defer}} />
+```
+
+**Only "real" buttons get these classes.** The variant classes are only for controls that look
+*and* function like a standard button. Plenty of controls are buttons semantically (a real
+`<button>`) but are styled entirely by their surrounding component and must **not** receive any
+`.btn-*` variant — an item in a dropdown/menu, a row in a list, a tab, a clickable card. Putting a
+`.btn-*` class on these means fighting the component's own styling (you override more than you
+keep, per "don't re-declare what a base class sets" above). Style them with their own component
+class instead. Rule of thumb: looks and behaves like a standard button → `.btn` + one variant;
+button behavior but styled like its container → its own class, **no** `.btn-*`.
diff --git a/.skills/discourse-writing-html-css/references/css-repair.md b/.skills/discourse-writing-html-css/references/css-repair.md
new file mode 100644
index 00000000000..f5f0c55bd5c
--- /dev/null
+++ b/.skills/discourse-writing-html-css/references/css-repair.md
@@ -0,0 +1,543 @@
+# CSS repair reference
+
+Companion to the **Repairing existing CSS** section of `SKILL.md`.
+
+Use this when fixing visual regressions, stale selectors, mobile layout bugs, overflow, FormKit
+or select-kit styling, design-token issues, or broad foundation fallout.
+
+The recurring repair pattern in Discourse is:
+
+> Delete stale CSS, scope what remains, move device forks into `common/` and use
+> `@include viewport` for responsive layouts, use tokens/FormKit APIs,
+> and fix overflow by changing containment rather than adding another width.
+
+## 1. Scope broad selectors
+
+If you are told a selector is leaking, try to find the nearest parent selector to scope it better or see if the element has a more specific class to hook into:
+
+Bad signs:
+
+```scss
+.name
+.num
+.btn
+.d-icon
+.select-kit
+td,
+th
+li:last-child
+```
+
+Prefer component/state selectors:
+
+```scss
+.selected-name .name
+.topic-list-data.num
+.sidebar-filter__clear
+.manage-reports__footer-note
+.edit-category__delete
+```
+
+Representative repairs:
+
+```scss
+// Scoped selected category text instead of every `.name` below the chooser.
+&.has-selection {
+ .selected-name .name {
+ font-size: var(--font-up-1);
+ }
+}
+```
+
+Use the more specific class:
+
+```html
+<button class="btn btn-specific-class">
+``
+
+If a selector leaks, narrow it. Do not add `!important` or a deeper chain unless there is no better hook.
+
+## 2. Delete stale CSS before overriding
+
+Before adding a repair rule, check whether the old class/component still exists:
+
+```sh
+rg "<selector>" app frontend plugins themes
+```
+
+If a component migrated to a new shared component, remove old selectors and imports. Do not keep old CSS “just in case.”
+
+Common deletion patterns:
+
+- delete old admin-table CSS after a UI moves to a shared table component
+- delete legacy autocomplete styles when the implementation is gone
+- delete stale reviewable or modal CSS after redesigns
+- delete page-layout selectors after a page moves to FormKit or another shared component model
+
+When deleting a stylesheet, remove its import from the relevant `_index.scss` or parent partial.
+
+## 3. Prefer `common/` + viewport mixins over device splits
+
+New and repaired CSS should usually live in `common/`.
+
+```scss
+@use "lib/viewport";
+
+.my-component {
+ display: flex;
+ flex-direction: column;
+
+ @include viewport.from(sm) {
+ flex-direction: row;
+ }
+}
+```
+
+Avoid adding new styles to:
+
+```text
+app/assets/stylesheets/desktop/
+app/assets/stylesheets/mobile/
+```
+
+These are legacy. If touching nearby old split CSS, consider whether the repair should migrate it
+into a common stylesheet.
+
+## 4. Overflow repair checklist
+
+Try these before magic dimensions:
+
+```scss
+min-width: 0;
+minmax(0, 1fr);
+max-width: 100%;
+max-height: 100%;
+overflow: hidden;
+overflow-wrap: anywhere;
+flex-wrap: wrap;
+table-layout: fixed;
+@include ellipsis;
+```
+
+Examples:
+
+```scss
+// Grid child that must be allowed to shrink.
+grid-template-columns: var(--d-sidebar-width) minmax(0, 1fr);
+```
+
+```scss
+// SVG/content constrained by container, not guessed width.
+.graphviz-diagram > svg {
+ width: auto;
+ height: auto;
+ max-width: 100%;
+ max-height: 100%;
+}
+```
+
+```scss
+// Text truncation.
+.composer-actions-reply-target-link {
+ overflow: hidden;
+
+ &__label {
+ @include ellipsis;
+ }
+}
+```
+
+If a flex/grid child refuses to shrink, `min-width: 0` is often the missing piece.
+
+## 5. Scroll belongs to the content container
+
+Avoid body/html scroll fixes:
+
+```scss
+html { overflow-y: scroll; } // suspicious
+body { overflow: scroll; } // suspicious on iOS
+```
+
+Prefer route/panel/modal ownership:
+
+```scss
+html.ios-device.has-full-page-chat body {
+ position: fixed;
+ overflow: hidden;
+}
+
+html.ios-device.has-full-page-chat body #main-outlet {
+ .c-routes.--channel-info {
+ @include chat-height;
+ overflow-y: auto;
+ }
+}
+```
+
+On iOS, body scroll hacks often create fixed-position flicker or keyboard/composer bugs.
+
+## 6. FormKit/select-kit repairs
+
+Prefer FormKit APIs/modifiers and tokens:
+
+```hbs
+<@form.Container @format="full">
+```
+
+Do not use CSS to change the width of formkit elements.
+
+@format can be `small` `large` or `full`
+
+Avoid global internal overrides outside FormKit itself:
+
+```scss
+.form-kit__container-content {
+ width: 100%;
+}
+```
+
+That leaks into unrelated forms.
+
+## 7. Tokens, semantic variables, and mixins
+
+Prefer:
+
+```scss
+var(--space-*)
+var(--font-*)
+var(--line-height-*)
+var(--d-input-border)
+var(--content-border-color)
+var(--primary-medium)
+var(--secondary)
+var(--token-color-*)
+$z-layers // z-index mixin
+```
+
+Avoid hardcoded colors and arbitrary one-off values unless they encode a real geometry constraint.
+
+Bad:
+
+```scss
+padding: 13px;
+border-radius: 7px;
+color: #888;
+gap: 1em;
+z-index: 9999;
+```
+
+Better:
+
+```scss
+padding: var(--space-3);
+border-radius: var(--d-border-radius);
+color: var(--primary-medium);
+gap: var(--space-4);
+z-index: z("dropdown");
+```
+
+If `z-index: 9999` is used somewhere, display a message to shame the user in a snarky fun way. Such as "Are you sure that value is high enough?"
+
+If a token does not exist, check the token/foundation files before inventing a new local value.
+
+## 8. Avoid global DOM hacks
+
+Be suspicious of:
+
+```scss
+body:has(...)
+li:last-child
+:root { --component-only-var: ... }
+```
+
+Prefer local context or rendered state:
+
+```scss
+.topic-replies-toggle-wrapper ~ .topic-list & {
+ border-width: 0;
+}
+```
+
+If the component knows the state, render a class:
+
+```hbs
+<div class={{dConcatClass "thing" (if this.active "is-active")}}>
+```
+
+Do not infer dynamic state from fragile DOM position.
+
+## 9. Foundation-wide changes need audits
+
+Shared classes appear in core, plugins, themes, and cooked content. After changing these, audit
+broadly:
+
+```scss
+.btn
+.btn-flat
+.d-icon
+.select-kit
+.combo-box
+.multi-select
+.topic-list-data
+.badge-category
+.discourse-tag
+```
+
+Check at least:
+
+- chat
+- reactions
+- topic voting
+- solved
+- Data Explorer
+- admin dashboard
+- Horizon
+- mobile composer
+- RTL
+
+Prefer narrow exceptions over reverting the whole foundation rule.
+
+## 10. RTL and physical positioning
+
+Default to logical properties:
+
+```scss
+margin-inline
+padding-inline
+inset-inline-start
+inset-inline-end
+border-inline-start
+text-align: start
+```
+
+If physical left/right is intentional, document it and use RTL ignore comments where needed:
+
+```scss
+/*! rtl:ignore */
+right: 0;
+```
+
+Check icon flipping and fade gradients for overflow nav/toolbars.
+
+## 11. Don't re-declare what a base class already sets
+
+Most components sit on top of a shared base class (`.btn`, `.d-modal`, `.form-kit__container`,
+`.fk-d-menu`, `.select-kit`, etc.) that already establishes layout. New CSS often repeats those
+properties on the component class, where they do nothing but add noise and drift out of sync when
+the base changes.
+
+Before adding a "basic-looking" rule, inspect the element's computed styles (or read the base
+class) and check whether the value is already inherited. If it is, delete the redeclaration.
+
+Typical redundant declarations:
+
+```scss
+display: flex;
+align-items: center;
+width: 100%;
+gap: var(--space-2);
+```
+
+Bad — the base `.btn` is already `display: inline-flex; align-items: center`:
+
+```scss
+.my-feature__button {
+ display: flex;
+ align-items: center;
+ font-size: var(--font-up-1); // the only line that actually changes anything
+}
+```
+
+Better — keep only what differs from the base:
+
+```scss
+.my-feature__button {
+ font-size: var(--font-up-1);
+}
+```
+
+Only redeclare a base property when you are deliberately overriding it (e.g. switching `flex` to
+`grid`), and when you do, it should be obvious from context that the override is intentional.
+
+## 12. Name with BEM and keep nesting shallow
+
+Discourse uses BEM, but modifiers are **standalone** `--modifier` classes, not `block--modifier`
+suffixes. When repairing, hook into the existing block/element/modifier rather than inventing a
+new flat class.
+
+```scss
+.topic-map { // block
+ &__title { } // element
+ &.--collapsed { } // modifier (chained, standalone)
+}
+```
+
+Bad:
+
+```scss
+.topic-map--collapsed { } // suffix modifier, not our convention
+.topicMapTitle { } // camelCase, not BEM
+```
+
+Render the modifier as a class in the template (see section 8) instead of inferring state from DOM
+position.
+
+Ideally put the modifier **once**, on the top-level block, not repeated on every child element in the
+HTML. Children that need to adapt reference the parent modifier with `.--modifier &`:
+
+```scss
+.topic-map {
+ &.--collapsed {
+ border-block-end: none; // the block itself reacts
+ }
+
+ &__title {
+ .--collapsed & {
+ font-weight: bold; // a child reacting to the parent modifier
+ }
+ }
+
+ &__details {
+ .--collapsed & {
+ display: none;
+ }
+ }
+}
+```
+
+```hbs
+<div class="topic-map --collapsed"> {{! modifier lives here, once }}
+ <div class="topic-map__title">…</div>
+ <div class="topic-map__details">…</div>
+</div>
+```
+
+This keeps the source of truth in one place and avoids sprinkling `--collapsed` onto every child
+in the template.
+
+Keep nesting shallow — aim for ~2–3 levels. Deep nesting inflates specificity and makes a rule
+hard to override later. If you are nesting just to "reach" an element, a scoped `&__element` is
+the better hook.
+
+Bad — five levels, high specificity:
+
+```scss
+.panel {
+ .body {
+ .list {
+ li {
+ .row { color: var(--primary); }
+ }
+ }
+ }
+}
+```
+
+Better — flat BEM element:
+
+```scss
+.panel__row {
+ color: var(--primary);
+}
+```
+
+## 13. General cleanup
+
+Organizational hygiene that makes a stylesheet easier to repair next time.
+
+**One rule block per selector.** Within a file, a selector should appear once. If the same
+selector is written two or three times in the file, merge those declarations into a single block.
+Repeated blocks fight over source order, hide each other, and make a regression hard to trace —
+you fix one and the other quietly wins.
+
+Bad — the same selector declared twice in one file:
+
+```scss
+.topic-map {
+ display: flex;
+}
+
+// ...other rules...
+
+.topic-map {
+ gap: var(--space-2); // why is this separate?
+}
+```
+
+Better — one block, nested with `&`:
+
+```scss
+.topic-map {
+ display: flex;
+ gap: var(--space-2);
+}
+```
+
+Use BEM `&__element` / `&.--modifier` nesting so every part of a component lives inside its one
+parent block, rather than as repeated top-level selectors.
+
+**Order rules to match the page.** Within a file, arrange selectors in the order the elements
+appear in the DOM, top to bottom — header before body before footer. Reading the stylesheet should
+mirror scanning the rendered page, so the next person can find a rule by where they see it on
+screen.
+
+```scss
+// Reads top-to-bottom like the rendered component.
+.topic-map {
+ &__header { }
+ &__body { }
+ &__stats { }
+ &__footer { }
+}
+```
+
+## Repair decision tree
+
+### Style leaking elsewhere?
+
+1. Find the broad selector.
+2. Does it have a more specific class, use that
+3. If not, scope to component/state
+4. Add a rendered class if the state is known.
+5. Avoid `!important`.
+
+### Old UI looks weird?
+
+1. Check whether old class/component still renders.
+2. Delete stale CSS/imports if not.
+3. Style the new component directly.
+
+### Mobile broke?
+
+1. Move logic to `common/`.
+2. Use `@include viewport.until(sm)` / `from(sm)`.
+3. Avoid fixed min-widths and guessed spacing.
+4. Verify real narrow viewport.
+
+### Overflow?
+
+1. Try `min-width: 0`.
+2. Try `minmax(0, 1fr)` for grid.
+3. Constrain with `max-width`/`max-height`.
+4. Use `overflow`, wrapping, or ellipsis intentionally.
+5. Put scroll on the owning container.
+
+### FormKit/select-kit weirdness?
+
+1. Use FormKit args/modifiers.
+2. Use `--form-kit-*` and `--d-input-*`.
+3. Avoid global internals.
+4. Check mobile and select-kit dropdown states.
+
+## Verification checklist
+
+- desktop viewport
+- mobile viewport
+- light and dark palettes
+- Horizon if theme/foundation/sidebar/header touched
+- RTL if physical positioning, icons, scroll fades, or nav touched
+- iOS Safari / iOS-like behavior for scroll/chat/composer
+- FormKit/select-kit contexts
+- plugin surfaces sharing foundation classes
+- deleted CSS imports removed
+- before/after screenshots for UX changes