Guide to CSS Template Sizing

Audience and purpose

This guide is best used by AI agents building raw template code, including the Lucit AI Assistant and third-party AI assistants. It is also a practical reference for developers editing template JSON, HTML, and CSS directly.

Read the Lucit Template CSS Guide alongside this guide. It describes the CSS architecture, positioning rules, and CSS supplied by the Render App; this guide explains how to choose and populate the sizing fields.

Lucit templates are responsive across multiple digital screen aspect ratios, not just different pixel resolutions. A single template can share HTML and JavaScript while using a different CSS layout for each screen format.

• Screen Format Reference: supported format keys, aspect-ratio ranges, recommended dimensions, and a format calculator.
• Lucit Screen Format Media Queries: the width/height aspect-ratio queries used to select screen-format CSS.

Quick instructions for AI agents

If a template needs different layouts for different screen ratios:

1. Set edit_mode_global to the boolean false.
2. List the supported screen-format keys in template_board_formats.
3. Create css_size_variants[format].css for every supported format.
4. Account for every HTML ID in every size variant, including elements hidden in that format.
5. Use visibility: visible and visibility: hidden to select the elements and background images that appear in each format.
6. Store ordinary CSS rules in each variant. Do not wrap them in media queries: the Lucit Dynamic Creative rendering engine (Render App) does that automatically.
7. Preview every supported format and verify positioning, text fit, and visibility before finishing.

Do not hand-author the standard media queries

Do not place CSS media queries directly into the template's global css field for normal screen-format sizing. Only add custom media queries when the existing aspect-ratio structure cannot satisfy a specific custom design requirement. Prefer css_size_variants for the standard formats.

Global CSS versus per-format CSS

The template's edit_mode_global setting controls which editing and sizing mode is used. It is a JSON boolean, not the string "true" or "false".

edit_mode_global	Template Designer Editor Mode	CSS behavior
true (default)	All Sizes	The template's global css is used across all screen sizes.
false	Each Size Independently	Each screen format has its own CSS in css_size_variants[format].css, applied through automatically generated aspect-ratio media queries.

Use global mode when the same layout works for all supported formats. Use independent mode when elements need different positions, dimensions, styling, or visibility across formats.

Although sometimes described as an array, css_size_variants is a JSON object keyed by screen-format name. Each value is an object containing a css string. In contrast, template_board_formats is an array of format keys.

Field	JSON type	Purpose
edit_mode_global	Boolean	Selects global or independent sizing mode.
css	String	Normal/global template CSS.
template_board_formats	Array of strings	Lists the template's supported formats, such as bulletin, vertical, or third.
css_size_variants	Object	Maps format keys to objects containing their CSS.
css_size_variants[format].css	String	CSS rules for one screen format, without a media-query wrapper.

In a template response, these fields belong under drive_template.templates.base, alongside html, js, and the other template settings. They are not top-level fields on drive_template.

How rendering works

The Render App automatically wraps each size variant's CSS in the appropriate aspect-ratio media query. The Template Designer and raw template CSS do not need to implement those wrappers.

When independent mode is enabled, the matching size variant overrides the corresponding rules in the normal css field. The global CSS can still appear in the rendered stylesheet; do not assume that changing modes removes it. As with other CSS, declarations that are not overridden may continue to affect an element.

For example, the engine wraps css_size_variants.vertical.css in a vertical-format media query, and css_size_variants.bulletin.css in a bulletin-format media query. The matching query is selected using screen width divided by screen height. Recommended pixel dimensions are examples, not fixed-resolution requirements.

See the rendered CSS examples in the CSS guide and the media-query reference for details. Store only the CSS inside those wrappers in the variant's css string.

Example: bulletin and vertical size variants

The following valid JSON object shows the sizing fields from the Bellamy Organics countdown example, formatted consistently. It is a sizing excerpt, not a complete template or API update request.

CSS strings use \n for line breaks and escaped quotes where needed. When generating JSON programmatically, use a JSON serializer rather than manually escaping CSS.

