Uniform

View saved version →

---
name: uniform-assets
description: >-
  Working with Uniform image/media assets end to end — defining an `asset`
  parameter, rendering an image `src` with `imageFrom` (the graceful,
  future-proof default), reading other fields off the raw asset item, the stored
  asset-value shape, DAM library assets vs external `custom-url` assets,
  seeding/migrating asset values in compositions, and the traps around parameter
  type transitions. Use when a component needs an image/photo/video from Uniform,
  when converting a `text` URL field to an `asset` field, when you want
  responsive/transformed images with focal points.
---

# Uniform assets

How to model, render, and author image/media assets in this Uniform.

## 1. Choose the parameter type deliberately

| Use | When |
|-----|------|
| `asset` parameter | Real content authors will pick/manage the image; you want the Canvas asset picker, DAM library, and image CDN/transforms. **Default for authored imagery.** |
| `text` parameter (URL) | Quick/pragmatic cases, throwaway/demo data, or an image URL that's genuinely just a string the author pastes. Simpler, but no picker, no metadata, no CDN transforms. |

Don't reach for `text` just to avoid the asset plumbing — the plumbing is small
(below). Reach for `text` only when a bare URL really is the right model and a text input is the right editor experience.

## 2. Define an asset parameter

In the component definition. Via MCP `mutateComponent` or `uniform-data/component/<type>.json`:

```json
{
  "id": "photo",
  "name": "Photo",
  "type": "asset",
  "typeConfig": { "allowedTypes": ["image"] },
  "guidance": "A square headshot image. If empty the card shows initials."
}
```

- `typeConfig.allowedTypes` ∈ `["image", "video", "audio", "other"]` (one or more).
- The parameter `id` must match the key you destructure in the `.tsx`.

## 3. Render an image `src` — `imageFrom` (the default)

**Default to `imageFrom` for turning an asset parameter into an img `src`.**
It is the most future-proof choice:

- Accepts a **raw asset item OR a bare URL string**, so it keeps working if the
  parameter's source ever changes (DAM ⇄ `custom-url` ⇄ external).
- **No-ops transforms** for non-image assets and anything outside the Uniform
  Asset Library — external / other-DAM URLs pass through unchanged, so one code
  path is correct for every source.
- **Auto-applies the asset's focal point** plus your resize/fit *when the image is
  a Uniform DAM asset*. Those features "just start working" after a move to the
  DAM, with **no code change**.

Use the `imageFrom` and `AssetParamValue` from `@uniformdev/assets`

```ts
import { imageFrom, type AssetParamValue } from "@uniformdev/assets";
```

### For use with a `ComponentParameter<AssetParamValue>`

When the parameter type you are working with is `ComponentParameter<AssetParamValue>`, first access the `.value`. It is an `AssetParamValue`, which is an array of `AssetParamValueItem`.

```tsx
// photo?: ComponentParameter<AssetParamValue>
const item = photo?.value?.[0];
```

### Build an img from a single `AssetParamValueItem`

Once you have a single item, build an img src and attributes from the `AssetParamValueItem` that `imageFrom` needs.

```tsx
const src = item
  ? imageFrom(item)
      .transform({ width: 192, height: 192, fit: "cover" })
      .url()
  : undefined;

if (!src) return null;
return <img src={src} alt={item?.fields.title?.value ?? ""} width={192} height={192} />;
```

Safety rules:

- **Give `imageFrom` a single item or a string — never the array.**
  `imageFrom([item])` returns `""` (empty), not the URL. Use `value[0]`.
- **Guard `undefined`/`null`.** `imageFrom(undefined)` / `imageFrom(null)`
  **throw** (`Cannot read properties … (reading 'fields')`). The `photo?.value?.[0]
  ? … : undefined` shape guards this; `imageFrom({}).url()` returns `""`.

`transform` options (`ImageFromTransformProps`): `width?`, `height?`,
`fit?: 'scale-down' | 'contain' | 'cover'`; and for `fit: 'cover'` also
`focal: 'auto' | 'center' | { x, y }` (numbers 0–1). The asset's own focal point
is respected automatically. Bare `imageFrom(asset).url()` extracts the URL with no
transform.

### With `next/image`

Enable the Uniform image host, then feed `imageFrom(...).url()` as `src`:

```ts
// next.config.ts
images: { remotePatterns: [{ protocol: "https", hostname: "img.uniform.global" }] }
```

Read intrinsic dimensions from the raw item (`item.fields.width?.value`) for DAM
assets; fall back to sensible defaults for external images.

## 4. Read other fields — off the raw item

`imageFrom` gives you the `src`. You already hold the **raw asset item** you passed
to it (`photo?.value?.[0]`), so **read the other fields straight off that item** —
each is a `{ type, value }` pair under `.fields`:

```tsx
const item = photo?.value?.[0];
const alt = item?.fields.title?.value ?? item?.fields.description?.value ?? "";
const width = item?.fields.width?.value;
const height = item?.fields.height?.value;
```

An item carries under `.fields` (whatever the asset has): `url`, `title`,
`description`, `mediaType`, `width`, `height`, `size`, `focalPoint`.

## 5. The stored asset-value shape

What lives in the composition JSON (and what Canvas edits) is an **array of
asset items** (`AssetParamValueItem[]`), even for a single image:

```json
"photo": {
  "type": "asset",
  "value": [
    {
      "type": "image",
      "_id": "<uuid>",
      "_source": "custom-url",
      "fields": {
        "url":       { "type": "text",   "value": "https://…/photo.jpg" },
        "title":     { "type": "text",   "value": "Jane Doe" },
        "mediaType": { "type": "text",   "value": "image/jpeg" },
        "width":     { "type": "number", "value": 300 },
        "height":    { "type": "number", "value": 300 }
      }
    }
  ]
}
```

`_id` is a unique ID that can be passed to a key attribute in certain frontend frameworks like React.

`_source` identifies where the asset came from (constants from `@uniformdev/canvas`):

- `ASSETS_SOURCE_UNIFORM` = `"uniform-assets"` — a managed **DAM library** asset.
- `ASSETS_SOURCE_CUSTOM_URL` = `"custom-url"` — an **external URL** with
  manually-set fields (no upload).

At render time `photo.value` arrives as this same `AssetParamValueItem[]` (each
element has `.fields`) — which is exactly what `imageFrom(value[0])` wants.

## Reference

- Rendering, `ComponentProps`, slots: `uniform-nextjs-app-router` skill,
  `references/components.md` (§ "Asset parameters").
