# Enad docs Full AI Docs

Generated: 2026-04-25T12:40:51.965Z

Use this bundle when an AI agent needs the full docs AI guidance set. Exact SDK/API facts remain authoritative in enad-packages and generated API/OpenAPI artifacts.

---

# AI Docs

URL: https://docsv3.enad.io/ai
Kind: guide
Authority: guidance
Domains: ai, docs
Copy-paste safe: guidance-only

# AI Docs

Docs is the canonical home for Enad AI-facing documentation. Use this section when you are giving an AI agent enough context to choose SDK surfaces, compose storefront UI, call APIs, use Search, work with Media or Events, or restore a playground theme safely.

## Static AI entrypoints

- <a href="/llms.txt" target="_blank" rel="noreferrer"><code>/llms.txt</code></a>: short AI index with the safest starting points. Use this first for route choice.
- <a href="/llms-full.txt" target="_blank" rel="noreferrer"><code>/llms-full.txt</code></a>: full AI docs bundle generated from docs AI pages. Use this when a task spans domains or the agent cannot browse route-by-route.
- <a href="/ai/manifest.json" target="_blank" rel="noreferrer"><code>/ai/manifest.json</code></a>: machine-readable manifest with route, package, version, source path, and copy-paste safety metadata.

## Choose one route first

Start with the narrowest authored AI route that matches the job. Use broader artifacts only when the task spans multiple domains.

| Job | Start route | Exact facts live in |
| --- | --- | --- |
| Give an agent safe Enad context fast | [Agent quickstart](/ai/agent-quickstart) | linked docs routes and generated/package truth sources |
| Explain what the AI artifacts are for | [AI artifacts and manifest](/ai/artifacts) | generated `/llms.txt`, `/llms-full.txt`, and `/ai/manifest.json` outputs |
| Copy a prompt skeleton without widening scope | [Prompt recipes](/ai/prompts) | the destination route and its owning generated/source artifacts |
| Build React storefront or theme work | [React SDK AI guide](/ai/react-sdk/latest) | package artifacts and public React docs routes |
| Choose React imports or component family before coding | [React SDK AI discovery and imports](/ai/react-sdk/latest/discovery) | generated package artifacts and package source |
| Restore a playground theme or reason about component sets/icons | [React SDK AI theme and icons](/ai/react-sdk/latest/theme-and-icons) | package artifacts and playground export flow |
| Split shopper UI work from Search or purchase-side truth | [React SDK AI commerce and Search handoff](/ai/react-sdk/latest/commerce-search-handoff) | React docs routes, Search docs, and owning commerce/API sources |
| Use the TypeScript SDK or package Search helpers | [TypeScript SDK AI guide](/ai/ts-sdk/latest) | package artifacts, package source, and generated API truth |
| Reason about APIs, OpenAPI, or Search GraphQL | [API and Search AI guide](/ai/apis/latest) | generated reference, OpenAPI specs, and generated Search artifacts |

If a task crosses several areas, start with <a href="/llms.txt" target="_blank" rel="noreferrer"><code>/llms.txt</code></a> for route choice or <a href="/llms-full.txt" target="_blank" rel="noreferrer"><code>/llms-full.txt</code></a> for the generated multi-domain bundle, then hand off to the narrowest authored route before writing code.

## Source-of-truth boundary

AI docs can explain how to use Enad, but they must not become the hand-maintained source of SDK or API facts.

- SDK exports, component props, hooks, Search client helpers, generated Search documents, and runtime behavior stay authoritative in `enad-packages`.
- docs-v3 should consume `docs-artifacts/enad-packages-manifest.json` for package truth instead of scraping package README prose.
- API endpoint truth stays generated from API/OpenAPI sources.
- Media contracts, event payloads, integration details, and delivery semantics stay in their owning source or generated artifacts.
- Theme-playground stays the runtime sandbox and export lab.
- Docs owns human docs, AI docs, manifests, and static llms entrypoints.

## Current stable docs-v3 routes

Package docs and AI agents should prefer these public routes:

- [React SDK](/react-sdk/latest)
- [React SDK setup](/react-sdk/latest/setup)
- [React product listing and search](/react-sdk/latest/guides/product-listing-search)
- [TypeScript SDK](/ts-sdk/latest)
- [Search GraphQL latest](/search/latest)
- [Search GraphQL reference latest](/reference/search-graphql/latest)
- [APIs](/apis)
- [Media](/media)
- [Events](/events)
- [Integrations](/integrations)
- [AI Docs](/ai)

`/reference/search-graphql/latest` is now a public route, but it is reference-compatible source-pending guidance rather than a generated schema reference.

## Theme and playground boundary

Agents should use public consumer surfaces only:

```tsx
import { EnadProvider } from "@enadhq/enad-react-sdk";
import { EnadThemeProvider } from "@enadhq/enad-react-sdk/client/theme";
```

Do not copy theme-playground internals or route code into applications. Use providers, theme helpers, generated CSS, documented component-set names, and the public playground export flow.

---

# Agent quickstart

URL: https://docsv3.enad.io/ai/agent-quickstart
Kind: quickstart
Authority: guidance
Domains: ai, docs
Copy-paste safe: prompt-safe

# Agent quickstart

Use this guide when you are asking an AI agent to work with Enad docs, SDKs, APIs, Search, Media, Events, or theme setup.

## Give the agent these files first

1. <a href="/llms.txt" target="_blank" rel="noreferrer"><code>/llms.txt</code></a> for the short routing index. Use it to choose the first route and avoid loading unrelated docs.
2. <a href="/llms-full.txt" target="_blank" rel="noreferrer"><code>/llms-full.txt</code></a> when the task spans multiple Enad domains or the agent cannot browse route-by-route.
3. <a href="/ai/manifest.json" target="_blank" rel="noreferrer"><code>/ai/manifest.json</code></a> when the agent or tool can consume machine-readable route metadata, version tracks, source paths, and copy-paste-safety hints.
4. The generated source artifact named by the relevant docs page when exact exports, props, operations, package versions, or API fields matter.

Use the smallest context that can answer the routing question, then add source artifacts only for contract details.

## Tell the agent the source-of-truth boundary

Copy this instruction into agent prompts:

```text
Use docs-v3 for Enad guidance, route selection, and source-boundary rules. Do not invent SDK exports, component props, API fields, Search schema details, Media fields, event payloads, or package versions from prose. When exact SDK/API/package facts matter, use generated artifacts or source files from enad-packages, with docs-artifacts/enad-packages-manifest.json as the package-truth boundary. Do not copy theme-playground internals into apps.
```

## Choose the right AI route

| Task | Give the agent | Boundary to preserve |
| --- | --- | --- |
| Build storefront UI with React components | [React SDK AI guide](/ai/react-sdk/latest), then [React SDK](/react-sdk/latest) | Use public React SDK imports; exact props stay in package artifacts. |
| Call Enad APIs from server code | [TypeScript SDK AI guide](/ai/ts-sdk/latest), then [TypeScript SDK](/ts-sdk/latest) | Use docs for flow; exact methods, types, and versions stay in package artifacts. |
| Work with Search GraphQL, facets, or generated Search documents | [API and Search AI guide](/ai/apis/latest), then [Search GraphQL latest](/search/latest) | Keep app, market, store-group, and locale context explicit; schema truth stays generated. |
| Work directly with HTTP APIs or OpenAPI-backed endpoint details | [API and Search AI guide](/ai/apis/latest), then [APIs](/apis) | Endpoint fields and operation truth stay generated from API/OpenAPI sources. |
| Work with Media or DAM concepts | [Media](/media) | Treat Media docs as guidance; do not infer asset schemas or upload contracts without the owning API/source artifact. |
| Work with Events or Integrations | [Events](/events) and [Integrations](/integrations) | Preserve event delivery and integration boundaries; verify payload truth in owning generated sources. |
| Restore a theme from the playground | [React SDK AI guide](/ai/react-sdk/latest) and [Prompt recipes](/ai/prompts) | Use public provider/theme surfaces; keep playground internals in the playground. |
| Generate or review prompts | [Prompt recipes](/ai/prompts) | Keep prompts concise, safe, and explicit about source truth. |
| Decide whether content belongs in docs or playground | [AI Docs](/ai) and [Playground](/playground) | Docs owns guidance and llms outputs; playground owns runtime sandbox/export behavior. |

## Safe operating rules

- Keep `docs.enad.io` and production `sdk.enad.io` routing unchanged until launch readiness work explicitly changes them.
- Treat docs AI docs as canonical guidance, not as endpoint, schema, package, or prop truth.
- Use `docs-artifacts/enad-packages-manifest.json` as the docs-v3 package truth boundary; do not depend on package README prose for exact facts.
- Prefer public imports from `@enadhq/enad-react-sdk` and `@enadhq/enad-react-sdk/client/theme` when React examples are needed.
- Keep theme-playground runtime/editor/export behavior in the playground.
- Record compatibility needs for old `/llms*` URLs instead of deleting or silently replacing them.

## Minimal prompt skeleton

```text
You are working with Enad docs. Start from /llms.txt and /ai/manifest.json. Use /llms-full.txt only when the task spans domains or you need a full docs bundle. Use docs-v3 for guidance and route selection. Use enad-packages, generated artifacts, or docs-artifacts/enad-packages-manifest.json for exact SDK exports, component props, API fields, Search schema details, event payloads, Media contracts, and package versions. Keep docs.enad.io and sdk.enad.io production routing unchanged unless the task explicitly says this is a launch-readiness phase.

Task: <describe the Enad SDK/API/Search/Media/Events/theme job>
```

---

# API and Search AI guide

URL: https://docsv3.enad.io/ai/apis/latest
Kind: api-guide
Applies to: api-management, api-shopper, api-auth, api-dam, api-media, api-search-graphql, api-events
Version: latest
Authority: guidance
Domains: api, search, graphql
Exact facts: API endpoint paths, methods, parameters, request bodies, responses, GraphQL fields, generated documents, fragment fields, and event payload facts require generated OpenAPI, GraphQL schema, package artifact, or event catalog sources.
Copy-paste safe: guidance-only

# API and Search AI guide

Use this page when an AI agent needs to reason about Enad APIs, OpenAPI specs, Search GraphQL, generated Search package artifacts, or docs corpus parity.

## Choose the API or Search route first

Use this authored page when the first job is route choice: which API family, which reference surface, or whether the task is really Search GraphQL instead of REST.

Choose a narrower route first when possible:

- Go to [Search GraphQL latest](/search/latest) for query-model guidance, GraphiQL usage, category or collection targeting, facets, autocomplete, and generated Search document handoff.
- Go to [Search GraphQL reference latest](/reference/search-graphql/latest) when the task needs the stable reference-compatible Search URL.
- Go to generated API reference or OpenAPI-backed routes before writing exact request, response, auth, or parameter code.
- Go to [React product listing and search](/react-sdk/latest/guides/product-listing-search) when the real task is shopper-facing UI composition rather than endpoint or schema truth.

Use this page to pick the owning truth surface. Keep authored prose guidance-only and use generated/reference/package artifacts for exact contracts.

## Current corpus inventory

The current public docs corpus inventory includes:

- 464 total links
- 432 API reference links
- 47 API categories
- 24 conceptual docs
- 7 OpenAPI specs
- 1 optional external link
- 588 route-map entries with zero unclassified entries

See [Current docs parity inventory](/start/current-docs-parity) for the machine-readable inventory and route map.

## API reference boundary

API endpoint truth should be generated from API/OpenAPI sources. Tome pages may explain concepts, but they should not become the hand-authored source of endpoint fields, request schemas, or response schemas.

For an API task, tell agents to:

1. Identify the API family and current route-map entry.
2. Check generated reference or OpenAPI data before writing request/response code.
3. Keep auth, app context, locale, and runtime placement explicit.
4. Avoid inventing endpoint fields from prose.

## MCP architecture boundary

For Enad MCP work, treat MCP as an orchestration and policy surface over canonical Enad platform contracts, not as a new source of endpoint truth.

Rules for AI agents:

- Prefer GraphQL-backed `search.*` capabilities for catalog discovery, product lookup, facets, category/collection browsing, redirects, autocomplete, and other read workflows that used to be routed through Shopper REST reads.
- Treat `shopper.*` capabilities as deprecated compatibility for existing Shopper REST read flows. Do not add new MCP read guidance that depends on `shopper.*` when an equivalent `search.*` capability exists.
- Treat `api.enad.io` and the Nabbit-backed Management/public APIs as the source of truth for catalog, commerce, media, and identity mutations.
- Route all MCP mutations through the governed change lifecycle: validate or construct intent, `changes.preview`, explicit approval when required, `changes.apply`, and `audit.get`/operation verification.
- Do not describe MCP tools as direct write proxies around raw REST or GraphQL endpoints. MCP should expose bounded capabilities with previewable impact, policy checks, attribution, and audit records.

## Search GraphQL boundary

Use [Search GraphQL latest](/search/latest) when the task is about app-scoped Search GraphQL, GraphiQL, query shape, category or collection targeting, facets, autocomplete, generated Search documents, or Search-backed SDK behavior. Use [Search GraphQL reference latest](/reference/search-graphql/latest) when an agent, package doc, or tool needs a stable reference-compatible Search GraphQL URL.

Rules for AI agents:

- Keep app, market, store-group, and locale context explicit.
- Use `@enadhq/enad-ts-sdk/search` and `createSearchClient()` when package-provided Search helpers are the right fit.
- Know the current named `SearchClient` helper coverage: products, product lookup by slug or SKU, facets, category browsing, category lookup by ID or URI, collection browsing, collection lookup by ID or URI, brands, series, redirects, variants, autocomplete completions, and product slugs.
- Use exported generated documents and types when no named convenience method exists.
- Treat Search attribute values as structured generated objects, not serialized JSON strings to be parsed by hand.
- Use named `searchBrands()` and `searchSeries()` helpers only when package source confirms the installed version includes them; generated brand and series documents remain available for lower-level execution.
- Keep top-level `warehouseSlug` out of `ProductFilter`.
- Treat category and collection targeting as query-model guidance, not shopper-UI guidance.
- Route shopper-facing search UI, filters, recommendations, PDP, or PLP behavior to React/commerce guidance.

## Fragment compatibility notes

Search product fragments now include richer media and merchandising fields such as videos, files, collections, brand and series media, variant-group fields, status, filterable tags, and filterable attributes. Variant fragments include `variantGroupId`. Price fragments include market/store-group fields, reference price, sale dates, and status.

Agents should not duplicate full fragment definitions from this page. Use generated package artifacts for exact field names, nesting, and nullability.

## React Search runtime boundary

When the task is React-specific, prefer provider-backed Search usage from the React SDK only if current package exports support the needed component or hook.

- Provider Search context keeps market, store group, and locale together.
- `graphql.storeGroupSlug` can override `groupId` for Search context.
- `mapSearchProductToProductCard()` accepts `storeGroupSlug` so Search product mapping can prefer the intended store-group price.

Use [React product listing and search](/react-sdk/latest/guides/product-listing-search) for shopper-facing PLP/search composition.

## OpenAPI specs captured

- `/swagger/management-api.json`
- `/swagger/auth-api.json`
- `/swagger/shopper-api.json`
- `/swagger/dam-api.json`
- `/swagger/auth.yaml`
- `/swagger/shopper-yaml.yaml`
- `/swagger/management-yaml.yaml`

Generated API reference and OpenAPI spec access should use stable docs URLs that point back to these source artifacts.

## Prompt skeleton

```text
Use docs route-map and AI docs to identify the current Enad API or Search source. API endpoint truth must come from generated API/OpenAPI sources, not hand-authored prose. Search GraphQL truth must come from generated Search package artifacts or schema sources. Keep app, market, store-group, locale, auth, and runtime placement explicit. For TypeScript Search usage, check @enadhq/enad-ts-sdk/search and createSearchClient(). For React Search usage, check current @enadhq/enad-react-sdk exports before writing code.
```

---

# AI artifacts and manifest

URL: https://docsv3.enad.io/ai/artifacts
Kind: artifact-guide
Authority: guidance
Domains: ai, docs
Copy-paste safe: guidance-only

# AI artifacts and manifest

Use this page when a person, tool, or agent needs the public AI entry artifacts without guessing what each file is for.

## The three public artifacts

| Artifact | Use it for | Do not use it for |
| --- | --- | --- |
| <a href="/llms.txt" target="_blank" rel="noreferrer"><code>/llms.txt</code></a> | short route selection and the smallest safe starting points | full SDK or API detail |
| <a href="/llms-full.txt" target="_blank" rel="noreferrer"><code>/llms-full.txt</code></a> | a generated bundle when the task spans multiple docs domains | exact package exports, endpoint schemas, or GraphQL field truth |
| <a href="/ai/manifest.json" target="_blank" rel="noreferrer"><code>/ai/manifest.json</code></a> | machine-readable route metadata, version tracks, source paths, and copy-paste-safety hints | a replacement for the owning package, OpenAPI, or Search artifact |

Start with the smallest artifact that answers the routing question. Escalate to the larger bundle only when the task truly spans multiple domains.

## What these artifacts include

The generated AI artifacts are public routing aids. They should include:

- public AI guidance pages under `/ai`
- stable docs routes that help agents choose the right surface
- version-track metadata for supported package and API surfaces
- source-boundary hints that point back to `enad-packages`, generated API reference, OpenAPI specs, or Search artifacts
- copy-paste-safety metadata that tells tools whether a page is guidance-only or safer to quote directly

## What they must leave out

These artifacts should not expose internal authoring material or pretend to be contract truth.

Keep these out of public AI outputs:

- internal authoring pages such as `AGENTS.md`
- hidden or draft AI pages
- playground-only internals and route code
- hand-authored prop tables, hook signatures, endpoint fields, or GraphQL fragment definitions
- private or review-only notes about unpublished docs structure

## Source-of-truth boundary

Use docs AI artifacts to choose the route. Use the owning artifact to verify the exact fact.

| Question | Trust this source |
| --- | --- |
| Which docs route should an agent open first? | `/llms.txt`, `/llms-full.txt`, or `/ai/manifest.json` |
| Which React or TypeScript package track does `latest` describe? | `/ai/manifest.json` and the version-track page |
| What is the exact SDK export, prop, hook, helper signature, or runtime behavior? | `enad-packages` and `docs-artifacts/enad-packages-manifest.json` |
| What is the exact REST path, request field, response field, or auth rule? | generated API reference and OpenAPI inputs |
| What is the exact Search operation, variable, fragment, or generated type? | generated Search artifacts and package source |
| What belongs to the live runtime sandbox? | the playground and `https://sdk.enad.io/sandbox` |

## Practical selection rule

1. Use <a href="/llms.txt" target="_blank" rel="noreferrer"><code>/llms.txt</code></a> to pick the smallest relevant docs route.
2. Use <a href="/ai/manifest.json" target="_blank" rel="noreferrer"><code>/ai/manifest.json</code></a> when a tool needs route metadata or version-track context.
3. Use <a href="/llms-full.txt" target="_blank" rel="noreferrer"><code>/llms-full.txt</code></a> only when the task crosses multiple Enad domains.
4. Before writing exact code, jump from the chosen docs route to the owning package, OpenAPI, or Search artifact.

## Related routes

- [AI Docs](/ai)
- [Agent quickstart](/ai/agent-quickstart)
- [React SDK AI guide](/ai/react-sdk/latest)
- [TypeScript SDK AI guide](/ai/ts-sdk/latest)
- [Prompt recipes](/ai/prompts)

---

# Prompt recipes

URL: https://docsv3.enad.io/ai/prompts
Kind: prompt-recipes
Authority: guidance
Domains: ai, react-sdk, ts-sdk, api, search, media, events, theming
Copy-paste safe: prompt-safe

# Prompt recipes

These prompts are designed for AI agents that can read docs pages and, when needed, inspect generated artifacts or `enad-packages` for exact SDK/API truth. Keep them short, then add the exact source artifact only when the task needs contracts, fields, exports, or versions.

## General routing prompt

```text
Use /llms.txt to choose the smallest Enad docs route for this task. Use /ai/manifest.json for route metadata and copy-paste-safety hints. Use /llms-full.txt only if the task spans React SDK, TypeScript SDK, Search, APIs, Media, Events, or theming. Before writing code, name the owning route and the source-of-truth artifact for exact contracts.
```

