Deterministic HTML quality metrics and autonomous design iteration agent.
DesignLoop AI provides two things:
- A standalone HTML quality metrics library (fully functional, 44 tests passing) that measures DOM structure, WCAG contrast ratios, layout symmetry, accessibility compliance, and responsive breakpoints.
- A design iteration agent that uses those metrics in a think-act-observe loop to autonomously improve HTML/CSS quality. The agent module depends on external source modules (an HTML generator and image processing pipeline) that are not bundled in this repository.
The metrics module is the primary value -- it implements real WCAG 2.1 math, gamma-corrected luminance calculations, and variance-based layout analysis. All functions are deterministic: same input HTML produces the same scores every run.
pip install design-loop-aiOr install from source:
git clone https://github.com/Lumi-node/design-loop-ai.git
cd design-loop-ai
pip install -e ".[dev]"The metrics module provides five deterministic measurement functions for HTML quality analysis. No external services or APIs required.
from metrics import extract_dom_depth
html = '<html><body><div><div><p>Hello</p></div></div></body></html>'
depth = extract_dom_depth(html) # Returns 6Calculates contrast ratios between text and background colors following the WCAG 2.1 formula with proper sRGB gamma correction.
from metrics import extract_contrast_ratios
html = '<div style="background-color: #FFFFFF; color: #000000;">High contrast</div>'
ratios = extract_contrast_ratios(html)
# Returns: {'element_0_text_bg': 21.0}
# Values range from 1.0 (no contrast) to 21.0 (maximum: black on white)Supports both inline styles and CSS class definitions, hex (#RRGGBB) and rgb() color formats.
Measures how evenly distributed flex or height-based layouts are, using variance of normalized proportions.
from metrics import calculate_layout_symmetry
# Three equal flex regions = perfect symmetry
html = '''
<div class="container">
<div style="flex: 1">A</div>
<div style="flex: 1">B</div>
<div style="flex: 1">C</div>
</div>
'''
score = calculate_layout_symmetry(html) # Returns 1.0 (perfectly symmetric)Returns a float from 0.0 (fully asymmetric) to 1.0 (perfectly symmetric).
Weighted WCAG 2.1 AA compliance score across structural elements, semantic HTML, contrast, alt text, form labels, and heading hierarchy.
from metrics import calculate_accessibility_score
score = calculate_accessibility_score(html) # Returns float 0-100Scoring breakdown:
- Required elements (
html,head,body,title): +10 each - Semantic elements (
h1,nav,main,footer): +5 each - Contrast pairs meeting AA threshold (4.5:1): +2 each, -1 for non-compliant
- Image alt text: +5 each (max +20)
- Form labels: +5 each (max +20)
- Correct heading hierarchy: +10
Extracts media query breakpoints from embedded CSS.
from metrics import extract_responsive_breakpoints
breakpoints = extract_responsive_breakpoints(html) # Returns sorted list, e.g. [480, 768, 1024]The agent_designer module implements DesignAgent and DesignIterationEnvironment for autonomous design improvement through a think-act-observe cycle.
Important: The agent's act() method depends on an html_generator module from an external source directory that is not included in this repository. The observe() and think() methods work standalone using the metrics module, but full end-to-end iteration requires providing the HTML generation pipeline separately.
Observe (metrics.py) --> Think (heuristics) --> Act (generate HTML)
^ |
|_____________ iterate until converged ______________|
The agent implements three heuristics:
- Contrast Gap Closure: shifts colors toward extremes when avg contrast < 4.5
- Layout Symmetry Balance: adjusts region percentages toward the mean when symmetry < 0.9
- Accessibility Score Gap: applies color/layout refinements when score < 70
from agent_designer import DesignIterationEnvironment
# Manage design specs and track iteration history
env = DesignIterationEnvironment()
print(env.spec) # Default spec with intentionally poor contrast/layout
# Validate and apply modifications
env.apply_spec_modifications({
'colors': {'header': ['#000000']},
'layout_regions': {'header_height_percent': 15}
})
# Record metrics per iteration
env.record_iteration({
'accessibility_score': 65.0,
'layout_symmetry': 0.8,
'dom_depth': 4,
'contrast_ratios': {'header_text_bg': 12.5},
'avg_contrast_ratio': 12.5
})metrics.py Standalone HTML quality metrics (fully functional)
extract_dom_depth() DOM nesting depth
extract_contrast_ratios() WCAG contrast ratio calculation
calculate_layout_symmetry() Variance-based layout balance
calculate_accessibility_score() Weighted WCAG 2.1 AA scoring
extract_responsive_breakpoints() Media query extraction
agent_designer.py Design iteration agent (requires external html_generator)
DesignAgent Think-act-observe agent with contrast/layout heuristics
DesignIterationEnvironment Spec management, validation, iteration tracking
design_agent.py Alternative agent (requires external sources/ directory)
DesignAgent Extends ReasoningAgent for image-based design refinement
iterative_design.py End-to-end orchestrator (requires external sources/)
main.py Iteration loop runner (requires external sources/)
The metrics module has comprehensive test coverage (44 tests):
pytest tests/test_metrics.py -vTests cover DOM depth extraction, WCAG contrast math, layout symmetry calculation, accessibility scoring, responsive breakpoints, edge cases, malformed HTML handling, and determinism guarantees.
This project explores closed-loop autonomous design systems where an agent observes its output, evaluates it against quantitative metrics, and modifies its generation parameters to converge on quality targets. The metrics module implements established WCAG 2.1 accessibility standards; the agent applies gradient-free heuristic optimization over the design parameter space.
Contributions are welcome. Please read CONTRIBUTING.md for guidelines.
MIT
Repository: https://github.com/Lumi-node/design-loop-ai Author: Andrew Young, Automate Capture Research