📐 Box Model Sentinel

Real-time CSS layout integrity analysis for responsive design

Box Model Sentinel is a VS Code extension that monitors CSS files in real-time, detecting box model integrity issues and responsiveness problems that break layouts on smaller devices.

🎯 Why Box Model Sentinel?

Websites break not because CSS is ugly, but because fixed pixels don't scale. Box Model Sentinel detects structural layout problems while you type:

❌ Fixed dimensions (width: 400px; height: 600px;)
❌ 100vw without scrollbar compensation (width: 100vw → overflow!)
❌ Rigid flex containers (flex-wrap: nowrap + flex-basis: 200px)
❌ Grid with fixed tracks (grid-template-columns: 250px 250px 250px)
❌ Rigid absolute positioning (left: 100px; width: 500px)
❌ Fixed spacing (padding: 20px without breakpoints)
❌ Media query conflicts (width changes between breakpoints)
❌ Overflow masking (body { overflow-x: hidden; })

And more. In real-time, as you type.

🚀 Installation

Via Visual Studio Code Marketplace

Open Visual Studio Code
Go to Extensions (Ctrl+Shift+X)
Search for "Box Model Sentinel"
Click Install

⚡ Getting Started

Install the extension from the Marketplace
Open any CSS/SCSS/LESS/SASS file
Wait ~500ms for real-time analysis to complete
Hover on underlined lines to see severity, impact, and fix suggestions
Open the Stats panel for a full list of issues
- Command: Box Model Sentinel: Show Stats (F1 or Ctrl+Shift+P)
Optional: Adjust settings in VS Code
- boxModelSentinel.mode: strict | pragmatic
- boxModelSentinel.fixedWidthThreshold, fixedHeightThreshold, fixedSpacingThreshold
- boxModelSentinel.ignoreSelectors

📖 Features

🔍 Real-time Analysis

Automatic detection on CSS/SCSS/LESS/SASS files
Debounced analysis (500ms default) for performance
12 specialized detectors for layout issues
Smart caching to avoid redundant analysis

📊 Stats Panel

Open the Stats panel to see all issues in the current file:

Command: Box Model Sentinel: Show Stats (F1 or Ctrl+Shift+P)

Features:

Visual severity indicators (Critical/Medium/Low)
Click-to-navigate to issue location
Filter by severity (click on severity cards)
Auto-refresh when analysis completes
Persistent state between tab switches

💡 Rich Hover Information

Hover over any underlined issue to see:

Severity icon (🚫 Critical / ⚠️ Medium / ℹ️ Info)
Detailed explanation of the problem
Viewport impact description
Actionable suggestion for fixing

🎨 Visual Feedback

Color	Severity	Meaning
🔴 Red	Critical	Guaranteed overflow on small viewports
🟡 Yellow	Medium	High risk of responsive issues
🔵 Blue	Info	Non-ideal pattern, less critical

🔍 Detectors (12 Total)

1. Fixed Dimensions

Detects width, height, min-width, min-height with fixed pixel values.

.box { width: 400px; }  /* ⚠️ Medium */
.card { width: 500px; height: 300px; }  /* 🚫 Critical - both fixed */

Severity: Medium (single) / Critical (both width + height)

2. Box Model Inconsistency

Detects mixed border-box and content-box in the same project.

* { box-sizing: border-box; }
.legacy { box-sizing: content-box; }  /* ⚠️ Medium */

Severity: Medium

3. Horizontal Overflow Risk

Detects fixed width with overflow-x: visible or cumulative padding/margins.

.container { 
  width: 1200px; 
  overflow-x: visible;  /* ⚠️ Medium */
}

Severity: Medium

4. Fixed Spacing

Detects margin, padding, gap with fixed values without breakpoints.

.box { 
  padding: 20px; 
  margin: 15px;  /* ℹ️ Info */
}

Severity: Low (Info)

5. Viewport Width Overflow (100vw)

Detects width: 100vw which includes scrollbar width.

.hero { width: 100vw; }  /* ⚠️ Medium - use 100% instead */

Severity: Medium

6. Flex Fragility

Detects flex containers without flex-wrap or with rigid basis.

.flex { 
  display: flex; 
  flex-wrap: nowrap; 
  flex-basis: 200px;  /* 🚫 Critical */
}

Severity: Critical (nowrap + fixed basis) / Medium (missing wrap)

7. Grid Rigidity

Detects grid tracks with fixed pixel sizes.