## React SDK component work

```text
Use Enad docs as guidance and use enad-packages, generated artifacts, or docs-artifacts/enad-packages-manifest.json for exact React SDK exports, component props, and package versions. I need to build <surface>. First identify the correct Enad component family and public import path. Then show the smallest React example using @enadhq/enad-react-sdk. Do not invent props.
```

## Storefront composition

```text
Use docs and /llms-full.txt to route this storefront task. Decide whether the primary domain is layout, storefront content blocks, compound composition, commerce, Search, or theming. Name the owner domain first, then produce a small implementation plan. Keep live sandbox/theme-playground behavior in the playground and do not copy its route internals into the app.
```

## TypeScript SDK API work

```text
Use docs for guidance and enad-packages, generated artifacts, or docs-artifacts/enad-packages-manifest.json for exact @enadhq/enad-ts-sdk APIs and package versions. I need to call <API family> from <runtime>. Identify the correct SDK/client boundary, required auth or app context, and generated API reference or OpenAPI source to check before writing code. Do not hand-author endpoint fields from memory.
```

## Search GraphQL work

```text
Use the Enad Search AI guidance. Keep app, market, store-group, and locale context explicit. If this is React-specific, route to the React SDK Search guidance. If this is endpoint/query-model guidance, route to Search GraphQL and generated Search artifacts. Do not invent operation names, variables, fragments, or schema fields.
```

## Media and DAM work

```text
Use /llms.txt and the Media route to understand where Media or DAM guidance belongs. Treat docs as guidance only. Do not infer upload contracts, asset schemas, transformations, or API fields from prose; verify them in the owning generated source or API artifact before giving code.
```

## Events and Integrations work

```text
Use the Events and Integrations routes for delivery, webhook, and integration guidance. Preserve source-of-truth boundaries: docs may explain behavior, but exact payload fields, retry contracts, signatures, and API details must be verified in the owning generated source before implementation.
```

## Theme restoration from playground

```text
Use public Enad theme surfaces only. Keep EnadProvider at the app root and wrap the themed subtree with EnadThemeProvider from @enadhq/enad-react-sdk/client/theme. If the playground export includes rich runtime theme data, prefer const themeHash = "..." plus <EnadThemeProvider hash={themeHash}>. Use componentSet="..." directly only for structural-set-only setup. Do not copy theme-playground internals or routes into the app.
```

## Theme debugging

```text
Debug Enad theme restoration in this order: verify the same hash is passed through, check whether an explicit componentSet prop overrides the hash, check whether explicit tokens override decoded values, then confirm the SDK stylesheet is imported so component-set selectors exist. Remember: componentSet is structural; token overrides change CSS variables.
```

## API reference parity

```text
Use docs inventory and route-map data to identify the current docs.enad.io source entry. API endpoint truth should be generated from API/OpenAPI sources. Do not move endpoint details into hand-authored Tome prose unless the task is explicitly about writing a conceptual guide.
```

## Review AI docs changes

```text
Review this docs AI docs change. Check that it preserves the source-of-truth boundary: docs owns guidance, route selection, manifests, and llms outputs; enad-packages and docs-artifacts/enad-packages-manifest.json own SDK/package facts; generated API/OpenAPI/Search artifacts own contract facts; theme-playground owns runtime sandbox/export behavior; production docs.enad.io and sdk.enad.io routing remain unchanged unless explicitly in scope.
```

---

# React SDK AI guide

URL: https://docsv3.enad.io/ai/react-sdk/latest
Kind: package-guide
Track: package-react-sdk
Applies to: package-react-sdk
Package: @enadhq/enad-react-sdk
Version: 1.6.0
Version range: >=1.6.0 <1.7.0
Authority: guidance
Domains: react-sdk, storefront, commerce, search, theming
Exact facts: Exact React SDK imports, props, hooks, component parts, package versions, and runtime behavior require generated enad-packages artifacts for this track.
Copy-paste safe: guidance-only

# React SDK AI guide

Use this page when an AI agent needs to work with `@enadhq/enad-react-sdk`.

## Choose the React AI route first

Use this authored page as the broad React SDK entrypoint when the task spans provider setup, storefront composition, Search runtime boundaries, or theme/runtime handoff.

Choose a narrower route first when possible:

- Go to [React SDK AI discovery and imports](/ai/react-sdk/latest/discovery) before choosing component families or public import surfaces.
- Go to [React SDK AI theme and icons](/ai/react-sdk/latest/theme-and-icons) for theme hashes, component sets, icon/runtime boundaries, or playground restoration.
- Go to [React SDK AI commerce and Search handoff](/ai/react-sdk/latest/commerce-search-handoff) when the job crosses shopper UI, Search GraphQL, pricing display, or purchase-adjacent behavior.
- Go to [Product listing and search](/react-sdk/latest/guides/product-listing-search) for shopper-facing search composition and [Search GraphQL latest](/search/latest) for query-model truth.

Use this page to route the work. Use generated package artifacts or package source for exact exports, props, hooks, helper signatures, and runtime behavior before writing code.

## Source-of-truth boundary

- Use this page for routing, composition guidance, and safe examples.
- Use `enad-packages` and generated package artifacts for exact exports, prop names, hook signatures, Search mapping helpers, and runtime behavior.
- Do not copy code from the theme-playground internals into consumer apps.
- Keep live sandbox/editor/export behavior in the playground.

## Focused AI routes

Use the smallest React SDK AI page that matches the job:

- [React SDK AI discovery and imports](/ai/react-sdk/latest/discovery) — choose the right component family and public import surface before writing code.
- [React SDK AI theme and icons](/ai/react-sdk/latest/theme-and-icons) — preserve provider nesting, theme hashes, component sets, and runtime icon boundaries.
- [React SDK AI commerce and Search handoff](/ai/react-sdk/latest/commerce-search-handoff) — keep shopper UI composition separate from Search GraphQL and purchase-side contract truth.

## Provider setup

`EnadProvider` is the root SDK runtime provider. It owns SDK-wide setup such as React Query, icon registration, locale, component resolver wiring, and optional client/search configuration.

```tsx
import { EnadProvider } from "@enadhq/enad-react-sdk";

export function AppShell({ children }: { children: React.ReactNode }) {
  return <EnadProvider>{children}</EnadProvider>;
}
```

Add `EnadThemeProvider` when the app needs runtime theme state, component-set selection, scoped token overrides, or playground hash restoration.

```tsx
import { EnadProvider } from "@enadhq/enad-react-sdk";
import { EnadThemeProvider } from "@enadhq/enad-react-sdk/client/theme";

export function AppShell({ children }: { children: React.ReactNode }) {
  return (
    <EnadProvider>
      <EnadThemeProvider componentSet="editorial">{children}</EnadThemeProvider>
    </EnadProvider>
  );
}
```

## Search runtime rules

Use [Product listing and search](/react-sdk/latest/guides/product-listing-search) for PLP, search-results, autocomplete, and connected Search component composition.

Rules for AI agents:

- Keep query/data responsibility separate from UI composition.
- Keep market, store group, and locale together in provider-backed Search runtime configuration.
- `graphql.storeGroupSlug` can override `groupId` for Search context.
- `mapSearchProductToProductCard()` accepts `storeGroupSlug` so mapped cards can prefer the intended store-group price.
- Use current package artifacts for exact hook, helper, and component props before writing code.
- Do not move cart, checkout, or purchase side effects into presentational Search cards.

## Runtime theming rules

- Correct nesting is `EnadProvider` outside and `EnadThemeProvider` around the themed subtree.
- Runtime precedence is explicit `EnadThemeProvider` props, then decoded hash values, then SDK defaults.
- `componentSet` is structural. It changes the UI language through `data-component-set`; it is not only a color preset.
- Token overrides change CSS variables. Keep token changes separate from component-set changes in explanations and examples.
- Playground share URLs and export snippets can carry both token state and `componentSet`.
- Prefer `hash={themeHash}` when restoring rich playground state.
- Use `componentSet="..."` directly when the setup is structural-set only and there is no richer hash state to restore.
- `enad-theme` generates CSS blocks. It does not replace `EnadThemeProvider` for runtime behavior.

## Theme restoration example

```tsx
import { EnadProvider } from "@enadhq/enad-react-sdk";
import { EnadThemeProvider } from "@enadhq/enad-react-sdk/client/theme";

const themeHash = "paste-playground-theme-hash-here";

export function StorefrontShell({ children }: { children: React.ReactNode }) {
  return (
    <EnadProvider>
      <EnadThemeProvider hash={themeHash}>{children}</EnadThemeProvider>
    </EnadProvider>
  );
}
```

If the restored app does not match the playground, debug in this order:

1. Verify the same `hash` is passed through.
2. Check whether explicit `componentSet` overrides the hash value.
3. Check whether explicit `tokens` override decoded token values.
4. Confirm the SDK stylesheet is imported so component-set selectors exist.

## Component work

Route broad React SDK questions before implementing:

| User intent | Primary docs domain |
| --- | --- |
| Choose the right component | Discovery |
| Compose public child parts | Compound composition |
| Build header/footer/page shell | Layout |
| Build hero/gallery/content blocks | Storefront |
| Build price/variant/cart flow | Commerce |
| Query products/facets/autocomplete | Search |
| Apply component set or theme hash | Theme |

When exact component props matter, inspect package source or generated package artifacts. Do not invent props from prose.

## Docs React SDK route map

Use these docs routes before falling back to the live playground docs surface:

- [React SDK latest](/react-sdk/latest) — public landing page for route selection, source boundaries, Search runtime facts, and package artifact guidance.
- [React SDK AI discovery and imports](/ai/react-sdk/latest/discovery) — package-aware route selection for component families and public imports.
- [React SDK AI theme and icons](/ai/react-sdk/latest/theme-and-icons) — theme restoration, component sets, and icon/runtime boundaries.
- [React SDK AI commerce and Search handoff](/ai/react-sdk/latest/commerce-search-handoff) — cross-surface routing for PLP, Search, pricing, and purchase-adjacent work.
- [React SDK setup](/react-sdk/latest/setup) — provider, stylesheet, and runtime setup order.
- [First React SDK app](/react-sdk/latest/guides/first-app) — smallest useful provider/theme shell and first-page checklist.
- [Theme from playground](/react-sdk/latest/guides/theme-from-playground) — restore playground theme hashes while preserving provider and precedence rules.
- [Storefront page guide](/react-sdk/latest/guides/storefront-page) — compose layout chrome, storefront sections, and app-owned routing/data boundaries.
- [Product listing and search](/react-sdk/latest/guides/product-listing-search) — compose PLP/search UI while keeping Search GraphQL truth in schema/generated sources.
- [Product detail page](/react-sdk/latest/guides/product-detail-page) — compose PDP media, price, variant, and purchase-adjacent UI without assigning cart/checkout side effects to presentational components.
- [React SDK troubleshooting](/start/troubleshooting) — symptom-based recovery for stylesheet, provider, theme, search, API, and AI docs issues.
- [React SDK theming](/react-sdk/latest/theming) — `EnadThemeProvider`, component sets, theme hashes, and runtime precedence.
- [Component resolver](/react-sdk/latest/resolver) — resolver-backed primitives, component sets, and custom component override boundaries.
- [React SDK components](/react-sdk/latest/components) — component docs grouped by Base UI, Layout, Storefront, and Commerce.
- [Base UI components](/react-sdk/latest/components/base-ui) — low-level resolver-backed primitives.
- [Layout components](/react-sdk/latest/components/layout) — Header, Footer, navigation, promotion, and shell components.
- [Storefront components](/react-sdk/latest/components/storefront) — editorial, merchandising, media, and content blocks.
- [Commerce components](/react-sdk/latest/components/commerce) — shopper decision, product, cart, search, and checkout-adjacent surfaces.
- [React SDK playground](/react-sdk/latest/playground) — boundary between docs guidance and the live sandbox/runtime lab.

The authored guides keep JavaScript and TypeScript snippets to the public root package import and the public theme import: `@enadhq/enad-react-sdk` and `@enadhq/enad-react-sdk/client/theme`. The setup guide may also show the required stylesheet import. When exact component, hook, Search GraphQL, or child-part imports matter, inspect generated package artifacts or package source instead of inventing imports from prose.

Component pages preserve their source playground route and source path, but they are guidance pages. When exact props or child parts matter, inspect generated package artifacts or package source.

## Playground bridge

Use [Playground](/playground) for runtime experimentation, theme export, and live-data sandboxing. Use docs for instructions, source-boundary guidance, and AI docs. The route-map keeps runtime playground routes in the playground while long-form component docs live in docs.

---

# React SDK AI commerce and Search handoff

URL: https://docsv3.enad.io/ai/react-sdk/latest/commerce-search-handoff
Kind: package-guide
Track: package-react-sdk
Applies to: package-react-sdk
Package: @enadhq/enad-react-sdk
Version: 1.6.0
Version range: >=1.6.0 <1.7.0
Authority: guidance
Domains: react-sdk, commerce, search, ts-sdk
Exact facts: Exact React SDK imports, props, hooks, component parts, package versions, and runtime behavior require generated enad-packages artifacts for this track.
Copy-paste safe: guidance-only

# React SDK AI commerce and Search handoff

Use this page when a task crosses shopper-facing React UI, Search GraphQL data, pricing display, or purchase-adjacent behavior.

## Keep the ownership split explicit

| Concern | Start here | Exact truth comes from |
| --- | --- | --- |
| Search query shape, variables, generated documents, fragments, and types | [Search GraphQL latest](/search/latest) | generated Search artifacts and package source |
| Server-side Search usage or custom data loading | [TypeScript SDK latest](/ts-sdk/latest) and [/ai/ts-sdk/latest](/ai/ts-sdk/latest) | `@enadhq/enad-ts-sdk/search` artifacts and helpers |
| Shopper-facing PLP, autocomplete, filters, result cards, and Search UI composition | [Product listing and search](/react-sdk/latest/guides/product-listing-search) | React SDK package artifacts for exact component and helper exports |
| PDP display composition and purchase-adjacent UI | [Product detail page](/react-sdk/latest/guides/product-detail-page) | React SDK artifacts for exact display surfaces |
| Cart, checkout, and write-side commerce effects | app-owned commerce integration, shopper APIs, and generated API reference | API/OpenAPI truth and app implementation |

The React SDK is the composition layer. Search GraphQL and API artifacts remain the contract layer.

## Current handoff rules to preserve

- Provider-backed Search runtime keeps market, store group, and locale together.
- `graphql.storeGroupSlug` can override `groupId` for Search context.
- `mapSearchProductToProductCard()` accepts `storeGroupSlug` so mapped cards can prefer the intended store-group price.
- Product cards and Search UI should display normalized data; they should not silently own cart or checkout side effects.
- Exact Search fields, filter names, fragment coverage, and generated types must come from Search artifacts, not prose memory.

## Practical agent workflow

1. Decide whether the question is mostly about contract truth or mostly about shopper UI.
2. If contract truth is the problem, start at [Search latest](/search/latest) or the relevant API reference before touching React composition.
3. If shopper UI is the problem, start at [Product listing and search](/react-sdk/latest/guides/product-listing-search) or [Commerce components](/react-sdk/latest/components/commerce).
4. Carry market, store group, locale, and any `warehouseSlug` context through the whole flow.
5. Keep cart, checkout, and other write-side effects in app-owned handlers after the display layer has done its job.

## Common mistakes

Do not let an agent:

- invent Search fields, fragment members, or helper signatures from docs prose
- treat a Search product card as the place to mutate cart or checkout state
- separate market, store group, and locale when debugging price or availability mismatches
- move server-side Search loading into browser-only UI code without checking runtime placement
- confuse React composition questions with OpenAPI or GraphQL schema questions

## Related routes

- [Search GraphQL latest](/search/latest)
- [React SDK setup](/react-sdk/latest/setup)
- [Product listing and search](/react-sdk/latest/guides/product-listing-search)
- [Commerce components](/react-sdk/latest/components/commerce)
- [TypeScript SDK latest](/ts-sdk/latest)
- [React SDK AI discovery and imports](/ai/react-sdk/latest/discovery)

---

# React SDK AI discovery and imports

URL: https://docsv3.enad.io/ai/react-sdk/latest/discovery
Kind: package-guide
Track: package-react-sdk
Applies to: package-react-sdk
Package: @enadhq/enad-react-sdk
Version: 1.6.0
Version range: >=1.6.0 <1.7.0
Authority: guidance
Domains: react-sdk, storefront, components, theming
Exact facts: Exact React SDK imports, props, hooks, component parts, package versions, and runtime behavior require generated enad-packages artifacts for this track.
Copy-paste safe: guidance-only

# React SDK AI discovery and imports

Use this page when an AI agent needs to choose the right React SDK route, component family, or public import surface before writing code.

## Source-of-truth boundary

- Use docs for route selection, component-family framing, and safe setup order.
- Use `enad-packages` and generated package artifacts for exact exports, props, hooks, child parts, and helper signatures.
- Do not invent deep import paths from prose.
- Do not copy playground route internals into an app just because a playground example exists.

## Start with the documented public import surfaces

These are the confirmed setup imports docs can show directly:

```tsx
import "@enadhq/enad-react-sdk/styles.css";
import { EnadProvider } from "@enadhq/enad-react-sdk";
import { EnadThemeProvider } from "@enadhq/enad-react-sdk/client/theme";
```

For grouped public barrels, documented storefront refinements, and the few retained deep exceptions, start with [Import surfaces](/react-sdk/latest/guides/import-surfaces) before guessing a path.

Treat everything beyond these setup imports as package-artifact truth. When an agent needs a component, hook, helper, or child-part import, it should inspect the current package artifacts before writing code.

## Route by job

| Job | Start here | Why |
| --- | --- | --- |
| Root setup and provider order | [React SDK setup](/react-sdk/latest/setup) | Confirms stylesheet, `EnadProvider`, and `EnadThemeProvider` placement. |
| Choose a grouped public entry point or documented exception | [Import surfaces](/react-sdk/latest/guides/import-surfaces) | Keeps root setup imports, grouped barrels, and retained deep seams straight before implementation. |
| Build login, signup, password-reset, sign-out, or current-user UI | [Account and auth UI](/react-sdk/latest/guides/account-and-auth-ui) | Keeps the public `client/user` surface aligned with runtime-adapter and Auth API boundaries. |
| Find the right component family | [React SDK components](/react-sdk/latest/components) | Groups the public docs by Base UI, Layout, Storefront, and Commerce. |
| Build shell chrome | [Storefront page guide](/react-sdk/latest/guides/storefront-page) and [Layout components](/react-sdk/latest/components/layout) | Keeps header, footer, navigation, and app-owned routing boundaries clear. |
| Build shopper-facing listing or search UI | [Product listing and search](/react-sdk/latest/guides/product-listing-search) | Separates Search GraphQL truth from React composition. |
| Build PDP or purchase-adjacent UI | [Product detail page](/react-sdk/latest/guides/product-detail-page) | Keeps display composition separate from cart and checkout side effects. |
| Apply theme hashes or component sets | [React SDK theming](/react-sdk/latest/theming) and [Theme from playground](/react-sdk/latest/guides/theme-from-playground) | Explains provider nesting, precedence, and playground handoff. |
| Feed an AI workflow | [React SDK AI guide](/ai/react-sdk/latest) | Gives route selection plus package-boundary rules. |

## Discovery workflow for agents

1. Name the job first: setup, imports, auth/account, layout, storefront, commerce, Search, or theming.
2. Open the matching docs route before guessing an import.
3. If the question is import-path selection, check [Import surfaces](/react-sdk/latest/guides/import-surfaces) before inventing a deeper path.
4. Verify the exact component or helper export in generated package artifacts.
5. Write the smallest example that stays on documented public package imports.
6. If the example depends on live Search, cart, client, or auth/session wiring, keep that integration at the app boundary rather than burying it inside presentational components.

## Red flags

Stop and re-route when an agent is about to:

