feat: introduce flat variant for SummaryCard with edge-to-edge layout

JakeLin · JakeLin · commit 90284d941139 · 2025-11-06T17:58:32.000+11:00
Add a new "flat" variant to the SummaryCard component, allowing for an edge-to-edge design without padding or elevation. This variant is ideal for seamless integration in grid layouts and carousels.

Key changes:
- Update SummaryCard styles to remove padding and border for the flat variant.
- Enhance the component's props to include a variant option.
- Add new stories to demonstrate the flat variant's use cases and layout.
- Adjust button width behavior based on the selected variant.

These updates improve the flexibility and usability of the SummaryCard component in various design contexts.
diff --git a/packages/ui/src/components/Card/SummaryCard.module.css b/packages/ui/src/components/Card/SummaryCard.module.css
@@ -6,6 +6,11 @@
   overflow: hidden;
 }
 
+/* Flat variant - Remove border for seamless appearance */
+.summaryCard[data-variant='flat'] {
+  border: none;
+}
+
 /* Image Section */
 .imageSection {
   margin: 0;
@@ -166,6 +171,11 @@
   gap: var(--ai-spacing-4); /* 8px between elements inside content */
 }
 
+/* Flat variant - Remove horizontal padding for edge-to-edge layout */
+.summaryCard[data-variant='flat'] .contentSection {
+  padding: 0;
+}
+
 /* Title Row - Title/subtitle + badge on same row */
 .titleRow {
   display: flex;
@@ -256,10 +266,23 @@
   padding: 0 var(--ai-spacing-2); /* 0 vertical, 4px horizontal - creates 12px total with card padding */
 }
 
+/* Flat variant - Remove horizontal padding for edge-to-edge layout */
+.summaryCard[data-variant='flat'] .buttonSection {
+  padding: 0;
+}
+
 .button {
   width: 100%;
 }
 
