← Utilities

Databoard Utilities Loop

How sass_v2, template defaults, Databoard field CSS, Databoard Sass, utility generation, and the agent API connect into one generated-site styling system.

🤖 Let AI help you style your site

Copy this prompt to ChatGPT, Claude, or any AI — it will understand ANTSAND's Databoard styling system and walk you through it.

Full Styling Control Stack

ANTSAND styling is intentionally layered. Agents should decide which layer owns a change before writing CSS. This keeps framework work reusable while allowing each generated site to have full page, section, and field-level control.

1. sass_v2 Framework

styles_antsand/sass_v2 defines shared tokens, components, utilities, patterns, and theme presets used across many generated sites.

2. Template Defaults

parameter_files.json defines the default class slots and starting classes for every section template and field.

3. Runtime Extraction

common_init_modern.volt reads saved Databoard CSS JSON and creates variables like data_h3_class, data_p_class, and section_container_class.

4. Runtime Rendering

service_3_modern.volt and component renderers apply those variables to the fixed Header/Body/Footer HTML hierarchy.

5. Databoard Field CSS

The UI stores per-page, per-section, and per-field classes such as section.container, data.container, data.sub_container, data.h3, data.p, and data.cta.

6. Databoard Sass

The board-level Sass editor owns one website's branding, page CSS, custom section classes, and overrides. This is site-specific CSS, not shared sass_v2 framework code.

7. Utility Compiler

The Databoard utility scanner reads saved css_class values and generates board-local _utilities.scss for Tailwind-like classes used by that site.

8. Agent API Loop

Agents can inspect a board, patch HMVC/list/menu/Sass, compile utilities, deploy, and smoke-test without manually clicking every UI knob.

Which Layer Should An Agent Change?

The Utility Loop

sass_v2/foundation/_utilities.scss
CSS rule definitions
→
antsand-v2.css
Compiled via sassc
→
Databoard Field CSS
Agent/user types class names
→
Sass Scanner
Scans css_class values
→
Site _utilities.scss
Board-specific rules

Step 1: Global utility classes are defined in sass_v2/foundation/_utilities.scss and compiled into antsand-v2.css.
Step 2: antsand-v2.css is served from the CDN (styles.antsand.com) and loaded by all generated sites.
Step 3: In Databoard, agents and users assign class names to fields via the CSS panel (e.g., data.h3 = "line-clamp-2 md:text-xl").
Step 4: The Databoard Sass scanner reads all css_class values from the datalist and detects which utilities are used.
Step 5: Board-specific utility rules (not in the global library) are written to a site-local _utilities.scss during Databoard Sass generation/compile before deployment.

Two-Tier CSS System

ANTSAND uses semantic classes first, utility classes second. Every section needs a design identity (Tier 1) before fine-tuning (Tier 2).

Tier 1 — Semantic Classes (Identity)

Define what a section IS. One root class + descendant selectors per section. 

// Component SCSS — root class with descendants
.pricing-grid {
    display: grid;
    grid-template-columns: repeat(3, 1fr);
    gap: 2rem;

    .data-sub-container { border-radius: 12px; }
    .data-h3 { font-size: 1.5rem; font-weight: 700; }
    .data-cta { width: 100%; }
}

// Semantic component classes:
// antsand-card, antsand-btn-primary, antsand-section-dark,
// antsand-grid-3, antsand-flex-between
Tier 2 — Utility Classes (Fine-Tuning)

Enhance individual fields within a Tier 1 structure. Never use alone. 

<!-- Utilities AUGMENT the semantic root -->
<div class="pricing-grid">                                   <!-- Tier 1 root -->
  <div class="antsand-card shadow transition-all              <!-- Tier 1 + Tier 2 -->
              hover:-translate-y-1 hover:shadow-lg">           <!-- Tier 2 motion -->
    <div class="aspect-video">                                <!-- Tier 2 media -->
      <img class="object-cover" />
    </div>
    <h3 class="line-clamp-2 md:text-xl">Title</h3>           <!-- Tier 2 text -->
    <p class="line-clamp-3 opacity-75">Excerpt</p>           <!-- Tier 2 truncation -->
    <button class="antsand-btn antsand-btn-primary">Buy</button> <!-- Tier 1 only -->
  </div>
</div>
Board-Specific — Generated by Databoard

When a site needs utility-like rules that don't belong in the global library, the Databoard Sass scanner generates a site-local _utilities.scss during Databoard Sass generation/compile. 

