Objectui

ObjectUI

A server-driven UI engine: it renders JSON metadata from the @objectstack/spec protocol into React interfaces built on Tailwind and Shadcn — dashboards, kanbans, CRUDs, forms, grids.

Where to go

Rules — read before writing schemas. These are the non-negotiables, and they are the anchor for every rule the guides only cue:

• JSON protocol — what is evaluated, what is read raw, why keys live on the node and not under props, layout responsiveness → rules/protocol.md
• Styling & Tailwind — the two published stylesheets, the @theme / @source split, recolouring → rules/styling.md
• Component composition → rules/composition.md

Scope

In scope: authoring and debugging JSON schemas rendered by SchemaRenderer, and using the @object-ui/* packages — core, components, fields, layout, react, providers, app-shell, plugins, CLI.

Out of scope (defer to the sibling skill):

Core Principles

1. Strict adherence to @objectstack/spec

All component schemas, JSON structures and data types follow @objectstack/spec. Do not invent schema properties — if the spec says columns, do not write fields. Check the spec before writing any interface or type.

2. Protocol agnostic (the universal adapter)

Never hardcode objectql.find() or any specific backend call. Go through the DataSource interface, injected via <SchemaRendererProvider dataSource={...} />. An app may back ObjectUI with REST, GraphQL, ObjectQL or a local JSON file.

3. "Shadcn native" aesthetics

ObjectUI is serializable Shadcn. A component follows Shadcn's DOM structure (CardHeader / CardTitle / CardContent) and always exposes className so styles can be overridden from JSON.

4. The action system (interactivity)

Actions are data, not functions:

{
  "events": {
    "onClick": [
      { "action": "validate", "target": "form_1" },
      { "action": "submit", "target": "form_1" },
      { "action": "navigate", "params": { "url": "/success" } }
    ]
  }
}

@object-ui/core dispatches these through an event bus.

5. Layout as components

Layouts are components that render children. Responsive column counts go on the node as columns — a number, or a breakpoint object (rules/protocol.md has the keys the renderer reads and the one it drops).

6. Type safety over magic

• No any — use strict generics.
• Registry — map type strings ("type": "button") to React components via ComponentRegistry.
• No eval() or runtime dynamic imports for component resolution.

Tech stack (strict constraints)

• Core: React 18+ (hooks), TypeScript 5.0+ (strict).
• Styling: Tailwind CSS. Required: class-variance-authority for variants, tailwind-merge + clsx (cn()) for overrides. Forbidden: inline styles (style={{}}), CSS Modules, styled-components.
• UI primitives: Shadcn UI (Radix) + Lucide icons.
• State: Zustand (global), React Context (scoped).
• Testing: Vitest + React Testing Library + Playwright.

Common mistakes to avoid

• Writing large bespoke React JSX trees before defining a schema.
• Hardcoding API calls inside visual renderers.
• Introducing package coupling (a UI package depending on business logic).
• Registering components without a namespace in plugin-heavy projects.
• Expecting a ${...} on a top-level value / label to evaluate, or "fixing" it by moving it under props — the first renders the literal, the second renders nothing at all. Resolve the value in the host, or carry it on a text node's content (rules/protocol.md).
• Missing the published stylesheet imports — @object-ui/components/style.css then @object-ui/fields/style.css, in that order. Components render but look completely unstyled (rules/styling.md).