+/* Desktop: Button auto-width when not full-width */
+@media (min-width: 768px) {
+  .buttonSection[data-full-width='false'] .button {
+    width: auto;
+    min-width: 120px;
+  }
+}
+
 /* Error State */
 .errorContainer {
   padding: 0; /* Card padding handles spacing */
diff --git a/packages/ui/src/components/Card/SummaryCard.stories.tsx b/packages/ui/src/components/Card/SummaryCard.stories.tsx
@@ -450,6 +450,79 @@ const SummaryCardsComponent: React.FC = () => {
         </div>
       </section>
 
+      {/* Flat Variant - Edge-to-Edge Layout */}
+      <section style={{ marginBottom: '64px' }}>
+        <header style={{ marginBottom: '24px' }}>
+          <h2 style={{ marginBottom: '8px' }}>Flat Variant - Edge-to-Edge Layout</h2>
+          <p style={{ color: 'var(--ai-color-text-secondary)', margin: 0, fontSize: '14px' }}>
+            Zero-elevation, edge-to-edge layout with no padding. Perfect for seamless integration in grids, carousels, or when the container provides spacing. Uses variant="flat".
+          </p>
+        </header>
+
+        <div
+          style={{
+            display: 'grid',
+            gridTemplateColumns: 'repeat(auto-fill, minmax(320px, 1fr))',
+            gap: '24px',
+            alignItems: 'start',
+          }}
+        >
+          <SummaryCard
+            variant="flat"
+            images={SAMPLE_IMAGES.restaurant}
+            title="Flat Variant"
+            subtitle="No padding or elevation"
+            badge="9.2"
+            description="Content extends to card edges for seamless layouts"
+            buttonText="View Details"
+            style={{ maxWidth: `${CARD_WIDTH}px` }}
+          />
+          <SummaryCard
+            variant="flat"
+            images={[
+              { src: SAMPLE_IMAGES.pizza, alt: 'Pizza' },
+              { src: SAMPLE_IMAGES.pasta, alt: 'Pasta' },
+              { src: SAMPLE_IMAGES.salad, alt: 'Salad' },
+            ]}
+            title="Grid with Flat"
+            subtitle="Edge-to-edge grid"
+            badge="9.0"
+            description="Image grid and content aligned to edges"
+            buttonText="Explore"
+            style={{ maxWidth: `${CARD_WIDTH}px` }}
+          />
+          <SummaryCard
+            variant="flat"
+            size="compact"
+            imageAspectRatio="4/3"
+            images={SAMPLE_IMAGES.restaurant}
+            title="Flat + Compact"
+            subtitle="Dense & seamless"
+            badge="8.8"
+            description="Combine flat variant with compact size"
+            metadata={[
+              { label: '$$$', separator: '•' },
+              { label: 'Italian', separator: '•' },
+              { label: 'Open' },
+            ]}
+            buttonText="Order Now"
+            style={{ maxWidth: `${CARD_WIDTH}px` }}
+          />
+        </div>
+
+        <div style={{ marginTop: '24px', background: 'var(--ai-color-bg-secondary)', border: '1px solid var(--ai-color-border)', borderRadius: '8px', padding: '16px' }}>
+          <h3 style={{ fontSize: '14px', fontWeight: '600', marginBottom: '8px', color: 'var(--ai-color-text-primary)' }}>
+            Use Cases
+          </h3>
+          <ul style={{ margin: 0, paddingLeft: '20px', fontSize: '13px', lineHeight: '1.6', color: 'var(--ai-color-text-secondary)' }}>
+            <li><strong>Tight Grids:</strong> Cards in dense grid layouts where container provides spacing</li>
+            <li><strong>Carousels:</strong> Seamless scrolling experiences without visual gaps</li>
+            <li><strong>Mobile Optimization:</strong> Maximize content area on small screens</li>
+            <li><strong>Custom Containers:</strong> When parent element handles padding and elevation</li>
+          </ul>
+        </div>
+      </section>
+
       {/* Discovery/Browse Mode - Compact Size (NEW - replaces DiscoveryCard) */}
       <section style={{ marginBottom: '64px' }}>
         <header style={{ marginBottom: '24px' }}>
@@ -915,6 +988,24 @@ const SummaryCardsComponent: React.FC = () => {
               default: "'default'",
               description: 'Badge styling variant',
             },
+            {
+              name: 'variant',
+              type: "'default' | 'flat'",
+              default: "'default'",
+              description: 'Card variant - "flat" for edge-to-edge layout with no padding or elevation',
+            },
+            {
+              name: 'size',
+              type: "'default' | 'compact'",
+              default: "'default'",
+              description: 'Card size/density - "compact" for dense layouts',
+            },
+            {
+              name: 'imageAspectRatio',
+              type: "'auto' | '16/9' | '4/3' | '1/1'",
+              default: "'auto'",
+              description: 'Image aspect ratio for single images',
+            },
             {
               name: 'description',
               type: 'string',
@@ -936,6 +1027,12 @@ const SummaryCardsComponent: React.FC = () => {
               type: '() => void',
               description: 'Button click handler',
             },
+            {
+              name: 'buttonFullWidth',
+              type: 'boolean',
+              default: 'Auto (true for default, false for flat)',
+              description: 'Button full width on desktop. Auto-determined based on variant if not set.',
+            },
             {
               name: 'loading',
               type: 'boolean',
diff --git a/packages/ui/src/components/Card/SummaryCard.tsx b/packages/ui/src/components/Card/SummaryCard.tsx
@@ -83,6 +83,14 @@ export interface SummaryCardProps extends Omit<CardProps, 'children'> {
    */
   badgeVariant?: BadgeVariant;
 
+  /**
+   * Card variant
+   * - "default": Standard card with padding and elevation
+   * - "flat": Edge-to-edge layout with no padding or elevation
+   * @default "default"
+   */
+  variant?: 'default' | 'flat';
+
   /**
    * Card size/density
    * - "default": Spacious layout, heading3 title, bodySmall subtitle
@@ -147,6 +155,15 @@ export interface SummaryCardProps extends Omit<CardProps, 'children'> {
    */
   buttonDisabled?: boolean;
 
+  /**
+   * Button full width on desktop.
+   * - undefined: Auto (full-width for default variant, auto-width for flat variant)
+   * - true: Full width on all screen sizes
+   * - false: Auto width on desktop (min 120px), full width on mobile
+   * @default undefined (auto based on variant)
+   */
+  buttonFullWidth?: boolean;
+
   // Phase 1: Critical Improvements (P0)
   /**
    * Loading state - shows skeleton UI
@@ -275,13 +292,15 @@ export const SummaryCard = React.forwardRef<HTMLDivElement, SummaryCardProps>((p
     subtitle,
     badge,
     badgeVariant = 'default',
+    variant = 'default',
     size = 'default',
     imageAspectRatio = 'auto',
     description,
     metadata,
     buttonText,
     onButtonClick,
     buttonDisabled = false,
+    buttonFullWidth,
     // Phase 1 props
     loading = false,
     loadingImageCount,
@@ -327,6 +346,10 @@ export const SummaryCard = React.forwardRef<HTMLDivElement, SummaryCardProps>((p
   const defaultLoadingCount = hasImages && !isSingleImage ? 3 : 1;
   const skeletonImageCount = loadingImageCount ?? defaultLoadingCount;
 
+  // Button width logic: auto-determine based on variant if not explicitly set
+  // Default variant: full-width, Flat variant: auto-width (not full)
+  const isButtonFullWidth = buttonFullWidth ?? variant === 'default';
+
   // Helper to render badge/chip based on text length
   const renderBadge = () => {
     if (badge === undefined) return null;
@@ -351,9 +374,11 @@ export const SummaryCard = React.forwardRef<HTMLDivElement, SummaryCardProps>((p
   return (
     <Card
       ref={ref}
-      padding={8}
+      padding={variant === 'flat' ? 0 : 8}
+      elevationLevel={variant === 'flat' ? 0 : cardProps.elevationLevel}
       className={cn(styles.summaryCard, className)}
       data-size={size}
+      data-variant={variant}
       {...cardProps}
     >
       {/* Loading State - Single Image */}
@@ -593,7 +618,7 @@ export const SummaryCard = React.forwardRef<HTMLDivElement, SummaryCardProps>((p
 
           {/* Action Button */}
           {hasButton && (
-            <div className={styles.buttonSection}>
+            <div className={styles.buttonSection} data-full-width={isButtonFullWidth}>
               <Button
                 variant="primary"
                 onClick={onButtonClick}
