gridlock

name

gridlock

description

Layout and spacing system analyzer that reverse-engineers grid systems, spacing rhythms, and density profiles from visual design references. Use when the user requests layout analysis from screenshots, editorial layouts, app screens, or website designs. Extracts grid primitives (column count, margins, gutters), spacing scales, breakpoint patterns, nested grid systems, and implementation recommendations (CSS Grid vs Flexbox). Ideal for design-to-code workflows, particularly when used alongside Hexed (colors), Specimen (typography), and Devourer (component generation).

GRIDLOCK

GRIDLOCK is a screenshot-to-layout-system analyzer that extracts structured grid systems, spacing rhythms, and density profiles from visual design references.

Overview

GRIDLOCK accepts design screenshots (PNG, JPG, WebP) and returns a complete layout system suitable for design systems, frontend development, and design tokens. The output is deterministic, structured, and ready for downstream automation.

This skill does not generate layouts, designs, or code. It only analyzes and extracts layout primitives from visual input.

---

When to Use This Skill

Use GRIDLOCK when the user:

• Uploads screenshots and asks to extract layout, analyze grid, or identify spacing
• Requests grid system details, spacing scales, or layout tokens from visual references
• Wants to understand breakpoint patterns or responsive behavior
• Needs structured layout data for design or development work
• Mentions terms like: "grid system", "spacing scale", "layout analysis", "breakpoints"

Example triggers:

• "Extract the grid system from this screenshot"
• "Analyze the spacing scale in this design"
• "What breakpoints does this layout use?"
• "Detect the layout method (Grid vs Flexbox)"

---

What GRIDLOCK Produces

Given a design screenshot, GRIDLOCK produces a structured layout system including:

1. Grid configuration: Column count, container width, margins, gutters
2. Spacing scale: Base unit, rhythm type, scale values
3. Breakpoint patterns: Inferred responsive behavior and grid transformations
4. Nested grids: Sub-grid systems within sections
5. Layout methods: CSS Grid vs Flexbox recommendations by section
6. Density profiles: Whitespace-to-content ratio analysis

The output structure is stable and designed for direct use in design systems and frontend tooling.

---

Usage Instructions

Step 1: Analyze the Design Screenshot

When the user uploads a screenshot, use Claude's vision capabilities to analyze:

# Visual analysis focuses on:
# - Alignment patterns (vertical and horizontal)
# - Consistent spacing values
# - Element groupings and hierarchies
# - Whitespace distribution
# - Content density per section

Step 2: Run Grid Detection

Use the grid analyzer to detect the underlying grid system:

import sys
sys.path.append('/mnt/skills/user/gridlock')

from scripts.grid_analyzer import detect_grid_system, detect_nested_grids

# Analyze the layout (element_positions from visual analysis)
grid_data = detect_grid_system(
    element_positions,  # List of {x, y, width, height}
    container_width=1440
)

# Detect nested grids
nested_data = detect_nested_grids(sections, grid_data)

Step 3: Extract Spacing Scale

Identify the spacing system and rhythm:

from scripts.spacing_analyzer import detect_spacing_scale

# Extract spacing values
spacing_data = detect_spacing_scale(element_gaps)
# Returns: base_unit, scale, type, rhythm

Step 4: Infer Breakpoints

Analyze responsive patterns:

from scripts.breakpoint_analyzer import infer_breakpoints

# Detect responsive behavior
breakpoint_data = infer_breakpoints(
    container_width=1440,
    margins=24,
    gutters=24,
    columns=12
)

Step 5: Classify Layout Method

Determine optimal implementation approach:

from scripts.layout_classifier import classify_layout_method

# Analyze layout patterns
layout_method = classify_layout_method(sections, grid_data)
# Returns: primary method, breakdown, recommendations

Step 6: Analyze Density

Calculate whitespace-to-content ratios:

from scripts.density_analyzer import analyze_section_density

# Measure density
density_data = analyze_section_density(sections)
# Returns: overall classification, per-section analysis

Step 7: Save and Present Outputs

Save the complete analysis to /mnt/user-data/outputs/:

