Agent conventions

Apply these rules after confirming the project uses Systhema. The installed consumer skills provide the detailed examples; this page is the review checklist.

Inspect before implementingLink to this section

Read the installed version, systhema.config.ts, existing routes and .systhema/references/tokens/_index.toon. If the references are missing, sync and re-read them before styling.

node -p "require('./node_modules/@systhemaui/core/package.json').version"
pnpm sync

Use project files for token values, modes, variants and breakpoints. Use version-matched documentation for APIs, props, blocks and commands. Do not measure the browser to infer token values or replace project facts with documentation defaults.

Tokens own the designLink to this section

Prefer component props and Systhema utility classes, then token-backed CSS variables when one property needs an override. Express brand changes in Design or customTokens, in runtime token shape.

Do not hand-edit exported src/tokens/*.json, generated references, generated types or .systhema/artifacts. Import a design export or use supported CLI operations, then sync.

Avoid hardcoded JSX colors, spacing, typography, shadows and radii when a token-backed affordance exists. Do not derive a token value from a screenshot. Use next/font or project-local font loading rather than a remote CSS @import in Next.js.

Use the project's breakpoint minWidth for responsive behavior, not its design screen width. In the shipped system, sm starts at zero, so use unprefixed classes for the base layout and md: or lg: for overrides. Read project overrides before assuming breakpoint thresholds. Large-screen layout caps live in customTokens.responsiveSizing, not newly invented responsive modes.

For a real styling gap, keep project rules in @layer app and derive their values from tokens. Do not copy a complete native component's styling into project CSS.

Compose the shipped componentsLink to this section

Use @systhemaui/next in Next.js pages. Check the catalog before rebuilding a card, grid, hero, form field or menu with raw Tailwind.

Use named variants such as primary, secondary, default and highlighted only when the project defines them. Themes and layout backgrounds are also token-defined names.

import { Section, Heading, Paragraph } from '@systhemaui/next'

export function Intro() {
  return (
    <Section>
      <Heading.h2>Our approach</Heading.h2>
      <Paragraph>Start with what the team needs.</Paragraph>
    </Section>
  )
}

Render this inside an Article. Keep prose as direct children of rich-text containers so their spacing rules apply. Do not put headings and paragraphs inside a vertical Stack or add space-y-* and margins to reproduce the rhythm.

Section padding={n} is a horizontal column inset. A single inline button, chip or icon belongs in a Paragraph; a row of inline items can use Stack. A still uses Figure and a sized Image; MediaWrapper is for playable media composition.

Preserve page and editor boundariesLink to this section

Code-owned pages have <main id="main-content"> and an Article containing Sections. The CMS page template owns that skeleton, so a block does not add another one.

Keep root content unwrapped when it contains section-level blocks. A template-wrapped field accepts region content only. Choose root, region, fragment or slot editors for their field roles; an editor builder does not force a block's nesting tier.

Start with native page blocks. Add a collection for shared records, a custom block for a real layout or query requirement, and a template field only when the page cannot work without it.

Respect project ownershipLink to this section

Project layouts, components, blocks, config and src/lib/ are yours. Keep consumer code out of (systhema) and do not patch (payload) routes to change the public site.

Review managed .new files during upgrades. Never edit package dist/, generated Payload types or the import map by hand. Regenerate them through the project's scripts.

Keep client code browser-safeLink to this section

A 'use client' boundary includes transitive imports. Keep payload, database code and runtime imports from the bare @systhemaui/core barrel out of client-reachable modules. Use @systhemaui/core/client for runtime client token readers and import type for types.

Custom blocks need browser converter registration for client preview. Use client setup and test both preview and published rendering.

Use pnpm and prove completionLink to this section

Use the project's configured pnpm scripts. The Payload starter's pnpm sync generates Systhema artifacts, Payload types and the import map.

pnpm exec tsc --noEmit
pnpm lint
pnpm format

Use a render or build check when authorized to catch boundary and runtime errors. For schema changes, plan the database lane and verify preserved data. Report failures and untested behavior explicitly.

See Project structure, Spacing model and Client and server code.