A platform for community discussion. Free, open, simple.
DOC: Split viewport/container docs out of designing-for-devices (#42312)
Manuel Kostka201d43ff56ab
diff --git a/docs/developer-guides/docs/03-code-internals/27-designing-for-devices.md b/docs/developer-guides/docs/03-code-internals/27-designing-for-devices.mdindex d53807903c8..c6ad2f76d86 100644--- a/docs/developer-guides/docs/03-code-internals/27-designing-for-devices.md+++ b/docs/developer-guides/docs/03-code-internals/27-designing-for-devices.md@@ -1,68 +1,11 @@----title: Designing for Different Devices (Viewport Size, Touch/Hover, etc.)+title: Designing for Different Devices (Touch & Hover)short_title: Designing for Devicesid: designing-for-devices---This document outlines the APIs used to adapt Discourse's user interface for different devices.-### Viewport Size--The most important characteristic to consider is the viewport size. We design "mobile first" and then add customizations for larger devices as needed. The breakpoints we use are:--| Breakpoint | Size | Pixels (at 16px body font size) |-| ---------- | ----- | ------------------------------- |-| sm | 40rem | 640px |-| md | 48rem | 768px |-| lg | 64rem | 1024px |-| xl | 80rem | 1280px |-| 2xl | 96rem | 1536px |--To use these in an SCSS file, add `@use "lib/viewport";` at the top of the file, then use one of the available mixins:--```scss-@use "lib/viewport";--@include viewport.from(lg) {- // SCSS rules here will be applied to- // devices larger than the lg breakpoint-}--@include viewport.until(sm) {- // SCSS rules here will be applied to- // devices smaller than the sm breakpoint-}--@include viewport.between(sm, md) {- // SCSS rules here will be applied to- // devices with a size between the sm- // and md breakpoints-}-```--In general, SCSS is the recommended way to handle layout differences based on viewport size. For advanced cases, the same breakpoints can be accessed in Ember components via the capabilities service. For example:--```gjs-import Component from "@glimmer/component";-import { service } from "@ember/service";--class MyComponent extends Component {- @service capabilities;-- <template>- {{#if this.capabilities.viewport.lg}}- This text will be displayed for devices larger than the lg breakpoint- {{/if}}-- {{#unless this.capabilities.viewport.sm}}- This text will be displayed for devices smaller than the sm breakpoint- {{/unless}}- </template>-}-```--These properties are reactive, and Ember will automatically re-render the relevant parts of the template as the browser is resized.-### Touch & HoverSome devices only have touchscreens, some only have a traditional mouse pointer, and some have both. Importantly, touchscreen users cannot "hover" over elements. Therefore, interfaces should be designed to work entirely without hover states, with hover-specific enhancements added for devices that support them.@@ -109,8 +52,9 @@ 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.+These techniques are now considered deprecated and should be replaced with the [viewport and capability-based strategies](28-designing-for-responsive-widths.md) discussed in the next document. For backwards-compatibility, legacy desktop/mobile CSS is used when the viewport is larger/smaller than the `sm` threshold.## See also+- [Designing for Responsive Widths](28-designing-for-responsive-widths.md) — breakpoints, viewport size, and container queries.- [Guidelines for CSS classes using BEM](25-css-guidelines-bem.md) — CSS class naming conventions.diff --git a/docs/developer-guides/docs/03-code-internals/28-designing-for-responsive-widths.md b/docs/developer-guides/docs/03-code-internals/28-designing-for-responsive-widths.mdnew file mode 100644index 00000000000..3a9fa6b3e35--- /dev/null+++ b/docs/developer-guides/docs/03-code-internals/28-designing-for-responsive-widths.md@@ -0,0 +1,106 @@+---+title: Designing for Responsive Widths (Breakpoints, Viewport & Containers)+short_title: Designing for Responsive Widths+id: designing-for-responsive-widths+---++This document outlines the APIs used to adapt Discourse's user interface to different widths — both the browser viewport, and individual containers on the page.++We design "mobile first" and then add customizations for larger sizes as needed. The breakpoints we use are:++| Breakpoint | Size | Pixels (at 16px body font size) |+| ---------- | ----- | ------------------------------- |+| xs | 20rem | 320px |+| sm | 40rem | 640px |+| md | 48rem | 768px |+| lg | 64rem | 1024px |+| xl | 80rem | 1280px |+| 2xl | 96rem | 1536px |++### Viewport Size++The most common way to use these breakpoints is based on the browser's viewport size. To use these in an SCSS file, add `@use "lib/viewport";` at the top of the file, then use one of the available mixins:++```scss+@use "lib/viewport";++@include viewport.from(lg) {+ // SCSS rules here will be applied to+ // devices larger than the lg breakpoint+}++@include viewport.until(sm) {+ // SCSS rules here will be applied to+ // devices smaller than the sm breakpoint+}++@include viewport.between(sm, md) {+ // SCSS rules here will be applied to+ // devices with a size between the sm+ // and md breakpoints+}+```++In general, SCSS is the recommended way to handle layout differences based on viewport size. For advanced cases, the same breakpoints can be accessed in Ember components via the capabilities service. For example:++```gjs+import Component from "@glimmer/component";+import { service } from "@ember/service";++class MyComponent extends Component {+ @service capabilities;++ <template>+ {{#if this.capabilities.viewport.lg}}+ This text will be displayed for devices larger than the lg breakpoint+ {{/if}}++ {{#unless this.capabilities.viewport.sm}}+ This text will be displayed for devices smaller than the sm breakpoint+ {{/unless}}+ </template>+}+```++These properties are reactive, and Ember will automatically re-render the relevant parts of the template as the browser is resized.++For a real example, see `app/assets/stylesheets/common/base/directory.scss`, which uses `viewport.until(sm)`/`viewport.until(md)` throughout to adapt the user directory table's layout at narrower viewport widths.++### Container Queries++Sometimes a component's layout should respond to the size of its own container, rather than the size of the whole browser viewport — for example, a card that's rendered both full-width and inside a narrow sidebar. For these cases, use `lib/container`, which shares the same breakpoint scale and mixin API as `lib/viewport`.++Container queries only work against an ancestor element that has been explicitly opted in with `container-type`. Set that (and, optionally, a `container-name` if you need to target a specific ancestor) on the element whose size you want to query against:++```scss+.my-component {+ container-type: inline-size;+ container-name: my-component;+}+```++Then, add `@use "lib/container";` at the top of the file, and use the mixins the same way as `lib/viewport`:++```scss+@use "lib/container";++.my-component {+ container-type: inline-size;+ container-name: my-component;++ @include container.until(sm, my-component) {+ // SCSS rules here will be applied when+ // .my-component itself is narrower than+ // the sm breakpoint+ }+}+```++The `$name` argument is optional. Omit it if there's only one queryable container in scope; pass it when you need to target a specific named container (for example, if the rule lives on a descendant, rather than the container element itself).++For a real example, see `.db-whos-posting` in `app/assets/stylesheets/admin/dashboard/engagement.scss`, which sets `container-type: inline-size; container-name: db-whos-posting;` and uses `container.until(sm, db-whos-posting)` to adapt its own layout independently of the viewport.++## See also++- [Designing for Different Devices (Touch & Hover)](27-designing-for-devices.md) — detecting touch/hover capability, and legacy mobile/desktop modes.+- [Guidelines for CSS classes using BEM](25-css-guidelines-bem.md) — CSS class naming conventions.