import json

output = {
    'layoutMethod': layout_method,
    'grids': {
        'page': grid_data,
        'nested': nested_data
    },
    'breakpoints': breakpoint_data,
    'spacing': spacing_data,
    'density': density_data,
    'metadata': {
        'analyzed_from': 'screenshot',
        'viewport_width': 1440,
        'confidence_score': 0.92
    }
}

# Save JSON analysis
with open('/mnt/user-data/outputs/gridlock-analysis.json', 'w') as f:
    json.dump(output, indent=2, fp=f)

Then use present_files to share with the user.

---

Output Structure

The compiled layout system follows this structure:

{
  "layoutMethod": {
    "primary": "css-grid",
    "secondary": "flexbox",
    "breakdown": {
      "grid": ["main-layout", "card-containers"],
      "flexbox": ["navigation", "button-groups"]
    },
    "confidence": "high",
    "recommendation": "Use CSS Grid for main layout, Flexbox for components"
  },
  "grids": {
    "page": {
      "columns": 12,
      "container_max_width": "1200px",
      "margins": "24px",
      "gutters": "24px",
      "type": "fixed",
      "confidence": 0.95
    },
    "nested": [
      {
        "context": "card-grid",
        "type": "3-column",
        "parent": "page",
        "gutters": "16px"
      }
    ]
  },
  "breakpoints": {
    "detected": ["768px", "1024px", "1440px"],
    "confidence": "medium",
    "grid_behavior": {
      "mobile": "4-column (inferred)",
      "tablet": "8-column (inferred)",
      "desktop": "12-column (detected)"
    }
  },
  "spacing": {
    "scale": [4, 8, 16, 24, 32, 48, 64, 96],
    "base_unit": 8,
    "type": "exponential",
    "rhythm": "neutral"
  },
  "density": {
    "overall": "spacious",
    "sections": {
      "header": "tight",
      "hero": "spacious",
      "content": "neutral"
    }
  }
}

---

Best Practices

1. Always analyze full-page screenshots for accurate grid detection
2. Use high-resolution images (minimum 1440px width) for precise measurements
3. Verify nested grids manually - automated detection is 80-90% accurate
4. Cross-reference with breakpoints - inferred responsive behavior should be validated
5. Consider context - editorial layouts differ from app layouts
6. Save outputs to /mnt/user-data/outputs/ so users can download them

---

Example Workflow

User: "Can you analyze the grid system in this screenshot?"

Claude response pattern:

1. Analyze screenshot using vision capabilities
2. Run detect_grid_system() with measured element positions
3. Run detect_spacing_scale() with measured gaps
4. Run infer_breakpoints() based on container width
5. Combine results into structured output
6. Save to /mnt/user-data/outputs/gridlock-analysis.json
7. Use present_files to share the JSON file

---

Limitations

• Requires visual analysis of screenshots (cannot analyze live sites directly)
• Breakpoint detection is inferred, not guaranteed
• Nested grid detection may miss complex hierarchies
• Works best with structured, grid-based designs
• No persistent storage - each analysis is independent
• Cannot detect layout logic (conditional rendering, dynamic content)

---

Technical Details

Algorithm:

1. Visual analysis of screenshot for alignment patterns
2. Detect grid system (columns, margins, gutters)
3. Extract spacing scale (base unit, rhythm, values)
4. Infer responsive breakpoints from container relationships
5. Identify nested grid structures within sections
6. Classify layout methods (CSS Grid vs Flexbox) by section
7. Analyze density and whitespace distribution

Dependencies:

• NumPy for statistical analysis
• Claude's vision capabilities for screenshot analysis

---

Troubleshooting

"Grid detection confidence is low": Screenshot may have inconsistent alignment or complex custom layouts. Try analyzing specific sections separately.

"Spacing scale unclear": Layout may use multiple spacing systems or custom values. Check the common_values data for actual usage patterns.

"Nested grids not detected": Automated detection works best with clear visual boundaries. Manually verify section hierarchies.

---

Created by Heathen (x.com/heathenft)