Improvements and extra suggestions for Fluid Spacing

[Justinabes007]

New section for Mobile-first and suggestions around controlling Fluid spacing with VW to the lowest value

Description

Adds a new documentation section: “Mobile-first clamp() strategy: controlling vw for reliable spacing”.
This section explains how to keep spacing at MIN on mobile (≈320–375px) by using low vw values (2–3vw). It includes principles, calculations, a reference table, and a theme.json example.

Related Issue: Fixes #[issue-number]

Type of Change

• 📝 Documentation update (content changes, new guidance)
• 🛠️ Automation/tooling (scripts, workflows, linting)
• 🏗️ Structure/organisation (file moves, renames, new directories)
• 🐛 Bug fix (corrects errors, broken links, typos)
• ✨ New feature (new instruction sets, agent personas, substantial content)
• 💥 Breaking change (affects existing workflows or references)

Quality Gate Checklist

Required for all PRs:

• Linked Issue referenced above
• Clear test/verification steps provided below
• Changes respect existing file structure and conventions
• No secrets or sensitive data included in changes

Content & Compliance:

• Accessibility considerations (semantic markup, clear language, contrast)
• Performance impact considered (no obvious regressions, efficient examples)
• Security considerations (safe code examples, proper escaping/sanitisation)
• i18n: user-facing strings properly wrapped/explained (N/A for doc-only change)

Documentation Standards:

• Documentation updated (CHANGELOG.md if needed)
• UK English spelling normalised
• WordPress-first context provided (theme.json examples)
• Links and cross-references verified as functional

Build & Integration:

• Generated catalogues updated (npm run build) if catalogue changes made
• Changes align with coding standards in coding-standards/

Testing Instructions

How to test these changes:

1. Open fluid-spacing.md and verify a new section titled “Mobile-first clamp() strategy: controlling vw for reliable spacing” appears before “Option 1: spacingScale”.
2. Confirm the reference table renders correctly in GitHub Markdown.
3. Copy the theme.json example into a test theme’s spacingSizes and validate spacing behaviour at mobile widths:
   • 320px / 375px → clamp resolves to MIN (12px)
   • ≥ 400px → fluid scaling begins
   • Large desktops → clamp caps at MAX (40px)
4. Check formatting matches surrounding sections.

Example verification:

• Run npm run build and verify no unexpected diffs
• Check that new links resolve correctly
• Validate spacing behaviour visually in responsive mode

Screenshots (if applicable)

N/A (documentation-only change)

Changelog Entry

Category: Added
Entry: Add Mobile-first clamp() guidance with 2–3vw recommendations, including reference table and theme.json example, to Fluid Spacing guide.

Additional Context

• File: fluid-spacing.md
• Placement: Inserted before “Option 1: spacingScale”
• Rationale: Keeps mobile layouts predictable (MIN up to ≈400px) while allowing fluid scaling on larger screens.

---

Review Guidelines

For Reviewers:

• Verify quality gate checklist completed accurately
• Test provided verification steps
• Check for WordPress-specific best practices alignment
• Ensure changes don’t conflict with existing guidance
• Validate accessibility, security, and performance considerations

For Authors:

• Be responsive to feedback and suggestions
• Update checklist as you address review comments
• Add follow-up commits rather than force-pushing over reviewed history
• Update the PR description if scope changes significantly

---

By submitting this pull request, I confirm that my contribution abides by the repository governance and will be licensed under the GPL-3.0-only licence.

Summary by CodeRabbit

• Documentation
  • Added “Mobile‑first clamp() strategy: controlling vw for reliable spacing,” detailing principles, mobile vw guidance, recommendations, an example token, a reference table, and suggested 2–3vw usage for fluid spacing in block themes.
  • Note: The new section currently appears twice in the document (duplicate content).

[coderabbitai]

Walkthrough

Adds a new documentation section “Mobile‑first clamp() strategy: controlling vw for reliable spacing” to fluid spacing guidance, including principles, recommendations, examples, and a reference table. The same section is inserted twice, creating a duplicate. No code or API changes.

Changes

Cohort / File(s)	Summary of Changes
Docs: Fluid spacing guidance docs/block-themes/fluid-spacing.md	Added a section titled “Mobile‑first `clamp()` strategy: controlling `vw` for reliable spacing,” including principles, recommendations, example token, guidance, and reference table; the section appears duplicated later in the document; no code modifications.

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~10 minutes

Poem

A nibble of notes in the margin I see,
Two carrot-cloned sections, alike as can be.
I’ll prune one sprout so the garden reads true,
Leaving crisp guidance in dew-fresh hue.
Hippity-hop—docs tidy and new! 🌱🐇

Pre-merge checks and finishing touches

❌ Failed checks (1 warning, 1 inconclusive)

Check name	Status	Explanation	Resolution
Description Check	⚠️ Warning	The description follows the repository template with sections for Description, Type of Change, Quality Gate Checklist, Testing Instructions, Changelog Entry, and Additional Context, but the Related Issue field still contains a placeholder instead of an actual issue number.	Please replace the placeholder in the Related Issue field with the actual issue number and verify that all required checklist items, such as generated catalogue updates if applicable, are addressed before merging.
Title Check	❓ Inconclusive	The title “Improvements and extra suggestions for Fluid Spacing” is related to the changeset but is too generic and does not clearly convey the primary addition of a mobile-first clamp() strategy and detailed guidance in the fluid-spacing documentation.	Please revise the title to specifically reflect the main change, for example: “Add mobile-first clamp() strategy guidance for fluid spacing,” so that it clearly summarizes the new documentation content.

✅ Passed checks (1 passed)

Check name	Status	Explanation
Docstring Coverage	✅ Passed	No functions found in the changes. Docstring coverage check skipped.

✨ Finishing touches

• 📝 Generate Docstrings

🧪 Generate unit tests

• Create PR with unit tests
• Post copyable unit tests in a comment
• Commit unit tests in branch fluid-spacing-improvements

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[coderabbitai]

Actionable comments posted: 1

📜 Review details

Configuration used: Path: .coderabbit.yml

Review profile: CHILL

Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between fd767af and 5faeb1b.

📒 Files selected for processing (1)

• docs/block-themes/fluid-spacing.md (1 hunks)

🧰 Additional context used

📓 Path-based instructions (1)

**/*.md

⚙️ CodeRabbit configuration file

**/*.md: Review the Markdown documentation for:

• Clarity and conciseness of explanations
• Consistent formatting and heading structure
• Proper use of code blocks and inline code
• Correct spelling, grammar, and punctuation
• Accurate and up-to-date technical information
• Useful internal and external links
• Well-organized sections and logical flow

Files:

• docs/block-themes/fluid-spacing.md

🪛 markdownlint-cli2 (0.18.1)

docs/block-themes/fluid-spacing.md

144-144: Tables should be surrounded by blank lines

(MD058, blanks-around-tables)

⏰ Context from checks skipped due to timeout of 90000ms. You can increase the timeout in your CodeRabbit configuration to a maximum of 15 minutes (900000ms). (1)

• GitHub Check: Link Validation

[coderabbitai]

⚠️ 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.