Responsive Breakpoints
Design uses the Framer model: every screen is ONE document (one DOM
tree). Breakpoint frames are the SAME document rendered at different
viewport widths — never separate copies. Edits cascade:
- The base is the primary (widest) frame. Base edits are plain
unprefixed classes / inline styles and cascade down to every narrower
breakpoint unless overridden there.
- Edits made while a narrower breakpoint is active persist as
width-scoped overrides that apply from just below the next-wider frame
down to zero. Narrower breakpoints layer their own overrides on top.
The bound for an override is next-wider frame width - 1 (e.g. breakpoints
390/810 with a 1280 primary: editing 810 scopes to ≤ 1279px, editing 390
scopes to ≤ 809px). breakpointUpperBoundPx in
shared/responsive-classes.ts is the canonical implementation.
Managing breakpoints
A newly generated design's frame set comes from generate-design's devices
param (("mobile"|"tablet"|"desktop")[], default ["desktop","mobile"]). The
cascade is desktop-base: the widest requested device is the primary/base
frame and each narrower device is a breakpoint frame. The default injected set
is therefore a Desktop base plus a single Mobile (390) breakpoint frame — the
narrower frame(s) only, never a frame at the primary desktop width and never an
auto-added tablet. An empty devices list is the same as leaving it out;
fixedCanvas: true asks for one fixed canvas with no breakpoint frames.
add-breakpoint — adds a device-width frame to designs.data.breakpointSet
(Framer defaults: Desktop 1200 / Tablet 810 / Phone 390, or custom 320-3840).
Duplicate widths are ignored.
remove-breakpoint — removes one by id (overrides already written stay in
the document until removed).
set-active-breakpoint — persists the active edit scope to application
state (design-active-breakpoint:<designId>); the UI mirrors it in the
design-selection state (activeBreakpointId). Check the active
breakpoint via view-screen before making responsive-only edits. Its
editScope is cascade-smaller by default (edits at this breakpoint also
apply to every narrower one); pass only when the user explicitly wants a
bounded, breakpoint-only override.
The UI's breakpoint bar (chips above the focused screen) and the overview's
side-by-side linked frames drive the same state — a chip click changes the
iframe viewport width AND calls set-active-breakpoint.
Editing responsively (agent parity)
Use apply-visual-edit with activeFrameWidthPx set to the ACTIVE
breakpoint frame width. This scopes BOTH class and style intents
uniformly through one class-vs-media decision:
- Values that are Tailwind utilities (
text-lg, p-4) become width-scoped
classes: max-[809px]:text-lg (arbitrary max-width variants the Tailwind
CDN JIT compiles to @media (max-width: 809px)).
- Raw CSS values (
137px, rgb(...), calc(...)) persist into the managed
<style data-agent-native-breakpoints> block as
@media (max-width: <bound>px) rules targeting the element's
data-agent-native-node-id. The block is deterministic (wider buckets
first so narrower ranges win by source order) and readable/editable in the
Code panel.
Other targeting options:
maxWidthPx — explicit desktop-down bound, overrides derivation.
intent.kind: "breakpoint-style" — direct managed-media write/remove:
{ target, maxWidthPx, property, value, operation: "set" | "remove" }.
activeBreakpoint: "md" etc. — LEGACY min-width prefix scoping for class
edits only (mobile-first md:text-lg). Still supported for documents
authored mobile-first; prefer activeFrameWidthPx for breakpoint-bar
parity.
When the design has no breakpoint set, activeFrameWidthPx falls back to
the legacy min-width prefix behaviour for class edits. When the active frame
IS the widest context, edits are base writes (correct — the widest frame is
the base).
Resolving and inspecting overrides
effectiveUtilityAtWidth(className, stem, widthPx) — which utility
renders at a width (narrowest applicable max-width scope wins, then
min-width prefixes, then base).
getBreakpointOverrideState({ className, html, nodeId, property, breakpointWidths, baseWidthPx, activeWidthPx }) from
shared/breakpoint-media.ts — aggregates class + media overrides for the
inspector's overridden-at-this-breakpoint indicators.
- To RESET an override: remove the scoped class
(
responsive-class remove with maxWidthPx + stem) or the media rule
(breakpoint-style with operation: "remove"); the base value cascades
back down.
Cautions
- Managed media rules anchor on
data-agent-native-node-id. Inline (SQL)
designs keep these ids; localhost write-back strips them — for local-file
sources prefer scoped classes.
- Never rewrite the managed block wholesale by hand; use the edit intents so
same-property writes replace instead of accumulate. The parser tolerates
Code-panel edits but unknown selectors are ignored.
- Adding a breakpoint between two existing widths changes the bound for NEW
overrides only; previously written overrides keep their original bounds.
1---2name: responsive-breakpoints3description: >-4 Framer-style responsive breakpoint editing in Design: one DOM tree per5 screen with cascading width-scoped overrides. Use when adding/removing6 breakpoints, editing a design at a specific device width, resolving which7 value renders at a width, or persisting responsive style changes.8metadata:9 source: https://skillmd.com/skills/builderio/responsive-breakpoints10---1112# Responsive Breakpoints1314Design uses the **Framer model**: every screen is ONE document (one DOM15tree). Breakpoint frames are the SAME document rendered at different16viewport widths — never separate copies. Edits cascade:1718- The **base** is the primary (widest) frame. Base edits are plain19 unprefixed classes / inline styles and cascade down to every narrower20 breakpoint unless overridden there.21- Edits made while a **narrower breakpoint is active** persist as22 width-scoped overrides that apply from just below the next-wider frame23 down to zero. Narrower breakpoints layer their own overrides on top.2425The bound for an override is `next-wider frame width - 1` (e.g. breakpoints26390/810 with a 1280 primary: editing 810 scopes to `≤ 1279px`, editing 39027scopes to `≤ 809px`). `breakpointUpperBoundPx` in28`shared/responsive-classes.ts` is the canonical implementation.2930## Managing breakpoints3132A newly generated design's frame set comes from `generate-design`'s `devices`33param (`("mobile"|"tablet"|"desktop")[]`, default `["desktop","mobile"]`). The34cascade is **desktop-base**: the widest requested device is the primary/base35frame and each narrower device is a breakpoint frame. The default injected set36is therefore a Desktop base plus a single Mobile (390) breakpoint frame — the37narrower frame(s) only, never a frame at the primary desktop width and never an38auto-added tablet. An empty `devices` list is the same as leaving it out;39`fixedCanvas: true` asks for one fixed canvas with no breakpoint frames.4041- `add-breakpoint` — adds a device-width frame to `designs.data.breakpointSet`42 (Framer defaults: Desktop 1200 / Tablet 810 / Phone 390, or custom 320-3840).43 Duplicate widths are ignored.44- `remove-breakpoint` — removes one by id (overrides already written stay in45 the document until removed).46- `set-active-breakpoint` — persists the active edit scope to application47 state (`design-active-breakpoint:<designId>`); the UI mirrors it in the48 `design-selection` state (`activeBreakpointId`). Check the active49 breakpoint via `view-screen` before making responsive-only edits. Its50 `editScope` is `cascade-smaller` by default (edits at this breakpoint also51 apply to every narrower one); pass `only` when the user explicitly wants a52 bounded, breakpoint-only override.5354The UI's breakpoint bar (chips above the focused screen) and the overview's55side-by-side linked frames drive the same state — a chip click changes the56iframe viewport width AND calls `set-active-breakpoint`.5758## Editing responsively (agent parity)5960Use `apply-visual-edit` with `activeFrameWidthPx` set to the ACTIVE61breakpoint frame width. This scopes BOTH `class` and `style` intents62uniformly through one class-vs-media decision:6364- Values that are Tailwind utilities (`text-lg`, `p-4`) become width-scoped65 classes: `max-[809px]:text-lg` (arbitrary max-width variants the Tailwind66 CDN JIT compiles to `@media (max-width: 809px)`).67- Raw CSS values (`137px`, `rgb(...)`, `calc(...)`) persist into the managed68 `<style data-agent-native-breakpoints>` block as69 `@media (max-width: <bound>px)` rules targeting the element's70 `data-agent-native-node-id`. The block is deterministic (wider buckets71 first so narrower ranges win by source order) and readable/editable in the72 Code panel.7374Other targeting options:7576- `maxWidthPx` — explicit desktop-down bound, overrides derivation.77- `intent.kind: "breakpoint-style"` — direct managed-media write/remove:78 `{ target, maxWidthPx, property, value, operation: "set" | "remove" }`.79- `activeBreakpoint: "md"` etc. — LEGACY min-width prefix scoping for class80 edits only (mobile-first `md:text-lg`). Still supported for documents81 authored mobile-first; prefer `activeFrameWidthPx` for breakpoint-bar82 parity.8384When the design has no breakpoint set, `activeFrameWidthPx` falls back to85the legacy min-width prefix behaviour for class edits. When the active frame86IS the widest context, edits are base writes (correct — the widest frame is87the base).8889## Resolving and inspecting overrides9091- `effectiveUtilityAtWidth(className, stem, widthPx)` — which utility92 renders at a width (narrowest applicable max-width scope wins, then93 min-width prefixes, then base).94- `getBreakpointOverrideState({ className, html, nodeId, property,95 breakpointWidths, baseWidthPx, activeWidthPx })` from96 `shared/breakpoint-media.ts` — aggregates class + media overrides for the97 inspector's overridden-at-this-breakpoint indicators.98- To RESET an override: remove the scoped class99 (`responsive-class` remove with `maxWidthPx` + stem) or the media rule100 (`breakpoint-style` with `operation: "remove"`); the base value cascades101 back down.102103## Cautions104105- Managed media rules anchor on `data-agent-native-node-id`. Inline (SQL)106 designs keep these ids; localhost write-back strips them — for local-file107 sources prefer scoped classes.108- Never rewrite the managed block wholesale by hand; use the edit intents so109 same-property writes replace instead of accumulate. The parser tolerates110 Code-panel edits but unknown selectors are ignored.111- Adding a breakpoint between two existing widths changes the bound for NEW112 overrides only; previously written overrides keep their original bounds.