create-skybridge 0.0.0-dev.ea04428 → 0.0.0-dev.ea09368

package/{template → templates/demo}/src/views/components/steps/tool-output.tsx

@@ -23,8 +23,8 @@ export default function ToolOutput() {
         ) : (
           <p>
             The view reads the <strong>tool output</strong>, but no{" "}
-            <code>name</code> was passed this time. Try again with you surname
-            to see with this view personalize.
+            <code>name</code> was passed this time. Try again with your surname
+            to see how this view personalizes.
           </p>
         )}
       </div>

package/{template → templates/demo}/src/views/onboarding.tsx

@@ -26,7 +26,7 @@ export default function Onboarding() {
 
   return (
     <div
-      className={`${theme === "dark" ? "dark" : ""} mx-auto w-full max-w-4xl rounded-xl border border-border overflow-hidden bg-background text-foreground`}
+      className={`${theme === "dark" ? "dark" : ""} mx-auto w-full max-w-4xl border border-border overflow-hidden bg-background text-foreground`}
     >
       <div className="min-h-136 md:min-h-95 flex flex-col items-center gap-6 p-6 bg-linear-to-br from-purple-50 via-white to-cyan-50 dark:from-purple-950/30 dark:via-zinc-950 dark:to-cyan-900/30 bg-size-[200%_200%] animate-aurora md:flex-row md:items-stretch">
         <div className="shrink-0 self-center animate-float">

package/templates/ecom/.dockerignore

@@ -0,0 +1,4 @@
+node_modules
+.git
+dist
+.env*

package/templates/ecom/.env.template

@@ -0,0 +1,2 @@
+# Copy to .env and fill in. Sourced by the server at startup.
+API_KEY=

package/templates/ecom/.ladle/components.tsx

@@ -0,0 +1,26 @@
+import type { GlobalProvider } from "@ladle/react";
+import "../src/index.css";
+import { viewFrame } from "../src/components/view-frame.css";
+import { darkTheme, lightTheme } from "../src/design/tokens";
+import { cx } from "../src/lib/cx";
+
+/**
+ * Ladle's built-in theme toggle (sun/moon in the toolbar) drives
+ * globalState.theme. We reuse it to flip the widget's own palette, so the
+ * preview theme and the widget theme always match. The Provider applies the
+ * real ViewFrame surface (viewFrame + theme class), and index.css loads the
+ * brand @font-face rules, so stories preview against the actual frame.
+ */
+export const Provider: GlobalProvider = ({ children, globalState }) => {
+  const themeClass = globalState.theme === "dark" ? darkTheme : lightTheme;
+
+  return (
+    <div
+      className={cx(viewFrame, themeClass)}
+      data-theme={globalState.theme}
+      style={{ minHeight: "100vh", padding: 32 }}
+    >
+      {children}
+    </div>
+  );
+};

package/templates/ecom/.ladle/config.mjs

@@ -0,0 +1,11 @@
+/** @type {import('@ladle/react').UserConfig} */
+export default {
+  stories: "src/**/*.stories.{ts,tsx}",
+  viteConfig: ".ladle/vite.config.ts",
+  addons: {
+    theme: {
+      enabled: true,
+      defaultState: "light",
+    },
+  },
+};

package/templates/ecom/.ladle/vite.config.ts

@@ -0,0 +1,11 @@
+import { vanillaExtractPlugin } from "@vanilla-extract/vite-plugin";
+import { defineConfig } from "vite";
+
+/**
+ * Ladle-only vite config. Intentionally omits the Skybridge plugin (which
+ * transforms MCP view boilerplate and crashes Ladle's bundler) and the
+ * @vitejs/plugin-react call (Ladle provides its own).
+ */
+export default defineConfig({
+  plugins: [vanillaExtractPlugin()],
+});

package/templates/ecom/AGENTS.md

@@ -0,0 +1,2 @@
+This is an MCP ecommerce app built with Skybridge.
+ALWAYS use the `chatgpt-app-builder` skill when planning or updating the codebase: see its "ecommerce" reference.

package/templates/ecom/Dockerfile

@@ -0,0 +1,53 @@
+# syntax=docker/dockerfile:1
+
+# Dockerfile for a Skybridge MCP server.
+#
+# Detects npm, yarn, or pnpm from the lockfile in your project.
+# (For bun or deno, adapt the install/build/prune commands below.)
+
+# Build stage: install deps, compile the app, then prune dev deps.
+FROM node:24.18.0-slim AS build
+WORKDIR /app
+
+COPY package.json yarn.lock* package-lock.json* pnpm-lock.yaml* .npmrc* ./
+RUN --mount=type=cache,target=/root/.npm \
+    --mount=type=cache,target=/usr/local/share/.cache/yarn \
+    --mount=type=cache,target=/root/.local/share/pnpm/store \
+    if [ -f package-lock.json ]; then \
+      npm ci; \
+    elif [ -f yarn.lock ]; then \
+      corepack enable yarn && yarn install --frozen-lockfile; \
+    elif [ -f pnpm-lock.yaml ]; then \
+      corepack enable pnpm && pnpm install --frozen-lockfile; \
+    else \
+      echo "No lockfile found." && exit 1; \
+    fi
+
+ENV NODE_ENV=production
+
+COPY . .
+RUN if [ -f package-lock.json ]; then \
+      npm run build && npm prune --omit=dev; \
+    elif [ -f yarn.lock ]; then \
+      corepack enable yarn && yarn build && yarn install --frozen-lockfile --production=true; \
+    elif [ -f pnpm-lock.yaml ]; then \
+      corepack enable pnpm && pnpm build && pnpm prune --prod; \
+    fi
+
+# Runtime stage: copy built artifacts and prod deps, run as non-root.
+FROM node:24.18.0-slim AS runtime
+WORKDIR /app
+ENV NODE_ENV=production
+
+USER node
+
+COPY --from=build --chown=node:node /app/node_modules ./node_modules
+COPY --from=build --chown=node:node /app/dist ./dist
+COPY --from=build --chown=node:node /app/package.json ./package.json
+
+EXPOSE 3000
+
+# Run the built server directly rather than via `npm start` / `skybridge start`.
+# Each wrapper adds a process layer that can swallow SIGTERM, which makes
+# graceful shutdowns time out on platforms like Cloud Run, Fly, and k8s.
+CMD ["node", "dist/__entry.js"]

package/templates/ecom/README.md

@@ -0,0 +1,92 @@
+# Skybridge Boilerplate
+
+A minimal TypeScript boilerplate for building MCP and ChatGPT Apps with the [Skybridge](https://docs.skybridge.tech) framework.
+
+## Getting Started
+
+### Prerequisites
+
+- Node.js 24+
+
+### Local Development
+
+#### 1. Install
+
+```bash
+npm install
+# or
+pnpm install
+# or
+bun install
+# or
+deno install
+# or
+yarn install
+```
+
+#### 2. Start your local server
+
+Run the development server from the root directory:
+
+```bash
+npm run dev
+# or
+pnpm dev
+# or
+bun dev
+# or
+deno task dev
+# or
+yarn dev
+```
+
+This command starts:
+- Your MCP server at `http://localhost:3000/mcp`.
+- Skybridge DevTools UI at `http://localhost:3000`.
+
+#### 3. Project structure
+
+```
+├── src/
+│   ├── server.ts         # Server entry point
+│   └── helpers.ts        # Shared utilities
+├── vite.config.ts
+├── alpic.json            # Deployment config
+└── package.json
+```
+
+### Create your first view
+
+#### 1. Add a new view
+
+- Register a tool in `src/server.ts` with a unique name (e.g., `my-view`) using [`registerTool`](https://docs.skybridge.tech/api-reference/register-tool) and a `view` config.
+- Create a matching React component at `src/views/my-view.tsx`. **The file name must match the view name exactly**.
+
+#### 2. Edit views with Hot Module Replacement (HMR)
+
+Edit and save components in `src/views/` — changes will appear instantly inside your App.
+
+#### 3. Edit server code
+
+Modify files in `src/` and refresh the tool list with your MCP Client to see the changes.
+
+### Testing your App
+
+You can test your app locally by using our DevTools UI on `http://localhost:3000` while running the `dev` command.
+
+To connect your app with web clients like ChatGPT or Claude, expose your server on the internet by adding the `--tunnel` flag.
+By enabling the tunnel, you'll also be able to access a playground to chat with your app and a real LLM. Learn more by reading the [test guide](https://docs.skybridge.tech/quickstart/test-your-app).
+
+
+## Deploy to Production
+
+Skybridge is infrastructure vendor agnostic, and your app can be deployed on any cloud platform supporting MCP.
+
+The simplest way to deploy your app is by running the `deploy` command, which will push your MCP server to the [Alpic](https://alpic.ai/) cloud for free.
+
+## Resources
+- [Skybridge Documentation](https://docs.skybridge.tech/)
+- [Apps SDK Documentation](https://developers.openai.com/apps-sdk)
+- [MCP Apps Documentation](https://github.com/modelcontextprotocol/ext-apps/tree/main)
+- [Model Context Protocol Documentation](https://modelcontextprotocol.io/)
+- [Alpic Documentation](https://docs.alpic.ai/)

package/templates/ecom/_gitignore

@@ -0,0 +1,9 @@
+node_modules/
+dist/
+build/
+.env*
+!.env.template
+.DS_store
+*.tsbuildinfo
+.skybridge/
+.vercel/

package/templates/ecom/alpic.json

@@ -0,0 +1,3 @@
+{
+  "$schema": "https://assets.alpic.ai/alpic.json"
+}

package/templates/ecom/node_modules/.bin/alpic

@@ -0,0 +1,21 @@
+#!/bin/sh
+basedir=$(dirname "$(echo "$0" | sed -e 's,\\,/,g')")
+
+case `uname` in
+    *CYGWIN*|*MINGW*|*MSYS*)
+        if command -v cygpath > /dev/null 2>&1; then
+            basedir=`cygpath -w "$basedir"`
+        fi
+    ;;
+esac
+
+if [ -z "$NODE_PATH" ]; then
+  export NODE_PATH="/home/runner/work/skybridge/skybridge/node_modules/.pnpm/alpic@1.148.1_@opentelemetry+api@1.9.1_@opentelemetry+core@2.8.0_@opentelemetry+api@1.9_dc7708ba103efafb508db02d69c9f925/node_modules/alpic/node_modules:/home/runner/work/skybridge/skybridge/node_modules/.pnpm/alpic@1.148.1_@opentelemetry+api@1.9.1_@opentelemetry+core@2.8.0_@opentelemetry+api@1.9_dc7708ba103efafb508db02d69c9f925/node_modules:/home/runner/work/skybridge/skybridge/node_modules/.pnpm/node_modules"
+else
+  export NODE_PATH="/home/runner/work/skybridge/skybridge/node_modules/.pnpm/alpic@1.148.1_@opentelemetry+api@1.9.1_@opentelemetry+core@2.8.0_@opentelemetry+api@1.9_dc7708ba103efafb508db02d69c9f925/node_modules/alpic/node_modules:/home/runner/work/skybridge/skybridge/node_modules/.pnpm/alpic@1.148.1_@opentelemetry+api@1.9.1_@opentelemetry+core@2.8.0_@opentelemetry+api@1.9_dc7708ba103efafb508db02d69c9f925/node_modules:/home/runner/work/skybridge/skybridge/node_modules/.pnpm/node_modules:$NODE_PATH"
+fi
+if [ -x "$basedir/node" ]; then
+  exec "$basedir/node"  "$basedir/../alpic/bin/run.js" "$@"
+else
+  exec node  "$basedir/../alpic/bin/run.js" "$@"
+fi

package/templates/ecom/node_modules/.bin/ladle

@@ -0,0 +1,21 @@
+#!/bin/sh
+basedir=$(dirname "$(echo "$0" | sed -e 's,\\,/,g')")
+
+case `uname` in
+    *CYGWIN*|*MINGW*|*MSYS*)
+        if command -v cygpath > /dev/null 2>&1; then
+            basedir=`cygpath -w "$basedir"`
+        fi
+    ;;
+esac
+
+if [ -z "$NODE_PATH" ]; then
+  export NODE_PATH="/home/runner/work/skybridge/skybridge/node_modules/.pnpm/@ladle+react@5.1.1_@types+node@24.13.2_@types+react@19.2.17_jiti@2.7.0_lightningcss@1.3_87a889c60e4b1fe9d02c5a43786e65ce/node_modules/@ladle/react/node_modules:/home/runner/work/skybridge/skybridge/node_modules/.pnpm/@ladle+react@5.1.1_@types+node@24.13.2_@types+react@19.2.17_jiti@2.7.0_lightningcss@1.3_87a889c60e4b1fe9d02c5a43786e65ce/node_modules:/home/runner/work/skybridge/skybridge/node_modules/.pnpm/node_modules"
+else
+  export NODE_PATH="/home/runner/work/skybridge/skybridge/node_modules/.pnpm/@ladle+react@5.1.1_@types+node@24.13.2_@types+react@19.2.17_jiti@2.7.0_lightningcss@1.3_87a889c60e4b1fe9d02c5a43786e65ce/node_modules/@ladle/react/node_modules:/home/runner/work/skybridge/skybridge/node_modules/.pnpm/@ladle+react@5.1.1_@types+node@24.13.2_@types+react@19.2.17_jiti@2.7.0_lightningcss@1.3_87a889c60e4b1fe9d02c5a43786e65ce/node_modules:/home/runner/work/skybridge/skybridge/node_modules/.pnpm/node_modules:$NODE_PATH"
+fi
+if [ -x "$basedir/node" ]; then
+  exec "$basedir/node"  "$basedir/../@ladle/react/lib/cli/cli.js" "$@"
+else
+  exec node  "$basedir/../@ladle/react/lib/cli/cli.js" "$@"
+fi

package/templates/ecom/node_modules/.bin/sb

@@ -0,0 +1,21 @@
+#!/bin/sh
+basedir=$(dirname "$(echo "$0" | sed -e 's,\\,/,g')")
+
+case `uname` in
+    *CYGWIN*|*MINGW*|*MSYS*)
+        if command -v cygpath > /dev/null 2>&1; then
+            basedir=`cygpath -w "$basedir"`
+        fi
+    ;;
+esac
+
+if [ -z "$NODE_PATH" ]; then
+  export NODE_PATH="/home/runner/work/skybridge/skybridge/node_modules/.pnpm/node_modules"
+else
+  export NODE_PATH="/home/runner/work/skybridge/skybridge/node_modules/.pnpm/node_modules:$NODE_PATH"
+fi
+if [ -x "$basedir/node" ]; then
+  exec "$basedir/node"  "$basedir/../skybridge/bin/run.js" "$@"
+else
+  exec node  "$basedir/../skybridge/bin/run.js" "$@"
+fi

package/templates/ecom/node_modules/.bin/skybridge

@@ -0,0 +1,21 @@
+#!/bin/sh
+basedir=$(dirname "$(echo "$0" | sed -e 's,\\,/,g')")
+
+case `uname` in
+    *CYGWIN*|*MINGW*|*MSYS*)
+        if command -v cygpath > /dev/null 2>&1; then
+            basedir=`cygpath -w "$basedir"`
+        fi
+    ;;
+esac
+
+if [ -z "$NODE_PATH" ]; then
+  export NODE_PATH="/home/runner/work/skybridge/skybridge/node_modules/.pnpm/node_modules"
+else
+  export NODE_PATH="/home/runner/work/skybridge/skybridge/node_modules/.pnpm/node_modules:$NODE_PATH"
+fi
+if [ -x "$basedir/node" ]; then
+  exec "$basedir/node"  "$basedir/../skybridge/bin/run.js" "$@"
+else
+  exec node  "$basedir/../skybridge/bin/run.js" "$@"
+fi

package/templates/ecom/node_modules/.bin/tsc

@@ -0,0 +1,21 @@
+#!/bin/sh
+basedir=$(dirname "$(echo "$0" | sed -e 's,\\,/,g')")
+
+case `uname` in
+    *CYGWIN*|*MINGW*|*MSYS*)
+        if command -v cygpath > /dev/null 2>&1; then
+            basedir=`cygpath -w "$basedir"`
+        fi
+    ;;
+esac
+
+if [ -z "$NODE_PATH" ]; then
+  export NODE_PATH="/home/runner/work/skybridge/skybridge/node_modules/.pnpm/typescript@6.0.3/node_modules/typescript/node_modules:/home/runner/work/skybridge/skybridge/node_modules/.pnpm/typescript@6.0.3/node_modules:/home/runner/work/skybridge/skybridge/node_modules/.pnpm/node_modules"
+else
+  export NODE_PATH="/home/runner/work/skybridge/skybridge/node_modules/.pnpm/typescript@6.0.3/node_modules/typescript/node_modules:/home/runner/work/skybridge/skybridge/node_modules/.pnpm/typescript@6.0.3/node_modules:/home/runner/work/skybridge/skybridge/node_modules/.pnpm/node_modules:$NODE_PATH"
+fi
+if [ -x "$basedir/node" ]; then
+  exec "$basedir/node"  "$basedir/../typescript/bin/tsc" "$@"
+else
+  exec node  "$basedir/../typescript/bin/tsc" "$@"
+fi

package/templates/ecom/node_modules/.bin/tsserver

@@ -0,0 +1,21 @@
+#!/bin/sh
+basedir=$(dirname "$(echo "$0" | sed -e 's,\\,/,g')")
+
+case `uname` in
+    *CYGWIN*|*MINGW*|*MSYS*)
+        if command -v cygpath > /dev/null 2>&1; then
+            basedir=`cygpath -w "$basedir"`
+        fi
+    ;;
+esac
+
+if [ -z "$NODE_PATH" ]; then
+  export NODE_PATH="/home/runner/work/skybridge/skybridge/node_modules/.pnpm/typescript@6.0.3/node_modules/typescript/node_modules:/home/runner/work/skybridge/skybridge/node_modules/.pnpm/typescript@6.0.3/node_modules:/home/runner/work/skybridge/skybridge/node_modules/.pnpm/node_modules"
+else
+  export NODE_PATH="/home/runner/work/skybridge/skybridge/node_modules/.pnpm/typescript@6.0.3/node_modules/typescript/node_modules:/home/runner/work/skybridge/skybridge/node_modules/.pnpm/typescript@6.0.3/node_modules:/home/runner/work/skybridge/skybridge/node_modules/.pnpm/node_modules:$NODE_PATH"
+fi
+if [ -x "$basedir/node" ]; then
+  exec "$basedir/node"  "$basedir/../typescript/bin/tsserver" "$@"
+else
+  exec node  "$basedir/../typescript/bin/tsserver" "$@"
+fi

package/templates/ecom/node_modules/.bin/tsx

@@ -0,0 +1,21 @@
+#!/bin/sh
+basedir=$(dirname "$(echo "$0" | sed -e 's,\\,/,g')")
+
+case `uname` in
+    *CYGWIN*|*MINGW*|*MSYS*)
+        if command -v cygpath > /dev/null 2>&1; then
+            basedir=`cygpath -w "$basedir"`
+        fi
+    ;;
+esac
+
+if [ -z "$NODE_PATH" ]; then
+  export NODE_PATH="/home/runner/work/skybridge/skybridge/node_modules/.pnpm/tsx@4.23.0/node_modules/tsx/node_modules:/home/runner/work/skybridge/skybridge/node_modules/.pnpm/tsx@4.23.0/node_modules:/home/runner/work/skybridge/skybridge/node_modules/.pnpm/node_modules"
+else
+  export NODE_PATH="/home/runner/work/skybridge/skybridge/node_modules/.pnpm/tsx@4.23.0/node_modules/tsx/node_modules:/home/runner/work/skybridge/skybridge/node_modules/.pnpm/tsx@4.23.0/node_modules:/home/runner/work/skybridge/skybridge/node_modules/.pnpm/node_modules:$NODE_PATH"
+fi
+if [ -x "$basedir/node" ]; then
+  exec "$basedir/node"  "$basedir/../tsx/dist/cli.mjs" "$@"
+else
+  exec node  "$basedir/../tsx/dist/cli.mjs" "$@"
+fi

package/templates/ecom/node_modules/.bin/vite

@@ -0,0 +1,21 @@
+#!/bin/sh
+basedir=$(dirname "$(echo "$0" | sed -e 's,\\,/,g')")
+
+case `uname` in
+    *CYGWIN*|*MINGW*|*MSYS*)
+        if command -v cygpath > /dev/null 2>&1; then
+            basedir=`cygpath -w "$basedir"`
+        fi
+    ;;
+esac
+
+if [ -z "$NODE_PATH" ]; then
+  export NODE_PATH="/home/runner/work/skybridge/skybridge/node_modules/.pnpm/vite@8.1.3_@types+node@24.13.2_esbuild@0.28.1_jiti@2.7.0_terser@5.44.1_tsx@4.23.0_yaml@2.8.2/node_modules/vite/node_modules:/home/runner/work/skybridge/skybridge/node_modules/.pnpm/vite@8.1.3_@types+node@24.13.2_esbuild@0.28.1_jiti@2.7.0_terser@5.44.1_tsx@4.23.0_yaml@2.8.2/node_modules:/home/runner/work/skybridge/skybridge/node_modules/.pnpm/node_modules"
+else
+  export NODE_PATH="/home/runner/work/skybridge/skybridge/node_modules/.pnpm/vite@8.1.3_@types+node@24.13.2_esbuild@0.28.1_jiti@2.7.0_terser@5.44.1_tsx@4.23.0_yaml@2.8.2/node_modules/vite/node_modules:/home/runner/work/skybridge/skybridge/node_modules/.pnpm/vite@8.1.3_@types+node@24.13.2_esbuild@0.28.1_jiti@2.7.0_terser@5.44.1_tsx@4.23.0_yaml@2.8.2/node_modules:/home/runner/work/skybridge/skybridge/node_modules/.pnpm/node_modules:$NODE_PATH"
+fi
+if [ -x "$basedir/node" ]; then
+  exec "$basedir/node"  "$basedir/../vite/bin/vite.js" "$@"
+else
+  exec node  "$basedir/../vite/bin/vite.js" "$@"
+fi

package/templates/ecom/package.json

@@ -0,0 +1,41 @@
+{
+  "name": "skybridge-ecom",
+  "version": "0.0.1",
+  "private": true,
+  "description": "Skybridge MCP ecommerce template",
+  "type": "module",
+  "scripts": {
+    "dev": "skybridge dev",
+    "dev:tunnel": "skybridge dev --tunnel",
+    "build": "skybridge build",
+    "start": "skybridge start",
+    "deploy": "alpic deploy",
+    "ladle": "ladle serve",
+    "ladle:build": "ladle build"
+  },
+  "dependencies": {
+    "react": "^19.2.4",
+    "react-dom": "^19.2.4",
+    "skybridge": "workspace:*",
+    "vite": "^8.1.3",
+    "zod": "^4.4.3"
+  },
+  "devDependencies": {
+    "@ladle/react": "^5.1.1",
+    "@skybridge/devtools": "^1.2.4",
+    "@types/node": "^24.13.2",
+    "@types/react": "^19.2.14",
+    "@types/react-dom": "^19.2.3",
+    "@vanilla-extract/css": "^1.20.1",
+    "@vanilla-extract/recipes": "^0.5.7",
+    "@vanilla-extract/sprinkles": "^1.6.5",
+    "@vanilla-extract/vite-plugin": "^5.2.2",
+    "@vitejs/plugin-react": "^6.0.1",
+    "alpic": "^1.147.1",
+    "tsx": "^4.23.0",
+    "typescript": "^6.0.3"
+  },
+  "engines": {
+    "node": ">=24.18.0"
+  }
+}

package/templates/ecom/src/components/empty-state.stories.tsx

@@ -0,0 +1,3 @@
+import { EmptyState } from "./empty-state";
+
+export const NoResults = () => <EmptyState message="No products to show." />;

package/templates/ecom/src/components/empty-state.tsx

@@ -0,0 +1,12 @@
+import { sprinkles, text } from "../design/tokens";
+
+/** Centered message shown when there is nothing to render (e.g. no results). */
+export function EmptyState({ message }: { message: string }) {
+  return (
+    <div
+      className={sprinkles({ p: "l", textAlign: "center", color: "subtle" })}
+    >
+      <p className={text({ style: "bodyM" })}>{message}</p>
+    </div>
+  );
+}

package/templates/ecom/src/components/product-card.css.ts

@@ -0,0 +1,136 @@
+import { keyframes, style } from "@vanilla-extract/css";
+import { recipe } from "@vanilla-extract/recipes";
+import { colors, primitives } from "../design/tokens";
+
+// @todo: number of title lines before it truncates with an ellipsis. Exported
+// so the skeleton reserves the same number of lines.
+export const TITLE_LINES = 2;
+
+// `framed: true` gives each card its own container; the default is a plain
+// layout shell (pair it with a framed carousel instead). Pick one, not both.
+export const card = recipe({
+  base: {
+    display: "flex",
+    flexDirection: "column",
+    gap: primitives.space["3xs"],
+    width: "100%",
+    textAlign: "left",
+  },
+  variants: {
+    framed: {
+      // @todo: tune the card container to your brand.
+      true: {
+        padding: primitives.space["3xs"],
+        borderRadius: primitives.radius.m,
+        border: `${primitives.stroke.thin} solid ${colors.border.thin}`,
+        backgroundColor: colors.surface.extraLight,
+      },
+      false: {},
+    },
+  },
+  defaultVariants: { framed: false },
+});
+
+export const imageBox = style({
+  position: "relative",
+  aspectRatio: "1",
+  overflow: "hidden",
+  borderRadius: primitives.radius.m,
+  // Stage behind the product image. @todo: pick the surface token that suits
+  // your imagery (a neutral grey for transparent cutouts, `extraLight`/white
+  // for full-bleed photos).
+  backgroundColor: colors.surface.subtle,
+});
+
+export const image = style({
+  width: "100%",
+  height: "100%",
+  // @todo: `contain` never crops; switch to `cover` for uniform, bleed-friendly
+  // cutout images.
+  objectFit: "contain",
+  display: "block",
+  // Keep image drag from hijacking the swipe/scroll gesture.
+  pointerEvents: "none",
+  userSelect: "none",
+});
+
+export const imageDimmed = style({ opacity: 0.5 });
+
+export const placeholder = style({
+  width: "100%",
+  height: "100%",
+  backgroundColor: colors.surface.subtle,
+});
+
+export const oosBadge = style({
+  position: "absolute",
+  top: primitives.space["3xs"],
+  left: primitives.space["3xs"],
+  padding: `${primitives.space["5xs"]} ${primitives.space["3xs"]}`,
+  borderRadius: primitives.radius.s,
+  backgroundColor: colors.surface.extraLight,
+  color: colors.content.intense,
+  fontFamily: primitives.font.family.primary,
+  fontSize: primitives.font.size.xs,
+});
+
+export const body = style({
+  display: "flex",
+  flexDirection: "column",
+  gap: primitives.space["5xs"],
+});
+
+export const title = style({
+  color: colors.content.intense,
+  display: "-webkit-box",
+  WebkitLineClamp: TITLE_LINES,
+  WebkitBoxOrient: "vertical",
+  overflow: "hidden",
+  // Reserve the clamp height (title line-height is 1.5) so prices line up
+  // across cards whatever the title length.
+  minHeight: `calc(${TITLE_LINES} * 1.5em)`,
+});
+
+export const price = style({ color: colors.content.subtle });
+
+// Skeleton (loading state).
+const pulse = keyframes({
+  "0%": { opacity: 1 },
+  "50%": { opacity: 0.4 },
+  "100%": { opacity: 1 },
+});
+
+export const skeletonBox = style({
+  backgroundColor: colors.surface.subtle,
+  borderRadius: primitives.radius.s,
+  animation: `${pulse} 1.5s ease-in-out infinite`,
+  "@media": {
+    "(prefers-reduced-motion: reduce)": { animation: "none" },
+  },
+});
+
+export const skeletonImage = style({
+  aspectRatio: "1",
+  borderRadius: primitives.radius.m,
+});
+
+// Text rows (title lines + price), evenly spaced. Its own container rather than
+// `body` so the skeleton can breathe a little more without moving the real card.
+export const skeletonBody = style({
+  display: "flex",
+  flexDirection: "column",
+  gap: primitives.space["4xs"],
+});
+
+export const skeletonLine = style({ height: primitives.font.size.m });
+
+// Last title line and the price row are stubbed short, the way text ends.
+export const skeletonLineShort = style({
+  height: primitives.font.size.m,
+  width: "60%",
+});
+
+export const skeletonPrice = style({
+  height: primitives.font.size.m,
+  width: "40%",
+});