.grid { 
  grid-template-columns: 250px 250px 250px;  /* ⚠️ Medium */
}

Severity: Medium

8. Absolute Positioning Rigidity

Detects position: absolute with fixed offsets or dimensions.

.modal { 
  position: absolute; 
  top: 50px; 
  left: 100px; 
  width: 500px;  /* ⚠️ Medium */
}

Severity: Medium

9. Media Query Instability

Detects properties that vary between base and breakpoints.

.card { width: 400px; }
@media (max-width: 768px) { 
  .card { width: 350px; }  /* ⚠️ Medium */
}

Severity: Medium

10. Body Overflow Masking

Detects overflow-x: hidden on body (masks structural problems).

body { overflow-x: hidden; }  /* ⚠️ Medium */

Severity: Medium

11. !important on Layout Properties

Detects !important on layout properties.

.alert { width: 100% !important; }  /* ℹ️ Info */

Severity: Low (Info)

12. Breakpoint Width Exceeded

Detects width larger than breakpoint inside @media query.

@media (max-width: 768px) {
  .container { width: 800px; }  /* 🚫 Critical - guaranteed overflow */
}

Severity: Critical

⚙️ Configuration

Add to your settings.json:

{
  "boxModelSentinel.enable": true,
  "boxModelSentinel.mode": "strict",
  "boxModelSentinel.debounceMs": 500,
  "boxModelSentinel.maxProblems": 100,
  "boxModelSentinel.fixedWidthThreshold": 320,
  "boxModelSentinel.fixedHeightThreshold": 320,
  "boxModelSentinel.fixedSpacingThreshold": 24,
  "boxModelSentinel.ignoreSelectors": []
}

Configuration Options

Option	Default	Description
`enable`	`true`	Enable/disable analysis
`mode`	`"strict"`	Analysis mode: `strict` or `pragmatic`
`debounceMs`	`500`	Delay before analyzing after change (ms)
`maxProblems`	`100`	Maximum problems reported per file
`fixedWidthThreshold`	`320`	Threshold (px) for fixed width in pragmatic mode
`fixedHeightThreshold`	`320`	Threshold (px) for fixed height in pragmatic mode
`fixedSpacingThreshold`	`24`	Threshold (px) for spacing in pragmatic mode
`ignoreSelectors`	`[]`	Selectors to ignore (case-insensitive substring match)

Analysis Modes

How to Switch Modes

Option 1: VS Code Settings UI

Open Settings (Ctrl+, or Cmd+,)
Search for "Box Model Sentinel"
Find "Mode" dropdown
Select strict or pragmatic

Option 2: settings.json

{
  "boxModelSentinel.mode": "pragmatic"  // or "strict"
}

Option 3: Workspace Settings Create .vscode/settings.json in your project:

{
  "boxModelSentinel.mode": "pragmatic"
}

Changes take effect immediately on the next file save or edit.

Strict Mode (Default)

Reports all rigid pixel usage without filters. 100% structural detection.

Best for:

New projects starting from scratch
Learning responsive design principles
Strict adherence to fluid layouts
Design systems with zero fixed dimensions

Pragmatic Mode

Applies thresholds to reduce noise in real projects. Suppresses small, safe values.

Best for:

Legacy codebases with many fixed values
Projects with established design systems
Reducing alert fatigue in large teams
Focusing on critical issues only

Comparison:

Type	Strict	Pragmatic
`width`/`height` (px)	Always reports	Reports if > thresholds
Spacing (`padding`/`margin`/`gap`)	Always	Suppresses if ≤ `fixedSpacingThreshold`
Grid tracks (px)	Always	Reports only tracks > `fixedWidthThreshold`
Flex basis (px)	Always	Reports only if > `fixedWidthThreshold`
Overflow masking / !important / breakpoints	Always	Always

Example:

/* This CSS file */
.button { padding: 8px; }           /* ℹ️ Strict: reported | Pragmatic: suppressed (≤24px) */
.card { width: 200px; }             /* ⚠️ Strict: reported | Pragmatic: suppressed (≤320px) */
.hero { width: 1200px; }            /* ⚠️ Both modes: reported (>320px) */
body { overflow-x: hidden; }        /* ⚠️ Both modes: always reported */

🎓 Philosophy

Box Model Sentinel doesn't "ban" pixels. It identifies when and where rigid pixel usage degrades responsiveness and reflow capability. The goal isn't stylistic—it's to preserve layout integrity across different viewports with practical, safe suggestions.

