Layout Specification

This document defines a minimal, deterministic subset of React and Tailwind CSS designed to describe UI layouts as structured instructions for AI. By constraining the available primitives, the spec eliminates ambiguity and keeps the instruction surface small enough for reliable generation and interpretation.

Elements

The full set of allowed JSX elements. No other HTML or custom components may be introduced unless explicitly defined elsewhere.

Variables

State is managed exclusively through React's useState hook. Each variable must declare its type.

const [count, setCount] = useState<number>(0);
const [label, setLabel] = useState<string>('');
const [visible, setVisible] = useState<boolean>(false);
const [config, setConfig] = useState<object>({});
const [items, setItems] = useState<array>([]);

The five types — number, string, boolean, object, array — cover all state needs within a layout. Default values are always provided inline.

className Tokens

All visual styling is expressed through Tailwind utility classes. Only the tokens listed below are valid.

Sizing

Control the dimensions of an element.

Layout

Arrange children within a container.

Spacing

Margin and padding follow Tailwind's numeric scale.

Styling

A deliberately small palette and typographic scale.

Colors — only three background values are permitted:

• bg-black
• bg-white
• bg-transparent

Borders — applied per-side or to all sides:

• border, border-t, border-r, border-b, border-l

Typography:

Conditional Rendering

Show or hide elements based on state. All conditions use short-circuit evaluation with &&.

{
  isVisible && <div>Shown when true</div>;
}

{
  count > 0 && <p>Count is positive</p>;
}

{
  status === 'error' && <p>Something went wrong</p>;
}

{
  !isLoading && <div>Content loaded</div>;
}

No ternary expressions. No if/else blocks. A condition is either met and the element renders, or it isn't and nothing renders.

Interaction

State updates are bound directly to onClick. Only two patterns are allowed:

// Set to a specific value
<button onClick={() => setCount(1)}>Reset</button>

// Toggle a boolean
<button onClick={() => setActive(!active)}>Toggle</button>

No inline logic beyond these two forms. Complex interactions should be decomposed into multiple state variables.

Responsive Prefixes

Any className token can be prefixed with a breakpoint to apply conditionally at that viewport width and above.

<div className='flex-col md:flex-row gap-4'>{/* Stacks vertically on mobile, horizontally on tablet+ */}</div>

The data-description Attribute

Any element may carry a data-description attribute containing freeform text. This attribute has no runtime effect — it exists purely as a semantic annotation for AI interpretation.

<div
  className='flex flex-col gap-2'
  data-description='Sidebar navigation that collapses on mobile. Contains 5-8 nav items.'>
  {/* ... */}
</div>

Use data-description to communicate intent, behavior, or context that cannot be expressed through the structural primitives alone. Think of it as a comment that travels with the element.

Design Principles

This spec is shaped by a few deliberate constraints:

1. Closed set. Every valid token is enumerated. There is no escape hatch into the full Tailwind or React API.
2. Flat state. useState with primitive types keeps state predictable and serializable.
3. No logic. No ternaries, no loops, no computed values. Conditions are binary. Interactions are assignments or toggles.
4. Semantic hints over code. data-description lets you annotate intent without expanding the executable surface.

The goal is a language that is small enough for an AI to handle reliably, and expressive enough to describe real layouts.