@upstart.gg/sdk 0.0.135 → 0.0.136

package/src/shared/bricks/manifests/card.manifest.ts

@@ -10,13 +10,15 @@ import { borderRef, roundingRef } from "../props/border";
 import { colorPresetRef } from "../props/color-preset";
 import { loopRef } from "../props/dynamic";
 import { StringEnum } from "~/shared/utils/string-enum";
+import { urlOrPageIdRef } from "../props/string";
+import type { BrickExample } from "./_types";
 
 export const manifest = defineBrickManifest({
   type: "card",
   name: "Card",
   description: "A card that can have a title, image, and content.",
   aiInstructions:
-    "Use this brick to create cards that contain an image, title, and text content. Cards are useful for displaying information in a concise and visually appealing way.",
+    "Use this brick to create visually distinct content blocks (product, feature, testimonial, event, article, CTA, etc.).\n\nGuidelines:\n- Button is REQUIRED. Always provide a short action label (1–3 words) and pick a color matching semantic weight (primary/accent for primary actions, neutral/secondary for low emphasis).\n- Image is OPTIONAL. If present you may set imagePosition to top | middle | bottom. Default is top. Pick middle for vertically centered feature highlights, bottom for caption-first layouts.\n- Set noTitle: true when the card is intentionally title-less (e.g. a quote card or pure media focus). Do NOT include an empty title string alongside noTitle.\n- Use dynamic tokens (e.g. {{products.price}}) instead of duplicating literal values.\n- Prefer gradient presets for more visual emphasis (e.g. primary-gradient-400 with gradientDirection).\n- border + rounding + shadow should be cohesive: stronger borders pair well with larger rounding + moderate shadow; minimal / flat cards may use border-0 + no shadow.\n- For internal navigation you can supply a page ID (e.g. 'about') OR a relative/absolute URL (e.g. '/pricing', 'https://example.com').\n- Keep HTML inside text minimal (<strong>, <em>, <br>) — for richer structure consider multiple bricks instead.\n- Avoid mixing noTitle with large heading text embedded inside the text field — in that case keep a proper title.\n\nReturn ONLY valid properties defined in the schema; do not invent new ones.",
   icon: BsCardText,
   defaultWidth: { desktop: "400px", mobile: "100%" },
   minWidth: { desktop: 300 },
@@ -39,8 +41,8 @@ export const manifest = defineBrickManifest({
       }),
     ),
     imagePosition: Type.Optional(
-      StringEnum(["top", "middle", "bottom", "left", "right"], {
-        enumNames: ["Top", "Middle", "Bottom", "Left", "Right"],
+      StringEnum(["top", "middle", "bottom"], {
+        enumNames: ["Top", "Middle", "Bottom"],
         title: "Image Position",
         description: "Where the image should be placed in the card",
         default: "top",
@@ -79,34 +81,147 @@ export const manifest = defineBrickManifest({
       }),
     ),
     loop: Type.Optional(loopRef()),
+    button: Type.Object(
+      {
+        label: Type.String({
+          title: "Button label",
+          default: "Click me",
+          examples: ["Learn more", "Buy now", "Sign up"],
+          metadata: {
+            category: "content",
+          },
+        }),
+        url: urlOrPageIdRef({
+          title: "Button URL",
+          description: "The URL the button should link to.",
+          metadata: {
+            category: "content",
+          },
+        }),
+        color: Type.Optional(
+          StringEnum(["btn-neutral", "btn-primary", "btn-secondary", "btn-accent"], {
+            enumNames: ["Neutral", "Primary", "Secondary", "Accent"],
+            title: "Color",
+            default: "btn-primary",
+          }),
+        ),
+      },
+      { title: "Button", description: "Button displayed at the bottom of the card" },
+    ),
   }),
 });
 
 export type Manifest = typeof manifest;
 
-export const examples: {
-  description: string;
-  type: string;
-  props: BrickProps<Manifest>["brick"]["props"];
-}[] = [
+export const examples: BrickExample<Manifest>[] = [
   {
     description: "A simple card with a title and content",
     type: "card",
     props: {
       title: "Card Title",
       text: "This is the body of the card.",
+      button: {
+        label: "Learn more",
+        url: "/learn-more",
+        color: "btn-primary",
+      },
     },
   },
+  // IMAGE POSITION MIDDLE VARIANT
   {
-    description: "Product card with image on the left",
+    description: "Feature highlight card with centered image (imagePosition=middle)",
     type: "card",
     props: {
-      cardImage: {
-        src: "https://via.placeholder.com/200x200",
-        alt: "Product image",
-      },
-      title: "Premium Headphones",
-      text: "High-quality wireless headphones with noise cancellation and 30-hour battery life.",
+      cardImage: { src: "https://via.placeholder.com/420x240", alt: "Feature visual" },
+      imagePosition: "middle",
+      title: "Blazing Performance",
+      text: "Our new engine reduces processing time by 45% while maintaining reliability.",
+      colorPreset: { color: "primary-100" },
+      border: { width: "border", color: "border-primary-200" },
+      rounding: "rounded-lg",
+      shadow: "shadow-sm",
+      button: { label: "Learn More", url: "/features/performance", color: "btn-primary" },
+    },
+  },
+  // IMAGE POSITION BOTTOM VARIANT
+  {
+    description: "Case study card with image at the bottom (imagePosition=bottom)",
+    type: "card",
+    props: {
+      title: "Case Study: ScaleOps",
+      text: "How ScaleOps handled 10x growth with zero downtime using our platform.",
+      cardImage: { src: "https://via.placeholder.com/600x260", alt: "Scale graph" },
+      imagePosition: "bottom",
+      colorPreset: { color: "secondary-50" },
+      rounding: "rounded-md",
+      shadow: "shadow-sm",
+      button: { label: "Read Study", url: "/cases/scaleops", color: "btn-secondary" },
+    },
+  },
+  // NO TITLE VARIANT
+  {
+    description: "Quote / testimonial style card without a title (uses noTitle=true)",
+    type: "card",
+    props: {
+      noTitle: true,
+      text: '"This toolkit accelerated our launch by weeks — the component quality is outstanding."<br><em>— CTO, FinEdge</em>',
+      colorPreset: { color: "neutral-100" },
+      border: { width: "border", color: "border-neutral-300" },
+      rounding: "rounded-xl",
+      shadow: "shadow-sm",
+      button: { label: "See More", url: "/testimonials", color: "btn-neutral" },
+    },
+  },
+  // INTERNAL PAGE ID LINK VARIANT
+  {
+    description: "Internal navigation card using a page ID instead of a URL",
+    type: "card",
+    props: {
+      title: "About Our Mission",
+      text: "Learn how we're building an open, extensible site generation platform for modern teams.",
+      colorPreset: { color: "base-100" },
+      rounding: "rounded-md",
+      button: { label: "About Us", url: "about", color: "btn-primary" },
+    },
+  },
+  // GRADIENT & STRONG BORDER VARIANT
+  {
+    description: "High-emphasis promotional card using gradient background and thick border",
+    type: "card",
+    props: {
+      title: "Limited Time Offer",
+      text: "Upgrade now and receive a complimentary strategy session plus extended analytics access.",
+      colorPreset: { color: "primary-gradient-400", gradientDirection: "bg-gradient-to-tr" },
+      border: { width: "border-4", color: "border-primary-400" },
+      rounding: "rounded-xl",
+      shadow: "shadow-lg",
+      button: { label: "Upgrade", url: "/pricing", color: "btn-accent" },
+    },
+  },
+  // MINIMAL / FLAT VARIANT (no border, no shadow, subtle preset)
+  {
+    description: "Minimal flat information card (border-0, no shadow)",
+    type: "card",
+    props: {
+      title: "Maintenance Window",
+      text: "Scheduled maintenance on Saturday 02:00–03:00 UTC. API responses may be delayed.",
+      colorPreset: { color: "neutral-50" },
+      border: { width: "border-0", color: "border-neutral-200" },
+      button: { label: "Status Page", url: "/status", color: "btn-neutral" },
+    },
+  },
+  // DARK / INVERTED VARIANT
+  {
+    description: "Dark themed spotlight card (primary-800 background)",
+    type: "card",
+    props: {
+      title: "Night Mode Preview",
+      text: "Experience the new adaptive dark theme optimized for low ambient light environments.",
+      colorPreset: { color: "primary-800" },
+      border: { width: "border", color: "border-primary-600" },
+      rounding: "rounded-lg",
+      shadow: "shadow-md",
+      button: { label: "Preview", url: "/themes/dark", color: "btn-primary" },
     },
   },
   {
@@ -115,29 +230,31 @@ export const examples: {
     props: {
       title: "Key Feature",
       text: "This feature provides exceptional value and enhances user experience significantly.",
+      colorPreset: { color: "primary-50" },
+      border: { width: "border", color: "border-primary-200" },
+      rounding: "rounded-lg",
+      shadow: "shadow-sm",
+      button: {
+        label: "Discover More",
+        url: "/features",
+        color: "btn-primary",
+      },
     },
   },
   {
     description: "Blog post card with image at the bottom",
     type: "card",
     props: {
-      title: "The Future of Technology",
+      title: "Future of Tech",
       text: "Exploring emerging trends and innovations that will shape our digital landscape in the coming decade.",
       cardImage: {
         src: "https://via.placeholder.com/400x200",
         alt: "Technology concept",
       },
-    },
-  },
-  {
-    description: "Testimonial card with right-side image",
-    type: "card",
-    props: {
-      title: "Customer Review",
-      text: '"This product exceeded my expectations. The quality is outstanding and the customer service is top-notch!"',
-      cardImage: {
-        src: "https://via.placeholder.com/150x150",
-        alt: "Customer photo",
+      button: {
+        label: "Read More",
+        url: "/blog/{{ blogPosts.$slug }}",
+        color: "btn-primary",
       },
     },
   },
@@ -147,6 +264,11 @@ export const examples: {
     props: {
       title: "Simple Announcement",
       text: "Important updates will be posted here regularly.",
+      button: {
+        label: "View Updates",
+        url: "/updates",
+        color: "btn-neutral",
+      },
     },
   },
   {
@@ -159,6 +281,11 @@ export const examples: {
       },
       title: "Annual Conference 2025",
       text: "Join us for three days of inspiring talks, networking opportunities, and hands-on workshops.",
+      button: {
+        label: "Register Now",
+        url: "/events/conference-2025",
+        color: "btn-primary",
+      },
     },
   },
   {
@@ -171,6 +298,11 @@ export const examples: {
       },
       title: "Breaking News Update",
       text: "Latest developments in the ongoing story with expert analysis and community reactions.",
+      button: {
+        label: "Read Full Article",
+        url: "/news/breaking-update",
+        color: "btn-secondary",
+      },
     },
   },
   {
@@ -179,6 +311,11 @@ export const examples: {
     props: {
       title: "Get Started Today",
       text: "Transform your workflow with our powerful tools. Sign up now and get 30 days free!",
+      button: {
+        label: "Sign Up Now",
+        url: "/signup",
+        color: "btn-primary",
+      },
     },
   },
   {
@@ -195,6 +332,11 @@ export const examples: {
       border: { width: "border", color: "border-primary-200" },
       rounding: "rounded-lg",
       shadow: "shadow-md",
+      button: {
+        label: "Buy Now",
+        url: "{{products.purchaseUrl}}",
+        color: "btn-primary",
+      },
       loop: {
         over: "products",
       },
@@ -214,6 +356,11 @@ export const examples: {
       colorPreset: { color: "neutral-100" },
       rounding: "rounded-xl",
       shadow: "shadow-lg",
+      button: {
+        label: "Contact",
+        url: "mailto:{{teamMembers.email}}",
+        color: "btn-neutral",
+      },
       loop: {
         over: "teamMembers",
       },
@@ -234,6 +381,11 @@ export const examples: {
       border: { width: "border", color: "border-secondary-300" },
       rounding: "rounded-md",
       shadow: "shadow-sm",
+      button: {
+        label: "Read More",
+        url: "{{blogPosts.url}}",
+        color: "btn-secondary",
+      },
       loop: {
         over: "blogPosts",
       },
@@ -254,6 +406,11 @@ export const examples: {
       border: { width: "border-2", color: "border-accent-400" },
       rounding: "rounded-lg",
       shadow: "shadow-md",
+      button: {
+        label: "Book Tickets",
+        url: "{{upcomingEvents.ticketUrl}}",
+        color: "btn-accent",
+      },
       loop: {
         over: "upcomingEvents",
       },
@@ -267,12 +424,17 @@ export const examples: {
         src: "{{customerReviews.customerPhoto}}",
         alt: "{{customerReviews.customerName}}",
       },
-      imagePosition: "left",
+      imagePosition: "top",
       title: "{{customerReviews.customerName}}",
       text: '"{{customerReviews.review}}"<br><br><strong>Rating: {{customerReviews.rating}}/5 stars</strong><br>{{customerReviews.company}} • {{customerReviews.position}}',
       colorPreset: { color: "neutral-50" },
       rounding: "rounded-xl",
       shadow: "shadow-lg",
+      button: {
+        label: "See All Reviews",
+        url: "/reviews",
+        color: "btn-neutral",
+      },
       loop: {
         over: "customerReviews",
       },
@@ -293,6 +455,11 @@ export const examples: {
       border: { width: "border", color: "border-primary-300" },
       rounding: "rounded-lg",
       shadow: "shadow-md",
+      button: {
+        label: "Learn More",
+        url: "{{companyServices.detailsUrl}}",
+        color: "btn-primary",
+      },
       loop: {
         over: "companyServices",
       },
@@ -312,6 +479,11 @@ export const examples: {
       colorPreset: { color: "secondary-100" },
       rounding: "rounded-md",
       shadow: "shadow-sm",
+      button: {
+        label: "View Project",
+        url: "{{portfolioWork.projectUrl}}",
+        color: "btn-secondary",
+      },
       loop: {
         over: "portfolioWork",
       },

package/src/shared/bricks/manifests/carousel.manifest.ts

@@ -9,13 +9,54 @@ import { roundingRef } from "../props/border";
 import { colorPresetRef } from "../props/color-preset";
 import { loopRef } from "../props/dynamic";
 import { cssLengthRef } from "../props/css-length";
+import type { BrickExample } from "./_types";
 
 export const manifest = defineBrickManifest({
   type: "carousel",
   name: "Carousel",
   description: "An image carousel with navigation arrows and dots or numbers indicator",
-  aiInstructions:
-    "Use this brick to create an image carousel or slideshow. It can display multiple images that users can navigate through using arrows or dots. Each image can have an optional legend or caption. This brick is ideal for showcasing portfolios, product images, or any visual content in an engaging way.",
+  aiInstructions: `Use the carousel component for showcasing sequential visual content with smooth navigation between images.
+
+WHEN TO USE:
+- Product galleries with multiple angles or variations
+- Portfolio showcases with project images
+- Step-by-step tutorials or processes (recipes, instructions)
+- Before/after comparisons or transformations
+- Team member profiles with photos
+- Event photo galleries or highlights
+- Feature demonstrations or software screenshots
+- Travel destinations or location showcases
+
+CONTENT GUIDELINES:
+- Optimal range: 2-8 images for best user engagement (max 12 supported)
+- Single image allowed only as placeholder for future expansion
+- Each image needs: { src: { src, alt }, legend }
+- Alt text MUST be descriptive and never empty
+- Legend text should be concise (≤90 characters) and informative
+- Use empty string ("") for legend only when no caption is intentionally desired
+
+IMAGE CONSISTENCY:
+- Keep aspect ratios similar across slides to prevent layout jumps
+- Avoid mixing very tall portrait with very wide landscape images
+- Use consistent image quality and style throughout carousel
+- Consider loading performance with image optimization
+
+STYLING OPTIONS:
+- padding: "0" for edge-to-edge, "1rem" for standard, "2rem+" for generous spacing
+- borderRadius: "rounded-none" for sharp/modern, "rounded-md" for standard, "rounded-xl" for friendly, "rounded-full" for circular (avatars)
+- colorPreset: Use sparingly - "neutral-50"/"primary-50" for subtle framing, gradients for premium feel
+
+DYNAMIC CONTENT:
+- Use loop property with single template object for data-driven carousels
+- Template variables in src and legend: "{{product.image}}", "{{team.name}} - {{team.role}}"
+- Perfect for: product catalogs, team directories, portfolio projects, event galleries
+
+AVOID:
+- Including unrelated properties (buttons, titles outside legend)
+- Heavy background colors that distract from images
+- Inconsistent aspect ratios that cause jarring transitions
+- More than 12 images (reduces focus and performance)
+- Empty or placeholder alt text (accessibility requirement)`,
   category: "media",
   defaultInspectorTab: "content",
   consumesMultipleQueryRows: true,
@@ -74,13 +115,10 @@ export const manifest = defineBrickManifest({
 
 export type Manifest = typeof manifest;
 
-export const examples: {
-  description: string;
-  type: string;
-  props: BrickProps<Manifest>["brick"]["props"];
-}[] = [
+export const examples: BrickExample<Manifest>[] = [
+  // BASIC CAROUSEL EXAMPLES
   {
-    description: "Basic image carousel with legends",
+    description: "Basic image carousel with legends - Simple content showcase",
     type: "carousel",
     props: {
       images: [
@@ -108,8 +146,10 @@ export const examples: {
       ],
     },
   },
+
+  // PRODUCT & COMMERCIAL
   {
-    description: "Product showcase carousel with rounded corners and padding",
+    description: "Product showcase carousel with rounded corners and padding - E-commerce gallery style",
     type: "carousel",
     props: {
       images: [
@@ -144,11 +184,13 @@ export const examples: {
       ],
       borderRadius: "rounded-xl",
       padding: "2rem",
-      colorPreset: { color: "gray-50" },
+      colorPreset: { color: "neutral-50" },
     },
   },
+
+  // PORTFOLIO & CREATIVE
   {
-    description: "Portfolio carousel with minimal styling",
+    description: "Portfolio carousel with minimal styling - Clean professional presentation",
     type: "carousel",
     props: {
       images: [
@@ -178,8 +220,10 @@ export const examples: {
       padding: "0",
     },
   },
+
+  // EVENTS & EXPERIENCES
   {
-    description: "Event photos carousel with primary color theme",
+    description: "Event photos carousel with primary color theme - Conference or gathering highlights",
     type: "carousel",
     props: {
       images: [
@@ -262,8 +306,10 @@ export const examples: {
       padding: "1rem",
     },
   },
+
+  // TEAM & PEOPLE
   {
-    description: "Team members carousel with blue color scheme",
+    description: "Team members carousel with circular images - Professional team showcase",
     type: "carousel",
     props: {
       images: [
@@ -296,13 +342,15 @@ export const examples: {
           legend: "Emily Chen - Marketing Director",
         },
       ],
-      colorPreset: { color: "blue-50" },
+      colorPreset: { color: "primary-50" },
       borderRadius: "rounded-full",
       padding: "2rem",
     },
   },
+
+  // TUTORIALS & PROCESSES
   {
-    description: "Recipe steps carousel with detailed descriptions",
+    description: "Recipe steps carousel with detailed descriptions - Step-by-step instructional content",
     type: "carousel",
     props: {
       images: [
@@ -335,7 +383,7 @@ export const examples: {
           legend: "Step 4: Season and serve hot",
         },
       ],
-      colorPreset: { color: "orange-50" },
+      colorPreset: { color: "accent-50" },
       borderRadius: "rounded-md",
       padding: "1.5rem",
     },
@@ -374,7 +422,7 @@ export const examples: {
           legend: "Living Room - After",
         },
       ],
-      colorPreset: { color: "green-50" },
+      colorPreset: { color: "accent-100" },
       borderRadius: "rounded-lg",
       padding: "1rem",
     },
@@ -406,7 +454,7 @@ export const examples: {
           legend: "Color Study #7 - 2024",
         },
       ],
-      colorPreset: { color: "gray-900" },
+      colorPreset: { color: "neutral-900" },
       borderRadius: "rounded-sm",
       padding: "3rem",
     },
@@ -459,7 +507,7 @@ export const examples: {
           legend: "Weekend Casual - Relaxed Fit",
         },
       ],
-      colorPreset: { color: "purple-100" },
+      colorPreset: { color: "secondary-100" },
       borderRadius: "rounded-xl",
       padding: "2rem",
     },
@@ -491,7 +539,7 @@ export const examples: {
           legend: "Electric Sedan",
         },
       ],
-      colorPreset: { color: "red-50" },
+      colorPreset: { color: "accent-50" },
       borderRadius: "rounded-lg",
       padding: "0.5rem",
     },
@@ -530,13 +578,13 @@ export const examples: {
           legend: "Security - Enterprise-grade protection",
         },
       ],
-      colorPreset: { color: "indigo-50" },
+      colorPreset: { color: "primary-50" },
       borderRadius: "rounded-2xl",
       padding: "4rem",
     },
   },
   {
-    description: "Dynamic product gallery using products query with pricing and details",
+    description: "Dynamic product gallery using products query - Data-driven product showcase",
     type: "carousel",
     props: {
       images: [
@@ -556,6 +604,90 @@ export const examples: {
       },
     },
   },
+
+  // DYNAMIC CONTENT EXAMPLES
+  {
+    description: "Loop template for portfolioProjects query (one object will repeat per row)",
+    type: "carousel",
+    props: {
+      images: [
+        {
+          src: {
+            src: "{{portfolioProjects.featuredImage}}",
+            alt: "{{portfolioProjects.projectName}} featured image",
+          },
+          legend:
+            "{{portfolioProjects.projectName}} – {{portfolioProjects.clientName}} ({{portfolioProjects.year}})",
+        },
+      ],
+      colorPreset: { color: "neutral-50" },
+      borderRadius: "rounded-md",
+      padding: "1rem",
+      loop: {
+        over: "portfolioProjects",
+      },
+    },
+  },
+
+  // SPECIAL STYLING VARIATIONS
+  {
+    description: "Showcase carousel with subtle gradient background frame",
+    type: "carousel",
+    props: {
+      images: [
+        {
+          src: { src: "https://via.placeholder.com/900x500.png?text=Showcase+1", alt: "Showcase slide 1" },
+          legend: "Launch Dashboard",
+        },
+        {
+          src: { src: "https://via.placeholder.com/900x500.png?text=Showcase+2", alt: "Showcase slide 2" },
+          legend: "Collaboration Tools",
+        },
+        {
+          src: { src: "https://via.placeholder.com/900x500.png?text=Showcase+3", alt: "Showcase slide 3" },
+          legend: "Usage Analytics",
+        },
+      ],
+      colorPreset: { color: "primary-gradient-300", gradientDirection: "bg-gradient-to-br" },
+      borderRadius: "rounded-xl",
+      padding: "2rem",
+    },
+  },
+  // MINIMAL EDGE (no padding, square corners)
+  {
+    description: "Minimal edge-to-edge carousel (no padding, no rounding)",
+    type: "carousel",
+    props: {
+      images: [
+        {
+          src: { src: "https://via.placeholder.com/800x400.png?text=Edge+1", alt: "Edge slide 1" },
+          legend: "",
+        },
+        {
+          src: { src: "https://via.placeholder.com/800x400.png?text=Edge+2", alt: "Edge slide 2" },
+          legend: "",
+        },
+      ],
+      borderRadius: "rounded-none",
+      padding: "0",
+    },
+  },
+  // SINGLE IMAGE (acts as prepared placeholder carousel)
+  {
+    description: "Single-image carousel (placeholder for future expansion)",
+    type: "carousel",
+    props: {
+      images: [
+        {
+          src: { src: "https://via.placeholder.com/1000x420.png?text=Banner", alt: "Promotional banner" },
+          legend: "Early Access Program",
+        },
+      ],
+      colorPreset: { color: "secondary-50" },
+      borderRadius: "rounded-lg",
+      padding: "1.25rem",
+    },
+  },
   {
     description: "Team member carousel using teamMembers query with roles and departments",
     type: "carousel",

package/src/shared/bricks/manifests/footer.manifest.ts

@@ -9,6 +9,7 @@ import { fontSizeRef } from "../props/text";
 import type { BrickProps } from "../props/types";
 import { toLLMSchema } from "~/shared/utils/llm";
 import { cssLengthRef } from "../props/css-length";
+import type { BrickExample } from "./_types";
 
 export const manifest = defineBrickManifest({
   type: "footer",
@@ -107,11 +108,7 @@ export const footerSchemaPropsLLM = toLLMSchema(manifest.props);
 
 export type FooterProps = Static<Manifest["props"]>;
 
-export const examples: {
-  description: string;
-  type: string;
-  props: BrickProps<Manifest>["brick"]["props"];
-}[] = [
+export const examples: BrickExample<Manifest>[] = [
   {
     description: "Simple footer with logo on the left",
     type: "footer",