- invent a component, hook, or deep import path from memory
- treat a docs table or prose paragraph as the prop reference
- scrape a playground route for consumer-app wiring
- mix Search GraphQL contract questions into a pure component-selection task
- move cart or checkout behavior into a product-display card because the UI surface looks convenient

## Related routes

- [React SDK latest](/react-sdk/latest)
- [Import surfaces](/react-sdk/latest/guides/import-surfaces)
- [Account and auth UI](/react-sdk/latest/guides/account-and-auth-ui)
- [React SDK AI guide](/ai/react-sdk/latest)
- [React SDK AI theme and icons](/ai/react-sdk/latest/theme-and-icons)
- [React SDK AI commerce and Search handoff](/ai/react-sdk/latest/commerce-search-handoff)
- [AI artifacts and manifest](/ai/artifacts)

---

# React SDK AI theme and icons

URL: https://docsv3.enad.io/ai/react-sdk/latest/theme-and-icons
Kind: package-guide
Track: package-react-sdk
Applies to: package-react-sdk
Package: @enadhq/enad-react-sdk
Version: 1.6.0
Version range: >=1.6.0 <1.7.0
Authority: guidance
Domains: react-sdk, theming, playground
Exact facts: Exact React SDK imports, props, hooks, component parts, package versions, and runtime behavior require generated enad-packages artifacts for this track.
Copy-paste safe: guidance-only

# React SDK AI theme and icons

Use this page when an AI agent needs to restore a playground theme, choose a component set, talk about icon behavior, or explain which runtime boundary owns theme state.

## Provider and runtime boundary

Keep these roles separate:

- `EnadProvider` is the root SDK runtime provider.
- `EnadThemeProvider` belongs inside `EnadProvider`.
- The root provider owns SDK-wide runtime setup such as icon registration and shared client/runtime wiring.
- The theme provider owns themed subtree state such as component-set selection, token overrides, and restored theme hashes.

Use the confirmed public imports only:

```tsx
import "@enadhq/enad-react-sdk/styles.css";
import { EnadProvider } from "@enadhq/enad-react-sdk";
import { EnadThemeProvider } from "@enadhq/enad-react-sdk/client/theme";
```

When exact icon APIs, icon names, provider options, or theme prop names matter, inspect package artifacts before writing code.

## Theme restoration rules

- Correct nesting is `EnadProvider` outside and `EnadThemeProvider` around the themed subtree.
- Runtime precedence is explicit `EnadThemeProvider` props, then decoded hash values, then SDK defaults.
- `componentSet` is structural. It changes the resolver-backed UI family, not only colors.
- Token overrides change CSS-variable state and should stay conceptually separate from `componentSet` decisions.
- Use `hash={themeHash}` when restoring richer playground state.
- Use `componentSet="..."` directly when the app only needs the structural family.

## Playground boundary

Use docs to explain the model. Use the playground to validate the live result.

- The playground owns runtime editing, share URLs, and export flows.
- docs own route selection, provider guidance, and source-boundary wording.
- `enad-theme` CSS output or exported snippets do not replace `EnadThemeProvider` for runtime restoration.
- Do not copy sandbox-only helpers or route code into a consumer app.

## Icon guidance for agents

This docs track can safely say that icon wiring lives at the SDK runtime boundary, but it should not hand-author exact icon registry APIs unless package artifacts confirm them.

Use this rule:

1. Keep icon setup discussion at the `EnadProvider` boundary.
2. Verify exact icon helpers, option names, or override APIs in package artifacts.
3. Keep theme state concerns in `EnadThemeProvider` rather than mixing them into icon guesses.

## Troubleshooting order

If a restored app does not match the playground or icon behavior looks wrong, check in this order:

1. `@enadhq/enad-react-sdk/styles.css` is imported once.
2. `EnadThemeProvider` is nested inside `EnadProvider`.
3. The same `hash` or `componentSet` used in the playground is being restored.
4. Explicit props are not overriding the intended hash values.
5. Exact icon/runtime APIs were taken from package artifacts instead of prose memory.

## Related routes

- [React SDK theming](/react-sdk/latest/theming)
- [Theme from playground](/react-sdk/latest/guides/theme-from-playground)
- [Playground](/playground)
- [React SDK AI discovery and imports](/ai/react-sdk/latest/discovery)
- [AI artifacts and manifest](/ai/artifacts)

---

# TypeScript SDK AI guide

URL: https://docsv3.enad.io/ai/ts-sdk/latest
Kind: package-guide
Track: package-ts-sdk
Applies to: package-ts-sdk
Package: @enadhq/enad-ts-sdk
Version: 0.19.0
Version range: >=0.19.0 <0.20.0
Authority: guidance
Domains: ts-sdk, api, search
Exact facts: Exact TypeScript SDK exports, method signatures, generated types, package versions, and runtime behavior require generated enad-packages artifacts for this track.
Copy-paste safe: guidance-only

# TypeScript SDK AI guide

Use this page when an AI agent needs to work with `@enadhq/enad-ts-sdk`, the `@enadhq/enad-ts-sdk/search` surface, or backend/client API usage boundaries.

## Choose the TypeScript route first

Use this authored page as the broad TypeScript SDK entrypoint when the task mixes package usage, Search helpers, root helpers, and direct API boundary questions.

Choose a narrower route first when possible:

- Go to [Product listing helpers](/ts-sdk/latest/guides/product-listing-helpers) for listing URL state or REST listing query shaping.
- Go to [Search GraphQL latest](/search/latest) when the task is primarily Search query shape, generated documents, facets, autocomplete, or targeting.
- Go to generated API reference or OpenAPI-backed routes before writing exact request, response, auth, or parameter code.
- Go to [React SDK AI guide](/ai/react-sdk/latest) when the real job is provider-backed React composition rather than TypeScript package usage.

Use this page to route the work and frame runtime boundaries. Use generated package artifacts or package source for exact exports, helper signatures, Search documents, and method behavior before writing code.

## Source-of-truth boundary

- Use docs for guidance, route selection, and source status.
- Use `enad-packages/packages/enad-ts-sdk` and `docs-artifacts/enad-packages-manifest.json` for exact exports, method signatures, generated types, generated Search documents, and package behavior.
- Use generated API reference or OpenAPI sources for endpoint fields.
- Do not hand-author endpoint, GraphQL operation, or fragment truth from memory.

## Safe agent workflow

1. Identify the API family, SDK surface, or Search operation the task needs.
2. Check whether the task is SDK usage, direct API usage, Search GraphQL usage, or root-helper usage.
3. Use this guide for boundaries and setup framing.
4. If the task is listing URL state or REST listing query shaping, open [Product listing helpers](/ts-sdk/latest/guides/product-listing-helpers) before inventing app-local utilities.
5. Inspect current package source or generated artifacts when exact signatures matter.
6. Keep auth, app context, market, store group, locale, and runtime placement explicit.

## Search workflow

For Search-specific tasks, start with [Search GraphQL latest](/search/latest) and keep app, market, store-group, and locale context explicit.

Current package facts for agents:

- `@enadhq/enad-ts-sdk/search` exposes the lower-level Search GraphQL surface.
- `createSearchClient()` is the package-supported Search client entry point.
- Named `SearchClient` methods cover products, product by slug/SKU, facets, category browsing, category lookup by ID or URI, collection browsing, collection lookup by ID or URI, brands, series, redirects, variants, completions, and product slugs.
- Generated documents, types, and named helpers are exported for brands and series when the installed package version includes the current Search helper parity work.
- Keep `warehouseSlug` as a top-level product/facet query variable, not as a `ProductFilter` field.

## Root helper reminder

`@enadhq/enad-ts-sdk` exposes a small root-package helper surface in addition to generated clients and the lower-level Search package.

Current helper families include:

- [Product listing helpers](/ts-sdk/latest/guides/product-listing-helpers): `toProductQueryOptions()`, `ProductListingQueryOptions`, `parseProductListingUrlState()`, `serializeProductListingUrlState()`, and `toggleProductFilterValue()`
- `resolveProductPrice()`
- `normalizeVariantStockSignal()`
- `orderProductsBySlugs()`

Reminder boundaries for agents:

- treat exact helper signatures and return types as package-artifact truth
- treat tuple-style SDK responses as `[data, error]` on the core Enad API client surface
- keep `normalizeVariantStockSignal()` limited to stock-only variant facts, not purchase or UI policy

## Prompt boundary

```text
Use docs for Enad TypeScript SDK guidance, but inspect enad-packages or generated package artifacts for exact exports, SearchClient methods, generated documents, helper signatures, and method signatures. Use @enadhq/enad-ts-sdk/search and createSearchClient() for package-backed Search GraphQL usage. Use the root package helper guide for listing URL state or REST listing query shaping. Do not invent request fields, response fields, GraphQL fragment fields, or convenience methods. If endpoint truth matters, check generated API reference or OpenAPI sources.
```

## API usage checklist

- Which Enad app or tenant context does the call need?
- Which API family owns the resource?
- Is this a server-side call, browser call, or build-time data fetch?
- Which auth token or credential boundary applies?
- Is there an OpenAPI spec or generated reference entry for the endpoint?
- Does the React SDK already provide a safer provider-backed surface for the same job?

## Versioning boundary

Docs versioning tracks package versions, not whole-site versions. Use the `latest` AI guide for current package guidance and preserved package-version routes when they exist.

---

# Preserved Enad SDK AI skill corpus

This appendix preserves SDK-focused AI guidance from enad-packages skills. It provides routing context, not a versioned package reference or authority for exact exports, component props, hooks, API fields, package versions, or runtime behavior. Prefer the selected manifest version track and its generated package/API artifacts. If this appendix conflicts with a versioned track or generated artifact, the track/artifact wins.

# Enad SDK Full AI Docs

Guidance for selecting and composing Enad SDK components.

# Enad SDK Overview

Route broad Enad SDK questions into the right guidance for component selection, compound composition, theming, icons, layout, storefront composition, Search GraphQL, and commerce flows.

# Enad SDK Overview

Use this guide for broad Enad SDK questions that have not yet settled into one domain.

This guide narrows a request to one of eight domains: discovery, compound composition, theme, icons, layout, storefront, Search, and commerce.

Start with the [domain map](references/domain-map.md) to identify the primary domain. Use [routing rules](references/routing-rules.md) when a prompt spans more than one area. Use [prompt examples](references/prompt-examples.md) when the closest path is still unclear.

## Responsibilities

1. Identify the primary domain in the request.
2. Explain why that domain is the best fit.
3. Name a secondary follow-up path when the prompt clearly spans domains.
4. Hand off to the matching focused guide when one exists.

Do not repeat detailed guidance that already belongs in the focused guides.

## Current domain targets

- discovery
- compound composition
- theme
- icons
- layout
- storefront
- search
- commerce

## Quick routing path

- Need to pick the right domain? Read [domain map](references/domain-map.md).
- Need help with a broad or mixed prompt? Read [routing rules](references/routing-rules.md).
- Need examples that match real questions? Read [prompt examples](references/prompt-examples.md).

## Rules

- Keep the overview narrow.
- Route by named rules, not undocumented taste.
- Prefer one clear primary domain.
- If a request spans domains, name the primary owner first and the follow-up path second.
- Do not let layout, storefront, Search, or commerce answers absorb component-choice guidance that belongs to discovery.
- Do not let other domains absorb compound-part composition guidance that belongs to compound composition.

## Reference: references/domain-map.md

# Enad SDK Domain Map

Use this file to decide which domain owns a request before answering in depth.

## Domains

| Domain               | Owns                                                                                                                                                                                                            | Does not own                                                                            | Focused guide                   |
| -------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------- | ------------------------------- |
| discovery            | Component selection, closest-fit options, comparing primitives, finding the right entry point, documented import-surface guidance                                                                               | Detailed composition recipes, layout systems, storefront patterns, Search semantics     | `enad-sdk-discovery`            |
| compound composition | Parent-led compound patterns, slot strategy, child-part lookup, and multi-part API shape                                                                                                                        | Broad component lookup, page-shell questions, full commerce flows                       | `enad-sdk-compound-composition` |
| theme                | `EnadProvider`, `EnadThemeProvider`, exported token semantics, token-role selection, component sets, runtime theme hashes, generated theme CSS, playground share restoration, and `enad-theme` CLI behavior     | Detailed icon-slot semantics, adapter choice, `Iconify` slot mapping                    | `enad-sdk-theme`                |
| icons                | Semantic icon slots, `IconSlotMap`, `Icon`, `useIcon`, shipped icon adapters, adapter overrides, and Iconify-backed slot mapping                                                                                | Component-set theming, layout systems, Search semantics, or buying-flow questions       | `enad-sdk-icons`                |
| layout               | Navigation chrome, page scaffolding, structure, shells, drawers used as layout or navigation primitives                                                                                                         | Storefront content blocks, product-specific flows, Search query semantics               | `enad-sdk-layout`               |
| storefront           | Editorial blocks, content rows, linked tiles, galleries, product-card display, mixed merchandising sections, and Media API usage for storefront image surfaces such as PLP cards, thumbnails, and PDP galleries | Product detail mechanics, cart behavior, Search API semantics                           | `enad-sdk-storefront`           |
| search               | Search GraphQL endpoints, GraphiQL, app-scoped Search context, query shapes, category and collection targeting, facets, autocomplete data contracts, and sandbox Search-backed live-data behavior               | Shopper-facing search UI behavior, cart and pricing flows, general layout questions     | `enad-sdk-search`               |
| commerce             | Price, selection, quantity, cart, quick view, shopper-facing search and filter behavior, recommendations, and PDP or PLP buying behavior                                                                        | General layout questions, pure editorial composition, Search GraphQL endpoint semantics | `enad-sdk-commerce`             |

## Domain selection heuristics

### Route to discovery when the user asks

- which component to use
- what the closest fit is
- whether two components are the better choice
- what import path the chosen component should use
- where to start in the SDK

Primary guide: `enad-sdk-discovery`

### Route to compound composition when the user asks

- how parent and child pieces should compose
- how slots, triggers, content, or child parts should work together
- what the consumer may customize versus what the SDK already owns
- how a compound family such as `Dialog`, `Sheet`, `Select`, or `Stepper` fits together

Primary guide: `enad-sdk-compound-composition`

### Route to theme when the user asks

- how `EnadProvider` and `EnadThemeProvider` should work together
- how component sets differ from token overrides
- what an exported theme token means or which token should own a UI role
- how nearby tokens differ, such as `--card` vs `--background` or `--primary` vs `--accent`
- how playground share URLs restore runtime theme state
- how `encodeThemeHash`, `decodeThemeHash`, `generateThemeCSS`, or `enad-theme` should be used

Primary guide: `enad-sdk-theme`

### Route to icons when the user asks

- how semantic icon slots work in the SDK
- whether to use `Icon` or `useIcon`
- how to switch icon adapters or override one slot
- how `createIconifyIcons()` works, including fallback behavior
- how to map `prefix:name` Iconify names from the playground into app setup

Primary guide: `enad-sdk-icons`

### Route to layout when the user asks

- how to structure shells, chrome, navigation, drawers, or structural primitives
- how to use `HeaderSection`, `StoreHeader`, `UtilityNav`, `PrimaryNav`, `MegaMenu`, `MobileNav`, `Header`, `Footer`, `PromotionBar`, or `MobileMenuDrawer` across a page
- how page framing should interact with fixed or transparent header behavior

Primary guide: `enad-sdk-layout`

### Route to storefront when the user asks

- how to build editorial or merchandising sections from SDK blocks
- how to compose rows, tiles, galleries, heroes, or other display surfaces
- how `ProductCard` should fit into merch rows as a display primitive
- how Enad media URLs should be sized or transformed for PLP cards, thumbnails, or PDP galleries
- whether raw `media.enad.io` originals or transformed media URLs should be used on storefront surfaces

Primary guide: `enad-sdk-storefront`

### Route to search when the user asks

- how Enad Search GraphQL works
- how to use GraphiQL against an Enad app
- which Search operation to use for products, facets, collections, autocomplete, or slug lookups
- how category and collection targeting should be shaped in `ProductFilter`
- how the theme playground sandbox uses Search after a live source is connected

Primary guide: `enad-sdk-search`

### Route to commerce when the user asks

- how price, variant selection, quantity, cart, quick view, recommendations, or shopper-facing search and filters should behave
- how commerce state should sit around PDP or PLP surfaces
- how shopper-facing overlays should fit into the buying flow

Primary guide: `enad-sdk-commerce`

## Multi-domain requests

When a prompt spans multiple domains:

1. Name the primary domain first.
2. Name the secondary domain second.
3. Stay at the overview layer only long enough to explain how the question splits.

Examples:

- `Dialog or Sheet for a product comparison drawer?` → primary: discovery, secondary: compound composition.
- `How should I restore a playground hash that also changes icon mappings?` → primary: theme, secondary: icons.
- `I need an editorial product row with linked tiles and pricing hints.` → primary: storefront, secondary: commerce.
- `I need a product card grid with filters and recommendations.` → primary: storefront when the question is about the row and card shape, secondary: commerce when the question shifts to shopper behavior.
- `How should I query a category page when the same URI may map to either a category or a collection?` → primary: search, secondary: commerce only if the follow-up turns into shopper-facing filter behavior.

## Reference: references/routing-rules.md

# Routing Rules

Use these rules after checking [domain map](domain-map.md).

## Primary routing rules

### 1. Component choice and comparison

If the user is deciding between components, finding the closest fit, asking what import path to use, or asking where to start:

- route to discovery
- use `enad-sdk-discovery`
- if the question depends on how multiple parts fit together, name compound composition as the follow-up path

### 2. Parent-child and slot structure

If the user asks about compound APIs, trigger or content parts, slot strategy, or what the consumer may customize:

- route to compound composition
- use `enad-sdk-compound-composition`
- if the user has not actually picked the right family yet, discovery may come first

### 3. Runtime theming, token semantics, and component sets

If the user asks about `EnadProvider`, `EnadThemeProvider`, exported token meaning, token-role selection, component sets, theme hashes, generated CSS, or the playground share-theme flow:

- route to theme
- use `enad-sdk-theme`
- treat questions like `What does --primary do?`, `When should I use --card instead of --background?`, or `Which token should a focus ring use?` as theme questions
- if the prompt becomes a layout or storefront composition question, hand off after the theme state model is clear

### 4. Icon slots and adapter setup

If the user asks about semantic icon slots, `IconSlotMap`, `Icon`, `useIcon`, icon adapter choice, `createIconifyIcons()`, fallback behavior, or how playground Iconify names map into app setup:

- route to icons
- use `enad-sdk-icons`
- if the prompt is mostly about runtime theme restoration, `EnadThemeProvider`, or share hashes, theme may be the first stop before icons takes over

### 5. Structural navigation and chrome

If the user asks about shells, header and footer framing, promotion-aware chrome, mobile navigation, or page structure:

- route to layout
- use `enad-sdk-layout`
- if the prompt starts as a component comparison, discovery may still be the first stop before layout takes over

### 6. Editorial and merchandising composition

If the user asks about heroes, linked tiles, editorial rows, galleries, image blocks, product-card display patterns, or how Enad media URLs should be used on storefront surfaces:

- route to storefront
- use `enad-sdk-storefront`
- if price, variant state, add-to-cart behavior, filters, or recommendations become central, route to commerce next

### 7. Search GraphQL and query semantics

If the user asks about Search GraphQL, GraphiQL, app-scoped Search context, query shapes, category or collection targeting, facets, autocomplete data contracts, or the sandbox's Search-backed runtime behavior:

- route to search
- use `enad-sdk-search`
- if the prompt starts with shopper-facing behavior for search or filters, commerce may be the first stop before Search takes over

### 8. Product and buying flows

If the user asks about price, PDP, PLP, selection, quantity, cart, quick view, shopper-facing search, filters, recommendations, or other buying flows:

- route to commerce
- use `enad-sdk-commerce`
- if the prompt starts with `which component should I use`, discovery can be the first stop before commerce takes over
- if the prompt is mostly about card layout or editorial row structure, storefront may be the first stop before commerce takes over
- if the prompt turns into Search endpoint or filter-schema guidance, route to Search next

## Mixed-domain handling

When a request spans multiple domains:

1. State the primary domain.
2. State the secondary domain.
3. Explain the split in one sentence.
4. Do not answer both domains in full from the overview.

