Overlays

An OverlaySpec allows tenants or users to customize UI layouts and field visibility without modifying the underlying application code. Overlays are cryptographically signed to ensure they respect policy boundaries and cannot introduce security vulnerabilities.

Why overlays matter

Different users have different needs. A power user might want to see all available fields and actions, while a casual user prefers a simplified interface. A tenant in a multi-tenant application might want to brand the UI or hide features they don't use.

Traditional approaches require either building multiple UIs or adding complex configuration logic throughout the codebase. OverlaySpecs provide a safer, more maintainable solution: users can customize their experience, but only within the bounds allowed by the underlying specs and policies.

What overlays can do

• Hide or show fields

  – Remove fields from forms or detail views (but only if the user has permission to see them in the first place)

• Reorder fields

  – Change the order in which fields appear

• Rename labels

  – Use different terminology that's more familiar to the user

• Change layouts

  – Switch between list, grid, or card views

• Add help text

  – Provide context-specific guidance

• Set default values

  – Pre-fill forms with tenant-specific defaults

• Apply branding

  – Customize colors, logos, and styling (within approved themes)

Example OverlaySpec

Here's an overlay that customizes an order form:

overlayId: acme-order-form
version: '1.0.0'.0.0
appliesTo:
  capability: createOrder
  tenantId: acme-corp

modifications:
  - type: hideField
    field: internalNotes
    reason: "ACME doesn't use internal notes"

  - type: renameLabel
    field: customerReference
    newLabel: "PO Number"

  - type: reorderFields
    fields:
      - customerReference
      - items
      - shippingAddress
      - billingAddress
      - paymentMethod

  - type: setDefault
    field: paymentMethod
    value: "net30"

  - type: addHelpText
    field: customerReference
    text: "Enter your purchase order number from your procurement system"

  - type: makeRequired
    field: customerReference

signature:
  algorithm: EdDSA
  publicKey: "acme-corp-overlay-key"
  signature: "base64-encoded-signature"

Safety guarantees

Overlays are powerful, but they must not compromise security or data integrity. ContractSpec enforces several guarantees:

• Overlays cannot grant new permissions

  – They can only hide or rearrange what the user is already allowed to see

• Overlays cannot bypass validation

  – Field types, constraints, and business rules from the underlying spec still apply

• Overlays must be signed

  – Only authorized parties (typically tenant admins) can create overlays

• Overlays are versioned

  – Changes to overlays are tracked and can be rolled back

• Overlays are audited

  – Every overlay application is logged

Creating overlays

Overlays can be created through:

• Visual editor

  – A drag-and-drop interface for non-technical users

• TypeScript/JSON

  – For developers who prefer code

• API

  – Programmatically create overlays for automation

Once created, overlays must be signed using a private key. The corresponding public key is registered with ContractSpec, which verifies the signature before applying the overlay.

See Overlay Engine docs and the Overlay Editor guide for end-to-end workflows.

Overlay scope

Overlays can be scoped to:

• Tenant

  – All users in a tenant see the same overlay

• User

  – Individual users can have personal overlays

• Role

  – All users with a specific role see the overlay

• Device

  – Different overlays for mobile vs desktop

If multiple overlays apply to the same user, they are merged in order of specificity (user overlays override role overlays, which override tenant overlays).

Best practices

• Start with the default UI and only create overlays when users request specific changes.

• Document why each overlay modification was made—this helps when reviewing or updating overlays.

• Test overlays thoroughly to ensure they don't break workflows or confuse users.

• Use tenant-level overlays for organizational customizations and user-level overlays for personal preferences.

• Regularly review overlays to remove ones that are no longer needed.

• Protect overlay signing keys carefully—they control what customizations are allowed.

Where overlays fit in the runtime

Overlays are safest when they sit on top of a declared bundle surface instead of ad hoc page code. Use the module-bundles docs first, then apply overlays as auditable customization on top of the resolved surface plan.