{
  "edit_mode_global": false,
  "template_board_formats": ["bulletin", "vertical"],
  "css_size_variants": {
    "bulletin": {
      "css": "#rectangle_default_bg {\n  width: 100%;\n  height: 100%;\n  top: 0%;\n  left: 0%;\n  background: white;\n}\n\n#img_1213926 {\n  width: 36%;\n  height: 45%;\n  top: 15%;\n  left: 24%;\n}\n\n#img_1213931 {\n  width: 36%;\n  height: 45%;\n  top: 15%;\n  left: 24%;\n}\n\n#img_1213932 {\n  width: 36%;\n  height: 45%;\n  top: 15%;\n  left: 24%;\n}\n\n#img_1213931_9af8gpvs {\n  width: 40%;\n  height: auto;\n  top: 24%;\n  left: 28%;\n  aspect-ratio: 3.5;\n  visibility: visible;\n}\n\n#obj_countdown_hours_and_days_l1zrijsn {\n  font-weight: bold;\n  white-space: pre-line;\n  overflow: visible;\n  width: 61.8382%;\n  height: 73.7762%;\n  top: 14.9421%;\n  left: 3.6542%;\n  font-family: \"Cinzel\";\n  color: #ffffff;\n  visibility: visible;\n  rotate: none;\n  text-transform: uppercase;\n  background: rgba(11, 103, 105, 0);\n  text-shadow: 3px 0px 5px rgba(254, 253, 253, 0.45);\n}\n\n#img_1214037 {\n  width: 40%;\n  height: auto;\n  top: 24%;\n  left: 28%;\n  aspect-ratio: 3.5;\n  visibility: hidden;\n}\n\n#img_1214038 {\n  width: 40%;\n  height: auto;\n  top: 24%;\n  left: 28%;\n  aspect-ratio: 3.5;\n  visibility: visible;\n}\n\n#img_1214049 {\n  width: 36%;\n  height: 45%;\n  top: 15%;\n  left: 24%;\n  visibility: hidden;\n}"
    },
    "vertical": {
      "css": "#rectangle_default_bg {\n  width: 100%;\n  height: 100%;\n  top: 0%;\n  left: 0%;\n  background: white;\n}\n\n#img_1213926 {\n  width: 36%;\n  height: 45%;\n  top: 15%;\n  left: 24%;\n}\n\n#img_1213931 {\n  width: 36%;\n  height: 45%;\n  top: 15%;\n  left: 24%;\n}\n\n#img_1213932 {\n  width: 36%;\n  height: 45%;\n  top: 15%;\n  left: 24%;\n  visibility: hidden;\n}\n\n#img_1213931_9af8gpvs {\n  width: 40%;\n  height: auto;\n  top: 24%;\n  left: 28%;\n  aspect-ratio: 3.5;\n  visibility: hidden;\n}\n\n#obj_countdown_hours_and_days_l1zrijsn {\n  font-weight: bold;\n  white-space: pre-line;\n  overflow: visible;\n  width: 90.0585%;\n  height: 21.3816%;\n  top: 22.8259%;\n  left: 4.2398%;\n  font-family: \"Cinzel\";\n  color: #ffffff;\n  visibility: visible;\n  rotate: none;\n  text-transform: uppercase;\n  background: rgba(11, 103, 105, 0);\n  text-shadow: 3px 0px 5px rgba(254, 253, 253, 0.45);\n}\n\n#img_1214037 {\n  width: 40%;\n  height: auto;\n  top: 24%;\n  left: 28%;\n  aspect-ratio: 3.5;\n  visibility: hidden;\n}\n\n#img_1214038 {\n  width: 40%;\n  height: auto;\n  top: 24%;\n  left: 28%;\n  aspect-ratio: 3.5;\n  visibility: hidden;\n}\n\n#img_1214049 {\n  width: 36%;\n  height: 45%;\n  top: 15%;\n  left: 24%;\n  visibility: visible;\n}"
    }
  }
}

What changes between the formats?

Element or property	Bulletin	Vertical
Countdown width	61.8382%	90.0585%
Countdown height	73.7762%	21.3816%
Countdown top	14.9421%	22.8259%
Countdown left	3.6542%	4.2398%
img_1213931_9af8gpvs	Visible	Hidden
img_1214038	Visible	Hidden
img_1214049	Hidden	Visible
img_1213932	No variant visibility declaration	Hidden