Example patterns:

- `Primary domain: storefront, because the prompt starts with the display shape of the section.`
- `Follow-up path: commerce, because filters and recommendations change the shopper behavior around that display.`

- `Primary domain: search, because the prompt is about Search GraphQL semantics and query shape.`
- `Follow-up path: commerce, if the next question becomes shopper-facing search or filter behavior.`

- `Primary domain: layout, because the prompt is about shell structure and chrome.`
- `Follow-up path: compound composition, if the follow-up becomes a question about how a drawer primitive composes.`

- `Primary domain: icons, because the prompt is about semantic icon-slot setup and adapter choice.`
- `Follow-up path: theme, if the next question becomes a share-hash or runtime-provider ownership question.`

## Focused guides

The overview should hand off directly to these guides:

- `enad-sdk-discovery`
- `enad-sdk-compound-composition`
- `enad-sdk-theme`
- `enad-sdk-icons`
- `enad-sdk-layout`
- `enad-sdk-storefront`
- `enad-sdk-search`
- `enad-sdk-commerce`

## Escalation rules

If the prompt is still ambiguous after one routing pass:

- ask one clarifying question only if the domain truly cannot be identified
- otherwise choose the most likely primary domain and explain the assumption

## Anti-patterns

Do not:

- turn the overview into a full component encyclopedia
- answer compound-structure questions as if they were plain discovery questions
- let layout, storefront, Search, or commerce answers absorb import-path guidance that belongs to discovery
- let layout, storefront, Search, or commerce answers absorb public child-part composition guidance that belongs to compound composition
- answer a mixed product-card, filters, and recommendations prompt as if only one domain exists

## Reference: references/prompt-examples.md

# Prompt Examples

Use these examples when the closest Enad guidance path is still unclear.

## Example questions

### 1. Lightweight inline disclosure

**Prompt:** `I need a lightweight inline disclosure, should I use Accordion or Collapsible?`

- Primary domain: discovery
- Why: the request is a first-pass component choice between two nearby primitives
- Expected answer direction: choose `Collapsible` for one reveal block and `Accordion` for grouped sibling sections, then give the supported import surface

### 2. Dialog composition

**Prompt:** `How should I compose DialogTrigger, DialogContent, and DialogHeader in Enad?`

- Primary domain: compound composition
- Why: the user already picked the component family and now needs a composition answer
- Expected answer direction: explain the `Dialog` family from the parent component outward, name the minimum public parts, and keep the answer on supported composition

### 3. ProductCard import surface

**Prompt:** `What import path should I use for ProductCard and when should I avoid a narrower path?`

- Primary domain: discovery
- Why: the question is about the documented public import surface for a chosen component
- Expected answer direction: answer with the documented public path and name any documented exception only when the docs already allow it

### 4. Linked gallery rows

**Prompt:** `What is the right Enad component for linked gallery rows, Gallery or GalleryWithLinkBlocks?`

- Primary domain: discovery
- Why: the user is choosing between two storefront wrappers with different child-shape expectations
- Expected answer direction: choose `GalleryWithLinkBlocks` for destination-led `LinkBlock` rows and `Gallery` for broader child mixes

### 5. Runtime theming guidance

**Prompt:** `How should I restore a shared theme from the playground and still keep EnadProvider at the root?`

- Primary domain: theme
- Why: the request is about runtime theme ownership, component sets, and shared hash restoration
- Expected answer direction: keep `EnadProvider` at the root, add `EnadThemeProvider` around the themed subtree, then explain precedence between explicit props, hash values, and defaults

### 6. Iconify slot overrides

**Prompt:** `How should I use createIconifyIcons in Enad if I only want to override search, cart, and heartFilled?`

- Primary domain: icons
- Why: the request is about semantic icon-slot mapping, adapter behavior, and fallback rules
- Expected answer direction: explain semantic slots, show `createIconifyIcons({ names: { ... } })`, and state that unmapped slots still fall back to the configured fallback map

### 7. Token semantics guidance

**Prompt:** `When should I use --card instead of --background, and should a focus state use --border or --ring?`

- Primary domain: theme
- Why: the request is about exported token meaning and token-role selection, not component choice or layout structure
- Expected answer direction: explain the canvas-versus-container split first, then distinguish passive structure tokens from active focus tokens

### 8. Layout shell guidance

**Prompt:** `How should I structure header, promotion bar, and mobile navigation in the Enad SDK?`

- Primary domain: layout
- Why: the request is about shell structure, chrome ownership, and page framing
- Expected answer direction: keep `Header` as the top shell, explain where `PromotionBar` and `MobileMenuDrawer` sit, and mention page-structure consequences such as fixed-header spacing

### 9. Editorial storefront pattern

**Prompt:** `What is the best Enad pattern for a hero followed by linked editorial tiles and a gallery row?`

- Primary domain: storefront
- Why: the request starts with editorial section composition and display rhythm
- Expected answer direction: use `Hero` for the opener, `LinkBlock` or `QuickLinks` for the linked tiles depending on weight, and `Gallery` or `GalleryWithLinkBlocks` based on child shape

### 10. Search GraphQL routing

**Prompt:** `How should I query Enad Search GraphQL for a category page when the same URI may be either a category or a collection?`

- Primary domain: search
- Why: the request is about Search filter semantics, not shopper-facing UI behavior
- Expected answer direction: explain `v1Products`, the `ProductFilter` shape, and when to send the same URI to both `categoryUrls` and `collectionUris`

### 11. Sandbox Search behavior

**Prompt:** `How does the theme playground sandbox choose products when I connect live data without selectors?`

- Primary domain: search
- Why: the request is about Search-backed sandbox runtime behavior and product-selection rules
- Expected answer direction: explain the connected Search-only path, discovery queries, category-driven query behavior, and why connected failures stay visible

### 12. Commerce flow guidance

**Prompt:** `How should price, variant selection, quantity, and add-to-cart fit together in Enad?`

- Primary domain: commerce
- Why: the request is about shopper decision state and buying-flow composition
- Expected answer direction: keep `Price`, `VariantSelector`, and `QuantityPicker` focused on their own jobs, then explain where quick preview or cart surfaces fit

### 13. Storefront media transforms

**Prompt:** `How should I size Enad media URLs for PLP cards, thumbnails, and PDP galleries?`

- Primary domain: storefront
- Why: the request is about storefront image-surface behavior and Media API usage, not Search or buying-flow state
- Expected answer direction: explain transformed Enad media URLs, recommend starting width, quality, format, and fit values by surface, and warn against raw originals on repeated card or thumbnail surfaces

### 14. Mixed display and buying prompt

**Prompt:** `I need a product card grid with filters and recommendations, where should I start?`

- Primary domain: storefront
- Secondary path: commerce
- Why: the prompt starts with the display shape of the grid, then shifts into filter and recommendation behavior
- Expected answer direction: describe the grid and card layer first, then move into commerce for shopper-facing filter, search-state, and recommendation flow

---

# Enad SDK Discovery

Choose the right Enad SDK component and public import path. Use when a request starts with component selection, nearest-fit comparisons, child-part lookup, or import-surface questions.

# Enad SDK Discovery

Use this guide when the request starts with choosing a component family or choosing a supported public import path.

This guide is about selection, not deep composition. Start with [component selection](references/component-selection.md). If the user is asking which public import path to copy, read [import surfaces](references/import-surfaces.md). If the prompt is a comparison question, read [comparison patterns](references/comparison-patterns.md).

## Responsibilities

1. Pick the right Enad component from the current docs, not from generic React patterns.
2. Explain the choice using the current component descriptions, `bestFor` guidance, and `When to use it` sections.
3. Route child-part questions back to the parent component family when the docs treat those parts as one system.
4. Recommend supported public import paths only.
5. Route to `enad-sdk-compound-composition` when the question turns into part structure, slot boundaries, or parent-child composition.

## What this guide owns

Use this guide for prompts such as:

- `Which Enad component should I use here?`
- `Should I use Accordion or Collapsible?`
- `Dialog or Sheet for this flow?`
- `What import path should I use for ProductCard?`
- `I searched for DialogContent. Which Enad component family owns that?`

## What this guide does not own

Do not stay in this guide when the user already knows the component family and now needs to understand:

- how `DialogTrigger`, `DialogContent`, and `DialogHeader` fit together
- which child parts stay inside the parent family
- which slot boundaries belong to the consumer versus the SDK
- how a compound family should be composed step by step

Those questions belong to `enad-sdk-compound-composition`.

## Discovery rules

- Ground every answer in the current Enad docs.
- Route child-part names such as `DialogContent`, `AccordionTrigger`, or `SheetHeader` back to the parent component family unless the docs present them as standalone components.
- Prefer the grouped public import paths documented in the SDK README.
- Only mention a narrower path when the README or current docs already document that exception.
- Do not recommend source-private paths such as `../../ui-resolver/dialog` or package-internal file paths.

## Reference: references/component-selection.md

# Component Selection

Use this workflow before answering any `which component should I use` question.

## Decision workflow

1. Read the component `description`, `bestFor`, and `When to use it` guidance first.
2. Check whether the user is asking about one component or comparing nearby alternatives.
3. If the prompt names a child part, map it back to the parent component family.
4. If the prompt is really about how parts fit together, hand off to `enad-sdk-compound-composition`.
5. If the prompt asks for code to copy, confirm the public import path from the SDK README before answering.

## Fast routing table

| User signal                                                                                            | Choose                                                         | Why                                                                                                      | Avoid when                                                                               |
| ------------------------------------------------------------------------------------------------------ | -------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------- |
| One expandable block with one trigger and one revealed region                                          | `Collapsible`                                                  | The docs position it as one root area for optional details or advanced controls                          | The UI is really a list of sibling expandable rows                                       |
| Several related expandable sections such as FAQ or product specs                                       | `Accordion`                                                    | The docs position it as a multi-item disclosure pattern with `single` or `multiple` modes                | The UI only has one expandable region                                                    |
| Centered overlay that interrupts the page until the visitor responds                                   | `Dialog`                                                       | The docs position it as a full-interruption modal for confirmations, edit forms, and detail previews     | The user should stay visually connected to the page behind the panel                     |
| Edge-mounted panel for cart, filters, navigation, or settings                                          | `Sheet`                                                        | The docs position it as a browsable side panel that keeps page context                                   | The flow needs a centered modal and full interruption                                    |
| Custom-styled single-choice picker with grouped items and a floating panel                             | `Select`                                                       | The docs position it as a single-select primitive for region pickers, sort controls, and variant choices | A native select is enough and custom trigger or content composition is not needed        |
| Known sequence with orientation inside checkout, onboarding, or a staged form                          | `Stepper`                                                      | The docs position it as a sequential progress primitive                                                  | The visitor should jump freely between unrelated panels                                  |
| Section wrapper for several visual children that share one heading and one layout rhythm               | `Gallery`                                                      | The docs position it as a wrapper for image, block, or product children with free-form composition       | Every child is primarily a `LinkBlock` destination tile                                  |
| Image-led row where each child is mainly a destination card                                            | `GalleryWithLinkBlocks`                                        | The docs position it as a `LinkBlock`-focused gallery row for discovery and wayfinding                   | The row mixes several child types or acts like a generic gallery shell                   |
| Repeatable product scan item for grids, search, or recommendation rails                                | `ProductCard`                                                  | The docs position it as the product display primitive                                                    | The real question is about the outer section wrapper rather than the product item itself |
| Full storefront header needed quickly with promo, utility, primary nav, actions, and mobile navigation | `HeaderSection`                                                | The docs position it as the fast public path for storefront navigation                                   | The app needs lower-level shell composition rather than the default section shape        |
| Lower-level storefront navigation family composition                                                   | `StoreHeader` family                                           | The docs position it as the family-level path beneath `HeaderSection`                                    | The app mostly fits the section and only needs the fast path                             |
| Full PDP hero needed quickly with media, merchandising, actions, and trust                             | `ProductHeroSection`                                           | The docs position it as the fast public path for the top of a product detail page                        | The app needs lower-level PDP family composition rather than the default section shape   |
| Lower-level PDP family composition                                                                     | `ProductMedia` / `BuyBox` / `PurchaseActions` / `ProductTrust` | The docs position them as the family-level path beneath `ProductHeroSection`                             | The app mostly fits the section and only needs the fast path                             |

## Parent-family lookup rules

Use the parent component family even when the prompt names a child part:

| Prompt mentions                                                         | Route to    | Why                                                        |
| ----------------------------------------------------------------------- | ----------- | ---------------------------------------------------------- |
| `AccordionItem`, `AccordionTrigger`, `AccordionContent`                 | `Accordion` | The parent family owns slot strategy and examples          |
| `DialogTrigger`, `DialogContent`, `DialogHeader`, `DialogFooter`        | `Dialog`    | The parent family owns modal composition and accessibility |
| `SheetTrigger`, `SheetContent`, `SheetHeader`, `SheetFooter`            | `Sheet`     | The parent family owns side-aware layout and behavior      |
| `SelectTrigger`, `SelectValue`, `SelectContent`, `SelectItem`           | `Select`    | The parent family owns the small composition system        |
| `StepperItem`, `StepperTitle`, `StepperDescription`, `StepperSeparator` | `Stepper`   | The parent family owns the sequence model                  |

## Answer shape

When you answer:

1. Name the Enad component.
2. Explain the deciding signal from the docs in plain language.
3. Name the nearest alternative and why it is a worse fit.
4. If the next step is part structure, route to `enad-sdk-compound-composition`.

## Reference: references/import-surfaces.md

# Import Surfaces

Use the public import paths from `packages/enad-react-sdk/README.md`.

## Default rule

Prefer the grouped domain entry points in docs and application code:

- `@enadhq/enad-react-sdk`
- `@enadhq/enad-react-sdk/client/storefront`
- `@enadhq/enad-react-sdk/client/cart`
- `@enadhq/enad-react-sdk/client/global`
- `@enadhq/enad-react-sdk/client/theme`
- `@enadhq/enad-react-sdk/client/icons`
- `@enadhq/enad-react-sdk/client/search`
- `@enadhq/enad-react-sdk/client/ui-resolver`

The current MDX docs confirm this pattern:

- Base UI docs use `@enadhq/enad-react-sdk/client/ui-resolver` for `Dialog`, `Sheet`, `Select`, and `Stepper` examples.
- Storefront docs use `@enadhq/enad-react-sdk/client/storefront` for `Gallery`, `GalleryWithLinkBlocks`, `ProductCard`, `HeaderSection`, and the new navigation family examples.

## Only use a narrower path when it is already documented

The SDK README states this rule plainly:

- prefer grouped domain entry points in docs and application code
- only document a narrower path when there is no grouped public barrel for that API
- keep README examples, Storybook docs, and theme-playground examples aligned with the same public path

## Current documented exception

Use the narrower path below only when the user needs the low-level composable pieces directly:

- `@enadhq/enad-react-sdk/client/storefront/blocks/product-card-parts`

That is the documented exception for `ProductCard` parts.

## Browser-only import-boundary rule

Keep the grouped public entry points as the default answer for normal app code, especially in Next or other server-aware runtimes.

But do **not** assume every public barrel is safe inside browser-only surfaces such as:

- Vite sandboxes
- theme-playground module maps
- Storybook browser previews
- any other environment that cannot execute server actions or Node-only helpers

For browser-only surfaces:

- do not import a mixed public barrel if it also exports server actions, auth helpers, or hooks that depend on server runtime config
- prefer a supported grouped public path or documented retained exception from the package exports, not an invented deeper leaf path
- if the component itself depends on server actions or auth / wishlist hooks, keep the code sample but do not mount a live preview in that browser-only surface

Current browser-boundary watchlist:

- `@enadhq/enad-react-sdk`
- `@enadhq/enad-react-sdk/client/user`
- `@enadhq/enad-react-sdk/client/wishlist`

Concrete example:

- for normal app code, `SearchBar` should be documented from `@enadhq/enad-react-sdk/client/search`
- for a browser-only preview surface, keep the same supported public path and gate the live preview on runtime compatibility instead of inventing a deeper import path

## Focused grouped subpaths

The README also allows grouped subpaths when they are public and make the scope clearer for docs or snippets:

- `@enadhq/enad-react-sdk/client/storefront/components`
- `@enadhq/enad-react-sdk/client/storefront/blocks`
- `@enadhq/enad-react-sdk/client/storefront/product`

Treat these as secondary public surfaces, not the first answer for normal application code.

## What to avoid

Do not recommend:

- package-internal source paths such as `../../ui-resolver/dialog`
- file-system paths inside `packages/enad-react-sdk/src/...`
- made-up per-component public paths that are not documented in the README or package exports
- narrower paths just because they look smaller or more specific

## Fast lookup table

| Need                                                                                                 | Public path to recommend first                                       | Notes                                                                                                            |
| ---------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------- |
| Enad provider or top-level utilities                                                                 | `@enadhq/enad-react-sdk`                                             | Use for `EnadProvider`, `ErrorBoundary`, and the root package surface                                            |
| Base UI primitives such as `Dialog`, `Sheet`, `Select`, or `Stepper`                                 | `@enadhq/enad-react-sdk/client/ui-resolver`                          | This matches the current MDX examples                                                                            |
| Storefront blocks and shopper-facing UI such as `Gallery`, `GalleryWithLinkBlocks`, or `ProductCard` | `@enadhq/enad-react-sdk/client/storefront`                           | This is the preferred application entry point in the README, and it is the first answer for `ProductCard` itself |
| Cart surfaces                                                                                        | `@enadhq/enad-react-sdk/client/cart`                                 | Use for cart components, hooks, and cart types                                                                   |
| Search surfaces                                                                                      | `@enadhq/enad-react-sdk/client/search`                               | Use when the component belongs to search                                                                         |
| Icons                                                                                                | `@enadhq/enad-react-sdk/client/icons`                                | Use only for icon imports                                                                                        |
| ProductCard low-level parts                                                                          | `@enadhq/enad-react-sdk/client/storefront/blocks/product-card-parts` | Mention only when the user explicitly asks for low-level ProductCard parts rather than the full `ProductCard`    |

## Answer shape

When answering an import-path question:

1. Give the grouped public path first.
2. Name the documented narrower exception only when the user's goal requires it.
3. Say why you are avoiding a narrower or internal path.
4. If the question turns into part structure after the import choice, hand off to `enad-sdk-compound-composition`.

## Reference: references/comparison-patterns.md

# Comparison Patterns

Use these patterns when the prompt compares nearby Enad components.

## Accordion vs Collapsible

### Choose `Accordion` when

- the UI has several sibling sections
- visitors may expand one or more rows inside the same group
- the pattern looks like FAQ, shipping and returns, or product specifications

### Choose `Collapsible` when

- the UI has one expandable root area
- the revealed content is secondary details or advanced controls
- the pattern reads like one section, not a stacked list

### Why

The `Accordion` docs describe a four-part multi-item composition. The `Collapsible` docs describe one root area with one trigger and one content region.

### Follow-up route

If the user already picked one and now asks how `Trigger` and `Content` should fit together, hand off to `enad-sdk-compound-composition`.

## Dialog vs Sheet

### Choose `Dialog` when

- the panel should interrupt the page
- the background should feel unavailable until the user responds
- the flow is a confirmation, edit form, or detail preview

### Choose `Sheet` when

- the page should stay visually present behind the panel
- the panel acts like a cart drawer, mobile menu, filter panel, or settings surface
- edge-mounted motion helps the user stay oriented in the page context

### Why

The `Dialog` docs position it as a centered modal for interruption. The `Sheet` docs position it as a side-aware panel for persistent, browsable side content.

### Accessibility note

Both components rely on labeled titles and keyboard dismissal. `Dialog` is the stricter interruption pattern. `Sheet` uses overlay and Escape dismissal too, but it keeps a stronger sense of page continuity.

## Gallery vs GalleryWithLinkBlocks

### Choose `Gallery` when

- the wrapper needs free-form children
- the section mixes image blocks, product blocks, or other visual cards
- layout choice such as `grid`, `masonry`, or `filmstrip` is the main concern

### Choose `GalleryWithLinkBlocks` when

