In a design system, how do you reconcile content-driven breakpoints with the few named breakpoints that every product team shares?

## Two ways to choose where layouts change A **device-driven breakpoint** is a width taken from hardware: the width of a popular phone, a common tablet, a standard laptop screen. A **content-driven breakpoint** is a width found by widening and narrowing the real content until it stops working: a line gets too long, a row of plan prices no longer fits, a label wraps into an awkward stack. | | Device-driven | Content-driven | |---|---|---| | Where the value comes from | Screen sizes of popular hardware | The width where real content breaks | | What it protects | A handful of devices at their exact widths | Every width, because the fix sits where the problem is | | How it ages | Revisited as hardware changes | Changes only when the content changes | | Main risk | Layouts that break between device widths | A different breakpoint for every piece of content | Content-driven is the better principle, but taken literally at the scale of a design system it creates its own problem: if every screen and component adds the width where *its* content breaks, the shared list grows without bound and teams stop agreeing on what "medium" means. ## Two altitudes resolve the tension Breakpoints live at two altitudes, and each is content-driven in its own way. 1. **System breakpoints (window-width classes).** A few named ranges where the **app shell and page templates** change structure: navigation moves, a second pane appears, a template gains a column. They are content-driven with respect to the shell's own content: the system team resizes the real templates and navigation and places the thresholds where those break. 2. **Component thresholds.** Widths at which **one component** changes its own arrangement, found by resizing that component with real data. They stay inside the component, are expressed against the component's own available width, are documented in its spec, and are not added to the shared list. With that split the shared list stays short and stable, and every local content problem still gets a fix at exactly the width where it occurs. ## A worked example In a telecom self-service app, the plan-comparison table shows four plans as columns with price, data allowance and roaming terms. At a width between the system's `medium` and `expanded` thresholds, the four columns no longer fit. - **Weak fix:** add a global `medium-plus` breakpoint. Every team inherits a fourth range that means nothing to their screens and must now be designed and tested. - **Weak fix:** move the `expanded` threshold so it lands on the table's width. The shell's navigation and two-pane layouts, tuned to the old value, now switch at the wrong place. - **Good fix:** the comparison table switches to stacked plan cards whenever *its own* width cannot fit the columns. It then works in the main column, in a narrower slot and on any window. ## When a new shared breakpoint is justified Promote a width to the shared list only when: - several page templates break **structurally** in the same range, not one component; - the fix is a change of arrangement at shell level (navigation, panes, template columns) that components cannot solve locally; - the system can support the extra range in design files, code, documentation and testing on every platform. Each extra shared range adds a layout variant to specify and test on every screen, so the bar is deliberately high. ## Finding the system's values 1. Build the real shell and two or three representative templates with realistic data, including long plan names and the longest supported translations. 2. Resize slowly from the narrowest supported width to the widest, noting every width where something breaks. 3. Sort the notes: breaks that belong to the shell become candidates for shared thresholds, and breaks that belong to one component become that component's own thresholds. 4. Name the resulting ranges, publish their values, and then check that common window widths, including split-screen and zoomed windows, fall sensibly into them. The last step is where device and window data belong: as a **check** on content-driven values, not as their source. If a very common width sits right on a threshold, nudging it within the content's tolerance avoids layouts flipping on tiny resizes. ## Pitfalls - Copying the widths of this year's popular devices into the shared list. - Adding a shared breakpoint for every reported layout bug. - Keeping a component's thresholds undocumented, so no one can predict how it behaves in a new slot. - Testing with short placeholder text, which places every threshold too low.