Skip to content
Open
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
50 changes: 50 additions & 0 deletions docs/block-themes/fluid-spacing.md
Original file line number Diff line number Diff line change
Expand Up @@ -100,6 +100,56 @@ Using clamp(10px, 2vw, 40px):

---

## Mobile‑first `clamp()` strategy: controlling `vw` for reliable spacing

### Principle
- The `clamp` expression is `clamp(MIN, FLUID, MAX)` — e.g. `clamp(12px, 3vw, 40px)`.
- On small viewports, you typically want spacing to **stay at MIN** until the viewport is wide enough that the `vw`-based FLUID value would exceed it.
- **Best practice:** choose `vw` so that, for common mobile widths (≈320–375px), `vw` computes to **less than MIN**.

### How to set `vw` for mobile
Calculate `vw` at your smallest intended mobile width (e.g., **320px**):

- **1vw** = 3.2px
- **2vw** = 6.4px
- **3vw** = 9.6px
- **4vw** = 12.8px
- **5vw** = 16px

If your **MIN** is **12px**:
- **3vw** @ 375px (iPhone X) = **11.25px** → `< 12px`, clamp yields **12px** (**MIN**).
- **4vw** @ 375px = **15px** → `> 12px`, clamp **starts scaling**.

### Recommendation
- Use **3vw or less** for the FLUID part if you want `clamp()` to hold **MIN** up to roughly **400px** wide.
- Avoid going below **2vw** unless you want **MIN** to persist on even wider screens.

### Example (theme.json token)
```json
{
"size": "clamp(12px, 3vw, 40px)",
"slug": "30",
"name": "3"
}
```
- On mobile (≤ ~400px), spacing is **always 12px**.
- On tablets and up, spacing **scales fluidly** until it reaches the max.

### Key guidance
- **Lowest sensible `vw`:** For most themes, **2vw** is a practical minimum; lower values risk never entering the fluid zone except on ultra‑wide screens.
- **Test visually:** Validate on emulators and physical devices.
- **Tip:** If you want mobile to always use **MIN**, pick `vw` so that its calculation at **375px** is **below MIN**.

### Reference table
| **vw** | **320px** | **375px** | **Chosen when MIN = 12px** |
|---|---:|---:|---|
| 2vw | 6.4px | 7.5px | **MIN (12px)** |
| 3vw | 9.6px | 11.25px | **MIN (12px)** |
| 4vw | 12.8px | 15px | **Fluid (≥ 12.8px)** |

### Final recommendation
Comment on lines +143 to +150
Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ Potential issue | 🟠 Major

Add required blank lines around the reference table

Markdownlint (MD058) flags this table because it isn’t separated from surrounding content by blank lines, which will fail the docs lint check. Please insert blank lines before and after the table.

 ### Reference table
+
 | **vw** | **320px** | **375px** | **Chosen when MIN = 12px** |
 |---|---:|---:|---|
 | 2vw | 6.4px | 7.5px | **MIN (12px)** |
 | 3vw | 9.6px | 11.25px | **MIN (12px)** |
 | 4vw | 12.8px | 15px | **Fluid (≥ 12.8px)** |
+
 ### Final recommendation
📝 Committable suggestion

‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.

Suggested change
### Reference table
| **vw** | **320px** | **375px** | **Chosen when MIN = 12px** |
|---|---:|---:|---|
| 2vw | 6.4px | 7.5px | **MIN (12px)** |
| 3vw | 9.6px | 11.25px | **MIN (12px)** |
| 4vw | 12.8px | 15px | **Fluid (≥ 12.8px)** |
### Final recommendation
### Reference table
| **vw** | **320px** | **375px** | **Chosen when MIN = 12px** |
|---|---:|---:|---|
| 2vw | 6.4px | 7.5px | **MIN (12px)** |
| 3vw | 9.6px | 11.25px | **MIN (12px)** |
| 4vw | 12.8px | 15px | **Fluid (≥ 12.8px)** |
### Final recommendation
🧰 Tools
🪛 markdownlint-cli2 (0.18.1)

144-144: Tables should be surrounded by blank lines

(MD058, blanks-around-tables)

🤖 Prompt for AI Agents
In docs/block-themes/fluid-spacing.md around lines 143 to 150, the reference
table is not separated from surrounding content by blank lines causing MD058;
insert a blank line immediately before the table (so there is an empty line
between the preceding paragraph/heading and the table) and another blank line
immediately after the table (so the following "Final recommendation" heading is
separated), then save to satisfy the markdownlint rule.

Set the FLUID part to **2vw–3vw** if you want spacing to stay at **MIN** on mobile and only start scaling on larger screens. This keeps mobile layouts tight and predictable while desktop remains fluid and scalable.

### Option 1: `spacingScale`

Use when you want a **scalable, incremental set of spacing values** generated by the system:
Expand Down
Loading