Global Classes (Embed Format)

Global Classes are named CSS classes (e.g. btn-primary, card-hover) created in the builder UI and **stored at the site DB level**. Apply once, edit anywhere — changing the class style updates every element that references it.

Element reference

Elements reference a class via shortId at top-level classes:

{
  "id": "btn001ax",
  "type": "button",
  "props": {...},
  "classes": ["7c58e7b3"]
}

shortId is an 8-char stable handle — unchanged when the class is renamed.

Embedded in Alus File Export

When you Export a schema whose elements use global classes, the builder embeds the class definitions in the JSON:

{
  "source": "alusioCopiedElements",
  "version": "1.4.0",
  "exportedAt": "2026-05-09T10:00:00.000Z",
  "sourceUrl": "https://your-site.alusio.com",
  "elements": [
    {
      "id": "btn001ax",
      "type": "button",
      "props": { "text": "Buy", "link": "/checkout", "alignment": "center", "width": "auto" },
      "classes": ["7c58e7b3"]
    }
  ],
  "globalClasses": [
    {
      "id": "7c58e7b3",
      "name": "btn-primary",
      "desktopStyle": {
        "background": { "color": "#3b82f6" },
        "typography": { "color": "#ffffff", "fontWeight": "600" },
        "layout": { "paddingTop": "12px", "paddingBottom": "12px", "paddingLeft": "24px", "paddingRight": "24px" },
        "border": { "radius": { "topLeft": "8px", "topRight": "8px", "bottomLeft": "8px", "bottomRight": "8px" } }
      },
      "pseudoStates": {
        ":hover": {
          "desktop": { "background": { "color": "#2563eb" } }
        }
      }
    }
  ]
}

The file is portable — paste into another site and the class travels with it.

ExportedGlobalClass shape

interface ExportedGlobalClass {
  id: string                  // 8-char shortId
  name: string                // human label, used as DOM class
  category?: string
  desktopStyle?: ElementStyle
  tabletStyle?: ElementStyle
  mobileStyle?: ElementStyle
  pseudoStates?: {
    [pseudo: string]: {       // ":hover" | ":active" | ":focus" | ":visited"
      desktop?: ElementStyle
      tablet?: ElementStyle
      mobile?: ElementStyle
    }
  }
}

ElementStyle has groups layout, typography, background, border, plus optional boxShadow. Drop unused groups.

Persistence on Import

When importing a file with globalClasses, the builder:

1. Pre-checks for conflicts: compares each incoming class to existing site classes (by name)
   • No class with the same name → create
   • Same name + identical style → auto-skip (use existing)
   • Same name + different style → conflict (per-class modal)
2. Conflict modal appears if there are style mismatches. Per class:
   • Skip — use existing, ignore imported style
   • Replace — overwrite existing with imported (affects every page using this class)
   • Rename — insert with a new name (e.g. btn-primary-imported)
3. Persists to the site's global_classes DB table.
4. Reusable across pages — the new class shows up in the builder UI for any page in the same site.

Hand-crafted globalClasses

You can hand-write classes in JSON without using the UI first — Import will persist them to the pool:

{

  "elements": [
    {
      "id": "h001abcd",
      "type": "heading",
      "props": { "text": "Promo!", "level": "h2", "alignment": "center" },
      "classes": ["promo01"]
    }
  ],
  "globalClasses": [
    {
      "id": "promo01",
      "name": "promo-text",
      "desktopStyle": {
        "typography": { "color": "#dc2626", "fontWeight": "700" }
      }
    }
  ]
}

After Import: promo-text is saved at the site → other pages can apply it via the builder.

Validation rules

• id: 4-20 char string
• name: 1-100 char, only [a-zA-Z0-9_-]+ (CSS-class-safe)
• desktopStyle etc: valid ElementStyle shape (layout/typography/background/border + boxShadow)
• Classes with the same id but different name are treated as separate — name is the primary conflict key

Tips

• Pick shortIds 4-8 chars long; avoid clashes with element ids (allowed, but confusing when reading JSON)
• Use category to group classes in the builder UI (e.g. "buttons", "cards")
• For a shared design system, export → commit JSON to Git → other team members import = same classes & styles