[data-reveal]{opacity:1!important;transform:none!important}
AntelopeJS DMS
DocumentationBest practices

Best practices

The three rules every AntelopeJS DMS page follows, why they matter, and the path an agent takes before it builds a custom block.

Every DMS page follows three rules. They keep each part of the page a permission of its own, and keep the page editable by the builder and by agents. The antelopejs:dms-best-practices skill of the antelopejs plugin makes Claude Code, Codex and the DMS AI assistant apply them on every page they build.

A page is always described as blocks

Describe every page on the backend as a tree of DMS blocks: a period selector, a grid of cards, a table, a form. Never describe it as one block that draws the whole screen.

Each block is a line in the roles editor, a target for .watch(), and a node the builder can move. A PeriodSelector can drive it. One block for the whole screen loses all of that.

src/pages/orders.ts ts
import { PageController, RegisterPage, pagesCategory } from "@antelopejs/interface-dms/page";
import { DefaultDataTypes } from "@antelopejs/interface-dms/base/data-types";
import { Grid, GridRow } from "@antelopejs/interface-dms/base/grid";
import { KpiCard } from "@antelopejs/interface-dms/base/kpi-card";
import { PeriodSelector } from "@antelopejs/interface-dms/base/period-selector";
import { TableView } from "@antelopejs/interface-dms/base/table-view";

@RegisterPage()
export class OrdersPage extends PageController("orders", {
  displayName: "$shop.orders.title",
  category: pagesCategory,
}) {
  static period = PeriodSelector({ id: "orders" });

  static kpis = Grid().child(
    "row",
    GridRow()
      .child("revenue", KpiCard({ title: "$shop.orders.revenue", fetchUrl: "/api/orders/revenue", periodScope: "orders" }))
      .child("count", KpiCard({ title: "$shop.orders.count", fetchUrl: "/api/orders/count", periodScope: "orders" })),
  );

  static table = TableView.fromSource({
    fetchUrl: "/api/orders",
    periodScope: "orders",
    columns: {
      reference: { name: "$shop.orders.reference", type: new DefaultDataTypes.StringType() },
      customer: { name: "$shop.orders.customer", type: new DefaultDataTypes.StringType() },
    },
  });
}

Build only the missing block

When a part of the screen has no DMS equivalent, such as a flow canvas or a seat map, build that block alone as a custom component. Keep everything around it as DMS blocks described on the backend. The rest of the page then keeps its permissions, the theme, the period, the live state and the builder.

Every custom block carries .meta()

Every custom block declares its name, description and icon with .meta(), with the name and description as i18n keys. The roles editor then shows a readable line for the block in every language. Without .meta(), the roles editor shows the raw component name.

src/pages/routes.ts ts
import { CustomComponent } from "@antelopejs/interface-dms/base/custom";

export const graph = CustomComponent("ApiRouteGraph")
  .options({ fetchUrl: "/api/routes/graph", periodScope: "api" })
  .meta({
    name: "$api.routes.graph.name",
    description: "$api.routes.graph.description",
    icon: "i-ph-graph",
  });

Add the keys to every locale file of your frontend layer. Use $ keys for every other text too: page names, titles, labels and button labels.

When to leave DMS blocks

A custom block is a deviation from the DMS, so an agent proposes it and lets you decide. It proposes one only in the cases of the left column:

Leave DMS blocks whenStay on DMS blocks when
No block covers the need, even through its options or a composition of blocks.The difference is spacing, color, radius, font or a minor layout that the theme or the block's options handle.
The interaction model differs: a drag-and-drop canvas, real-time collaborative editing.The DMS block only looks slightly different from the mockup.
You asked for pixel perfect on this element.Another element of the page is custom. A custom block never pulls its neighbours along.
A measured constraint, such as performance or data volume, is beyond what the block can meet.The constraint is a guess rather than a measurement.

Before any custom block

An agent follows the same path before it writes any custom block, one element at a time:

Search the catalog

The agent looks for a block that fits. In the DMS AI assistant, it searches the builder catalog of @antelopejs/dms. Elsewhere, it reads the DMS block catalog (GET /api/block-preview/types on a running instance) or the exports of @antelopejs/interface-dms/base. It tries the block's options first, then a composition of blocks, such as a Card that holds a KeyValueList.

Compare

With the mockup tools, the agent builds or updates a mockup that holds the closest DMS option, your design as the reference and a sketch of the custom block it would build. Without them, it writes a short comparison table.

Ask

The agent asks one closed question with three answers: Keep the DMS block, Adjust it through its options, or Build a custom block.

Build

If you choose to adjust, the agent changes the block's options and updates the mockup. Only when you choose the custom block does the agent build it, alone and with .meta(). The rest of the page stays DMS blocks.

In Safe mode, the DMS AI assistant cannot write custom code. It tells you so, offers the closest DMS composition, and asks whether to switch to Code mode for that one block.

When a design is involved

When you hand an agent a mockup or a screenshot, it follows the design-fidelity protocol. It asks one framing question, then runs this path for each component that differs visibly.

Next steps

Design fidelity

From a mockup to blocks, one component at a time.

Block fundamentals

How blocks nest, read data and carry permissions.