- Uniform docs: "Rendering assets" — https://docs.uniform.app/docs/guides/composition/manage-assets/rendering-assets
- Modeling parameters/slots well: `uniform-experience-modeling` skill.

Referenced files: 1

View saved version →

---
name: uniform-automations
description: >-
  Uniform Automations (`defineAutomation`, `defineScoutAutomation`, `ScoutClient`, `*.automation.ts`). Use when handling a Uniform content event, a schedule, an inbound webhook, an `aiTool`, a Scout workflow-stage job, a Uniform sync with an external system, or reviewing a `*.automation.ts` module.
license: MIT
---

# Uniform automations

Serverless functions authored in the user's repo and deployed with the Uniform CLI. This skill is the judgement the SDK types don't give you. Product surface: [automations guide](https://docs.uniform.app/docs/guides/automations). Signatures: JSDoc in `@uniformdev/automations-sdk` and `@uniformdev/canvas`.

## Mental model

One automation is one TypeScript module that default-exports the result of a define function. Everything else it imports is just modules.

| | `defineAutomation({ metadata, handler })` | `defineScoutAutomation(metadata, instructions)` |
|---|---|---|
| You write | code | natural-language instructions |
| The actions are | whatever your handler does | the tool calls the Scout agent makes |
| Runs as | your bundled code, in Uniform's sandbox | Uniform's Scout agent, headlessly |
| `permissions` | optional | required — the agent has no authority without a role |
| Cost | compute only | consumes AI credits per run |

Both live in `*.automation.ts`; the CLI infers which from the default export. The public ID is the filename: `send-welcome.automation.ts` deploys as `send-welcome`. Renaming orphans the deployed automation; deleting the old one is a separate `uniform automation delete`.

## Decision procedure

State, in order, before opening any file: Kind (`handler` | `scout` | `hybrid`), Binding (`stage <id>` | `event <name>` | `none`), Triggers (the array), Filter (the CEL, or `none`), Identity (`role <name from the user>` | `none`).

**1. Kind.** Handler for deterministic work. Reach for AI only where the task is judgement-shaped. `defineScoutAutomation` when the whole job is agentic; `defineAutomation` plus `ScoutClient` when you need control around one AI step. [Code automations](https://docs.uniform.app/docs/guides/automations/code-automations) are this skill's path.

**2. Binding.** Work *to* content binds to a `workflow.transition` on a stage the automation owns. A save is not a binding. One owning automation per auto-transitioning stage. [workflows](https://docs.uniform.app/docs/guides/composition/workflows).

**3. Triggers.** Always an array. Events, `schedule`, and `incomingWebhook` compose and reduce to one `eventType`-discriminated `input` union. `aiTool` is exclusive — it runs as the invoking caller. At most one `schedule`, at most one `incomingWebhook`, no duplicate event names. Event names and payloads: `@uniformdev/webhooks`, [webhooks](https://docs.uniform.app/docs/guides/webhooks), [event catalog](https://www.svix.com/event-types/us/org_2HgMLYs57QWpjfM80UPmW98qTgT/).

**4. Filter.** Cheap predicates go in the CEL `filter`; keep filters total (only fields the payload schema guarantees). Expensive predicates and authenticity checks stay in the handler. A miss records no run. [filtering](https://docs.uniform.app/docs/guides/automations/triggers#filtering).

**5. Identity.** No `permissions` means no Uniform API access. Role names are not discoverable: ask the user which role to grant, or to create one. They can only grant roles they hold; automations cannot run as a team admin. [the automation identity](https://docs.uniform.app/docs/guides/automations/code-automations#the-automation-identity).

When Kind is `scout` or `hybrid`, read [references/scout.md](references/scout.md). Then read [references/best-practices.md](references/best-practices.md) — workflow-stage, filters, outcomes, delivery, limits, and webhook auth if Triggers includes `incomingWebhook`.

Then write:

6. Module shape: [references/sdk-api.md](references/sdk-api.md). Copy a [template](templates/) when the types don't lead you there — stage (`on-workflow-stage`), Scout in a handler (`scout-client`), Scout instructions (`scout-workflow-stage`).
7. Filter first, then handler. Explicit outcome on every path.
8. Unit test by calling the default export; invoke contract in [references/sdk-api.md](references/sdk-api.md).
9. Walk [references/review-checklist.md](references/review-checklist.md) before deploying.
10. Leave deploy to the user: `npx uniform automation deploy` (or a project npm script). [CLI automation](https://docs.uniform.app/docs/guides/cli/commands/automation).

## Guardrails

- Reads that will be written back: invoke `uniform-sdk`, then return here.
- Secrets: literal `process.env.UNIFORM_ENV_*`.
- Logs: operation + entity id.
- Notifications: wrap, continue.
- Handlers: idempotent.

Referenced files: 8

View saved version →

---
name: uniform-content-modeling
description: Best practices for content modeling in Uniform — designing content types with well-chosen fields, validations, and naming, deciding what belongs in structured content vs the experience layer, modeling content classification (categories, tags, taxonomies), modeling relationships between entries with references, designing content for discoverability across search and answer engines and multi-channel delivery, and organizing entries for reuse and localization. Use when creating or updating Uniform content types or entries, migrating structured content from another CMS into Uniform, or reviewing an existing content model for best-practice violations.
license: MIT
---

# Uniform content modeling

Content modeling defines display-agnostic content types and the entries created from them. Experience modeling defines how content is displayed and composed via component definitions and patterns. Keep the two separate: this skill is about building content models that are reusable across presentations and channels.

## Key principles

### Model content, not presentation

Display concerns (layout, styling, variants) belong in component definitions and patterns, not content types.

### Model classification once, deliberately

Classify with select fields or references to a classification content type — never free text. Pick one mechanism per classification and reuse it across types.

### Model for findability

Fields you filter or sort on must use filterable field types. Blocks, asset, image URL, JSON, and link fields cannot be filtered by the Edge Delivery API — decide query requirements before choosing field types.

### Borrow from Schema.org

Use Schema.org types as field checklists, model explicit fields, and let the frontend serialize JSON-LD. Only store raw JSON-LD when a Mesh integration or AI agent like Scout computes it.

## Gotchas

Uniform facts that defy reasonable assumptions — know these before changing a model:

- **Field public IDs are immutable after creation.** A rename means a new field plus content migration, so decide IDs deliberately and keep them consistent across types.
- **A reference field's single/multi choice cannot be changed after setup.** Default to a multi reference with plural naming and a `max: 1` validation; relaxing a max later is a validation change, switching single → multi is a re-model.
- **Filtering on a reference field matches only the referenced entry's id, slug, and name** — never its custom fields. Slugs on referenced types are the filter key.
- **Block fields cannot be filtered and cannot be marked overridable in entry patterns.** Keep queryable or per-entry-variable data out of blocks.
- **The native entry slug field is not localizable.** Localized URL paths need a custom localizable text field driving routing.
- **Changing or removing a select option value does not update existing entries.** Treat vocabulary changes as content migrations.

## Resources

Read the reference file for the task at hand:
- [Content types](references/content-types.md) — read when creating or updating a content type or block type: naming, public IDs, slugs, display name, validation philosophy, field-level AI guidance
- [Entries](references/entries.md) — read when organizing entries at scale, choosing a reuse mechanism (reference vs block vs entry pattern), using entry patterns, or planning localization
- [Relationships](references/relationships.md) — read before adding a reference field or designing shared types (Author, Brand, Category): reference vs embed, cardinality, graph hygiene, publishing behavior
- [Content classification](references/content-classification.md) — read when modeling categories, tags, or taxonomies: select vs reference decision, hierarchies, anti-patterns, enrichments vs content classification
- [SEO and multi-channel](references/seo-and-multichannel.md) — read when modeling SEO/OpenGraph fields, structured data, or content for answer engines and non-web channels
- [Delivery-aware modeling](references/delivery-aware-modeling.md) — read before choosing field types for any type that will be filtered, sorted, or listed: filterability, projection, resolution depth
- [Review checklist](references/review-checklist.md) — read when asked to audit or review an existing content model: workflow, per-type checklist, report format

Referenced files: 8

View saved version →

---
name: uniform-enrichment-recommendations
description: >-
  Add personalized, relevance-ranked content recommendations to a Uniform +
  React/Next.js project by boosting Content API results with Uniform Context
  enrichment scores. Use when a user wants visitor-personalized recommendations,
  dynamic product/article/promotion lists ranked by interest, enrichment-based
  content ranking, or mentions enrichment boosting, boost orderBy, or the `ufvd`
  cookie with Uniform.
license: MIT
---

# Uniform Enrichment-Boosted Recommendations

Add a feature that re-ranks a Uniform Content API query by the current visitor's
**enrichment scores** (their interest profile from Uniform Context), so each
visitor sees the same content pool ordered by what is most relevant to them.
Works for any content type (products, articles, promotions, events, ...).

## How it works (read first)

1. Uniform Context accumulates visitor **enrichment scores** in the `ufvd`
   cookie, keyed `<categoryId>_<value>` → number (e.g. `int_internet: 50`).
2. On the server, those scores are converted into a Content API **boost clause**
   passed to `orderBy`: `boost|fields.<field>:<value>:<weight>`.
3. `EntryDeliveryClient.list({ orderBy: [clause] })` re-ranks the result set.
4. No scores → no clause → graceful fallback to default ordering.

**Critical alignment rule:** the enrichment value's suffix (after the first
`_`) must equal the value stored in the content field you boost on. Enrichment
`int_internet` only boosts entries whose target field holds `internet`. If they
don't match, nothing re-ranks. Validate this before writing code.

For the full conceptual reference, terminology, and troubleshooting, read
[references/reference.md](references/reference.md).

## Prerequisites — verify before implementing

Stop and confirm each. If one is missing, set it up or tell the user it's
required first.

- [ ] **Uniform Context available.** `@uniformdev/context` provides the scoring
      engine. In Next.js App Router it ships bundled with
      `@uniformdev/next-app-router` and the tracker/provider is wired by the SDK
      (e.g. `UniformComposition` + `clientContextComponent`), so a separate
      `@uniformdev/context` install or hand-rolled `<UniformContext>` is **not**
      required — do not flag the feature as broken just because you can't find one.
      The server-side boost reads the `ufvd` cookie directly and falls back to
      default ordering when no scores are present, so the component works
      regardless. (Live per-visitor re-ranking still needs scores to actually
      accumulate — see the score-growth note below.)
- [ ] **Content client deps available** (`@uniformdev/canvas`).
- [ ] **API key + project ID** in env (commonly `UNIFORM_API_KEY`,
      `UNIFORM_PROJECT_ID`) with read-entries permission.
- [ ] **A target content type** exists with a field whose values can match
      enrichment value suffixes (the alignment rule above).
- [ ] Detect the framework (Next.js App Router vs Pages vs other React). The
      cookie read differs; templates assume Next.js App Router (`cookies()` from
      `next/headers`). Adapt for other setups.

## Workflow

Copy this checklist and track progress:

```
- [ ] Step 1: Confirm prerequisites + detect framework/conventions
- [ ] Step 2: Confirm enrichment categories + content field alignment in Uniform
- [ ] Step 3: Add the three frontend layers (helpers, score reader, fetch)
- [ ] Step 4: Build/render the component (async server component or Suspense)
- [ ] Step 5: Register the Uniform component definition + component pattern (MCP)
- [ ] Step 6: Wire boostEnrichments param, then verify re-ranking
```

### Step 1 — Confirm prerequisites and conventions

Run the prerequisite checklist. Inspect the repo to match its conventions:
where utilities live (e.g. `src/utils`), how Uniform components are registered
(the component resolver/mapping), and the cookie/SSR approach. Reuse existing
patterns; do not introduce a new structure.

### Step 2 — Confirm enrichments and content alignment in Uniform

Use the **Uniform MCP tools** (never edit `uniform-data` YAML/JSON directly) to:

- `getOptimizationData` — list enrichment categories and value public IDs.
- Inspect the target content type's fields (`getDefinition`/`searchEntries`).

Confirm the alignment rule for each enrichment you intend to use: enrichment
value suffix == stored content field value. If enrichments don't exist yet,
create them (`mutateEnrichment`) and tell the user content must be tagged so
scores actually accumulate (see references/reference.md §"make scores grow").

### Step 3 — Add the three frontend layers

Adapt the templates in `templates/` to the project's paths, naming, and content
type. Keep names generic unless the user specifies otherwise.

1. `templates/search.ts` — pure helpers (`getEnrichmentAndFieldKey`,
   `getEnrichmentKeysWithScore`, `getOrderByClause`). No I/O.
2. `templates/getEnrichmentBoostedOrderBy.ts` — reads `ufvd` from the request
   cookie via `CookieTransitionDataStore`, builds the boost map, returns the
   `orderBy` clause (or `undefined`).
3. `templates/getRecommendations.ts` — calls the Content API with
   `orderBy: [clause]`, filtered to a single content type.

### Step 4 — Build and render the component

Use `templates/RecommendationsServerComponent.tsx`. Because the fetch is async
and per-visitor, render as an async server component, or wrap in `<Suspense>`
with a skeleton so it doesn't block first paint. Map raw entries to your card UI.

### Step 5 — Register the Uniform component (MCP)

Use the Uniform MCP tools to create the component definition and a component
pattern (follow project rules: always create a pattern, allow overridability,
configure new slots with `allowAllComponents=true`). Parameters:

- `contentType` (select) — one option per recommendable content type.
- `boostEnrichments` (multi-select) — each option value is
  `"<enrichmentCategoryId>,<contentFieldId>"`, e.g. `"int,category"`.
- `maxRecommendations` (number).
- presentation params + a title slot as needed.

Then register the code component in the project's component resolver/mapping and
run `npm run uniform:pull` (or `pnpm`) to sync serialized data to disk.

### Step 6 — Wire params and verify

Pass `boostEnrichments`, `contentType`, `maxRecommendations` from the Uniform
component into `getRecommendations`. Then verify (see references/reference.md §Verifying):
simulate a visitor profile, log the generated `orderBy`, confirm matching
entries move to the top, change the profile, confirm ordering changes.

## Guardrails

- Use `orderBy` boost, not `filters`, so visitors still see a full set, just
  re-ranked. Use `filters` only to hard-exclude.
- The score reader must run server-side (it reads cookies). In Next.js App
  Router use `'use server'` + `cookies()`; elsewhere pass the cookie explicitly.
- Enrichment value public IDs: `<categoryId>_<value>` with no extra underscores
  (the parser keeps only the segment after the first `_`).
- Never hand-edit Uniform `uniform-data` files; use MCP, then `uniform:pull`.
- Always create a code component for the Uniform component definition (incl.
  matching slots) or the visual editor preview breaks.

Referenced files: 6

View saved version →

---
name: uniform-experience-modeling
description: Best practices for experience modeling in Uniform — designing component definitions with well-chosen parameters, slots, editors, and naming, deciding between slots and parameters, blocks and slots, content-agnostic and content-specific components, choosing component granularity (atomic building blocks vs pre-composed components), and using component and composition patterns well (overrides, pattern data resources, slot sections, localization). Use when creating or updating Uniform component definitions or patterns, mapping code components (React, etc.) or a design system to Uniform components, or reviewing an existing component library for best-practice violations.
license: MIT
---

# Uniform experience modeling

Experience modeling is the process of building Uniform component definitions that represent the experience layer of a digital product: how content is displayed and how authors compose it. It contrasts with content modeling, which defines display-agnostic structured content (content types and entries). This skill encodes best practices for building component sets that are easy to author, easy to maintain, and map cleanly to code components.

## Key principles

### Components map to code components

A Uniform component typically maps to a frontend code component. Parameters map to props; slots map to children or child-component props. Not every prop needs to be exposed — hardcode props that editors should not manage. Align parameter public IDs and types with the corresponding props to avoid mapping logic.

### Choose the right component granularity

Components correlate strongly to the design system rendering the experience, and atomic design is a useful lens: atoms and molecules map to component definitions (or parameters — not every design-system component needs a Uniform component), organisms to definitions plus component patterns, templates to composition patterns, pages to compositions. Balance granular atomic and layout components (flexible, but shifts design decisions, design consistency, and responsive handling to editors) against pre-composed components and patterns (easier, more guard rails); both can coexist, with granular components reserved for exceptions and experimentation.

### Design for editors first

Names, help text, grouping, and editor controls exist for non-technical authors. Use non-technical names, write help text only when the purpose isn't obvious, group related parameters, collapse advanced settings, and pick the editor control (radio, segmented control, slider, switch, checkboxes) that matches how authors think about the setting.

### Restrict slots deliberately

Never enable the allow-all-components toggle on a slot. Allow only the components and patterns that make sense, plus the built-in Personalization and A/B Test components where optimization is expected, and the Loop component where children are rendered dynamically from data. An explicit allow-list may still be wide for granular setups — what to avoid is the allow-all toggle, not a long list.

### Prefer slots over parameter groups and blocks for nested UI

Slots keep nested elements flexible: extensible, personalizable, A/B testable, and reusable via patterns. Use parameter groups when simplicity matters more, and blocks only for non-visual structured data. When requirements are unclear, default to a restricted slot.

### Keep composition parameters for global page data

Reserve composition parameters for global, page-level data (e.g. SEO/OpenGraph metadata); experience content belongs in components in the composition's content slot.

### Keep components content-agnostic

Prefer "Card" over "Recipe Card" — the component is a display container. Create content-specific variations with component patterns — either static (fixed, reused content) or connected to a data resource that wires entry fields to the base component's parameters. Only create content-specific components for core domain objects or use-case-specific behavior.

### Use patterns deliberately

A pattern reuses exact content (static), a preset configuration, or a connection to data — choose which intent it serves. Override settings are the governance dial: lock what must stay consistent, open only what instances legitimately vary, and reserve extension points with restricted slot sections.

### Validate sparingly

Keep validations on components limited to essential parameters. Strict validation belongs on content types, where data integrity matters more than authoring speed.

## Resources

See `references/` for detailed guidance:
- [Component definitions](references/component-definitions.md) — Component metadata, descriptions as AI guidance, display variants, mapping from code components
- [Component naming](references/component-naming.md) — A method for choosing structural (not content-based) names, deferring to the existing design system, layout-qualifier variants, and child component naming conventions
- [Component granularity](references/component-granularity.md) — Atomic design as a lens, classifying design-system elements, layout components, granular vs pre-composed balance
- [Parameters](references/parameters.md) — Naming, type matching, help text and guidance, localization, grouping, editors, validations, display name
- [Slots](references/slots.md) — Single vs multiple slots, slot naming, restricting slots, optimization and Loop components, slots vs parameter groups, composition parameters vs content slots, blocks vs slots
- [Component scope](references/component-scope.md) — Content-agnostic vs content-specific components, patterns for content-specific variations
- [Patterns](references/patterns.md) — Pattern strategy, overrides, pattern data resources, slot sections, editions, localization
- [Review checklist](references/review-checklist.md) — Audit workflow and checklist for reviewing an existing component library

Referenced files: 9

View saved version →

---
name: uniform-forms
description: >-
  Use when adding a form (like contact, signup, newsletter, lead-capture or survey) to a
  Uniform project, when creating form field component definitions or building a generic form submission endpoint.
  Do not use when embedding an iframe for an external form provider.
license: MIT
---

# Uniform forms

A form in Uniform is not a special entity — it is a **composition of components**. A `Form` container component renders the `<form>` element and owns the resulting submit action; each input is its own component placed in the container's slot. Authors assemble forms in Uniform's visual editor; developers own the markup, state, and submission.

## Architecture

```
form                       container: renders <form>, owns state, submits
├── slot: formFields       formTextField, formTextAreaField, formSelectField,
│                          formCheckboxField, formRadioField (+ $personalization, $test)
└── slot: formButtons      formButton (min 1) (+ $personalization, $test)

formSelectField / formRadioField
└── slot: options          formSelectOption, formRadioOption (+ $personalization, $test)
```

Field components **self-register** with that context on mount and read/write their own value through it. The container never inspects its slot contents.

## Author-set Field name and identifier

**Every field must have a stable, author-set identifier.** The `name` parameter is required on every field component. Slugify it to get the identifier used for the HTML `name`/`id`, and the payload key. **Never fall back to a generated identifier, warn in the Uniform's visual editor when a field is missing an identifier**.

## Form Submit or Fields should self-register

**Do not introspect slots.** Do not walk `component.slots.formFields` to build fields. That code can easily miss fields nested inside `$personalization` or `$test` wrappers, and duplicates the slot's structure in two places. Use the form submit event to gather the data or self-register each field based on the component's nested context.

## Options are a slot, not a `$block` parameter

Dropdown and radio options are components in an `options` slot. This is good practice for these components as it allows them to be personalized, be A/B tested, or support visibility conditions. Do not use blocks or a `$block` parameter as **it cannot be created or edited via MCP or AI**, so a block-based model cannot be built or maintained by an agent.

## Restrict every slot explicitly

**Never set `allowAllComponents: true`.** List the field components, and add `$personalization` and `$test` to `formFields` so individual fields can be optimized.

## Always validate on the server

Client-side validation, `required`, `minlength`, `maxlength`, `pattern` and other built-in form input parameters drive the HTML validation UX only. Re-check every required field in the API route.

## Keep track of the form submit state

Track `idle | submitting | success | error`. Disable the submit button while submitting and render the result in the page with `aria-live`. Never use `alert()` or `confirm()`.

## Build order

1. **Model the components** in Uniform — `form` first, then fields, then `formButton`, then `formSelectOption`. See [modeling.md](references/modeling.md).
2. **Build a single API route** to receive submissions according to the payload contract. See [submission.md](references/submission.md).
3. **Build the form submission logic** to send submissions according to the payload contract.
5. **Build all components** in the current tech stack and ensure the `<form>` submit event triggers the form submission logic.
6. **Assemble a form in Uniform's visual editor** and submit it to confirm the payload keys match the authored field names.

## Payload contract

The container POSTs this to `/api/forms/submit` which expects the payload contract defined in [submission.md](references/submission.md).
The generic nature of the payload means that it is important to have some mitigation for potential spam or malicious requests.

## References

- [Modeling](references/modeling.md) — component definitions for the form with parameter tables and slot restrictions
- [Submission](references/submission.md) — the API route, payload contract and server-side validation

Referenced files: 3

View saved version →

---
name: uniform-mesh
description: Building Uniform Mesh integrations end to end — scaffold with the CLI, define the mesh-manifest, implement locations, register/install and deploy — plus how to discover and use @uniformdev/design-system components for composing location UI. Covers custom data connectors, Canvas parameter editors, editor tools, personalization algorithms, asset library providers, dashboard/project tools, and edgehancers, on Next.js Page Router (canonical) and App Router (with client-component boundaries). Use when building, scaffolding, or extending a custom Mesh integration, or when choosing and using Uniform design-system components inside a Mesh location.
license: MIT
---

# Uniform Mesh integrations

Build a custom Uniform Mesh integration from a plain use case. A Mesh integration is a
Next.js web app you host, described by a `mesh-manifest.json`, that renders custom UI into
specific **locations** in the Uniform dashboard over iframe messaging. This skill covers
the whole path: turn a use case into the right locations, scaffold, implement with the mesh
SDK and the Uniform design system, and register it. For the exact manifest structure,
always rely on the manifest JSON schema (see `references/manifest.md`) rather than
memorized field lists.

## Build loop

1. **Clarify the use case** — what external system or authoring need, and what the author
   does in the UI (pick a record? edit a value? browse assets?).
2. **Map it to location types** — see the map below and `references/use-case-recipes.md`.
3. **Scaffold or extend** — in a *new* project, `npx @uniformdev/cli@latest new-integration`
   (Page Router Next.js app, API keys, initial registration). In an *existing* project, skip
   the scaffold: add the dependencies and wire the app in place, leaving the existing
   `package.json`, `tsconfig.json`, and framework config intact — merge into them, never
   overwrite them or drop entries you did not add. See `references/build-workflow.md`.
4. **Wire the app** — `MeshApp` provider (Page Router `_app.tsx`, or an App Router client
   provider). Add one page/route per location.
5. **Author the manifest** — per-environment `mesh-manifest.{local,canary,stable}.json`;
   declare each location under `locations`. Validate against the manifest JSON schema
   (`references/manifest.md`).
6. **Implement locations** — `useMeshLocation<'...'>()` for value/metadata; build the UI
   from `@uniformdev/design-system`.
7. **Register + install** — `uniform integration definition register` then
   `uniform integration install <type>`. An integration must be registered to a team and
   installed to a project before it can be tested.
8. **Deploy** — host on HTTPS, point the manifest `baseLocationUrl` at it, re-register.

## Location types → use case (quick map)

Which location serves which use case. The exact manifest keys and fields for each are
defined by the manifest JSON schema — **validate against it** (`references/manifest.md`);
they change across SDK versions, so don't trust field lists memorized here.

| Use case | Location |
|---|---|
| Connect an external system as a data source | data connector |
| Custom Canvas component parameter | parameter type editor |
| Toolbar/tool inside the Canvas editor | editor tool |
| Custom personalization | personalization algorithm |
| External asset provider | asset library / asset parameter |
| Integration-wide config | settings |
| Install-time description | install |
| Tool in the project nav | project tool |
| Tool in the dashboard nav | dashboard tool |

## Two things to always get right

- **The design system is required.** Build all location UI from `@uniformdev/design-system`
  (`Input`, `InputSelect`, `Callout`, `LoadingOverlay`, `ScrollableList`, …) so the
  integration matches the dashboard. Do not hand-roll raw `<input>`/`<select>`/`<button>` or
  add another UI kit. The installed package is the source of truth for what exists and what
  props it takes — `references/design-system.md` shows how to look it up.
- **Secrets go in the data source only.** Store API keys/tokens in the data source value
  (`custom` and header/parameter values are encrypted). Never put secrets in `settings` or
  data type values, and never hard-code them.

## Next.js Routers

- **Page Router is canonical** — the CLI scaffolds it and every shipped integration uses
  it. Prefer it.
- **App Router works but is unofficial.** Because locations rely on `useMeshLocation` hooks
  and iframe `postMessage`, every location component must be a client component
  (`"use client"`), and `MeshApp` must be wrapped in a client provider. See
  `references/build-workflow.md`.

## Resources

See `references/` for detailed guidance:
- [Manifest](references/manifest.md) — the manifest JSON schema is the source of truth for
  structure and fields; validate against it instead of hardcoding
- [Build workflow](references/build-workflow.md) — scaffold → manifest → app setup (both
  routers) → register → deploy, with CLI verbs and scripts
- [Design system](references/design-system.md) — how to discover which `@uniformdev/design-system` component
  to use, real snippets, error/loading/validation/dialog patterns, storybook links
- [Use case recipes](references/use-case-recipes.md) — use case → locations → components →
  example pointers
- [Data connector](references/data-connector.md) — deep dive: the data source / data type /
  data resource editors and the picker pattern
- [Custom edgehancers](references/custom-edgehancers.md) — edge hooks for a connector:
  `preRequest` for auth, draft/published and cache control; `request` for batching, OAuth and
  response shaping — with the batching helpers, deployment and testing
- [Identity delegation](references/identity-delegation.md) — call Uniform APIs as the signed-in
  author: the session-token → BFF exchange → sealed-cookie flow, expiry recovery, the CSRF and
  CORS rules that must not be broken, plus manifest/runtime authorization
- [Editor state API](references/editor-state.md) — `editorState`: read and mutate the
  surrounding composition/entry from a location, so configuration done in your UI writes real
  parameters. Which locations expose it, the `updateNodeProperty` contract, and the traps

Referenced files: 9

View saved version →

---
name: uniform-navigation
description: Model and build header navigation in Uniform — authored, reorderable nav items, dropdown flyouts, mega-menu panels with a category rail and promo area, and mobile drawers. Covers modeling the component chain, the slot-data techniques a parent needs to read its own children, variant-driven layout, and the interaction and accessibility layer. Use when adding a navigation bar, header, navbar, mega menu, flyout, or dropdown menu to a Uniform project, restructuring navigation so editors can author and reorder menu items, adding a mobile navigation drawer, or reviewing a navigation implementation for authoring or accessibility problems.
license: MIT
---

# Uniform navigation and mega menus

Navigation in Uniform is a chain of small components, authored and reordered in the visual
editor. The hard part is that **a slot hands a parent already-rendered, opaque children** —
so a menu shell that needs its children's *labels*, to draw a category rail or a mobile
section heading, cannot get them by reading the slot. Everything here follows from that.

## Workflow

### 1. Discover before you model

Never assume the project is greenfield, and never assume which component library it uses.
Find out which of these you are in — the answer changes every later step. See
[references/discovery.md](references/discovery.md) for the greps.

| What you find | Do |
|---|---|
| Navigation components already exist | **Extend them.** Add the panel/category level; keep existing IDs |
| A header exists but is flat (links only) | Add the flyout + panel levels beneath it |
| Nothing exists | Model the full chain from scratch |

Also determine, before writing any parameter: **is the Design Extensions integration
installed?** If it is not, `dex-*` parameter types produce values your code has no resolver
for. Use plain `select` / `text` / `asset` / `link` types instead.

### 2. Model the chain, not a component

Navigation is a chain of small components, each slot allowing only the next level. Menu
depth is a consequence of **which components a slot allows** — never a depth parameter, and
never numbered parameters (`link1`, `link2`).

```text
header
└── (center slot)  → link | flyout
    └── flyout                            ← trigger + panel shell; variant switches layout
        ├── (panel slot)  → link | group | category
        │   └── category                  ← rail label + its own panel
        │       └── (panel slot) → group | link | image | rich text | layout
        │           └── group             ← labelled column of links
        │               └── (links slot) → link
        └── (aside slot)  → promo content
```

Full slot policy, naming, and the pattern layer: [references/modeling.md](references/modeling.md).

### 3. Wire the parent → child data path *first*

Before any layout work, prove the shell can read its children. This is where navigation
builds fail, and the failure is silent. See
[references/slot-data-access.md](references/slot-data-access.md).

The shape, framework-neutral:

- The **rail** (labels) comes from raw child component instances, read server-side.
- The **panel** (content) comes from rendering the slot normally and filtering to the
  active child by `_id`.

Never rebuild children from raw data — read labels from it, render children through the slot.

### 4. Branch layout on variant, not on a parameter

A dropdown, a full-bleed mega panel, and a master-detail mega panel are the same component
in different layouts. Use a display **variant** for the layout switch and let the presence
of categories pick the sub-shape:

| Variant | Categories present | Layout |
|---|---|---|
| default | — | absolute panel anchored to the trigger |
| mega | none | full-bleed panel, edge to edge |
| mega | one or more | rail + panel, plus optional aside |

Full-bleed panels must be positioned below the header, not below the trigger. Measure the
header's bottom edge on resize and scroll rather than hard-coding a height.

### 5. Build the interaction layer

Hover intent with asymmetric delays, Escape to close, focus management, and `inert` on
closed panels. Do not ship a keyboard-reachable closed menu.
[references/interaction-and-a11y.md](references/interaction-and-a11y.md).

### 6. Compose into a pattern

Assemble the header once as a **component pattern**, then place it in the page composition's
header slot — typically inside a **composition pattern** so every page inherits it. Which
parameters to lock and which to open is a project decision, not a rule; make the trade
explicit rather than defaulting to locking everything.

That header slot is one you did not create. Confirm it accepts a *pattern*, not just your
header component — `patternsInAllowedComponents` reads backwards and blocks patterns when
set to `true`. See [references/modeling.md](references/modeling.md).

## Framework specifics

This skill is framework-neutral by design. How a parent reads child data, and whether that
code is a server or client component, is your framework SDK's business:

- **Next.js App Router** — [uniform-nextjs-app-router](../uniform-nextjs-app-router/SKILL.md),
  whose `references/advanced.md` documents the composition cache
- **Next.js Page Router** — [uniform-nextjs-page-router](../uniform-nextjs-page-router/SKILL.md)

General slot, parameter, naming, and pattern rules live in
[uniform-experience-modeling](../uniform-experience-modeling/SKILL.md); this skill does not
restate them.

## Guardrails

- **Repetition is a slot.** Numbered parameters (`link1`, `linkText2`) cap the count, block
  reordering, and forfeit personalization and A/B testing on individual menu items. The
  general rule is in
  [uniform-experience-modeling](../uniform-experience-modeling/references/slots.md).
- **Render editable labels with `UniformText`**, not as a raw string, or the editor cannot
  edit them inline. This bites on a category rail specifically: the label there is read from
  slot data, and printing that string produces a label nothing can click. Either render the
  rail label through the slot as well, or state plainly that the rail is edited from the
  component tree.
- **A parent must never rebuild its children** from raw slot data. It loses personalization,
  A/B tests, patterns, and editor affordances. Read metadata from raw data; render children
  through the slot.
- **Never enable allow-all on a navigation slot.** A promo/aside slot is the one place a wide
  allow-list is defensible — still enumerate it rather than toggling allow-all.
- **Editor placeholder items are real slot items.** Checking `items.length` to decide whether
  a region has content is always true in the editor. Filter out placeholder entries first.
- **A curated menu is authored as components; the project map drives *derived* navigation**
  — breadcrumbs, a sitemap, a section index. Nav items should still link *to* project map
  nodes. Entries behind a data resource are a valid third option when the menu genuinely
  mirrors content already modeled that way. All three, and when each is right:
  [references/modeling.md](references/modeling.md).

## Resources

- [Discovery](references/discovery.md) — find the existing navigation surface, the design
  system, and the token layer before changing anything
- [Modeling](references/modeling.md) — the component chain, slot policy, parameters, depth,
  and the pattern layer
- [Slot data access](references/slot-data-access.md) — the mechanism: how a shell reads its
  own children, the four techniques, and the silent failures
- [Interaction and accessibility](references/interaction-and-a11y.md) — hover intent, focus
  management, `inert`, the rail's correct ARIA pattern, mobile

Referenced files: 5

View saved version →

---
name: uniform-nextjs-app-router
description: Guides integration of Uniform CMS with Next.js App Router using the @uniformdev/next-app-router v2 SDK and React Server Components. Covers project setup, environment variables, required edge middleware and advanced routing, the uniform/[code] composition route, component mapping with resolveComponent, rendering slots and parameters, asset handling, client-side personalization with quirks and scores, contextual editing preview, Next.js 16 cacheComponents, composition data enhancement, and adapter compatibility mode. Use when adding Uniform to a Next.js 16 App Router project, creating Uniform-powered React server components, or configuring live preview, personalization, and caching.
license: MIT
---

# Uniform with Next.js App Router

Integration guide for wiring Uniform CMS to a Next.js application using the App Router. The integration uses React Server Components and the `@uniformdev/next-app-router` package (the **v2** SDK, version `20.58.0` or later).

## Requirements

- **Next.js 16+** and **App Router only** (this v2 SDK does not support the Page Router).
- **Node.js 22+**.
- A Uniform project with compositions.
- On Next.js 15 + Page Router, use the Page Router SDK instead. Migrating Page Router → App Router? Contact Uniform support.

## Quick start

Scaffold a working project instead of integrating from scratch:

```bash
npx @uniformdev/cli@latest new
```

Select **Next.js**, then the **Component Starter Kit** (full-featured) or **Hello World** (minimal). Otherwise follow the manual setup in [references/setup.md](references/setup.md).

## Required packages

`@uniformdev/next-app-router` (version `20.58.0`+), `@uniformdev/canvas` and  `@uniformdev/cli`. For advanced client-side context customization, also add `@uniformdev/next-app-router-client` and `@uniformdev/context`.

## Architecture essentials

- **Middleware is required.** It resolves the route via the Uniform Route API, evaluates personalization/A/B tests at the edge, and rewrites the request to `/uniform/[code]` (where `code` is serialized page state). For Next.js 16, the file MUST be named `middleware.ts` and the config export MUST include `runtime: "experimental-edge"`. Next.js 16.2+ prints a build warning recommending renaming to `proxy.ts` — ignore it and keep `middleware.ts`: `proxy.ts` does not support the edge runtime Uniform requires (renaming fails the build with "Proxy does not support Edge runtime"). The deprecation warning is harmless.
- **The composition route is `app/uniform/[code]/page.tsx`**, not a catch-all. `UniformComposition` fetches and renders the tree, sets up `UniformContext` internally (in `Suspense`), and calls `notFound()` if the route can't resolve.
- **Do NOT place `UniformContext` in `layout.tsx`.** It's handled by `UniformComposition`.
- **Parameters are accessed via the `parameters` object** (`parameters: { title }`), each wrapped in `ComponentParameter<T>` and marked optional.
- **The manifest is fetched at runtime** — no local download needed. Publish it (`uniform context manifest publish`) when you sync manifest definitions; the npm script is optional.
- **Enable `cacheComponents`** (Next.js 16) and import `resolveRouteFromCode` from `@uniformdev/next-app-router/cache` for static-like performance and automatic cache invalidation.

## Key differences from Page Router

| Aspect | App Router (`@uniformdev/next-app-router`) | Page Router |
|--------|-------------------------------------------|-------------|
| Component mapping | `resolveComponent` function | `registerUniformComponent()` registry |
| Routing | `middleware.ts` → `uniform/[code]` route | `withUniformGetServerSideProps` |
| Data fetching | `resolveRouteFromCode` / `createUniformStaticParams` | `getServerSideProps` wrapper |
| Parameter access | `parameters` object, wrapped in `ComponentParameter<T>` | direct prop / registry value |
| Text rendering | `<UniformText component={component} parameter={title} />` | `<UniformText parameterId="..." />` |
| Context manifest | fetched at runtime; publish optional/CLI | manifest download into build |

## Import paths

| Category | Exports | Import path |
|----------|---------|-------------|
| Core | `UniformComposition`, `UniformContext`, `UniformPlayground`, `resolveRouteFromCode`, `resolvePlaygroundRoute`, `precomputeComposition`, `createUniformStaticParams`, `createCompositionCache`, `ResolveComponentFunction`, `ResolveComponentResult` | `@uniformdev/next-app-router` |
| Routing / Data | `findRouteMatch`, `CustomRoute`, `DefaultDataClient`, `EnhanceRouteOptions` | `@uniformdev/next-app-router` |
| Cache | `resolveRouteFromCode` (wrapped in `'use cache'`) | `@uniformdev/next-app-router/cache` |
| Compat | `createAdapterResolveComponentFunction`, `ResolveComponentResultWithType`, `UniformText`, `UniformSlot` | `@uniformdev/next-app-router/compat` |
| Clients | `getCanvasClient`, `getRouteClient`, `getManifest`, `getManifestClient`, `getProjectMapClient` | `@uniformdev/next-app-router` |
| Components | `UniformSlot`, `UniformText`, `UniformRichText`, `getUniformSlot` | `@uniformdev/next-app-router/component` |
| Types | `ComponentProps`, `ComponentParameter`, `ComponentContext` | `@uniformdev/next-app-router/component` |
| Hooks | `useUniformContext`, `useQuirks`, `useScores` | `@uniformdev/next-app-router/component` |
| Middleware | `uniformMiddleware`, `handleUniformRoute` | `@uniformdev/next-app-router/middleware` |
| Config | `withUniformConfig`, `UniformServerConfig` | `@uniformdev/next-app-router/config` |
| Handlers | `createPreviewGETRouteHandler`, `createPreviewPOSTRouteHandler`, `createPreviewOPTIONSRouteHandler` | `@uniformdev/next-app-router/handler` |
| Client context | `createClientUniformContext`, `useInitUniformContext`, `ClientContextComponent` | `@uniformdev/next-app-router-client` |
| Canvas | `enhance`, `EnhancerBuilder`, `ASSETS_SOURCE_*`, `LinkParamValue`, `RichTextParamValue` | `@uniformdev/canvas` |
| Assets | `imageFrom` (default for an image `src`), `AssetParamValue`, `AssetParamValueItem`, `AssetClient` | `@uniformdev/assets` |

## Resources

See `references/` for detailed guidance:
- [Setup](references/setup.md) — Prerequisites, env vars, packages, file structure, server config, `next.config.ts`, basic middleware, composition and playground routes, manifest
- [Routing](references/routing.md) — Advanced middleware: `handleUniformRoute`, quirks injection, locale handling, custom route mapping, query keys, moving the page, matcher scoping, consent, releases
- [Components](references/components.md) — `resolveComponent`, typed parameters, `UniformText`/`UniformRichText` props, slots, assets, and type definitions
- [Personalization](references/personalization.md) — Client context, `useQuirks`/`useScores` hooks, custom client context component, server-side precomputation, Vercel geo-IP quirks
- [Advanced](references/advanced.md) — Next.js 16 `cacheComponents`, suspense/streaming, enhancing composition data, composition cache, adapter compatibility mode, server clients
- [Preview](references/preview.md) — Contextual editing handler (GET) and ISR handler (POST), playground route

Referenced files: 7

View saved version →

---
name: uniform-nextjs-page-router
description: Guides integration of Uniform CMS with Next.js Page Router. Covers project setup, component registration with registerUniformComponent, fetching compositions with withUniformGetServerSideProps, rendering slots and parameters, contextual editing preview, personalization and A/B testing with Uniform Context, and how the Page Router integration differs from the App Router. Use when adding Uniform to a Next.js Page Router project, creating registered Uniform components, or configuring personalization and A/B testing.
license: MIT
---

# Uniform with Next.js Page Router

Integration guide for wiring Uniform CMS to a Next.js application using the Page Router. The Page Router integration uses `@uniformdev/canvas-next` and `@uniformdev/canvas-react` with SSR via `getServerSideProps`.

## Key differences from App Router

| Aspect | Page Router | App Router |
|--------|------------|-----------|
| Component mapping | `registerUniformComponent()` registry + barrel file | `resolveComponent` function |
| Data fetching | `withUniformGetServerSideProps` in catch-all route | `retrieveRoute` in async server component |
| Imports | `@uniformdev/canvas-next` + `@uniformdev/canvas-react` | `@uniformdev/canvas-next-rsc` |
| Slot rendering | `<UniformSlot name="slotName" />` | `<UniformSlot context={context} data={component} slot={slots.name} />` |
| Text rendering | `<UniformText parameterId="..." placeholder="..." />` | `<UniformText component={component} context={context} parameterId="..." />` |
| Context manifest | Required — download and embed in build | Not needed (handled server-side) |

## Required packages

```
@uniformdev/canvas
@uniformdev/canvas-react
@uniformdev/canvas-next
@uniformdev/context-react
```

## Resources

See `references/` for detailed guidance:
- [Setup](references/setup.md) — Project configuration, composition fetching, component registration pattern
- [Components](references/components.md) — Component registration, typed props, slots, text, rich text, and asset rendering
- [Preview](references/preview.md) — Contextual editing handler, playground page
- [Personalization](references/personalization.md) — Uniform Context setup, manifest download, SSR personalization, A/B testing

Referenced files: 5

View saved version →

---
name: uniform-sdk
description: Uniform SDK developer reference covering authentication, CLI configuration, routing, and the content API clients that read and write compositions, entries, and content types. Use when setting up Uniform in a frontend project, configuring the CLI, working with the Route API, or reading or writing Uniform content in code with EntryManagementClient, EntryDeliveryClient, CompositionManagementClient, or the deprecated CanvasClient and ContentClient.
license: MIT
---

# Uniform SDK

Framework-agnostic developer reference for integrating Uniform into applications. Covers authentication, the Uniform CLI, routing via Project Map, and the content API clients used to read and write Uniform content from code.


## Key principles

### Always use MCP tools for content operations

CRITICAL: Never manipulate YAML or JSON files in the `uniform-data` folder directly. Always use the Uniform MCP tool for creating, modifying, or deleting components, content types, or any other Uniform entity. After making changes via MCP, run `npm run uniform:pull` to sync the latest state to disk.

### Pin all Uniform packages to the same version

All `@uniformdev/*` npm packages in a project must use the same version. Mismatched versions cause hard-to-debug dependency conflicts and runtime errors. When installing or upgrading, ensure every Uniform package resolves to the identical version number.

### SDK setup checklist

When adding Uniform SDK to a project:
1. Install the appropriate framework-specific packages (all at the same version)
2. Create a component in code for every composition component found in the Uniform project
3. Add all slots from the component definition
4. This ensures preview works correctly

## Resources

See `references/` for detailed guidance:
- [Authentication](references/authentication.md) — API keys, `.env` setup, permissions
- [CLI reference](references/cli-reference.md) — Configuration, push/pull commands, help system
- [Routing](references/routing.md) — Project Map and dynamic route delegation
- [Content API clients](references/clients.md) — Delivery vs management, reading and writing entries, field shapes, deprecated predecessors

Referenced files: 5