The countdown stays visible but occupies a different bounding box. Image visibility changes without changing the shared HTML or countdown JavaScript.

Existing-template CSS can contain historical selectors

The supplied template export contains CSS selectors such as img_1213926, img_1213931, and img_1213931_9af8gpvs that do not appear in its current HTML. A CSS selector alone does not create an element. When adapting an existing template, inspect the actual HTML and layers, preserve required IDs and asset macros, and ensure every current HTML ID is covered in every variant. For newly generated templates, explicitly set visibility for elements that switch between formats rather than relying on an inherited/default value.

Account for every element in every format

Each size variant must account for every HTML ID on the template, even if the element should not appear at that size. Define its layout and intended visibility instead of simply omitting its CSS.

Follow the CSS guide's positioning rules:

• Use relative percentage units for width, height, top, and left, with four decimal places for calculated positions.
• Use height: auto with aspect-ratio where appropriate to preserve an image's proportions.
• Do not use CSS transforms for positioning.
• Lucit's primary element classes already supply absolute positioning; do not unnecessarily reimplement the Render App's layout rules.

Common scenario: format-specific background images

Pre-made background artwork often has different aspect ratios for different screens. Keep each required background image as a separate element in the shared HTML. In every variant, explicitly show the correct background and hide the others with CSS visibility.

For example, bulletin and third formats may share landscape artwork while vertical uses portrait artwork:

Background element	Bulletin	Vertical	Third
Landscape background	visibility: visible	visibility: hidden	visibility: visible
Portrait background	visibility: hidden	visibility: visible	visibility: hidden

Hidden elements remain part of the template. Keep their IDs, asset references, and per-format CSS intact. This lets a single template render the appropriate artwork at each ratio without removing or rebuilding elements.

Template Designer controls

Editor Mode toggle

In the template's Template Designer → Canvas tab, find the Editor Mode toggle:

• All Sizes maps to "edit_mode_global": true.
• Each Size Independently maps to "edit_mode_global": false.

In independent mode, select a size tab before editing its CSS. The CSS editor corresponds to the selected screen format.

Adding and removing sizes

Use the size tabs above the template:

• Click Plus (+) to add a screen format.
• Click the small × on a size tab to remove that format.

Adding or removing sizes updates both:

1. template_board_formats: the list of supported screen-format keys.
2. css_size_variants: the per-format entries and their CSS.

When an AI agent edits raw JSON, it must keep these fields synchronized itself. Adding a format name alone is not a substitute for supplying and reviewing that format's CSS. When removing a format, remove its variant entry too.

Adding third to the countdown example

After adding third, the supported formats become:

{
  "template_board_formats": ["bulletin", "vertical", "third"]
}

The css_size_variants object must now contain bulletin, vertical, and third, each with its own css string. In the supplied expanded countdown example, third.css has the same CSS as bulletin.css, while vertical.css remains different. An agent can copy the bulletin CSS into the third entry as a starting point, then preview and adjust it for the third aspect-ratio range. Do not assume that a copied layout automatically fits another format.

The complete JSON example below demonstrates the three-format structure with shorter CSS strings.

Complete JSON example: independent sizing in a template response

This is a simplified illustrative response-shaped JSON example, not the full Bellamy Organics API export and not an API request schema. It retains the success → drive_template → templates → base structure and supplies shared HTML, global CSS, and complete size-variant CSS for all of its HTML IDs. Unrelated response metadata, font records, layer records, asset records, account details, and countdown formatting JavaScript are omitted to keep the sizing mechanism readable.

In the full Bellamy Organics response, the same sizing fields sit alongside fonts, colors, fields, layers, filters, used_macros, playback/render settings, and other template metadata. Changing sizing does not require replacing those unrelated fields. Preserve the existing template's HTML attributes, layers, fonts, asset macros, and registered JavaScript when editing it.

The short background IDs and solid colors below are illustrative. For pre-made artwork, use the template's actual image elements and asset references; the per-format visibility pattern stays the same.

