MATRIZ — Canonical Terminology
One word per concept. When code, UI, or docs disagree, this file wins. Casing convention across boundaries: DB columns are
snake_case, TypeScript types/fields arecamelCase, and REST/JSONB wire payloads usesnake_case(to match DB column names). Drizzle converts between the first two automatically.
| Concept | Canonical term | What it is | Do NOT also call it |
|---|---|---|---|
| Tree element | node (API/types); UI may say “element” for UX | A row in dom_nodes — a div/section/heading/component-instance in the page tree. |
domNode (ok as the TS type DomNode), “block” |
| Page | page (informal) | A subtree rooted at a dom_node with is_page_root = true, addressed by page_path. |
— |
| Page metadata | site_page | Editorial/SEO metadata row (site_pages: title, slug, seo, status). Distinct from the node tree. |
“the page record” (ambiguous) |
| Reusable definition | component | A template in the components table (Button, Card, …). |
“element definition” |
| A component on a page | component instance | A node carrying component_instance JSONB (variant + slot overrides + link status). |
“component node” (ok informally) |
| Content schema column | field | A column in a content_type.schema (CMS). |
“slot” |
| Component/text content key | slot | A keyed content value on a node (slot_values), e.g. text, src, href. Y.Text-backed for text. |
“field”, “property” |
| CMS row | content item | A row in content_items (itemId in REST params, ContentItem in TS). |
— |
| Repeating UI container | repeater | A node that renders its template once per item of a bound collection. | “list block” |
| The bound data set | collection | A content_type with many items (data_source.type = 'content_collection'). |
“repeater” (that’s the UI), “list” |
| Node → data link | data_binding | JSONB on a node mapping it to a collection/item + per-slot bindings. | “binding config” |
| Design token | design token (DesignToken TS / /api/tokens REST / design_tokens DB) |
A named design value resolved to a CSS variable. | “variable” |
| Make a site live | publish | Compile published nodes → static HTML → R2 (POST /api/publish/:siteId). |
“deploy”, “build” |
| Ship code/infra | deploy | wrangler deploy / CI deploy of the Worker or Pages app. |
“publish” |
| Record of a publish | build | A row in builds tracking one publish’s result. |
“deploy” |
Version noise — do not introduce
Section titled “Version noise — do not introduce”The v2/v3/v4 suffixes are historical and have been removed from code (zero v3
identifiers remain). The component system is just “the component system”. Plan/schema
files keep a version in their filename only as a document version, never in code identifiers.