DESIGN.md
Style Generator

Why AI Coding Assistants Struggle with Layout Aesthetics

In the era of agentic AI coding tools, writing structural code (like database schemas or API fetch loops) is a solved problem. However, UI assembly remains a major bottleneck. Large Language Models (LLMs) do not possess eyes to audit their visual outputs. Instead, they operate strictly on text tokens.

When you ask an AI tool like Claude Code or Cursor to build a component, it compiles a layout based on default styles or generic styling rules. Without a centralized style guideline file, it has no reference parameters. It guesses border radii, invents font weight scales, and uses color hex codes that do not exist in your project, creating a styling drift.

How a Local DESIGN.md Reference Solves CSS Chaos

A `DESIGN.md` file acts as a visual map for AI agents. By placing a detailed breakdown of your UI variables at the root of your project workspace, the AI agent reads this file during its initial workspace scanning process.

When the AI knows that your layout utilizes a specific typography scale, a fixed grid system, and an exact set of color classes, it builds components conforming strictly to these tokens. This prevents layout drift, decreases styling errors by up to 90%, and eliminates the need for tedious manual visual tweaking.

Inside StyleScribe's Heuristic DOM Classifier Engine

StyleScribe AI features a custom client-side heuristic engine that processes stylesheet rules. When you trigger a scan, the extension reads all sheets loaded inside the active viewport, normalizing shorthand properties (like margin shorthand values) and resolving CSS variables.

Next, the heuristic classifier assigns semantic categories. By analyzing computed color contrast, element dimensions, and CSS selectors, it infers the roles of variables: background colors, card grids, text highlights, border weights, and active state transitions. It outputs these variables in formats designed for easy parsing by AI parsers.