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.mdindex 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 layoutand 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-regionannouncements, 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-autfor truncation, `d-animation` (bakes in reduced-motion), `unselectable`. Details and thelegacy 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 conventionsDiscourse 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 theycarry 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 becauseyou 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'scontents are conditional, put the container inside the condition so it isn't emitted whenempty — an empty-but-present element still counts as a flex/grid item and `gap` slot, leavingdiff --git a/.skills/discourse-writing-html-css/references/accessibility.md b/.skills/discourse-writing-html-css/references/accessibility.mdindex 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 inlinethere — 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 regionsWhen content appears or a value changes without a full page navigation (async search results, adiff --git a/.skills/discourse-writing-html-css/references/css-authoring.md b/.skills/discourse-writing-html-css/references/css-authoring.mdindex 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-overridepattern 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 ofre-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 atequal specificity, so it wins everywhere and flattens your responsive shrink. This isn'tspecific to variables — an unconditional redeclared property does the same — but it means avalue 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 isan optional shorthand for the standard ring's appearance — pair it inside `:focus-visible` ifyou 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.mdnew file mode 100644index 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