pixel-point/prime-skills/primeui-page-builder

PrimeUI Page Builder

Use this skill when the user asks to build or edit a local page in an exported PrimeUI project.

PrimeUI Responsibilities

PrimeUI supplies candidate scoring, registry metadata, component delivery, props validation, and automatic external-planning diagnostics. The coding agent owns task interpretation, exported-project inspection, local file edits, ordered block state, and local verification.

Readiness

1. Confirm .primeui/project.json exists at the exported project root. If it is missing, run npx @primeuicom/cli setup --ai-preset <agent> only after classifying the target as an empty directory or an existing Next.js project. The setup command exports a complete starter into an empty directory and performs a non-overwriting connection for an existing Next.js project. If no matching organization profile exists, setup opens browser login and waits, including in non-interactive local terminals. Show the user the verification URL and pairing code, and keep the CLI process alive while they sign in, choose an organization, compare the code and approve. Do not approve the connection on the user's behalf. The CLI receives and stores credentials privately, then resumes setup. For a remote terminal or failed browser launch, show the supplied URL or use npx @primeuicom/cli login --no-open before rerunning setup. Never request bootstrap commands, device secrets or API tokens in chat, and never read or print local credential files. If the request expires or is declined, report that and let the user initiate another login. Stop on any other non-empty target.
2. If the MCP client starts outside the exported project, pass explicit projectRoot to PrimeUI MCP tools.
3. Verify PrimeUI MCP health before planning with npx @primeuicom/mcp@latest --health /absolute/project/path.
4. For local or staging Studio, set PRIMEUI_API_BASE_URL to the intended Studio URL before health checks or MCP calls. For production, use the linked project config unless the environment intentionally overrides it.
5. Stop before planning or editing if readiness still fails after safe setup. Ask the user to complete browser approval, rerun PrimeUI AI setup, pass the correct projectRoot, or fix the API base/key.

Task Intake

Before planning, identify:

• request scope: full page or section-only
• target slug and stable pageSlug
• page theme or pageType intent
• product/business context and source copy
• acceptance expectations and local verification expectations

Reuse the same pageSlug for candidate retrieval, props validation, and diagnostics.

Select The Source Mode

Classify the request before planning or calling page tools:

• design-driven: the user supplies a Figma file or node. Use the installed figma-to-prime workflow. When this skill is invoked from that workflow, preserve its page or section-only scope and use the candidate and delivery sections below for each normalized design section.
• template-driven: the user supplies no Figma source and requests a standard Prime page type or bundle. Read and follow template-driven pages.
• composition-driven: no supplied design or complete standard template fits. Plan and assemble the page from Prime component candidates using the sections below.

Do not call a Figma provider for a template-driven or composition-driven request.

Inspect The Exported Project

Before editing, inspect:

• route and page-file layout
• naming and slug conventions
• component import paths
• styling and design-token conventions
• existing PrimeUI component usage and local wrapper patterns
• package scripts for typecheck, build, dev, render, or browser checks

Plan A Composed Page

Create a short local plan:

• chosen pageType
• intended sections and first-pass content outline
• expected local route/page file
• initial ordered blocks[]

For composition-driven pages and design-driven sections, start with an empty ordered blocks[] and append-first operations. Use insert only when placing a section before an already planned block, and replace only when revising a chosen block. Do not decompose a template-driven blog or documentation bundle into independent component-copy operations.

For section-only, inspect the existing route and identify the narrow insertion or replacement anchor. Preserve unrelated route composition and pass stable surrounding Prime block IDs only when they are known. If custom local neighbors cannot be represented truthfully, use blocks: [] for candidate planning and preserve the real insertion point during the local edit.

Candidate Retrieval

Use MCP component_candidates_get; do not call the PrimeUI API directly.

For a design-driven section, define its structural signature before requesting candidates: macro anatomy, grid topology and spans, content order, media placement, caption layout, visible controls and icons, and responsive transitions. Page-rhythm scores are useful only after structural compatibility is established.

For each section, provide:

• pageSlug
• pageType
• blocks: current ordered blocks as { "componentId": "..." }
• operation: omit for append or pass explicit append/insert/replace
• optional count
• optional narrow constraints: spreadDegree, allowedGroups, excludedGroups, excludeComponentIds
• sectionIntent for design-driven work: plausible preferredGroups, required interactions, layout, grid topology, and media placement
• optional projectRoot when needed

When more than one group could fit the structural signature, include every plausible group in sectionIntent.preferredGroups; reserve constraints.allowedGroups for a genuine hard allow-list. Do not constrain the first request to one guessed family. Reject intentMatch.status: "mismatch", investigate partial unknown evidence, and compare compatible candidates using totalScore, grid and content anatomy, group/family/layout rhythm, descriptions, functionality, visual metadata, default props, schemas, local context, page stage, and copyHints.

