Oleg Isonen
1b48716ff4
## Summary - Document how people create, connect, edit, validate, and publish MDX-backed Content Blocks. - Document the complete MCP workflow, including scoped expression sources, frontmatter updates, diagnostics, conflicts, and disconnect behavior. - Add two focused screenshots for the human workflow. - Fix issues found by a low-reasoning MCP agent while executing every documented workflow. Ref #6182 ## Implementation notes - Connection confirmation uses the public `confirmReplacement` field because `confirm` is reserved as a hidden transport field. - MCP edits frontmatter with `update-content-block-frontmatter`; materialized MDX elements are not persistent targets for generic instance mutation tools. - Reload now intentionally discards a conflicted local source and accepts the Asset's latest storage revision before an edit is reapplied. - Generated MCP documentation and runtime contracts are updated from their source files. ## Checklist - [x] Document the human MDX Content Block workflow. - [x] Document MCP discovery, connection, editing, diagnostics, frontmatter, dynamic sources, conflicts, and disconnection. - [x] Add only screenshots that clarify otherwise hard-to-describe UI steps. - [x] Test every documented MDX capability through the local MCP CLI with a low-reasoning agent. - [x] Reproduce and fix the replacement-confirmation schema mismatch. - [x] Reproduce and fix persistent-session conflict reload and reapply. - [x] Add regression tests that failed before each product fix and pass afterward. - [x] Regenerate runtime contracts and generated MCP documentation. - [x] Review authoritative `docs/` content and update affected pages. - [x] Run affected tests, typechecks, formatting, and diff checks. ## Verification - Project Build: 208 affected tests passed. - Content Engine Asset session: 8 tests passed. - CLI documentation tests: 14 tests passed. - MCP docs generator: 3 tests passed. - Content Engine, Project Build, CLI, and MCP docs typechecks passed. - `pnpm oxfmt --check` passed. - `git diff --check` passed. - Low-reasoning MCP evaluation passed all documented workflows, including a real two-client revision conflict, reload, reapply, and final saved inspection.
5.2 KiB
description
| description |
|---|
| Add, edit, and manage breakpoints to control how your site responds to different screen sizes and conditions. |
📱 Breakpoints
Breakpoints are found at the top of the builder canvas. They define the screen widths (and other media conditions) at which your site's styles change. Webstudio is desktop-first by default — Base has no media condition and applies everywhere, and the default breakpoints use max-width to adjust styles as the screen gets smaller. You can change this by adding min-width breakpoints instead, making your project mobile-first.
For guidance on how to use breakpoints to build responsive layouts, see Responsive design.
Two types of width breakpoints
Max-width breakpoints apply styles when the screen is at or below the specified width. This is the desktop-first approach — you design for large screens first on Base, then add max-width breakpoints to adjust styles as the screen gets smaller.
Min-width breakpoints apply styles when the screen is at or above the specified width. This is the mobile-first approach — you design for small screens first, then add min-width breakpoints to adjust as the screen gets larger.
You can mix both types in one project if needed.
Default breakpoints
The default breakpoints use the max-width (desktop-first) approach:
| Breakpoint | Condition | Description |
|---|---|---|
| Base | None (default) | Applies to all screen sizes — the starting point for all styles |
| Tablet | max-width: 991px |
Screens 991px wide and below |
| Mobile landscape | max-width: 767px |
Screens 767px wide and below |
| Mobile portrait | max-width: 479px |
Screens 479px wide and below |
How styles cascade
Styles cascade in the direction that narrows the match:
- With max-width breakpoints: styles flow from Base (largest) downward to smaller breakpoints. A style set on Base applies everywhere; a style on the 479px breakpoint only applies at 479px and below.
- With min-width breakpoints: styles flow upward. A style set on a 768px min-width breakpoint applies to all screens 768px and wider.
Each breakpoint can override styles inherited from the previous one in the cascade.
Adding a breakpoint
- Click any breakpoint in the top bar to open the breakpoint menu.
- Click + to add a new breakpoint.
- Set a min-width or max-width value, or choose a media condition (see below).
- Give it a label.
Editing and deleting breakpoints
Click any breakpoint to open its settings. You can change the width, label, or media condition. Breakpoints can be deleted unless they are the base breakpoint.
Custom media conditions
Beyond screen width, Webstudio supports any CSS media condition. This lets you style for user preferences and device capabilities:
| Category | Conditions |
|---|---|
| Color scheme | dark, light |
| Reduced motion | reduce, no-preference |
| Orientation | portrait, landscape |
| Contrast | more, less, no-preference |
| Pointer | coarse, fine, none |
| Display mode | fullscreen, standalone, minimal-ui, browser |
Example: dark mode
- Add a breakpoint, select Color Scheme: Dark.
- Label it "Dark".
- Select it and style your dark theme — the canvas immediately previews dark mode.
- The published site automatically switches based on the visitor's system preference.
Example: reduced motion
- Add a breakpoint with condition Reduced Motion: Reduce.
- Disable or simplify animations for affected users.
- Improves accessibility for users with vestibular disorders.
Related
- Responsive design – How to use breakpoints to build responsive layouts
- Style panel – Applying styles at each breakpoint
Style label colors
When a breakpoint is active, style property labels in the Style Panel use color to show where a value comes from.
An orange label means the value is inherited from a larger breakpoint
{% hint style="warning" %}
Mixing min-width and max-width breakpoints in the same project makes style cascading harder to reason about. Stick to one direction for maintainability.
{% endhint %}
Related
- Responsive design – How to build layouts that adapt to different screen sizes
- Style panel – Apply styles at the selected breakpoint
- Label colors – Full reference for property label colors
- Project settings – Breakpoints can also be managed via Project settings