Agent Guide

• Button

  Import: @mediayard/agoratopia-ui/components/button

  Use when: Any primary, secondary, submit, or link-like action.

  Key props: variant, href, disabled, loading, loading_text, type, children.

  Agent note: Use href for anchor mode; use rel="external" for external links.

• Input

  Import: @mediayard/agoratopia-ui/components/input

  Use when: Floating-label text, email, password, phone, checkbox, or search field.

  Key props: type, placeholder, bind:value, bind:checked, errors, default_country.

  Agent note: Phone inputs include a calling-code dialog and normalize the submitted value.

• Select

  Import: @mediayard/agoratopia-ui/components/select

  Use when: Searchable modal selection backed by a SvelteKit remote form field.

  Key props: field, options, placeholder, default_value, option_renderer snippet.

  Agent note: Create the remote form/schema first; Select submits through a hidden field.

• Dialog

  Import: @mediayard/agoratopia-ui/components/dialogs

  Use when: Slide-in modal panels, pickers, editors, and nested flows.

  Key props: open, onclose, title, onback, header snippet, footer snippet.

  Agent note: Consumer owns open state; Dialog owns overlay, focus, Escape, and scroll lock.

• AddressSelect + AddressForm

  Import: @mediayard/agoratopia-ui/components/address-select

  Use when: Checkout shipping/billing address selection and editing.

  Key props: addresses, selected_field, mode_field, fields, allowed_countries, save_field.

  Agent note: Picker, editor dialog, async save, and persistence are intentionally composed by the caller.

• ProductCard

  Import: @mediayard/agoratopia-ui/components/product-card

  Use when: Commerce product grids, rails, and loading skeletons.

  Key props: product: ProductCardData; ProductCardLoader for pending state.

  Agent note: Provide stable product hrefs and CDN image paths; variable products show a From price.

• Sections

  Import: @mediayard/agoratopia-ui/components/sections

  Use when: Campaign hero, media frames, landing sections, and product rails.

  Key props: cta, media, mobile_media, logo, description, tag, query.

  Agent note: Use the Media union and resolved CTA hrefs; LandingSection lazy-loads products by tag.

• Image / Source

  Import: @unpic/svelte

  Use when: Responsive CDN-backed raster images and art direction.

  Key props: src, alt, width/height or aspectRatio, layout, cdn, options, operations.

  Agent note: Always reserve dimensions; use Cloudflare domain cdn.agoratopia.com.

• Icons / Flags

  Import: @mediayard/agoratopia-ui/assets/vectors

  Use when: SVG UI icons, logos, country flags, dynamic country rendering.

  Key props: SVG width/height/class/aria props; flags map for runtime CountryAlpha2 values.

  Agent note: Pair flags/icons with text labels when meaning is not already obvious.

1. Identify the target UI entity and choose the closest kitchen-sink component.
2. Copy the page-level LLM guidance for the component family.
3. Copy the section-level LLM guidance for the exact state or composition pattern.
4. Use the documented import path and Svelte 5 syntax.
5. Keep remote form fields, snippets, bind directives, and accessibility props intact.
6. Run the project checks after implementation.

You are editing a Svelte 5 / SvelteKit project that uses @mediayard/agoratopia-ui.
Before implementing UI, choose the closest existing component from the kitchen-sink.
Use the exact import paths documented by the kitchen-sink page or section.
Prefer Svelte 5 runes: $state for local reactive state, $derived for computed values, $props for component props, onclick/oninput attributes for events, and snippets for component slots.
For forms, prefer SvelteKit remote forms and pass RemoteFormField objects into Select, Slider, Switch, AddressSelect, and AddressForm where documented.
For media, use @unpic/svelte Image/Source with Cloudflare cdn.agoratopia.com, reserve dimensions, and set priority only on the LCP image.
For overlays, compose Dialog with caller-owned open state and callbacks. Do not recreate overlay, focus, or scroll-lock behavior.
For product UI, use ProductCard/ProductCardLoader and ProductCardData. Keep product lists keyed by stable ids or hrefs.
Preserve accessibility: real labels, aria-invalid with errors, role="switch" behavior, dialog labels, keyboard navigation, disabled states, and visible focus.