Reject a candidate even with a high score when its grid, card spans, media-to-copy order, caption structure, or control anatomy conflicts with the source. Record credible rejected candidates and blocking differences. If no candidate is structurally compatible, use the custom authoring path instead of stretching the closest score.

When multiple credible candidates remain or the user requests visual review, read and follow visual component selection. The picker supplements structural review; it does not replace mismatch rejection, props validation, or component delivery.

Props Authoring And Validation

Author props from user context, local copy/content conventions, candidate metadata, defaultProps, compactSchema, and jsonSchema.

Use MCP component_props_validate; do not call the PrimeUI API directly. Validate with:

• pageSlug
• componentId
• stable caller-provided blockId for this planned local component instance
• props
• optional projectRoot when the MCP workflow needs an explicit exported-project root

Treat valid: false as normal structured feedback, not as a tool failure. It returns no propsValidationId; do not proceed to component export until props are corrected. Use errors[].path, errors[].message, hints, and schemas to revise props and retry validation.

When validation returns valid: true, keep normalizedProps as validated registry content props for the PrimeUI export handoff only. Use the returned propsValidationId and block identity (blockId, componentId, contentKey) to export a materialized component instance. Do not blindly spread normalizedProps into exported React components; slot-like props may be transformed by PrimeUI export materialization.

Keep renderCheck as a diagnostic only. Do not claim browser rendering is proven unless the response says a render check was attempted and passed.

Component Delivery

Deliver or refresh the chosen component instance before editing the page. Follow copyHints.deliveryToolchain:

1. create_component_export
2. download_component_export
3. copy_registry_component

When validation was performed, pass propsValidationId to create_component_export. If no validation was performed intentionally, omit propsValidationId; this is the default-props export path and still returns a complete insertable component instance.

After copy_registry_component, use its selectedBlock for traceability and its insertion payload as the local page source of truth:

• insertion.imports
• insertion.propsCode
• insertion.jsx
• insertion.referenceFiles

You may refactor where the returned props live to match local project conventions, but preserve the materialized props/JSX semantics from the downloaded virtual export.

Local Edit Loop

1. Edit local page files only after the component is available locally and props are valid or the intentional default-props export path was used.
2. Add the component instance using copy_registry_component.insertion.imports, insertion.propsCode, and insertion.jsx.
3. Update local ordered blocks[] with the chosen componentId.
4. Repeat candidate retrieval, optional delivery, prop authoring, validation, local edit, and block-state update until the page is complete.

In section-only, stop after the requested section and its minimal route insertion or replacement are complete. Do not continue filling, restructuring, or restyling the page.

Local Verification And Evidence

Run project-appropriate local checks, such as typecheck, build, dev-server smoke, route rendering, or browser checks.

Before browser acceptance, inventory visible tabs, carousel arrows, selectors, accordions, and buttons. Exercise each one and verify an observable content, position, or accessible-state change. A visually accurate but dead control is a failed implementation.

Keep content and controls as semantic DOM even when the design source contains a flattened composite image. It must not replace section copy, card structure, or visible controls. If alternate interaction content is absent, reuse known content or repeat known carousel items, preserve truthful labels and accessible state, and record the synthesized fallback.

Do not download Figma raster media by default. Use the project's Prime token-based media placeholder with exact slot geometry and media-pending evidence; keep it replaceable by image, video, or animation. Use exact vectors and existing or user-approved local assets. A raster logo or brand mark is the only default export exception when no vector exists. Never approximate dense product UI unless functional reconstruction was explicitly requested.

For design-driven verification, compare every requested semantic section at the exact reference viewport. Missing visible icons, controls, labels, or media slots; wrong grid topology or spans; changed media/caption order; incorrect placeholder geometry or light/dark treatment; and materially different typography, wrapping, alignment, or proportions are blocking even when build and interaction checks pass. layout-parity may pass with pending media, but full visual parity and pixel-perfect status may not.

Preserve evidence:

• selected candidates and why they were chosen
• supplied sectionIntent plus every match, mismatch, and unknown diagnostic used in selection
• credible rejected candidates and their blocking anatomy differences
• validation outcomes
• touched local files
• verification commands/results
• tested affordances and observed state changes
• section-level reference and rendered crop results, including any blocking mismatch
• synthesized states caused by incomplete source designs
• every media-pending slot and its replacement contract
• external-planning log paths

Diagnostics And Non-Mutation