- each child is mainly a destination tile
- the row is for category discovery, room browsing, or editorial wayfinding
- the children are `LinkBlock`-style cards that should feel like one navigation set

### Why

The `Gallery` docs describe a wrapper for varied children and layout rhythm. The `GalleryWithLinkBlocks` docs describe a more opinionated row that expects `LinkBlock`-style children and destination-led browsing behavior.

## ProductCard and section wrappers

### Choose `ProductCard` when

- the unit of choice is the individual product tile
- the user is building grids, search results, or recommendation rails
- scan behavior and card layout are the primary decision

### Do not substitute `ProductCard` for a section wrapper

If the question is really about the outer section shape:

- use `Gallery` for a mixed or free-form gallery wrapper
- use `GalleryWithLinkBlocks` for destination-led `LinkBlock` rows
- place `ProductCard` inside a suitable section wrapper instead of treating it as the wrapper itself

### Import exception

For `ProductCard` itself, recommend `@enadhq/enad-react-sdk/client/storefront` and stop there.

Only mention `@enadhq/enad-react-sdk/client/storefront/blocks/product-card-parts` when the user explicitly asks for low-level composable parts instead of the full card.

## Answer shape

For comparison prompts:

1. Name the winning component first.
2. Name the deciding difference in one sentence.
3. Name the losing alternative and why it is a worse fit.
4. If the user then asks how the chosen component's parts fit together, hand off to `enad-sdk-compound-composition`.

---

# Enad SDK Compound Composition

Explain Enad parent-led compound systems, slot boundaries, and safe child-part composition. Use when a request already knows the component family and needs to understand how the pieces fit together.

# Enad SDK Compound Composition

Use this guide when the component family is already known and the next question is about how public child parts fit together.

Start with [parent-led compounds](references/parent-led-compounds.md). If the prompt is about what the consumer may customize versus what the SDK owns, read [slot boundaries](references/slot-boundaries.md). If the user needs a copyable shape, read [composition examples](references/composition-examples.md).

## Responsibilities

1. Explain how Enad compound component families fit together.
2. Keep child-part lookup attached to the parent component family instead of treating common parts as standalone components.
3. Separate consumer composition from SDK-owned behavior.
4. Keep guidance tied to the current Enad public exports and docs examples.
5. Route back to `enad-sdk-discovery` when the user still has not picked the right component family.

## What this guide owns

Use this guide for prompts such as:

- `How should I compose DialogTrigger, DialogContent, and DialogHeader in Enad?`
- `Which Select parts do I need for a grouped menu?`
- `How do Stepper items, titles, and separators fit together?`
- `What belongs to the parent component family versus the public child parts?`

## Rules

- Start from the parent component family.
- Treat common child parts as supporting pieces unless the docs present them as standalone components.
- Stay on supported public child parts only.
- Call out accessibility-critical pieces when the current docs do, such as `DialogTitle`, keyboard dismissal, and sequence state.
- If the question turns back into `which component should I use`, hand off to `enad-sdk-discovery`.

## Reference: references/parent-led-compounds.md

# Parent-Led Compounds

Many Enad compound families are easiest to understand from the parent component first.

## Core rule

Start from the parent component family.

The parent component explains:

- when to use the family
- how the public parts fit together
- which examples are worth copying
- accessibility and behavior notes that only make sense in the full composition

Treat common child parts as supporting pieces unless the docs present them as standalone components.

## Why Enad does this

Enad compound families are documented and exported around the parent surface. That keeps composition, behavior, and accessibility guidance together instead of scattering it across many tiny entry points.

## Current parent-led families

| Family      | Start with  | Supporting parts                                                                                                    |
| ----------- | ----------- | ------------------------------------------------------------------------------------------------------------------- |
| `Accordion` | `Accordion` | `AccordionItem`, `AccordionTrigger`, `AccordionContent`                                                             |
| `Dialog`    | `Dialog`    | `DialogTrigger`, `DialogContent`, `DialogHeader`, `DialogFooter`, `DialogTitle`, `DialogDescription`, `DialogClose` |
| `Sheet`     | `Sheet`     | `SheetTrigger`, `SheetContent`, `SheetHeader`, `SheetFooter`, `SheetTitle`, `SheetDescription`, `SheetClose`        |
| `Select`    | `Select`    | `SelectTrigger`, `SelectValue`, `SelectContent`, `SelectGroup`, `SelectLabel`, `SelectItem`, `SelectSeparator`      |
| `Stepper`   | `Stepper`   | `StepperItem`, `StepperTitle`, `StepperDescription`, `StepperSeparator`                                             |

## Child-part lookup

When a prompt mentions a child part:

1. route to the parent component family
2. answer from the parent composition guidance
3. explain the child part in context
4. do not treat it as a standalone component unless the current docs or public API do

## Reference: references/slot-boundaries.md

# Slot Boundaries

Use this file to explain what consumers compose directly and what stays inside the SDK boundary.

## Boundary rule

Consumers compose the public parts. The SDK owns the portal, motion, built-in affordances, and recipe behavior.

When a component exposes semantic `classNames` or explicit icon hooks, treat those as the supported customization boundary. Reach for those hooks before recommending raw descendant selectors or a local fork. They let one product create very different branded implementations while the SDK keeps behavior and accessibility.

## Current boundary table

| Family      | Consumer composes directly                                                                                                                           | SDK already owns                                                              | Notes                                                                                             |
| ----------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------- |
| `Accordion` | `Accordion`, `AccordionItem`, `AccordionTrigger`, `AccordionContent`, each item `value`, `single` or `multiple` mode                                 | chevron rotation, content height animation, border and surface treatment      | Use `AccordionBlock` instead when the input is CMS title/body data rather than direct composition |
| `Dialog`    | `Dialog`, `DialogTrigger`, `DialogContent`, `DialogHeader`, `DialogFooter`, `DialogTitle`, `DialogDescription`, controlled `open` state when needed  | portal, overlay, centered panel motion, overlay dismissal                     | Always include a title. `DialogTitle` is required for accessible labeling                         |
| `Sheet`     | `Sheet`, `SheetTrigger`, `SheetContent`, `SheetHeader`, `SheetFooter`, `SheetTitle`, `SheetDescription`, `side`, controlled `open` state when needed | portal, overlay, side-aware slide animation, default close affordance         | Use it for cart, filters, navigation, or settings that should stay connected to the page          |
| `Select`    | `Select`, `SelectTrigger`, `SelectValue`, `SelectContent`, `SelectItem`, optional groups, labels, and separators                                     | floating panel behavior, shared input-style tokens, listbox interaction model | Keep trigger width explicit when layout consistency matters                                       |
| `Stepper`   | `Stepper`, `StepperItem`, `StepperTitle`, `StepperDescription`, `StepperSeparator`, `activeStep`, orientation                                        | sequence framing and connector treatment                                      | Drive `activeStep` from real flow state, not a disconnected constant                              |

## Accessibility boundary notes

Call these out when relevant:

- `Dialog` needs `DialogTitle`, and it uses keyboard dismissal plus focus-management expectations.
- `Sheet` closes on overlay click and Escape, but it stays in the side-panel mental model rather than the centered modal mental model.
- `Select` should preserve the trigger, value, and item structure that the docs describe for the listbox pattern.
- `Stepper` should keep current-step state tied to the real flow so orientation and progress stay truthful.

## What not to recommend

Do not tell users to:

- re-create the overlay or portal manually for `Dialog` or `Sheet`
- pull child parts out into separate docs just because they are exported names
- bypass the documented parent composition by inventing unsupported wrappers
- use private source paths to reach lower-level internals

## Reference: references/composition-examples.md

# Composition Examples

Use these examples when the user needs a safe Enad composition shape instead of a component-choice answer.

## HeaderSection and StoreHeader family

### Good answer shape

- start from `HeaderSection` when the user wants the fast path
- name the section zones first: promo, utility, primary nav, featured, actions, mobile nav
- explain that those zones map down to `PromotionBar`, `StoreHeader`, `UtilityNav`, `PrimaryNav`, `MegaMenu`, and `MobileNav`
- use the featured region override seam before abandoning the section entirely
- drop to `StoreHeader` and the family parts only when the shell itself needs lower-level composition control

### Why

The current docs now treat `HeaderSection` as the section-first public entry point and `StoreHeader` plus the family parts as the lower-level supported navigation anatomy beneath it.

### Parent-doc rule

Do not answer a top-level navigation question by inventing separate standalone guidance for `StoreHeader.Action`, `PrimaryNav.Trigger`, or `MegaMenu.Feature` first. Start from the parent section or family, then explain the public parts in that context.

## ProductHeroSection and PDP family

### Good answer shape

- start from `ProductHeroSection` when the user wants the fast path
- name the section zones first: media, header, options, actions, trust
- explain that those zones map down to `ProductMedia`, `BuyBox`, `PurchaseActions`, and `ProductTrust`
- use a single-zone override seam before abandoning the section entirely
- drop to the lower-level PDP family only when the hero anatomy itself needs more control

### Why

The current docs now treat `ProductHeroSection` as the section-first public entry point for the top of a PDP and the new PDP family surfaces as the lower-level supported anatomy beneath it.

### Parent-doc rule

Do not answer a top-level PDP-hero question by inventing separate standalone guidance for `BuyBox.Title`, `PurchaseActions.Primary`, or `ProductTrust.Item` first. Start from the parent section or family, then explain the public parts in that context.

## Dialog family

### Good answer shape

- start from `Dialog`
- put the opener in `DialogTrigger`
- keep the panel inside `DialogContent`
- use `DialogHeader` and `DialogFooter` for internal layout
- include `DialogTitle` and `DialogDescription` for labeling

### Why

The current docs say `DialogContent` already wraps itself with the portal and overlay. The consumer should compose the public parts, not rebuild modal infrastructure.

### Parent-doc rule

Do not create separate child docs for `DialogContent` or `DialogHeader`. Keep those explanations in the parent `Dialog` doc.

## Sheet family

### Good answer shape

- start from `Sheet`
- open it through `SheetTrigger`
- place the panel in `SheetContent`
- choose `side` on `SheetContent`
- frame the top with `SheetHeader`, `SheetTitle`, and `SheetDescription`
- keep sticky actions in `SheetFooter` when needed

### Why

The current docs position `Sheet` as a side-aware `Dialog` variant for cart drawers, filters, navigation, and settings.

### Parent-doc rule

Do not document `SheetHeader` or `SheetFooter` as standalone pages. Their meaning comes from the full sheet structure.

## Accordion family

### Good answer shape

- use `Accordion` as the group root
- wrap each section in `AccordionItem`
- put the row control in `AccordionTrigger`
- place the revealed body in `AccordionContent`
- choose `type="single"` with `collapsible` by default unless the visitor needs multiple open sections

### Why

The current docs describe `Accordion` as a four-part disclosure system for grouped content, not a single optional-details block.

## Select family

### Good answer shape

- use `Select` as the root
- place the field shell in `SelectTrigger`
- show the current value through `SelectValue`
- place options in `SelectContent`
- add `SelectGroup`, `SelectLabel`, and `SelectSeparator` only when the option set needs structure

### Why

The current docs describe `Select` as a small composition system. Most use cases only need the root, trigger, value, content, and item pieces.

## Stepper family

### Good answer shape

- use `Stepper` as the root
- drive `activeStep` from real flow state
- wrap each stage in `StepperItem`
- keep labels in `StepperTitle`
- add `StepperDescription` only when titles need more context
- place `StepperSeparator` between stages

### Why

The current docs position `Stepper` as a parent-led sequence primitive for checkout, onboarding, and staged flows.

## Answer shape

When answering a composition prompt:

1. name the parent component first
2. list the minimum public child parts to compose
3. name the built-in behavior the SDK already owns
4. if relevant, point out the semantic `classNames` or icon hooks that let consumers style the public anatomy without brittle selectors
5. state the boundary the user should not cross
6. if the user is still choosing the family, route to `enad-sdk-discovery`

---

# Enad SDK Theme

Explain Enad SDK theming, exported token semantics, component sets, runtime theme restoration, EnadProvider, EnadThemeProvider, theme hashes, and the enad-theme CLI. Hand off icon-slot and adapter questions to the dedicated icons guide.

# Enad SDK Theme

Use this guide when the request is about how Enad theme state is applied, restored, shared, or described token-by-token.

Start with [token semantics](references/token-semantics.md) when the question is about what an exported token means, which token should be used for a UI role, or how nearby tokens differ. Use [runtime theming](references/runtime-theming.md) when the question is about `EnadThemeProvider`, component sets, or hash restoration in an app. Use [theme tooling](references/theme-tooling.md) when the question is about `encodeThemeHash`, `decodeThemeHash`, `generateThemeCSS`, or the `enad-theme` CLI. Use [playground flow](references/playground-flow.md) when the question is about the theme-playground share URL, export snippet, or how playground state maps into consumer setup. If the prompt becomes mostly about semantic icon slots, adapter choice, `Icon`, `useIcon`, or `createIconifyIcons()`, hand off to `enad-sdk-icons`.

## Responsibilities

1. Explain the difference between structural component sets and token overrides.
2. Explain what exported theme tokens mean and which UI roles they should own.
3. Clarify when to use `EnadProvider` and when to add `EnadThemeProvider`.
4. Explain the runtime precedence between explicit props, decoded hash values, and defaults.
5. Explain how the playground share URL restores theme state in a consumer app.
6. Route to other guides when the question is really about component choice, layout, storefront composition, Search semantics, or commerce behavior.

## What this guide owns

Use this guide for prompts such as:

- `How should I apply an Enad component set at runtime?`
- `When should I use EnadThemeProvider instead of only EnadProvider?`
- `How does a theme hash from the playground map into an app?`
- `What does --primary do, and when should I use --accent instead?`
- `When should I use --card instead of --background?`
- `Which token should a border, input, or focus ring use?`
- `What does enad-theme apply do, and where does componentSet fit?`
- `How do component sets, runtime tokens, and generated CSS fit together?`

## What this guide does not own

Do not stay in this guide when the user is really asking:

- which Enad component they should choose
- how semantic icon slots, icon adapters, or `createIconifyIcons()` should work
- how compound child parts fit together
- how storefront rows or page shells should look
- how Search GraphQL works
- how price, cart, filters, or recommendation flows behave

Those questions belong to `enad-sdk-discovery`, `enad-sdk-icons`, `enad-sdk-compound-composition`, `enad-sdk-layout`, `enad-sdk-storefront`, `enad-sdk-search`, or `enad-sdk-commerce`.

## Rules

- Treat component sets as structural choices and theme hashes as token and state transport.
- Treat exported theme tokens as semantic UI roles, not raw palette slots.
- Keep `EnadProvider` as the root SDK provider for core runtime services.
- Use `EnadThemeProvider` when the app needs runtime component-set switching, share-hash restoration, or scoped token overrides.
- Prefer the hash-based export/setup flow when the goal is to restore the exact current playground state in an app.
- Keep examples on the public import surface: `@enadhq/enad-react-sdk` and `@enadhq/enad-react-sdk/client/theme`.
- If the request turns into component selection or page composition, hand off to the owning guide instead of stretching theme guidance too far.

## Reference: references/token-semantics.md

# Token Semantics

Use this reference when the question is about what a token means, which token should be used for a UI role, or how exported Enad theme tokens should be described.

This guide focuses on the semantic token surface exposed through the SDK stylesheet, `SDK_DEFAULTS`, `TOKEN_DEFAULTS`, and generated theme CSS.

If the question is about providers, hashes, or runtime restoration, pair this file with [runtime theming](runtime-theming.md) or [theme tooling](theme-tooling.md).

## Core rule

Treat exported tokens as semantic roles, not raw palette slots.

Choose the token by the job it does in the UI first, then tune the underlying value.

## Foundation surface tokens

### `--background`

- Main page or app canvas.
- Use for the overall viewport background and base reading surface.
- Do not use for raised containers that should feel distinct from the page.
- Common confusion: if the element should read as a contained panel, use `--card` instead.

### `--foreground`

- Default text and icon color on `--background`.
- Use for body copy, standard headings, and default iconography on the main page surface.
- Do not use on top of colored actions or specialty surfaces without checking contrast.

### `--card`

- Elevated or grouped content surface that sits on top of the page canvas.
- Use for cards, grouped modules, PDP info panels, and similar contained blocks.
- Do not use as the global page background unless the design intentionally removes surface hierarchy.
- Common confusion: `--background` is the canvas, `--card` is the container sitting on it.

### `--card-foreground`

- Default text and icon color on `--card`.
- Use for content that lives on card surfaces.
- Do not assume it always matches `--foreground`; card contrast may be tuned separately.

### `--popover`

- Floating transient surface.
- Use for menus, dropdown content, tooltips with substantial body content, and other overlay panels.
- Prefer this over `--card` when the UI is explicitly layered above the page.

### `--popover-foreground`

- Default content color on `--popover`.
- Use for text and icons inside floating surfaces.

## Action and emphasis tokens

### `--primary`

- Main brand or action color.
- Use for primary CTAs, selected states that should read as the main action, and strongest intentional emphasis.
- Do not use as a general decoration color everywhere.
- Common confusion: if the element is supportive rather than primary, try `--accent` or `--secondary` instead.

### `--primary-foreground`

- Content color that sits on `--primary`.
- Use for button labels, icons, and any text placed directly on a primary-filled surface.
- Always keep contrast with `--primary` as the priority.

### `--secondary`

- Supportive action or alternative surface.
- Use for secondary buttons, quieter chips, and supportive emphasis that should be visible but not dominant.
- Do not use when the UI element is intentionally low-emphasis or disabled-feeling; `--muted` is usually the better fit there.

### `--secondary-foreground`

- Content color on `--secondary`.
- Use for text and icons placed on secondary-filled surfaces.

### `--accent`

- Highlight color for supportive emphasis, selection hints, or decorative energy.
- Use for highlighted rows, active but non-primary affordances, or branded moments that should not overpower primary actions.
- Do not automatically swap this in for `--primary`; it is supporting emphasis, not the main CTA role.

### `--accent-foreground`

- Content color on `--accent`.
- Use for text and icons shown on accent surfaces.

### `--accent-muted`

- Soft accent-tinted surface.
- Use for subtle highlight backgrounds, tinted callouts, gentle badges, and low-noise selected states.
- Common confusion: use this when `--accent` feels too strong but plain `--muted` loses the visual connection to the brand highlight.

### `--accent-muted-foreground`

- Content color on `--accent-muted`.
- Use for text and icons on soft accent surfaces.

### `--destructive`

- Negative or danger action color.
- Use for destructive CTAs, removal flows, critical validation states, and warning affordances with real consequence.
- Do not use as a generic attention color when the action is not actually destructive.

### `--destructive-foreground`

- Content color on `--destructive`.
- Use for labels and icons on destructive-filled surfaces.

## Quiet and support tokens

### `--muted`

- Quiet support surface.
- Use for subdued containers, placeholders, low-emphasis rows, skeleton-adjacent surfaces, and supporting fills behind secondary information.
- Do not use where the UI still needs to feel interactive or brand-linked; consider `--secondary` or `--accent-muted` in those cases.

### `--muted-foreground`

- Lower-emphasis content color.
- Use for metadata, helper text, captions, tertiary labels, and supporting icons.
- Do not use for primary reading text or critical content.

### `--border`

- Default boundary color.
- Use for separators, card outlines, dividers, table rules, and control outlines in their resting state.
- Do not use as the focus indicator; `--ring` owns focus emphasis.

### `--input`

- Control boundary or fill token for form fields.
- Use for input borders and input-adjacent control chrome.
- Keep it visually compatible with `--border`, but it may diverge if form controls need distinct treatment.
- Common confusion: `--border` is general UI structure, `--input` is specifically for form-control treatment.

### `--ring`

- Focus and interaction outline color.
- Use for focus-visible rings, active accessibility outlines, and other interaction-emphasis halos.
- Do not use as a resting border replacement.
- Common confusion: `--border` is passive structure, `--ring` is active interaction emphasis.

## Hover-state tokens

### `--primary-hover`

- Hover color for primary-filled actions.
- Use when a primary surface needs an explicit hover override.
- If not overridden, it should remain visually derived from `--primary` rather than becoming a new semantic brand color.

### `--secondary-hover`