// Board-specific rules — auto-generated, NOT in sass_v2
// e.g., custom brand colors, one-off layout tweaks
.brand-gradient { background: linear-gradient(135deg, #b90000, #ff4444); }
.hero-height { min-height: 60vh; }

Examples by Component

How to combine Tier 1 + Tier 2 in Databoard field mappings for common section types.

🧭 Navigation (Header Scope)
// Databoard field → class mapping
header.section    = "antsand-section antsand-section-dark"         // Tier 1 — identity
header.container  = "antsand-container antsand-flex-between"       // Tier 1 — layout
header.h1         = "text-xl font-bold"                            // Tier 2 — fine-tune
header.cta        = "antsand-btn antsand-btn-outline-primary"      // Tier 1 — identity

// Root SCSS for nav-specific descendants
.site-nav {
    header.section { backdrop-filter: blur(8px); }
    .nav-link { transition: color 0.2s; }
    .nav-link:hover { color: var(--primary); }
}
🃏 Card Grid (Body Scope)
// Databoard field → class mapping
data.container      = "services-grid antsand-grid md:grid-cols-3 gap-4 md:gap-6"
data.sub_container  = "antsand-card antsand-card-shadow transition-all hover:-translate-y-1"
data.img_container  = "aspect-video"
data.img            = "object-cover rounded-lg"
data.h3             = "line-clamp-2 font-semibold md:text-xl"
data.p              = "line-clamp-3 opacity-75 text-sm"
data.cta            = "antsand-btn antsand-btn-primary antsand-btn-sm"

// Root SCSS
.services-grid {
    .data-sub-container:first-child { border-top: 3px solid var(--primary); }
}
📰 Blog Article (Body Scope)
// Databoard field → class mapping
data.container      = "blog-listing antsand-grid md:grid-cols-2 lg:grid-cols-3 gap-6"
data.sub_container  = "antsand-card shadow transition-all hover:shadow-lg"
data.img_container  = "aspect-photo"                                // 4:3 ratio
data.img            = "object-cover"
data.h3             = "line-clamp-2 font-bold"
data.p              = "line-clamp-3 opacity-75"
data.span           = "text-sm font-mono opacity-50"               // date/meta
data.cta            = "antsand-btn antsand-btn-outline-primary antsand-btn-sm"

// Root SCSS — blog-specific refinements
.blog-listing {
    .data-sub-container { overflow: hidden; }
    .data-span { font-family: 'JetBrains Mono', monospace; }
}
🦶 Footer (Footer Scope)
// Databoard field → class mapping
footer.section    = "antsand-section antsand-section-dark md:py-6"
footer.container  = "antsand-container antsand-grid md:grid-cols-4 gap-6"
footer.h3         = "text-sm font-bold uppercase"
footer.p          = "text-sm opacity-75"
footer.cta        = "opacity-75 hover:opacity-100 transition-opacity"

// Root SCSS
.site-footer {
    .footer-links { list-style: none; padding: 0; }
    .footer-links a { color: inherit; text-decoration: none; }
    .footer-links a:hover { transform: translateX(4px); }
}
📋 Contact Form (Body Scope)
// Databoard field → class mapping
data.container      = "contact-form antsand-container md:p-8"
data.content_wrapper = "antsand-card antsand-card-shadow p-6 md:p-8 rounded-lg"
data.h2             = "text-2xl md:text-3xl font-bold text-center"
data.p              = "text-center opacity-75 mb-6"

// Form fields use Tier 1 semantic classes exclusively:
// antsand-form-group, antsand-form-label, antsand-form-control
// Enhance with Tier 2 for focus: focus:ring-primary transition-colors

// Root SCSS
.contact-form {
    .antsand-form-control:focus {
        border-color: var(--primary);
        box-shadow: 0 0 0 3px rgba(var(--primary-rgb), 0.15);
    }
}

Stable Shared Utilities

These classes are defined in sass_v2/foundation/_utilities.scss, compiled into antsand-v2.css, and available on all generated sites via the CDN. Safe to use in any Databoard field.

Category Classes Typical Databoard Field
Spacing p-1..p-8, px-*, py-*, m-1..m-8, mx-auto, gap-1..gap-8 data.container, section.container
Display block, hidden, flex, grid, inline-flex data.container, data.span_container
Flexbox flex-row, flex-col, flex-wrap, items-center, justify-between data.container, header.container
Typography text-sm..text-5xl, font-bold, font-semibold, text-center data.h3, data.p, header.h1
Line Clamp line-clamp-1..line-clamp-5, truncate data.h3, data.p, data.description
Opacity opacity-0, opacity-25, opacity-50, opacity-75, opacity-100 data.p, data.span, footer.p
Aspect Ratio aspect-video (16:9), aspect-square (1:1), aspect-photo (4:3), aspect-portrait (3:4) data.img_container
Object Fit object-cover, object-contain, object-center, object-top data.img
Borders rounded, rounded-lg, rounded-full, border, border-0 data.sub_container, data.img
Shadows shadow-sm, shadow, shadow-md, shadow-lg, shadow-xl data.sub_container, data.content_wrapper
Transitions transition-all, transition-colors, transition-opacity, duration-200..duration-500 data.sub_container, data.cta
Hover hover:scale-105, hover:-translate-y-1, hover:shadow-lg, hover:opacity-100 data.sub_container, data.cta
Backdrop backdrop-blur, backdrop-blur-lg, bg-white/85, bg-black/50 header.section, overlay elements
Divide / Space divide-y, divide-x, space-y-2..space-y-8, space-x-2..space-x-4 data.container, footer.container
Focus / Ring ring, ring-primary, focus:ring, focus-visible:ring form inputs, data.cta
Animation animate-fade-in, animate-slide-up, animate-spin, animate-pulse data.sub_container, loading states
Scroll scroll-smooth, snap-x, snap-start, scrollbar-hide data.container (carousel sections)
Height min-h-screen, max-h-[500px], h-screen, h-[50vh] section.container, data.img_container
Whitespace whitespace-nowrap, whitespace-pre-wrap, break-words data.p, data.description

Responsive Prefixes

Mobile-first breakpoint prefixes. Unprefixed = all screens. Prefixed = that breakpoint and up.

Prefix Breakpoint Available Utilities
sm: 640px+ display, grid-cols (1-3), flex
md: 768px+ display, flex-direction, grid-cols (1-4), text-align, spacing (p, gap), text sizes (lg-4xl)
lg: 1024px+ display, grid-cols (2-6), text-align, text sizes (2xl-5xl) 
// Responsive grid — 1 col mobile → 2 col tablet → 4 col desktop
data.container = "antsand-grid grid-cols-1 md:grid-cols-2 lg:grid-cols-4 gap-4 md:gap-6"

// Responsive text — scales up at larger screens
header.h1 = "text-2xl md:text-4xl lg:text-5xl font-bold"

// Responsive spacing
section.container = "antsand-section p-4 md:p-6 md:py-8"

// Show/hide by breakpoint
data.sidebar = "hidden md:block"

Rules for Agents

⚠️ Semantic class first, utility class second

Every section MUST have a Tier 1 root class defining its design identity. Tier 2 utilities are modifiers on individual Databoard fields — never the primary structure.

Do Don't
Section root data.container = "pricing-grid antsand-grid" data.container = "flex flex-wrap gap-4 p-8"
Cards "antsand-card shadow transition-all" "bg-white rounded-lg border p-4"
Buttons "antsand-btn antsand-btn-primary" "px-4 py-2 bg-blue-500 text-white rounded"
Images "aspect-video object-cover" (Tier 2 is fine for media) No aspect-ratio → images distort or overflow
Text truncation "line-clamp-3 opacity-75" (Tier 2 for text control) Raw CSS style="overflow:hidden" on the field
Board-specific Let Databoard Sass scanner generate site-local rules Adding one-site rules to the global _utilities.scss

Agent API Loop

The same styling model can be driven through the Databoard API. This is the agent-friendly path: inspect the board, patch the field classes/Sass, compile generated utilities, deploy, then smoke-test. 

# 1. Inspect board state
GET /api/v1/databoards/{objectid}

# 2. Patch HMVC/list/menu/Sass using Import DSL patch semantics
POST /api/v1/databoards/{objectid}/patch

# 3. Compile Databoard Tailwind-like utilities after class/Sass changes
POST /api/v1/databoards/{objectid}/utilities/compile

# 4. Deploy generated site when the board is ready
POST /api/v1/databoards/{objectid}/deploy

# 5. Smoke-test generated routes and visual contracts
make test-site-smoke SITE=https://example.com
Agent Goal Best API/Layer Why
Change nav/footer/classes on existing pages /patch or /list Classes belong to Databoard field mappings, not hardcoded templates.
Add one-site CSS for ShivasNotes-style branding Databoard Sass/common_styles Website-specific CSS should travel with the board.
Add utility classes like px-6 py-16 sticky top-0 /utilities/compile The compiler scans field CSS and emits board-local utility rules.
Create reusable class for all future sites sass_v2 Git change Framework-level rules should be versioned and shipped through antsand-v2.css.
Make a better default section template parameter_files.json Template defaults seed the UI and should match runtime field aliases.

Dual Naming Convention

Most utilities have both an antsand- prefixed version (Bootstrap-style) and an unprefixed version (Tailwind-compatible). Both work — use whichever is more readable.

ANTSAND Prefixed Unprefixed Effect
antsand-text-centertext-centertext-align: center
antsand-text-whitetext-whitecolor: white
antsand-flex-centeritems-center justify-centercentered flex items
antsand-shadow-lgshadow-lglarge box-shadow
antsand-p-4p-4padding: 1.5rem
antsand-mb-3mb-3margin-bottom: 1rem
antsand-rounded-lgrounded-lgborder-radius: 0.75rem