{
  "success": true,
  "drive_template": {
    "name": "Independent screen-format sizing example",
    "templates": {
      "base": {
        "html": "<div id=\"rectangle_default_bg\" class=\"lc_ut_designer lc_dt_object lc_dt_default_background\"></div>\n<div id=\"background_landscape\" class=\"lc_ut_designer lc_dt_object\"></div>\n<div id=\"background_portrait\" class=\"lc_ut_designer lc_dt_object\"></div>\n<div id=\"message\" class=\"lc_ut_designer lc_dt_text lc_format_fit_text\">Your message</div>",
        "js": "",
        "css": "#rectangle_default_bg { width: 100%; height: 100%; top: 0%; left: 0%; background: white; }\n#background_landscape { width: 100%; height: 100%; top: 0%; left: 0%; background: #0b6769; visibility: hidden; }\n#background_portrait { width: 100%; height: 100%; top: 0%; left: 0%; background: #23404d; visibility: hidden; }\n#message { width: 80%; height: 30%; top: 35%; left: 10%; color: #ffffff; visibility: visible; }",
        "edit_mode_global": false,
        "template_board_formats": ["bulletin", "vertical", "third"],
        "css_size_variants": {
          "bulletin": {
            "css": "#rectangle_default_bg { width: 100%; height: 100%; top: 0%; left: 0%; background: white; visibility: visible; }\n#background_landscape { width: 100%; height: 100%; top: 0%; left: 0%; background: #0b6769; visibility: visible; }\n#background_portrait { width: 100%; height: 100%; top: 0%; left: 0%; background: #23404d; visibility: hidden; }\n#message { width: 61.8382%; height: 73.7762%; top: 14.9421%; left: 3.6542%; color: #ffffff; visibility: visible; }"
          },
          "vertical": {
            "css": "#rectangle_default_bg { width: 100%; height: 100%; top: 0%; left: 0%; background: white; visibility: visible; }\n#background_landscape { width: 100%; height: 100%; top: 0%; left: 0%; background: #0b6769; visibility: hidden; }\n#background_portrait { width: 100%; height: 100%; top: 0%; left: 0%; background: #23404d; visibility: visible; }\n#message { width: 90.0585%; height: 21.3816%; top: 22.8259%; left: 4.2398%; color: #ffffff; visibility: visible; }"
          },
          "third": {
            "css": "#rectangle_default_bg { width: 100%; height: 100%; top: 0%; left: 0%; background: white; visibility: visible; }\n#background_landscape { width: 100%; height: 100%; top: 0%; left: 0%; background: #0b6769; visibility: visible; }\n#background_portrait { width: 100%; height: 100%; top: 0%; left: 0%; background: #23404d; visibility: hidden; }\n#message { width: 61.8382%; height: 73.7762%; top: 14.9421%; left: 3.6542%; color: #ffffff; visibility: visible; }"
          }
        }
      }
    }
  }
}

Notice that the global CSS initially hides both format-specific backgrounds. The matching size variant explicitly overrides visibility to reveal the correct one. Bulletin and third have separate entries even though they share the same starting CSS.

Validation checklist for AI-generated templates

• [ ] edit_mode_global is a boolean and is false when per-format layouts are required.
• [ ] Every key in template_board_formats is a supported format from the screen-format reference.
• [ ] Every supported format has a matching css_size_variants entry containing a CSS string.
• [ ] Every HTML ID has CSS coverage in every size variant, including hidden elements.
• [ ] Format-specific elements have explicit visibility rules in every variant.
• [ ] Standard screen-format media queries are not manually inserted into global or variant CSS.
• [ ] Percentage-based positioning follows the CSS guide; image proportions are handled intentionally.
• [ ] JSON parses correctly, including escaped CSS quotes and line breaks.
• [ ] Existing HTML, layers, asset references, fonts, and registered JavaScript are preserved when updating a template.
• [ ] Every format is previewed for text clipping, unwanted visible images, overlaps, and layout fit.
• [ ] Added or removed formats are reflected in both template_board_formats and css_size_variants.

Related documentation

• Lucit Template CSS Guide
• Screen Format Reference
• Lucit Screen Format Media Queries