- Hover color for secondary-filled actions.
- Use for secondary button hover states and similar supportive interactions.

### `--destructive-hover`

- Hover color for destructive-filled actions.
- Use for destructive hover feedback while keeping the destructive role visually obvious.

## Typography and radius tokens

### `--radius`

- Base radius for the theme.
- Use as the shared source for rounded UI geometry.
- Derived size tokens should follow from this rather than hard-coding separate radii without purpose.

### `--font-sans`

- Default sans-serif family for body UI.
- Use for standard application copy and most component text.

### `--font-heading`

- Heading family.
- Use for display text, titles, and other places where the theme wants structural typographic character.
- It may match `--font-sans`, but it exists so component sets and themes can diverge intentionally.

### `--font-mono`

- Monospace family.
- Use for code, structured IDs, tabular debug output, or other machine-like text.
- Do not use for regular storefront body copy.

## Generated Enad shape tokens

### `--enad-button-radius`

- Radius specifically for button geometry.
- Use when buttons should diverge from the base radius without changing every other component.

### `--enad-card-radius`

- Radius for card-like containers.
- Use to tune card personality independently from buttons or inputs.

### `--enad-input-radius`

- Radius for form controls.
- Use when inputs should feel sharper or softer than the rest of the component system.

### `--enad-image-radius`

- Radius for image treatment.
- Use to control media cropping character independently from container geometry.

## Generated Enad depth tokens

### `--enad-shadow-sm`, `--enad-shadow-md`, `--enad-shadow-lg`

- Shadow scale for small, medium, and large elevation steps.
- Use as an elevation ladder rather than inventing one-off shadows per component.
- Keep the steps meaningfully ordered from subtle to prominent.

### `--enad-shadow-color`

- Base color contribution for generated shadows.
- Use when the overall depth language needs to warm, cool, soften, or intensify.

## Generated Enad typography styling tokens

### `--enad-heading-weight`

- Heading font-weight override.
- Use to move the theme toward quieter editorial tone or stronger display tone without changing the entire font family.

### `--enad-heading-tracking`

- Heading letter-spacing.
- Use for display rhythm and tone.
- Common confusion: this is a heading-style control, not a replacement for choosing the right font family.

### `--enad-body-weight`

- Body copy weight.
- Use to tune density and legibility for the overall reading tone.

### `--enad-heading-transform`

- Heading text transform.
- Use for structural casing choices such as uppercase display systems.
- Do not use to patch content-model problems one component at a time.

## Generated border and overlay tokens

### `--enad-border-width`

- Shared border-width for the Enad component language.
- Use to globally sharpen or soften the feel of outlined surfaces.

### `--enad-overlay-color`

- Base overlay color for image and hero treatments.
- Use for overlays on media-backed sections.

### `--enad-overlay-from-opacity`

- Stronger end of a gradient or layered overlay.
- Use to control readability where text sits on top of media.

### `--enad-overlay-to-opacity`

- Softer end of a gradient or layered overlay.
- Use to keep media visible while still shaping readability.

## Generated motion tokens

### `--delight-duration`

- Shared transition duration for delight-driven interactions.
- Use to keep motion tempo consistent across hover, active, and focus states.

### `--delight-easing`

- Shared easing curve for delight-driven interactions.
- Use to keep interaction timing stylistically coherent.

### `--delight-hover-transform`

- Hover transform pattern.
- Use for subtle lift, scale, or translation behavior on interactive surfaces.

### `--delight-hover-shadow`

- Hover-state shadow pattern.
- Use alongside hover transforms when elevation should increase on interaction.

### `--delight-active-transform`

- Active or pressed-state transform.
- Use for tactile press feedback.

### `--delight-focus-shadow`

- Focus-state shadow treatment.
- Use when the focus style includes more than a plain ring.

## Data and sidebar compatibility tokens

### `--chart-1` through `--chart-5`

- Ordered chart-series palette slots.
- Use for data visualization series, not for general CTA or surface styling.
- Keep them visually distinct from one another before making them brand-expressive.

### `--sidebar`, `--sidebar-foreground`

- Dedicated sidebar surface and content colors.
- Use when the UI includes a true sidebar or navigation rail with its own contrast needs.
- Do not treat these as a replacement for global page tokens.

### `--sidebar-primary`, `--sidebar-primary-foreground`

- Primary action color pair inside sidebar contexts.
- Use for the strongest sidebar-local emphasis.

### `--sidebar-accent`, `--sidebar-accent-foreground`

- Supportive highlight pair inside sidebar contexts.
- Use for selected rows or supportive emphasis within the sidebar surface.

### `--sidebar-border`

- Divider and outline color inside sidebar contexts.

### `--sidebar-ring`

- Focus ring color inside sidebar contexts.

## Common token choices

When deciding between nearby tokens:

- use `--background` for the canvas and `--card` for contained surfaces
- use `--primary` for the main action and `--accent` for supporting emphasis
- use `--secondary` for quieter actions and `--muted` for low-emphasis surfaces
- use `--border` for resting structure and `--ring` for focus/active emphasis
- use `--input` when the question is specifically about form-control chrome
- use `--accent-muted` when `--muted` is too neutral and `--accent` is too loud

## Answer shape

When answering a token question:

1. name the token's UI role in one sentence
2. name the most common place it should be used
3. name the closest token it is often confused with
4. say what to use instead if the proposed use is semantically wrong

## Reference: references/runtime-theming.md

# Runtime Theming

Use this reference when the question is about applying Enad theme state in a running app.

## Core rule

Use `EnadProvider` for the SDK runtime. Add `EnadThemeProvider` around the part of the tree that should receive a component set or runtime token overrides.

```tsx
import { EnadProvider } from "@enadhq/enad-react-sdk";
import { EnadThemeProvider } from "@enadhq/enad-react-sdk/client/theme";

export function AppShell({ children }: { children: React.ReactNode }) {
  return (
    <EnadProvider>
      <EnadThemeProvider componentSet="editorial">{children}</EnadThemeProvider>
    </EnadProvider>
  );
}
```

## What each provider owns

- `EnadProvider` owns SDK-wide runtime setup such as React Query, icon registration, locale, component resolver wiring, and Search GraphQL client setup when `clientConfig` is present.
- `EnadThemeProvider` owns runtime component-set selection, scoped token CSS from a hash, and direct token overrides.

If the question turns from provider ownership into semantic icon slots, adapter choice, `Icon`, `useIcon`, or `createIconifyIcons()`, hand off to `enad-sdk-icons`.

## Runtime precedence

Use this order when explaining or debugging runtime theme behavior:

1. explicit `EnadThemeProvider` props
2. decoded hash values
3. SDK defaults

Practical rule:

- `componentSet` prop wins over `componentSet` inside the hash
- `tokens` prop wins over decoded token values from the hash
- if neither is present, the runtime falls back to the default component set and default tokens

## Structural vs token changes

- `componentSet` changes the structural language of the UI through `data-component-set`
- runtime token values change CSS variables for colors, radii, typography, and related theme tokens

Keep those two ideas separate. A component set is not just a color preset.

## Answer shape

If the app also needs Search GraphQL hooks such as `useEnadGraphQLQuery()` or `useEnadGraphQLQueryContext()`, keep that inside the same `EnadProvider` root by passing shopper-facing `clientConfig`.

1. State whether the app needs only root setup or root setup plus runtime theming.
2. Name which provider owns which concern.
3. State the precedence rule if both hash and explicit props are involved.
4. Show the smallest public example.

## Reference: references/theme-tooling.md

# Theme Tooling

Use this reference when the question is about hashes, generated CSS, or CLI behavior.

## Theme hash helpers

Use these from `@enadhq/enad-react-sdk/client/theme`:

- `encodeThemeHash`
- `decodeThemeHash`
- `generateThemeCSS`
- `SDK_DEFAULTS`

Typical roles:

- `encodeThemeHash` builds a compact shareable theme payload
- `decodeThemeHash` restores that payload into runtime theme data
- `generateThemeCSS` turns theme data into CSS variable blocks

## CLI role

`enad-theme` is the CSS-generation helper. It does not replace `EnadThemeProvider`.

Use the CLI when you want to write a theme block into a stylesheet:

```bash
enad-theme apply <hash> --target app/globals.css
```

Use `--component-set <name>` when you want the generated CSS to record the intended structural set alongside the token CSS.

## Practical boundary

- CLI output is good for generated CSS blocks
- `EnadThemeProvider` handles scoped runtime theme restoration and set switching

If the user asks which one should own runtime behavior, use the provider.

## Answer shape

1. Name the helper or CLI command.
2. State whether it generates CSS or applies runtime behavior.
3. Point back to `EnadThemeProvider` when the question crosses into runtime state.

## Reference: references/playground-flow.md

# Playground Flow

Use this reference when the question is about the theme-playground export and share flow.

## Share URL rule

The theme-playground share URL carries both:

- token state
- `componentSet`

That means a copied playground URL can restore the same structural set and token overrides in a consumer app.

## Consumer setup flow

1. choose a component set and token state in the playground
2. copy the share URL or exported setup snippet
3. keep `EnadProvider` at the app root
4. add `icons={...}` on `EnadProvider` as well when the playground export uses a non-default icon adapter or Iconify slot overrides
5. wrap the target subtree with `EnadThemeProvider`
6. pass `componentSet`, `hash`, or `tokens` based on the setup you want

## Export snippet guidance

The exported snippet should show:

- `EnadProvider` at the app shell level
- `const themeHash = "..."` plus `EnadThemeProvider hash={themeHash}` when the current playground state has non-default runtime theme data
- `EnadThemeProvider componentSet="..."` only when the setup is structural-set only and there is no richer hash state to restore

## Debugging rule

If a shared playground URL does not restore the same look in an app, check these in order:

1. was the same `hash` passed through?
2. did an explicit `componentSet` prop override the hash value?
3. are explicit `tokens` overriding decoded values?
4. is the SDK stylesheet imported so component-set selectors exist?

## Answer shape

1. State what the playground exports.
2. Explain how that maps into `EnadProvider` plus `EnadThemeProvider`.
3. Name the first debugging step if the restored app does not match the playground.
4. Hand off to `enad-sdk-icons` when the missing piece is really icon-slot mapping rather than runtime theme state.

---

# Enad SDK Icons

Explain Enad SDK semantic icon slots, icon adapters, Icon, useIcon, custom IconSlotMap setup, and Iconify-backed slot overrides.

# Enad SDK Icons

Use this guide when the request is about semantic icon slots, icon-adapter setup, or how icon configuration moves from the SDK and theme-playground into consumer app code.

Start with [semantic slots and provider ownership](references/semantic-slots-and-provider-ownership.md) when the question is about `EnadProvider`, `IconSlotMap`, `Icon`, or `useIcon`. Use [adapter selection and fallbacks](references/adapter-selection-and-fallbacks.md) when the question is about shipped adapters, slot overrides, or when to supply a full custom map. Use [Iconify workflow](references/iconify-workflow.md) when the question is about `createIconifyIcons()`, `prefix:name` values, the Icones lookup format, or partial slot mapping from the playground.

## Responsibilities

1. Explain the semantic slot model instead of talking in library-specific icon imports.
2. Clarify what `EnadProvider` owns versus what `Icon` and `useIcon()` consume.
3. Recommend the right adapter path: curated adapter, adapter with overrides, `createIconifyIcons()`, or a full custom `IconSlotMap`.
4. Explain fallback behavior clearly when only some slots are remapped.
5. Hand off to `enad-sdk-theme` when the dominant question is really about component sets, theme hashes, or runtime token precedence.

## What this guide owns

Use this guide for prompts such as:

- `How do semantic icons work in the Enad SDK?`
- `Should I use Icon or useIcon?`
- `How do I swap Enad to Lucide or Carbon icons?`
- `How should I use createIconifyIcons if I only want to remap a few slots?`
- `When should I provide a full IconSlotMap instead of using an adapter helper?`

## What this guide does not own

Do not stay in this guide when the user is really asking:

- how `EnadThemeProvider` restores a shared hash
- how component sets differ from token overrides
- how a shell, layout, or storefront composition should work
- how cart, price, or Search behavior should work

Those questions belong to `enad-sdk-theme`, `enad-sdk-layout`, `enad-sdk-storefront`, `enad-sdk-commerce`, or `enad-sdk-search`.

## Rules

- Treat semantic slot names as the public icon API.
- Keep examples on the public import surface: `@enadhq/enad-react-sdk` and `@enadhq/enad-react-sdk/client/icons`.
- Recommend curated adapters first when the whole app should use one family.
- Recommend `createIconifyIcons({ names })` when the app only needs to remap selected slots.
- State the fallback rule explicitly: unmapped slots use the fallback map, which defaults to Phosphor.
- Recommend a full `IconSlotMap` only when the consumer truly owns the whole icon system.

## Reference: references/semantic-slots-and-provider-ownership.md

# Semantic Slots and Provider Ownership

Use this reference when the question is about how the Enad SDK icon layer is structured.

## Core rule

The public icon API is the **semantic slot name**, not a library-specific icon import.

Think in slots such as:

- `search`
- `cart`
- `chevronDown`
- `heartFilled`
- `truck`

SDK components request those slots. `EnadProvider` supplies the active `IconSlotMap` for the tree.

## What each piece owns

- `EnadProvider` receives the active icon map through the `icons` prop and makes it available to SDK and app code.
- `IconSlotMap` is the complete semantic contract for all supported slots.
- `Icon` renders one resolved slot directly.
- `useIcon()` returns the resolved icon component when a custom component needs to compose with it.

If the app does not pass `icons`, `EnadProvider` falls back to `phosphorIcons`.

## Public usage shapes

Use `Icon` for direct rendering:

```tsx
import { Icon } from "@enadhq/enad-react-sdk/client/icons";

<Icon name="search" className="size-4" aria-hidden />;
```

Use `useIcon()` for composition:

```tsx
import { useIcon } from "@enadhq/enad-react-sdk/client/icons";

function SearchButton() {
  const SearchIcon = useIcon("search");
  return <SearchIcon className="size-4" aria-hidden />;
}
```

## Answer shape

1. Name the semantic slot model first.
2. State that `EnadProvider` owns the active icon map.
3. Recommend `Icon` or `useIcon()` based on whether the user needs direct rendering or composition.
4. State the default fallback to `phosphorIcons` when relevant.

## Reference: references/adapter-selection-and-fallbacks.md

# Adapter Selection and Fallbacks

Use this reference when the question is about how an app should choose or customize an icon family.

## Shipped adapter choices

The SDK ships curated adapters for:

- `phosphorIcons`
- `lucideIcons`
- `hugeIcons`
- `carbonIcons`

Use a curated adapter when the whole app should move to one icon family with minimal setup.

```tsx
import { EnadProvider } from "@enadhq/enad-react-sdk";
import { lucideIcons } from "@enadhq/enad-react-sdk/client/icons";

<EnadProvider icons={lucideIcons}>{children}</EnadProvider>;
```

## When to use overrides

Use adapter `overrides` when one family is almost right and only a few slots need to change.

That keeps the app on a curated base map while swapping individual slots locally.

## When to use Iconify names

Use `createIconifyIcons({ names })` when the app wants to keep Enad semantic slots but source selected icons from Iconify.

This is the right choice for:

- partial remaps
- custom brand accents on a few slots
- playground-exported Iconify setup

## When to use a full custom IconSlotMap

Use a full custom `IconSlotMap` only when the product owns the complete icon system and does not want adapter defaults.

That path means the app is responsible for every slot in the contract.

## Fallback rule

State this explicitly whenever partial mappings are discussed:

- unmapped slots use the fallback map
- the default fallback map is Phosphor
- consumers may pass another fallback map if they do not want Phosphor as the base

## Answer shape

1. Recommend the smallest ownership level that solves the problem.
2. Name the fallback rule explicitly.
3. Only recommend a full custom map when the user truly needs full ownership.

## Reference: references/iconify-workflow.md

# Iconify Workflow

Use this reference when the question is about `createIconifyIcons()` or the theme-playground's custom Iconify flow.

## Core rule

`createIconifyIcons()` maps **semantic Enad slots** to **Iconify names**.

The values use the standard `prefix:name` format, such as:

- `mdi-light:magnify`
- `mdi-light:cart`
- `solar:heart-bold`

The playground points users at Icones because Icones exposes the same Iconify naming format.

## Partial mapping pattern

Use this public pattern:

```tsx
import { EnadProvider } from "@enadhq/enad-react-sdk";
import { createIconifyIcons } from "@enadhq/enad-react-sdk/client/icons";

const icons = createIconifyIcons({
  names: {
    search: "mdi-light:magnify",
    cart: "mdi-light:cart",
    heartFilled: "solar:heart-bold",
  },
});

<EnadProvider icons={icons}>{children}</EnadProvider>;
```

## Fallback behavior

Any slot that is not listed in `names` still resolves through the fallback map.

Default behavior:

- fallback map = Phosphor
- partial mappings are safe
- the app does not need to define every slot just to replace a few

## Playground export rule

When the playground uses `Custom (Iconify)`, the exported setup should keep:

- `EnadProvider` at the root
- `const icons = createIconifyIcons({ names: { ... } })`
- explicit mappings in app code
- `EnadThemeProvider` only for the runtime theme layer

If the prompt becomes about restoring hash state or component-set precedence, hand off to `enad-sdk-theme` after the icon mapping piece is clear.

## Answer shape

1. State that the mapping starts from semantic slots, not raw icon imports.
2. Mention the `prefix:name` format.
3. Show a partial mapping example.
4. State the fallback rule explicitly.
5. Hand off to theme only when the question turns into runtime theme ownership.

---

# Enad SDK Layout

Explain Enad layout shells, navigation chrome, and page-structure choices. Use when a request is about HeaderSection, StoreHeader-family navigation, Header, Footer, PromotionBar, MobileMenuDrawer, or how storefront shell pieces fit together across a page.

# Enad SDK Layout

Use this skill when the request is already about shells, navigation chrome, or page structure.

Start with [navigation and chrome](references/navigation-and-chrome.md) when the question is about HeaderSection, StoreHeader-family navigation, Header, PromotionBar, MobileMenuDrawer, or Footer. Use [page structure](references/page-structure.md) when the question is about how those shell pieces frame the rest of the page.

## Responsibilities

1. Explain how the layout shell pieces fit together in the current Enad docs.
2. Keep the guidance on page framing, fixed-header behavior, and shell ownership.
3. Tell the user when the opinionated layout components fit and when a custom shell is the better call.
4. Route to `enad-sdk-discovery` when the user is still choosing a component family or import path.
5. Route to `enad-sdk-compound-composition` when the question turns into public child parts, slot boundaries, or `Dialog` and `Sheet` composition.

## What this skill owns

Use this skill for prompts such as:

- `How should I structure HeaderSection, promotion bar, and mobile navigation in Enad?`
- `When should I use HeaderSection versus StoreHeader and the lower-level nav family?`
- `How do Header and Footer frame a storefront page?`
- `When should I use MobileMenuDrawer directly instead of relying on Header or MobileNav?`
- `How should a hero page interact with the transparent header variant?`
- `How do I keep layout chrome clear without mixing in product-flow logic?`

## What this skill does not own

Do not stay in this skill when the user is really asking:

- which component they should choose in the first place
- what public import path to copy
- how `SheetContent`, `DialogHeader`, or other child parts compose
- how price, variant selection, cart, filters, or recommendations fit together
- how editorial blocks or gallery rows should be merchandised

Those questions belong to `enad-sdk-discovery`, `enad-sdk-compound-composition`, `enad-sdk-commerce`, or `enad-sdk-storefront`.

## Rules

- Keep the answer grounded in the current layout docs.
- Treat `Header` and `Footer` as opinionated shells, not low-level primitives.
- Keep shell guidance at the page level. Do not drift into product, search, or cart flow details.
- Mention accessibility and interaction behavior where the current docs already name it.
- If the prompt becomes a component-choice question, hand off to `enad-sdk-discovery`.
- If the prompt becomes a public-part composition question, hand off to `enad-sdk-compound-composition`.

## Reference: references/navigation-and-chrome.md

# Navigation and Chrome

Use this reference when the question is about the storefront shell pieces themselves.