Design Principles

Structural, not stylistic - Focus on layout integrity, not code style
Real-time feedback - Catch issues while typing, not after deployment
Actionable suggestions - Every issue includes a fix suggestion
Performance-conscious - Debouncing, caching, and efficient parsing
Non-intrusive - Read-only analysis, never modifies your code

📦 Release Notes

1.1.9

Marketplace README streamlined for end users (removed contributor/dev sections)
Added “Getting Started” quick steps
No behavior changes; analysis logic unchanged

1.1.8

Added official extension icon at resources/icon.png
Packaging hygiene: exclude .kiro/ and *.vsix from VSIX and repository
README updated with version badge 1.1.8

1.1.7

Renamed extension to box-model-sentinel
Publisher set to mikaelmc
Repository URLs updated to mikaelcarrara/box-model-sentinel

🤝 Integration with AI Assistants

Box Model Sentinel produces structural diagnostics in real-time. You can optionally use AI extensions (GitHub Copilot, VS Code AI) to complement these signals with contextual fix suggestions.

What AI Helps With

Identify layout inconsistencies beyond syntax
Offer contextual "Quick Fixes" from diagnostic lines
Explain business rules from code comments
Propose refactorings based on project patterns

How to Use

Quick Fix icon (✨/💡): Position cursor on underlined issue, use Ctrl+. or Alt+Enter
Selection + Chat: Select CSS block, use "Ask Copilot / Explain this selection"
Command Palette: Ctrl+Shift+P → "Copilot: Fix this" or "Ask Copilot"

Example Prompts

"Explain why this 'Fixed width' diagnostic appeared and propose a safe fix"
"Can padding in % with fixed width cause overflow? Suggest refactoring using clamp()"
"Explain the ERROR-201 comment and generate a patch to fix it"

🔧 Troubleshooting

Native CSS Validation Conflicts

If you're mixing SCSS in .css files, VS Code's native validator may show many syntax errors. To work without noise:

// .vscode/settings.json
{
  "css.validate": false
}

Box Model Sentinel diagnostics continue working normally.

Stats Panel Shows Empty

If the Stats panel opens empty:

Wait for analysis to complete (~500ms after opening file)
Check if file is a supported type (CSS/SCSS/LESS/SASS)
Verify boxModelSentinel.enable is true in settings
Check Output panel (View → Output → Box Model Sentinel) for errors

Performance Issues

For large files (>5000 lines):

Increase debounceMs to 1000-2000ms
Reduce maxProblems to 50
Use ignoreSelectors to skip utility classes
Consider splitting CSS into smaller files

🐛 Bug Reports

Found a bug?

Check if it's a configuration issue (not a CSS problem)
Provide the CSS file that causes the issue
Describe expected vs observed behavior
Include VS Code version and extension version

Open an issue on GitHub

"Microsoft", "Visual Studio Code", "VS Code", and "GitHub" are trademarks of their respective owners. Mentions of these tools serve exclusively to describe compatibility and optional integration.

📄 License

This project is distributed under the MIT License. See the LICENSE file for details.

Made with ❤️ for better CSS layouts

Box Model Sentinel

mikaelmc

📐 Box Model Sentinel

🎯 Why Box Model Sentinel?

🚀 Installation

Via Visual Studio Code Marketplace

⚡ Getting Started

📖 Features

🔍 Real-time Analysis

📊 Stats Panel

💡 Rich Hover Information

🎨 Visual Feedback

🔍 Detectors (12 Total)

1. Fixed Dimensions

2. Box Model Inconsistency

3. Horizontal Overflow Risk

4. Fixed Spacing

5. Viewport Width Overflow (100vw)

6. Flex Fragility

7. Grid Rigidity

8. Absolute Positioning Rigidity

9. Media Query Instability

10. Body Overflow Masking

11. !important on Layout Properties

12. Breakpoint Width Exceeded

⚙️ Configuration

Configuration Options

Analysis Modes

How to Switch Modes

Strict Mode (Default)

Pragmatic Mode

🎓 Philosophy

Design Principles

📦 Release Notes

1.1.9

1.1.8

1.1.7

🤝 Integration with AI Assistants

What AI Helps With

How to Use

Example Prompts

🔧 Troubleshooting

Native CSS Validation Conflicts

Stats Panel Shows Empty

Performance Issues

🐛 Bug Reports

📄 License