Publishers

Quality handbook

Package components so hosted buyers get a clean install — clear typeIds, honest presentation, useful slots, strong defaults, and a solid preview.

Hosted buyers cannot fork your CSS

Most Store installs run your hosted bundle. Design through fields, tokens, and slots — not by expecting buyers to edit the source. Full build playbook: How to build great Store components.

typeId namespacing

Declare only a namespaced typeId (for example @your-brand/my-slider). Macro derives the custom element tag (your-brand-my-slider). Optional tag in the bundle is ignored when it does not match the derived value. Treat scopes like npm: unique brand + package name. Collisions fail registration and confuse installs.

typescript

export const mySliderNode: MacroNodeDefinition = {
  typeId: '@your-brand/my-slider', // → custom element your-brand-my-slider
  label: 'My Slider',
  // ...
}

Presentation honesty

Content — inherit host design; warn/score penalties for hardcoded brand palettes.
Styled — ship a look, expose design fields, document tokens.
One presentation per listing. Need both? Ship two listings.

Details: Presentation.

Slots for hosted buyers

Name	Type	Description
`items`	`slot`	Editor-managed list (add / remove / reorder) with fixed item fields — ideal for slides, cards, FAQ rows.
`project`	`slot`	Site developer projects HTML into a named region; primitives inside stay editable; not a repeater.

Prefer items slots whenever editors should grow structure without code access. Deep dive: Slots. References: @macro/content-slider (items), @macro/free-section (project).

Field & default quality

Labels read like product UI (“Headline”, “Interval (ms)”), not internal property names.
defaultPayload should look intentional in an empty install — not lorem spam or broken empty states.
Only expose fields buyers need; skip decorative toggles that never change the render.
Group design controls under group: 'design' for styled widgets; keep shell behavior under content.

Preview and Store demo

Gallery / preview assets must match what the runtime actually renders.
Use website + editor demos so buyers try inline edit and the sidebar before installing.
Broken demos hurt conversion more than a missing screenshot.

Scanner / Macro Score mindset

Validation catches forbidden patterns, presentation drift, and packaging mistakes. Treat a low score as a product bug, not a marketing inconvenience. Pipeline details: Bundles & Macro Score.

Ship one presentation per listing; publish a second listing if you need both looks.
For content blocks, use inherit / currentColor and a small set of CSS variables (for example --macro-accent).
Expose items slots when editors should add/remove/reorder structural pieces.
Aim for a high Macro Score — buyers see the number and reasons.
Test with a non-author editor account on a clean website install.

Don’t

Don’t mix content and styled behavior in a single listing.
Don’t hardcode brand colors in content blocks that fight the host site.
Don’t invent custom element tags by hand — namespace the typeId instead.
Don’t leave forbidden patterns in comments that fail the scanner.
Don’t bury the only way to edit content in an undocumented JSON field.

Also see

Build great components

Architecture playbook for Store authors.

Bundles & score

Validation pipeline and Stripe requirements.

Custom components

Developer implementation guide (MacroNodeDefinition).

Store components runtime

Buyer-side install and SDK load path.