## Fast routing table

| User signal                                                                                                                               | Use                                                           | Why                                                                                                                        | Use another guide when                                                       |
| ----------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------- |
| Full site header with primary nav, utility links, search or cart actions, promotion-aware chrome, and optional desktop mega-menu behavior | `HeaderSection`                                               | It is the new fast public path for storefront navigation and maps cleanly to the public header family                      | The user wants lower-level shell composition or is still choosing primitives |
| Lower-level storefront header shell with explicit family zones                                                                             | `StoreHeader` with `UtilityNav`, `PrimaryNav`, `MegaMenu`, `MobileNav` | It gives the app lower-level composition control while staying inside the supported navigation family                      | The prompt is really still about which component to choose first             |
| Thin announcement strip above the header                                                                                                  | `PromotionBar`, usually through `HeaderSection` or `StoreHeader` | It handles a rotating and optional dismissible notice strip                                                                | The user needs shell persistence strategy or a component comparison          |
| Two-level mobile navigation drawer or the mobile branch of the header family                                                              | `MobileNav` or `MobileMenuDrawer` depending on level          | `MobileNav` is the family-level answer; `MobileMenuDrawer` remains the lower-level controlled drawer surface               | The prompt turns into `Sheet` part composition or slot structure             |
| Closing shell with link columns, newsletter content, legal links, and payment signals                                                     | `Footer`                                                      | It handles the closing shell with predictable navigation and support content                                               | The user is really choosing storefront content blocks inside the page body   |
| A shell that does not match the section-first header shape                                                                                | Compose a custom shell around the public header family first   | `HeaderSection` is the fast path, but the public family exists for lower-level variation before dropping to one-off shells | The user needs help picking those lower-level pieces first                   |

## Enad shell rules

- Prefer `HeaderSection` when you want the full top shell quickly. It is now the default fast path for storefront navigation.
- Use `StoreHeader` with `UtilityNav`, `PrimaryNav`, `MegaMenu`, and `MobileNav` when the shell itself needs lower-level composition control.
- Use the `Header` composition shell when you intentionally want the older lower-level surface or need direct child-slot control that is still easier to express there.
- Use the featured region override seam on `HeaderSection` before abandoning the section entirely.
- Use `PromotionBar` directly only when it must live outside the standard header section or family shell. Dismiss is local unless the page shell persists it.
- Use `MobileNav` when the app is composing the family directly. Use `MobileMenuDrawer` directly only when you are building a custom header below the family layer.
- Use `Footer` when the page needs closing navigation, newsletter content, or trust signals in one predictable grid.

## Interaction and access notes

- `Header` is fixed by default. The page shell needs top padding or a spacer below it.
- Transparent header is for hero-led pages. Solid header is the safer default for ordinary content and catalog pages.
- The desktop mega-menu panel should collapse when focus moves to non-owning links or when a destination inside the panel is activated.
- Promotion controls need to stay keyboard reachable.
- Mobile drawer flows should close on Escape and return focus to the opener.
- Keep shell motion quiet. Do not pile extra carousel or animation-heavy behavior into always-present chrome.

## Answer shape

1. Name the shell piece first.
2. Cite the deciding behavior from the current docs.
3. State what the shell owns so the page stays coherent.
4. Hand off if the question becomes component choice or child-part composition.

## Reference: references/page-structure.md

# Page Structure

Use this reference when the question is about how layout pieces frame the rest of the page.

## Page-shell workflow

1. Choose the opening shell: `HeaderSection` is the default top frame for storefront pages.
2. Drop to `StoreHeader` and the lower-level navigation family when the shell itself needs more control.
3. Decide whether the page is hero-led or content-led.
4. Leave editorial blocks and galleries inside the main content area.
5. Leave buying flows, filters, cart, and recommendations to commerce surfaces.
6. Close the page with `Footer` when the page needs support navigation, newsletter content, or trust signals.

## Common page shapes

| Page shape                                                | Pattern                                                                                                    | Why                                                                                  | Follow-up path                                                                 |
| --------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------ |
| Hero-led landing page                                     | Transparent `HeaderSection` over `Hero`, then the page settles into the normal content rhythm                           | The shell can overlay the hero while the hero content itself stays composition-first                         | Use `enad-sdk-storefront` for the Hero and follow-on content blocks            |
| Standard catalog or editorial page                        | Solid `HeaderSection`, main content below the fixed chrome, optional `Footer` at the end                                | The shell stays predictable and the fixed header does not compete with the content                           | Use `enad-sdk-storefront` or `enad-sdk-commerce` for the body modules          |
| Page with lightweight shortcut navigation inside the body | `HeaderSection` plus normal page shell, then use body-level navigation such as storefront shortcuts inside `main`       | Body navigation is not the same thing as site chrome                                                         | Use `enad-sdk-storefront` for the shortcut blocks                              |
| Custom shell anatomy or explicit family-level composition | `StoreHeader` plus the public navigation family, then normal page structure                                               | The app still stays inside the supported family before dropping to one-off shell composition                 | Use `enad-sdk-compound-composition` when the question turns into family parts   |
| Custom navigation overlay or utility drawer choice        | Stop at the shell boundary and pick the right lower-level primitive or family surface first                              | Layout should not guess between `MobileNav`, `MobileMenuDrawer`, `Dialog`, `Sheet`, or other building blocks | Use `enad-sdk-discovery` first, then `enad-sdk-compound-composition` if needed |

## Layout boundaries

- Keep `Header` and `Footer` focused on shell framing.
- Keep editorial story blocks, galleries, and linked tiles in storefront.
- Keep price, selection, search, filters, cart, and recommendation behavior in commerce.
- If the question is really about how public child parts fit together, move to `enad-sdk-compound-composition`.

## Practical notes

- `HeaderSection` is the recommended section-first opening shell for most storefront pages.
- `StoreHeader`, `Header`, `Hero`, and `Footer` remain composition-first shells or family surfaces. Reach for public child slots and public family parts before asking a root component for more props.
- Fixed chrome means the main content has to respect header height.
- If the page uses a desktop mega-menu, collapse the header panel once a destination is chosen so the fixed shell does not linger over the page content.
- Landmark structure and skip links matter more when the header stays fixed across the whole session.

## Answer shape

1. State the shell pattern.
2. Say which page layer owns the next concern.
3. Keep the layout answer at the page level.
4. Hand off when the next question belongs to storefront, commerce, discovery, or compound composition.

---

# Enad SDK Storefront

Explain Enad storefront content blocks, gallery systems, merchandising display patterns, and Media API usage for storefront image surfaces. Use when a request is about Hero, LinkBlock, ImageBlock, QuickLinks, Gallery, GalleryWithLinkBlocks, ProductCard, ProductImage, or how storefront image URLs and display pieces fit together.

# Enad SDK Storefront

Use this skill when the request is about editorial content blocks, galleries, or merchandising display patterns.

Start with [content blocks](references/content-blocks.md) when the question is about section openers, destination tiles, supporting imagery, or editorial copy blocks. Use [gallery and card systems](references/gallery-and-card-systems.md) when the question is about rows, wrappers, product-card usage, or media systems.

## Responsibilities

1. Explain which storefront block or wrapper fits the current editorial or merchandising shape.
2. Keep the guidance on section rhythm, gallery choice, product-card display behavior, and storefront image rules.
3. Explain how storefront image URLs should use Enad Media API transforms for repeated card, thumbnail, and gallery contexts.
4. Route to `enad-sdk-discovery` when the user is still choosing a component family or import path.
5. Route to `enad-sdk-compound-composition` when the question turns into public child parts or slot boundaries.
6. Route to `enad-sdk-commerce` when price, variant state, add-to-cart behavior, search, filters, or recommendations become central.

## What this skill owns

Use this skill for prompts such as:

- `What is the best Enad pattern for a hero followed by linked editorial tiles and a gallery row?`
- `Should this section use Hero, LinkBlock, or ImageBlock?`
- `When should I use GalleryWithLinkBlocks instead of Gallery?`
- `How should ProductCard fit into a merchandised row?`
- `How do I keep one visual language across a storefront section?`
- `How should I size Enad media URLs for PLP cards, thumbnails, or PDP galleries?`
- `Should I use raw media.enad.io URLs or transformed media URLs in storefront cards?`
- `How should ProductCard and ProductImage think about image transforms and image loading?`

## What this skill does not own

Do not stay in this skill when the user is really asking:

- which component they should choose in the first place from a broad comparison set
- what public import path to use
- how public child parts compose inside a compound primitive
- how price, variant selection, cart, filters, search, or recommendations should work together

Those questions belong to `enad-sdk-discovery`, `enad-sdk-compound-composition`, or `enad-sdk-commerce`.

## Rules

- Ground every answer in the current storefront docs.
- Prefer the documented block roles over generic merchandising language.
- Keep one visual language per row or section.
- Treat `ProductCard` as a display primitive. Do not turn it into the whole product model.
- For repeated storefront image surfaces, prefer transformed Enad media URLs over raw originals.
- If buying behavior becomes central, move to `enad-sdk-commerce`.
- If the prompt starts as component choice or import-path selection, move to `enad-sdk-discovery`.

## Reference: references/content-blocks.md

# Content Blocks

Use this reference when the question is about section-level editorial or merchandising blocks.

## Fast routing table

| User signal                                                                 | Use                  | Why                                                                            | Use another guide when                                                           |
| --------------------------------------------------------------------------- | -------------------- | ------------------------------------------------------------------------------ | -------------------------------------------------------------------------------- |
| Opening a campaign, collection, or brand story section                      | `Hero`               | It handles the main opener and supports branded layout tuning                  | The user is still deciding between component families or asking for import paths |
| Building a promotional destination tile with image, title, and CTA          | `LinkBlock`          | It handles a clickable destination tile with more weight than a plain link     | The user only needs compact shortcut navigation                                  |
| Showing a standalone supporting image with optional caption                 | `ImageBlock`         | It handles simple visual support with figure-caption behavior                  | The section needs overlaid text, CTA, or side-by-side story composition          |
| Pairing editorial copy with a supporting gallery and optional product cards | `ContentWithGallery` | It handles a story-plus-gallery section where copy and imagery share the stage | Product state and buying flow matter more than the section shape                 |
| Offering fast grouped shortcut navigation                                   | `QuickLinks`         | It handles compact grouped wayfinding with pill or card treatment              | The section needs richer destination tiles or a full gallery row                 |

## Block rules

- Use `Hero` when the section needs to set the page tone. Pick the layout by content priority, not by habit.
- For branded redesigns, map the active layout matrix through `Hero` presets, split controls, `actions`, and `classNames` before reaching for a local fork.
- Use `LinkBlock` when the destination is the point. Overlay, card, and text-only variants change the weight, not the job.
- When storefront blocks expose semantic `classNames` hooks, recommend those before local forks. They are the supported way to create wildly different branded implementations while keeping shared behavior intact.
- Use `ImageBlock` for pure media support. No CTA, no text overlay, no extra narrative layer.
- Use `ContentWithGallery` when the story and the visuals need equal weight in one composed section.
- Use `QuickLinks` when speed and grouping matter more than editorial drama. Pills are denser. Cards carry more imagery.

## Interaction and access notes

- `Hero` overlay layouts need readable contrast over the image.
- If a branded Hero needs more tuning, use `contentInset`, `contentWidth`, `splitRatio`, `actions`, and `classNames` before building a local version.
- `LinkBlock` makes the whole surface clickable, so the destination and focus treatment must stay clear.
- `ImageBlock` depends on meaningful alt text and optional caption text for context.
- `QuickLinks` should keep labels short so the set stays scannable across breakpoints.

## Shared boundaries

- If the question starts as `which component should I use`, hand off to `enad-sdk-discovery`.
- If the question adds price, variant state, cart actions, filters, search, or recommendation logic, hand off to `enad-sdk-commerce`.
- If the question becomes about public child parts or slot boundaries, hand off to `enad-sdk-compound-composition`.

## Answer shape

1. Name the block.
2. Quote the deciding signal from the docs in plain language.
3. Name the nearby alternative and why it loses.
4. Hand off if the next concern belongs to discovery, compound composition, or commerce.

## Reference: references/gallery-and-card-systems.md

# Gallery and Card Systems

Use this reference when the question is about wrappers, rows, cards, product-media display, or how Enad Media API URLs should be used for storefront image surfaces.

## Fast routing table

| User signal                                                           | Use                     | Why                                                                           | Use another guide when                                                      |
| --------------------------------------------------------------------- | ----------------------- | ----------------------------------------------------------------------------- | --------------------------------------------------------------------------- |
| Several visual children need one heading and one layout rhythm        | `Gallery`               | It handles a free-form wrapper for image, block, or product children          | The row is really a destination-first strip of linked tiles                 |
| Every child is mainly a linked destination tile                       | `GalleryWithLinkBlocks` | It handles a row built around `LinkBlock`-style browsing                      | The row mixes several child shapes or stops being destination-led           |
| Repeatable product scan items in grids, search, or merchandising rows | `ProductCard`           | It handles standard product display for image, name, and price                | The question becomes about selection, add-to-cart, or other buying behavior |
| Product detail media gallery or variant-linked imagery                | `ProductImage`          | It handles PDP media with thumbnails, lightbox viewing, and variant awareness | The question becomes about variant resolution, buy-box state, or cart flow  |

## Enad row rules

- Keep one visual language per gallery row. Mixing too many card shapes makes the section noisy.
- Use `Gallery` when the wrapper owns the section rhythm and the children stay flexible.
- Use `GalleryWithLinkBlocks` when the point is destination-first browsing.
- Use `ProductCard` when shoppers need a fast scan of image, name, and price. Pick the layout by scan behavior, not just taste.
- Use `ProductImage` when the page needs high-importance product media browsing rather than a simple merch card.

## ProductImage rules

- Treat `ProductImage` as the PDP media owner, not as a generic image carousel.
- The default interaction is lightbox-first. Use `interaction="none"` only when the gallery should stay inline.
- Use `activeIndex`, `defaultActiveIndex`, and `onActiveIndexChange` when the inline gallery and fullscreen viewer need shared state.
- Use `lightboxOpen`, `defaultLightboxOpen`, and `onLightboxOpenChange` when the page wants to control the fullscreen viewer explicitly.
- Use `showThumbnails`, `thumbnailPosition`, and `maxThumbnails` to shape the navigation rail without letting it dominate the layout.
- When the page needs branded thumbnail treatment, use the semantic `classNames` hooks on `ProductImage` for the rail, buttons, active state, and overflow indicator before recommending aria-label selectors or a local gallery fork.
- Give images stable `id` values when the host app wants shared-element continuity into the fullscreen viewer.

## Practical notes

- `Gallery` variants (`grid`, `masonry`, `filmstrip`) change the layout rhythm. Start with the default grid when the row needs balance.
- `ProductCard` layout selection belongs to the surface: `gallery` for standard grids, `horizontal` for tighter drawers and search rows, denser layouts when scan density matters.
- Inside recommendation rails, `ProductCard imageBehavior="auto"` stays on a single image so the outer rail remains the only carousel.
- `ProductImage` can follow axis-level variant state or resolved variant ids. That media behavior is storefront display, but the buying flow around it belongs to commerce.
- Use `activeVariant` when the page works with simple selector values such as `"oak"` or `"black"`.
- Use `activeVariantId` when the page has already resolved a concrete purchasable variant such as `"sku-oak-001"`.
- If both are present, `ProductImage` should follow `activeVariantId` first.
- `ProductImage` uses `ImageLightbox` for fullscreen viewing, and the fullscreen state should feel like part of the same PDP media object.

## Enad Media API rules for storefront surfaces

- For repeated storefront surfaces such as PLP cards, recommendation rails, and thumbnail strips, use transformed Enad media URLs rather than raw `media.enad.io` originals.
- For PLP cards, start with a transformed URL sized for the card surface, for example `width=720`, `quality=72`, `format=webp`, and `fit=contain` when full-product visibility matters.
- For thumbnails and small previews, use a smaller transformed width such as `160-320` and choose `cover` only when the grid should crop consistently.
- For PDP galleries, use a larger transformed width such as `1200-1600`, matched to the rendered gallery surface rather than the raw original.
- Use `contain` when the product should stay fully visible inside the frame. Use `cover` when the layout expects edge-to-edge crop behavior.
- Do not treat raw originals as the default storefront path. Raw originals are easy to ship accidentally and make listing pages heavier than they need to be.
- Image transforms and mounting strategy belong together. On repeated card surfaces, prefer a transformed active image first rather than mounting several gallery images up front.

## Answer pattern for media questions

1. Name the storefront surface, such as PLP card, thumbnail, or PDP gallery.
2. Give a starting transform recommendation with width, quality, format, and fit.
3. Explain whether the display should preserve the whole product with `contain` or crop with `cover`.
4. Mention when card or gallery loading behavior should stay single-image first.
5. Hand off to commerce only if the question turns into buying-flow behavior.

## Shared boundaries

- If the prompt starts with broad component choice or import-path selection, hand off to `enad-sdk-discovery`.
- If the prompt becomes about filters, search, recommendations, price, variant selection, or add-to-cart flow, hand off to `enad-sdk-commerce`.
- If the prompt becomes about public child parts, hand off to `enad-sdk-compound-composition`.

## Answer shape

1. Name the wrapper or display primitive.
2. Explain the row shape or media role it fits.
3. State the boundary where storefront display stops.
4. Hand off when the next concern belongs to commerce, discovery, or compound composition.

---

# Enad SDK Search

Explain Enad Search GraphQL, GraphiQL, app-scoped context, category and collection targeting, facets, autocomplete, and sandbox Search-backed live-data behavior. Use when a request is about Search API semantics rather than shopper-facing commerce UI.

# Enad SDK Search

Use this skill when the request is about Search GraphQL, app-scoped search context, GraphiQL, query shape, category or collection targeting, facets, autocomplete, or Search-backed sandbox behavior.

Start with [Search endpoints and context](references/graphql-endpoints-and-context.md) when the question is about where Search lives, how requests should be scoped, or how to work in GraphiQL. Use [query patterns and targeting](references/query-patterns-and-targeting.md) when the question is about which Search operation to use or how to shape filters and sort rules. Use [sandbox Search-backed behavior](references/sandbox-live-data-behavior.md) when the question is about the theme playground's live-data resolution rules.

## Responsibilities

1. Explain the Search GraphQL surface without mixing it with shopper-facing UI behavior.
2. Keep app, market, store-group, and locale context explicit.
3. Explain which Search operations match which storefront job.
4. Clarify category and collection targeting semantics.
5. Prefer the Enad React SDK's provider-backed Search GraphQL surface when the question is about React usage, including typed query factories, typed query hooks, `useSearch`, and autocomplete hooks.
6. Hand off to `enad-sdk-commerce` when the question turns into shopper-facing search, filter, recommendation, PDP, or PLP behavior.

## What this skill owns

Use this skill for prompts such as:

- `How do I call Enad Search GraphQL for a product grid?`
- `How should I use GraphiQL against an Enad app?`
- `Which Search query should I use for PDP lookup by slug or SKU?`
- `How should categoryUrls and collectionUris be used in ProductFilter?`
- `How does the sandbox choose products when no selector is configured?`

## What this skill does not own

Do not stay in this skill when the user is really asking:

- how `SearchBar`, `SearchAutocomplete`, `FilterPanel`, or `ProductRecommendations` should behave for shoppers
- how cart, pricing, quick view, or quantity fit into buying flows
- which Enad component to choose from a broad comparison set
- how an editorial or merch row should look visually

Those questions belong to `enad-sdk-commerce`, `enad-sdk-discovery`, or `enad-sdk-storefront`.

## Rules

- Keep Search guidance app-scoped and context-explicit.
- Prefer direct Search GraphQL guidance over pretending `@enadhq/enad-ts-sdk` already wraps the Search API.
- When the question is React-SDK-specific, prefer the provider-backed GraphQL client, typed query factories, typed query hooks, and autocomplete hook exported from `@enadhq/enad-react-sdk/client/search`.
- Treat category and collection targeting as query-model guidance, not as shopper-UI guidance.
- Keep examples generic and reusable across Enad apps.
- If the question starts with shopper behavior or component choice, hand off to the owning domain instead of expanding this one.

## Reference: references/graphql-endpoints-and-context.md

# Search endpoints and context

Use this reference when the question is about how to talk to Enad Search at all.

## Base URL and endpoint shape

Enad Search is app-scoped.

Base URL pattern:

```text
https://graphql.enad.io/{appId}
```

GraphQL endpoint:

```text
https://graphql.enad.io/{appId}/graphql
```

GraphiQL endpoint:

```text
https://graphql.enad.io/{appId}/graphiql
```

If the question is about shopper-facing UI behavior, hand off to `enad-sdk-commerce`. This reference is about the Search surface itself.

## Context is part of the query contract

Most Search operations need all of these values:

- `appId`
- `marketSlug`
- `storeGroupSlug`
- `locale`

Treat them as required query context, not as optional decoration.

Practical rule:

- keep the same market, store group, and locale values in your GraphiQL repros that your app uses in production
- if a query behaves strangely, check context before changing the query shape

## Typical request helper

`@enadhq/enad-ts-sdk` does not currently expose a first-class Search GraphQL client.

In React apps that already use `EnadProvider`, prefer the built-in provider-backed pattern:

- pass shopper-facing `clientConfig` to `EnadProvider`
- use `useEnadGraphQLQueryContext()` to resolve `marketSlug`, `storeGroupSlug`, and `locale`
- use the typed query factories from `@enadhq/enad-react-sdk/client/search`
- use the typed query hooks from `@enadhq/enad-react-sdk/client/search` for common product, facets, collections, and completions queries
- use `useSearchAutocomplete()` when the question is specifically about typed Search completions in React
- use `useSearchFacets()` when the question is about UI-friendly normalized facet groups
- use `useProductSearchPage()` when the question is about a page-level React composition for products, facets, paging, and submit-driven search state
- use `useEnadGraphQLQuery()` or `useEnadGraphQLMutation()` for TanStack Query-backed GraphQL calls when you need a lower-level path
- rely on the package-local GraphQL Code Generator output for typed documents and variables

```tsx
import { gql } from "graphql-request";
import {
  useEnadGraphQLQuery,
  useEnadGraphQLQueryContext,
} from "@enadhq/enad-react-sdk/client/global";

const SearchProductsDocument = gql`
  query SearchProducts(
    $page: Int!
    $perPage: Int!
    $marketSlug: String!
    $storeGroupSlug: String!
    $locale: String!
    $search: String
  ) {
    v1Products(
      page: $page
      perPage: $perPage
      marketSlug: $marketSlug
      storeGroupSlug: $storeGroupSlug
      locale: $locale
      search: $search
    ) {
      products {
        id
        slug
        name
      }
    }
  }
`;

function ProductGrid() {
  const { marketSlug, storeGroupSlug, locale } = useEnadGraphQLQueryContext();

  return useEnadGraphQLQuery({
    operationName: "SearchProducts",
    document: SearchProductsDocument,
    variables: {
      page: 1,
      perPage: 24,
      marketSlug,
      storeGroupSlug,
      locale,
      search: "chair",
    },
  });
}
```

Outside that provider-backed React flow, call Search directly with `fetch`.

```ts
async function fetchSearchGraphQL<T>(
  baseUrl: string,
  query: string,
  variables?: Record<string, unknown>,
) {
  const response = await fetch(`${baseUrl}/graphql`, {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
    },
    body: JSON.stringify({ query, variables }),
  });

  if (!response.ok) {
    throw new Error(`Search request failed (${response.status})`);
  }

  const payload = (await response.json()) as {
    data?: T;
    errors?: { message: string }[];
  };

  if (payload.errors?.length) {
    throw new Error(payload.errors.map((error) => error.message).join("; "));
  }

  if (!payload.data) {
    throw new Error("Search response missing data");
  }

  return payload.data;
}
```

## GraphiQL workflow

Use GraphiQL when you need to confirm a query shape, test a filter, or verify field availability against one app.

Recommended flow:

1. Open the app-scoped GraphiQL URL.
2. Start with a small query and explicit context.
3. Add variables for `page`, `perPage`, `search`, or `filter` instead of hard-coding everything.
4. Mirror the same market, store group, and locale values your app uses.
5. Copy the stable query shape into application code only after the GraphiQL result matches the target storefront behavior.

## When to use Search directly vs the TypeScript SDK

Use Search GraphQL directly when you need:

- product grids and search-result pages
- PDP lookup by slug or SKU
- collection browsing
- autocomplete
- facets
- Search-aware sorting and filtering

Use the `EnadProvider` GraphQL helpers when you are already inside the Enad React SDK runtime and want TanStack Query-backed GraphQL requests without wiring a separate client.

Use the typed search factories and typed search hooks from `@enadhq/enad-react-sdk/client/search` when you want the SDK to own the common Search operation shapes for product search, PDP lookup, facets, collections, or autocomplete.

Use `@enadhq/enad-ts-sdk` when you need:

- existing REST catalog helpers already wrapped by `ShopperClient`
- non-Search flows the SDK already owns
- shared domain knowledge from the SDK without pretending it wraps Search GraphQL today

## Answer shape

1. Name the app-scoped Search endpoint.
2. State the required context.
3. Give the smallest useful request shape.
4. Point to GraphiQL when the user needs to verify fields or filters interactively.

## Reference: references/query-patterns-and-targeting.md

# Query patterns and targeting

Use this reference when the question is about which Search operation to use or how to shape Search filters.

## Fast operation table

| Need                                                                             | Use                   | Why                                                 |
| -------------------------------------------------------------------------------- | --------------------- | --------------------------------------------------- |
| Search results, PLP grids, category or collection listings, sorted product pages | `v1Products`          | Main product-grid and result-list query             |
| PDP lookup by slug                                                               | `v1ProductBySlug`     | Direct product lookup keyed by slug                 |
| PDP or integration lookup by SKU                                                 | `v1ProductBySku`      | Direct product lookup keyed by SKU                  |
| Filter metadata and counts                                                       | `v1Facets`            | Faceted navigation data for a current query context |
| Collection landing pages or collection pickers                                   | `v1Collections`       | Collection metadata and discovery                   |
| Predictive search suggestions                                                    | `v1SearchCompletions` | Autocomplete and quick suggestion data              |
| Route generation or prebuild slug fetches                                        | `v1ProductSlugs`      | Product slug inventory                              |

## Common Search query choices

### Product grids with `v1Products`

Use `v1Products` for:

- search result pages
- PLPs
- category or collection listings
- sorted product grids
- filter-aware catalog views

Keep `page`, `perPage`, `sortBy`, `search`, and `filter` explicit so the request stays debuggable.

### Product detail lookups

Use `v1ProductBySlug` when the route is slug-based.
Use `v1ProductBySku` when the selector or integration is SKU-based.

If the caller already has an exact slug or SKU, prefer direct lookup over issuing a broader discovery query.

### Facets with `v1Facets`

Use `v1Facets` for filter sidebars, counts, and price ranges.

Keep the same `filter`, `marketSlug`, `storeGroupSlug`, and `locale` context that drives the matching product-grid query. Facets and grid data should describe the same search state.

### Autocomplete with `v1SearchCompletions`

Use `v1SearchCompletions` for predictive search.

Keep autocomplete focused on quick pivots and likely matches. If the question turns into how a shopper-facing autocomplete should behave in the UI, hand off to `enad-sdk-commerce`.

## ProductFilter shape

`ProductFilter` is structured. Treat it as Search input, not as a loose query-string convention.

Common condition fields confirmed in current Enad usage include:

- `brandsSlug`
- `seriesSlug`
- `categoryUrls`
- `categoryIds`
- `collectionUris`
- `tagKeys`
- `attributeKeys`
- `priceGte`
- `priceLte`
- `inStock`
- `status`

Typical shape:

```ts
const filter = {
  all: [
    { conditions: { collectionUris: ["dining-room"] } },
    { conditions: { brandsSlug: ["enad-brand"] } },
    { conditions: { priceGte: 1000, priceLte: 10000 } },
  ],
};
```

## Category vs collection targeting

`categoryUrls` and `collectionUris` are not interchangeable names for the same field. They target different Search concepts.

Use:

- `categoryUrls` when the browse context is category-backed
- `collectionUris` when the browse context is collection-backed

If one app or picker surface uses one shared URI space and the same selected value may resolve to either concept, send the same URI to both fields in the same condition set.

Example:

```ts
const filter = {
  all: [
    {
      conditions: {
        categoryUrls: [selectedUri],
        collectionUris: [selectedUri],
      },
    },
  ],
};
```

Use that pattern deliberately. Do not apply it by default when you already know which concept owns the route.

## Sorting notes

Confirmed sort rules include:

- `RELEVANCY`
- `MOST_POPULAR`
- `NAME_ASC`
- `NAME_DESC`
- `PRICE_ASC`
- `PRICE_DESC`
- `CREATED_AT_DESC`
- `CATEGORY_ORDER_ASC`

Practical rules:

- keep sort selection explicit in Search code and GraphiQL repros
- some sort rules depend on the active market or store-group context
- category-order sorting can need category context to be meaningful

## Answer shape

1. Name the Search operation.
2. State why it fits the job.
3. Show the smallest useful filter or variable shape.
4. Clarify category vs collection semantics when that boundary matters.
5. Hand off to `enad-sdk-commerce` if the next question is about shopper-facing behavior instead of Search semantics.

## Reference: references/sandbox-live-data-behavior.md

# Sandbox Search-backed behavior

Use this reference when the question is about how the theme playground sandbox uses Enad Search after a live source is connected.

## Source configuration

The sandbox Source Panel uses four runtime values:

- `appId`
- `groupId` or store-group slug
- `market`
- `locale`

The sandbox builds the Search context directly from those values.

## Search requests in the sandbox

Once connected, the sandbox uses Search GraphQL for:

- product detail lookups
- product grids
- related products
- search results
- facets
- collections

Use this model when you explain sandbox data behavior:

- disconnected sandbox state uses mock data
- connected sandbox state uses Search data
- connected errors stay visible instead of switching back to mock data

## Product selection behavior

### Primary product and quick view

If no explicit selector is configured for the primary product, the sandbox picks the first usable Search product.

### Product grids and related products

If no explicit selectors are configured for a grid or related-product surface, the sandbox uses discovery products from `v1Products` sorted by `MOST_POPULAR`.

### Category-driven grids

If a category URI is selected and product selectors are blank, the sandbox sends that URI to both `categoryUrls` and `collectionUris` in the same filter condition.

Use that pattern when one selected URI may map to either category-backed or collection-backed catalog structure.

### Explicit selectors

If explicit slug or SKU selectors are present, the sandbox uses them before category-driven or discovery queries.

## Discovery panel behavior

The sandbox discovery panel combines these Search operations:

- `v1Products` for discovery products
- `v1Facets` for live filter metadata
- `v1Collections` for collection choices

Use that mental model when a question is about why the discovery UI shows a specific product, facet, or collection.

## Result states

Keep these states separate:

1. disconnected mock-data state
2. connected Search success
3. connected Search partial result
4. connected Search error

A `partial` result means Search returned enough data to render a useful preview even if some preferred fields are missing.

## Answer shape

1. State whether the sandbox is disconnected or connected.
2. Name the product-selection rule that applies.
3. Explain whether explicit selectors, category targeting, or discovery queries own the result.
4. Keep Search errors separate from empty-by-design UI states.

---

# Enad SDK Commerce

Explain Enad commerce building blocks for pricing, variant selection, quantity, cart, shopper-facing search, filters, and recommendation flows. Use when a request is about shopper decision surfaces or buying behavior in the Enad SDK.

# Enad SDK Commerce

Use this skill when the request is about buying behavior, shopper state, or commerce-specific surface composition.

Start with [pricing, selection, and cart](references/pricing-selection-and-cart.md) when the question is about money display, option picking, quantity, quick preview, or cart flow. Use [filtering, search, and recommendations](references/filtering-search-and-recommendations.md) when the question is about shopper-facing discovery behavior inside search and listing flows.

## Responsibilities

1. Explain how commerce components fit together across shopper flows.
2. Keep the guidance on controlled commerce state, localized pricing, and buying-surface boundaries.
3. Route to `enad-sdk-search` when the question turns into Search GraphQL, GraphiQL, endpoint context, or filter-schema semantics.
4. Route to `enad-sdk-discovery` when the user is still choosing a component family or import path.
5. Route to `enad-sdk-compound-composition` when the question turns into public child parts or slot boundaries.
6. Route to `enad-sdk-storefront` when the question is mostly about editorial or display structure instead of buying behavior.

## What this skill owns

Use this skill for prompts such as:

- `How should price, variant selection, quantity, and add-to-cart fit together in Enad?`
- `When should I use CartDrawer versus a full cart page?`
- `When should search stay submit-driven and when should it use autocomplete?`
- `How should FilterPanel and ProductRecommendations behave around a product grid?`
- `How should QuickView fit into a listing-page purchase flow?`

## What this skill does not own

Do not stay in this skill when the user is really asking:

- how Search GraphQL works
- how to use GraphiQL against an Enad app
- how `ProductFilter` should be shaped for categories, collections, facets, or autocomplete
- which component they should choose from a broad comparison set
- what public import path to use
- how an editorial section or merch row should be arranged visually

Those questions belong to `enad-sdk-search`, `enad-sdk-discovery`, `enad-sdk-compound-composition`, or `enad-sdk-storefront`.

## Rules

- Ground every answer in the current commerce docs.
- Keep `Price` numeric and localized. Do not normalize commerce copy by hard-coding display strings.
- Treat selection and quantity as controlled state that stays close to inventory and cart logic.
- Keep overlays concise. If the flow needs long-form editing, say so.
- If the prompt is mostly about display shape, product-card layout, or editorial rhythm, hand off to `enad-sdk-storefront`.
- If the prompt starts as component choice or import-path selection, hand off to `enad-sdk-discovery`.
- If the prompt turns into Search endpoint or query-model guidance, hand off to `enad-sdk-search`.

## Reference: references/pricing-selection-and-cart.md

# Pricing, Selection, and Cart

Use this reference when the question is about the core buying flow after a shopper has chosen a product surface.

## Fast routing table

| User signal                                                                | Use                  | Why                                                               | Use another guide when                                                             |
| -------------------------------------------------------------------------- | -------------------- | ----------------------------------------------------------------- | ---------------------------------------------------------------------------------- |
| Full PDP hero needed quickly with media, merchandising, actions, and trust | `ProductHeroSection` | It handles the top-of-PDP structure through explicit public zones | The app needs lower-level PDP family composition rather than the section fast path |
| Localized money display with sale and original-price state                 | `Price`              | It handles money display for cards, cart rows, and summaries      | The question is about the surrounding display block instead of money output        |
| Multi-axis product option picking                                          | `VariantSelector`    | It handles size, color, material, and other option axes           | The user is still choosing between component families or public child parts        |
| Small bounded quantity changes                                             | `QuantityPicker`     | It handles compact increment and decrement controls               | The flow needs freeform numeric entry or broader cart-page editing                 |
| Fast product preview without leaving the listing page                      | `QuickView`          | It handles short product preview flows with an action slot        | The visitor needs the full PDP instead of a short decision surface                 |
| Quick cart review and checkout access                                      | `CartDrawer`         | It handles mini-cart review and checkout movement in an overlay   | The cart experience needs more detail than an overlay should carry                 |

## Enad buying-flow pattern

1. Keep product discovery and row display in storefront.
2. Start from `ProductHeroSection` when the app needs the full top-of-PDP structure quickly.
3. Use `Price` for localized money output once the surface knows the numeric values and locale.
4. Resolve options through `VariantSelector` when the product has structured axes.
5. Use `QuantityPicker` for bounded count changes that stay close to the buy action.
6. Use `QuickView` for short preview-and-act flows on listing pages.
7. Use `CartDrawer` for concise review and checkout movement, not for full cart management.

## Practical notes

- Pass numeric values and locale into `Price`. Keep tax, financing, and delivery copy outside the component.
- Keep axis names stable in `VariantSelector` because they key the selected map.
- Unavailable variant options should stay visible but clearly unavailable.
- `QuantityPicker` should make min and max limits clear.
- `QuickView` takes `price` as a ReactNode, so a `Price` component can sit inside the preview.
- `CartDrawer` and `QuickView` are overlays. Focus handling, close controls, and return-to-trigger behavior matter.

## Shared boundaries

- If the prompt is still about choosing between components or public import paths, hand off to `enad-sdk-discovery`.
- If the prompt becomes about child-part composition, hand off to `enad-sdk-compound-composition`.
- If the prompt is mostly about product-card layout, editorial rows, or gallery shape, hand off to `enad-sdk-storefront`.

## Answer shape

1. Name the buying-flow surface.
2. Explain the shopper state it owns.
3. State the boundary where the surface stops.
4. Hand off if the next concern belongs to storefront, discovery, or compound composition.

## Reference: references/filtering-search-and-recommendations.md

# Filtering, Search, and Recommendations

Use this reference when the question is about shopper-facing product discovery behavior inside search and listing flows.

If the question is really about Search GraphQL, GraphiQL, query shape, category and collection targeting, facets, autocomplete data contracts, or sandbox Search-backed runtime behavior, hand off to `enad-sdk-search`.

## Fast routing table

| User signal                                                        | Use                      | Why                                                                      | Use another guide when                                                               |
| ------------------------------------------------------------------ | ------------------------ | ------------------------------------------------------------------------ | ------------------------------------------------------------------------------------ |
| Straight submit-driven query field                                 | `SearchBar`              | It handles simple search submission when suggestions are not the point   | The experience needs live suggestions or richer search-first navigation              |
| Predictive search with live suggestions                            | `SearchAutocomplete`     | It handles controlled search input, suggestions, and selection           | The question is mainly about header layout, editorial placement, or Search semantics |
| Full faceted filter surface with grouped options and applied state | `FilterPanel`            | It handles controlled faceted filtering for collection and result pages  | The need is only a small chip set, sort control, or Search filter shape              |
| Related products, complete-the-look, or recently viewed rail       | `ProductRecommendations` | It handles recommendation rails, child cards, view-all links, and arrows | The question is about product-card display or storefront row structure               |

## Enad discovery-flow rules

- Use `SearchBar` when the page only needs query submission.
- Use `SearchAutocomplete` when live suggestions should help the shopper pivot before full submission.
- Keep suggestion lists short and relevant.
- Keep `FilterPanel` fully controlled and make sure its option values match the backend query model exactly.
- Use `ProductRecommendations` for recommendation context, not as the primary product-card layout system.
- When `ProductRecommendations` wraps `ProductCard` children, `imageBehavior="auto"` keeps the rail as the main carousel.
- Recommendation rails still benefit from transformed Enad media URLs on their card images. Keep repeated card surfaces on transformed media rather than raw originals.

## Practical notes

- `SearchAutocomplete` owns `value`, `onValueChange`, `suggestions`, `onSelect`, and `onSearch`. Keep the contract clear.
- `FilterPanel` owns `filters`, `activeFilters`, `onFilterChange`, `open`, and `onOpenChange`. That state should stay close to the search or PLP shell.
- `productCount` gives `FilterPanel` a clear result-state connection.
- Recommendation rails should stay concise. Too many competing carousels make the flow harder to scan.
- If the question is `How should a product card grid look?`, that is usually storefront first.
- If the question is `How should filters and recommendations behave around it?`, that is commerce.
- If the question is `How should the Search query or filter be shaped?`, that is Search.

## Shared boundaries

- If the prompt starts with broad component choice or import-path selection, hand off to `enad-sdk-discovery`.
- If the prompt is mostly about product-card layout, gallery choice, or editorial row composition, hand off to `enad-sdk-storefront`.
- If the prompt becomes about child-part composition, hand off to `enad-sdk-compound-composition`.
- If the prompt becomes about Search endpoint semantics, GraphiQL, or category and collection filter shape, hand off to `enad-sdk-search`.

## Answer shape

1. Name the shopper-facing discovery surface.
2. Explain the shopper behavior it supports.
3. State the boundary where commerce stops and storefront display or Search semantics start.
4. Hand off when the next concern belongs to storefront, Search, discovery, or compound composition.