@empline/preflight 1.1.11 → 1.1.13

package/dist/checks/consolidated/ui-spacing.d.ts

@@ -0,0 +1,751 @@
+#!/usr/bin/env tsx
+/**
+ * Consolidated UI Spacing Preflight
+ *
+ * Combines spacing checks into one comprehensive module:
+ * - card-content-padding (Card padding)
+ * - component-padding-validation (general padding)
+ * - footer-spacing-validation (footer margins)
+ * - header-spacing-consistency (header margins)
+ * - header-to-content-spacing (content after page headers)
+ * - action-button-spacing (buttons after cards)
+ * - section-to-section-spacing (KPIs, filters, tables spacing consistency)
+ * - cta-section-spacing (newsletter/CTA sections need top margin)
+ * - hero-section-spacing (hero/intro sections need vertical padding)
+ * - header-section-to-content-spacing (header sections need bottom margin before content)
+ * - breadcrumb-to-content-spacing (content after breadcrumbs needs top padding)
+ * - section-heading-spacing (h3-h6 headings need margins from surrounding content)
+ * - button-group-spacing (buttons need consistent spacing from preceding text)
+ * - stacked-padding (detects redundant padding in nested elements)
+ * - cta-card-spacing (CTA/promotional cards need mt-8 after visual content)
+ * - sibling-element-spacing (siblings need explicit spacing when not in Stack/flex with gap)
+ * - card-internal-spacing (Cards should have consistent internal structure)
+ * - visual-hierarchy-spacing (section-to-section spacing should be mt-8 minimum)
+ * - image-content-spacing (content after images/galleries needs proper spacing)
+ * - card-to-card-spacing (Cards following Cards need mt-8 minimum)
+ * - section-component-spacing (Section components need consistent margins)
+ * - typography-header-spacing (Typography headers need margin-bottom)
+ * - consistent-section-margins (Detect inconsistent margins in same file)
+ * - card-container-gap-consistency (STRICT: Card containers MUST use gap-6)
+ * - card-margin-consistency (Cards must not mix gap with margin)
+ *
+ * Usage:
+ *   pnpm preflight:ui-spacing              # All spacing checks
+ *   pnpm preflight:ui-spacing cards        # Card padding only
+ *   pnpm preflight:ui-spacing components   # Component padding only
+ *   pnpm preflight:ui-spacing footer       # Footer spacing only
+ *   pnpm preflight:ui-spacing header       # Header spacing only
+ *   pnpm preflight:ui-spacing sections     # Section-to-section spacing only
+ *   pnpm preflight:ui-spacing toolbar-gap  # DataTableToolbar → UnifiedEmptyState gap
+ *   pnpm preflight:ui-spacing cta          # CTA/Newsletter section spacing only
+ *   pnpm preflight:ui-spacing hero         # Hero/intro section spacing only
+ *   pnpm preflight:ui-spacing header-section # Header section to content spacing only
+ *   pnpm preflight:ui-spacing breadcrumb   # Breadcrumb-to-content spacing only
+ *   pnpm preflight:ui-spacing headings     # Section heading spacing only
+ *   pnpm preflight:ui-spacing buttons      # Button group spacing only
+ *   pnpm preflight:ui-spacing stacked      # Stacked padding detection only
+ *   pnpm preflight:ui-spacing cta-card     # CTA card spacing after visual content
+ *   pnpm preflight:ui-spacing siblings     # Sibling element spacing
+ *   pnpm preflight:ui-spacing card-internal # Card internal structure spacing
+ *   pnpm preflight:ui-spacing hierarchy    # Visual hierarchy spacing
+ *   pnpm preflight:ui-spacing image-content # Image to content spacing
+ *   pnpm preflight:ui-spacing card-to-card # Card-to-Card minimum spacing
+ *   pnpm preflight:ui-spacing section-component # Section component spacing
+ *   pnpm preflight:ui-spacing typography-header # Typography header margin-bottom
+ *   pnpm preflight:ui-spacing consistent-margins # Consistent section margins
+ *   pnpm preflight:ui-spacing card-gap     # Card container gap consistency (STRICT)
+ *   pnpm preflight:ui-spacing card-margin  # Card margin consistency
+ */
+interface Issue {
+    file: string;
+    line?: number;
+    type: string;
+    severity: "error" | "warning" | "info";
+    message: string;
+    suggestion?: string;
+    snippet?: string;
+}
+interface CheckResult {
+    name: string;
+    passed: boolean;
+    blocking: boolean;
+    issues: Issue[];
+    duration: number;
+}
+interface ModuleResult {
+    module: string;
+    passed: boolean;
+    totalDuration: number;
+    checks: CheckResult[];
+    summary: {
+        total: number;
+        passed: number;
+        failed: number;
+        errors: number;
+        warnings: number;
+    };
+}
+declare class UISpacingModule {
+    private verbose;
+    private parallel;
+    constructor(options?: {
+        verbose?: boolean;
+        parallel?: boolean;
+    });
+    /**
+     * Card Content Padding - ensures Cards use CardContent for proper padding
+     *
+     * Valid patterns:
+     * - Card with CardContent, CardHeader, or CardMedia children
+     * - Card with direct padding via sx={{ p: "var(--spacing-*)" }} or className="p-*"
+     */
+    checkCardPadding(): Promise<CheckResult>;
+    /**
+     * Component Padding Validation - checks for missing padding/gap
+     *
+     * NOTE: Many patterns are valid:
+     * - Tailwind gap-X classes
+     * - CSS-in-JS with design tokens
+     * - Flex/Grid with space-between (no gap needed)
+     * - Components that inherit spacing from parent
+     */
+    checkComponentPadding(): Promise<CheckResult>;
+    /**
+     * Footer Spacing Validation - ensures NO explicit bottom padding before Footer
+     *
+     * NEW CONVENTION: The Footer component now includes a spacer (h-16) at the top.
+     * Pages should NOT have paddingBottom on the main content container to avoid
+     * double spacing.
+     *
+     * Invalid patterns:
+     * - paddingBottom: "var(--spacing-*)" on main/content container
+     * - pb: "var(--spacing-*)" on main/content container
+     * - mb: "var(--spacing-*)" on last content element before Footer
+     * - Tailwind pb-* or mb-* classes
+     *
+     * Valid patterns:
+     * - No bottom spacing on the main container
+     */
+    checkFooterSpacing(): Promise<CheckResult>;
+    /**
+     * Header Spacing Consistency - checks UnifiedHeader margins
+     *
+     * The page header variant uses a Card with:
+     * - marginTop: 0 (layout provides top spacing)
+     * - marginBottom: 0 (layout provides bottom spacing via Stack/gap)
+     *
+     * This check validates these values are correct.
+     */
+    checkHeaderSpacing(): Promise<CheckResult>;
+    /**
+     * Header-to-Content Spacing - ensures content after page headers doesn't have doubled spacing
+     *
+     * UnifiedHeader variant="page" already has marginBottom: "var(--spacing-3)" (12px).
+     * Content after it should NOT add marginTop, as this creates doubled spacing.
+     *
+     * WRONG: UnifiedHeader (mb: 12px) + Stack (mt: 24px) = 36px gap (too much!)
+     * RIGHT: UnifiedHeader (mb: 12px) + Stack (no mt) = 12px gap (correct)
+     *
+     * Detects:
+     * - Stack/Box/div with marginTop or mt after UnifiedHeader variant="page"
+     * - style={{ marginTop: "var(--spacing-*)" }} patterns
+     * - sx={{ mt: "var(--spacing-*)" }} patterns
+     */
+    checkHeaderToContentSpacing(): Promise<CheckResult>;
+    /**
+     * Action Button Spacing - ensures buttons after cards/content have proper spacing
+     * Standard: Action buttons (Save, Submit, etc.) should have pt/mt spacing from preceding content
+     */
+    checkActionButtonSpacing(): Promise<CheckResult>;
+    /**
+     * Section-to-Section Spacing - ensures consistent spacing between major page sections
+     * Standard: Use --spacing-4 (16px) between adjacent sections (KPIs, filters, tables, etc.)
+     *
+     * Detects:
+     * - StatCardGrid/KPI sections with inconsistent margin-bottom
+     * - Filter cards with inconsistent margin-bottom
+     * - Doubled spacing (both mb on section A and mt on section B)
+     */
+    checkSectionSpacing(): Promise<CheckResult>;
+    /**
+     * Sibling Cards Gap Check - ensures containers with multiple Card children use gap
+     *
+     * Pattern to detect:
+     * - div/Box/Container containing multiple <Card> elements
+     * - Parent uses className="mb-4" on individual cards instead of gap on container
+     * - Parent has no gap property
+     * - Multiple sibling <Card> elements without gap on parent (even without mb-* classes)
+     * - Cards using mb-* where some cards have it and some don't (inconsistent spacing)
+     *
+     * Correct pattern:
+     * - Parent container should use style={{ display: "flex", flexDirection: "column", gap: "var(--spacing-4)" }}
+     * - Individual cards should NOT need mb-4 classes
+     */
+    checkSiblingCardsGap(): Promise<CheckResult>;
+    /**
+     * KPI to Content Spacing - ensures proper spacing after StatCardGrid/KPI sections
+     *
+     * Pattern to detect:
+     * - <StatCardGrid> or wrapper Box containing it, followed by <Card> without spacing
+     * - KPI sections immediately followed by content cards without gap
+     *
+     * Correct patterns (in order of preference):
+     * 1. Wrapper Box with style={{ marginBottom: "var(--spacing-8)" }} (PREFERRED)
+     * 2. Parent container with gap
+     * 3. Tailwind mb-* class (legacy, still accepted)
+     */
+    checkKpiToContentSpacing(): Promise<CheckResult>;
+    /**
+     * CTA Section Spacing - ensures proper spacing before newsletter/CTA sections
+     *
+     * Pattern to detect:
+     * - PaperCard/Card containing CTA text (Subscribe, Newsletter, Stay Updated, etc.)
+     * - Wrapper Box without proper top margin (mt-8, mt-12, mt-16)
+     * - CTA section immediately following content grid/list without gap
+     *
+     * Correct patterns:
+     * - CTA wrapper Box with className="mt-16" or similar large margin
+     * - Parent Stack with spacing that includes CTA
+     * - Explicit gap on parent container
+     */
+    checkCtaSectionSpacing(): Promise<CheckResult>;
+    /**
+     * Hero Section Spacing - ensures hero/intro sections have proper padding
+     *
+     * Pattern to detect:
+     * - Box/div with flex-col and centered text (hero layout)
+     * - Contains heading (h2, h3) + description Typography
+     * - Missing vertical padding (py-*) on the container
+     *
+     * Correct patterns:
+     * - Hero wrapper Box with className="py-6" or "py-8"
+     * - Box with padding: "var(--spacing-6) 0" or similar
+     *
+     * Hero patterns this catches:
+     * - "Help Center" + description + search box
+     * - Page intro sections with title + subtitle
+     * - Landing sections with centered headings
+     */
+    checkHeroSectionSpacing(): Promise<CheckResult>;
+    /**
+     * Header Section to Content Spacing - ensures proper margin after header sections
+     *
+     * Pattern to detect:
+     * - Box containing heading (h3, h4) + subtitle (h6, body1) followed by content grid/cards
+     * - Header section wrapper Box without marginBottom before content
+     * - Common in login pages, feature sections, dashboard headers
+     *
+     * Example of issue (LoginPerksSection):
+     * <Box>  <!-- Header section wrapper - NEEDS marginBottom -->
+     *   <Typography variant="h3">Welcome to SuperCatch</Typography>
+     *   <Typography variant="h6">The premier marketplace...</Typography>
+     * </Box>
+     * <div style={{ display: "grid" }}>  <!-- Content grid immediately follows -->
+     *
+     * Correct patterns:
+     * - Header Box with style={{ marginBottom: "var(--spacing-6)" }}
+     * - Header Box with className="mb-6" or "mb-8"
+     * - Parent container with gap that includes both header and content
+     */
+    checkHeaderSectionToContentSpacing(): Promise<CheckResult>;
+    /**
+     * Breadcrumb-to-Content Spacing - ensures content after UnifiedBreadcrumbs has proper top padding
+     *
+     * Pattern to detect:
+     * - UnifiedBreadcrumbs followed by content without paddingTop: "var(--spacing-3)"
+     * - Content areas that don't use DashboardPageLayout (which provides spacing automatically)
+     *
+     * Correct patterns:
+     * - DashboardPageLayout (provides paddingTop: spacing-3 automatically)
+     * - Box with paddingTop: "var(--spacing-3)" after breadcrumbs
+     * - Content with pt-3 class
+     * - Parent container with pt-3 that contains both breadcrumbs and content
+     *
+     * Why this matters:
+     * - Without top padding, content appears too close to breadcrumbs
+     * - Creates inconsistent spacing across pages
+     * - Standard is 12px (spacing-3) between breadcrumbs and content
+     */
+    checkBreadcrumbToContentSpacing(): Promise<CheckResult>;
+    /**
+     * Section Heading Spacing - ensures proper spacing around section headings
+     *
+     * COMPREHENSIVE CHECK for:
+     * 1. Section headings (h3, h4, h5, h6 Typography) need top margin from content above
+     * 2. Section headings need bottom margin before content below
+     * 3. Content grids/cards followed by headings without gap
+     * 4. Headings after Dividers need spacing
+     * 5. Box/Stack wrappers around headings without margin
+     *
+     * Standard spacing:
+     * - Major section headings (h3): mt-8 or mt-12 (32-48px) from content above
+     * - Sub-section headings (h4, h5, h6): mt-6 or mt-8 (24-32px) from content above
+     * - Bottom margin: mb-4 or mb-6 (16-24px) before content
+     *
+     * Exceptions (don't flag):
+     * - First heading after page header (UnifiedHeader handles spacing)
+     * - Headings inside Cards (Card padding provides spacing)
+     * - Headings with parent Stack spacing >= 3
+     */
+    checkSectionHeadingSpacing(): Promise<CheckResult>;
+    /**
+     * HTML Heading After Card Spacing - ensures HTML headings (h1-h6) have proper top margin after Card components
+     *
+     * Pattern to detect:
+     * - HTML heading elements (h1, h2, h3, h4, h5, h6) with mt-8 or less after a Card component
+     * - Section headings that need mt-12 (48px) minimum for proper visual separation
+     *
+     * Example of BAD pattern:
+     *   <Card>...</Card>
+     *   <div className="mt-8">           <- mt-8 (32px) is too little after a Card
+     *     <h5>Similar Items</h5>
+     *   </div>
+     *
+     * Correct patterns:
+     * - Use mt-12 (48px) or mt-16 (64px) for section headings after Cards
+     * - Use spacing-12 or spacing-16 CSS variables
+     */
+    checkHtmlHeadingAfterCardSpacing(): Promise<CheckResult>;
+    /**
+     * Section Container Spacing - ensures section heading containers have proper spacing
+     *
+     * Pattern to detect:
+     * - Box/div containing a section heading (h3-h6) that closes
+     * - Followed by sibling content (Card, Box, etc.) without gap
+     * - The heading's wrapper Box has no bottom margin
+     *
+     * Example of BAD pattern:
+     *   <Box className="mt-8">           <- has top margin, good
+     *     <Stack className="mb-4">       <- inner margin doesn't help
+     *       <Typography variant="h3">FAQ</Typography>
+     *     </Stack>
+     *   </Box>                           <- Box closes with no bottom margin
+     *   <Card>...</Card>                 <- Card starts immediately - NO GAP!
+     *
+     * Correct patterns:
+     * - Box wrapper has mb-4 or mb-6 className
+     * - Parent container has gap property
+     * - Card has mt-4 or mt-6 className
+     */
+    checkSectionContainerSpacing(): Promise<CheckResult>;
+    /**
+     * Button Group Spacing - ensures buttons have consistent spacing from preceding text
+     *
+     * Pattern to detect:
+     * - Stack/Box containing Button(s) after Typography paragraph text
+     * - CardContent with text followed by buttons without top margin on button container
+     * - Buttons get bottom padding from CardContent but no top spacing from text above
+     *
+     * Correct patterns:
+     * - Stack with spacing prop that includes both text and buttons
+     * - Button container with mt-4 or marginTop: "var(--spacing-4)"
+     * - Parent flex container with gap
+     *
+     * Standard: Buttons should have at least 16px (--spacing-4) margin from preceding text
+     */
+    checkButtonGroupSpacing(): Promise<CheckResult>;
+    /**
+     * Upload Progress Stepper Stats Spacing
+     * Ensures the approved/pending/total summary has bottom padding so it doesn't
+     * visually collide with the next section.
+     */
+    checkUploadProgressStepperStatsSpacing(): Promise<CheckResult>;
+    /**
+     * UnifiedFileInterface Dropzone Padding
+     *
+     * Ensures the expanded empty-state drop zone uses design-token padding and stays
+     * within a reasonable range so it visually aligns with surrounding Cards.
+     */
+    checkUnifiedFileInterfaceDropzonePadding(): Promise<CheckResult>;
+    /**
+     * CTA Card Spacing - ensures promotional/CTA cards have adequate spacing from surrounding content
+     *
+     * CTA cards (gradient backgrounds, promotional content) need more visual separation
+     * than regular content to stand out and not feel cramped.
+     *
+     * BAD patterns:
+     * - CTA card with mt-4 or mt-6 after image gallery (needs mt-8 minimum)
+     * - CTA card with no top margin after content
+     * - Promotional box touching image/gallery above
+     *
+     * GOOD patterns:
+     * - CTA card with mt-8 or mt-12 after images/galleries
+     * - CTA card inside its own section with proper spacing
+     */
+    checkCtaCardSpacing(): Promise<CheckResult>;
+    /**
+     * Sibling Element Spacing - ensures sibling elements have consistent spacing
+     *
+     * When elements are siblings (not in a Stack/flex with gap), they need explicit margins.
+     * This check finds cases where sibling elements have inconsistent or missing spacing.
+     *
+     * BAD patterns:
+     * - Component followed by Box with no margin
+     * - Card followed by Card with only mt-4 (should be mt-6 or mt-8)
+     * - Image/Gallery followed by content with insufficient margin
+     *
+     * GOOD patterns:
+     * - Siblings in Stack with spacing prop
+     * - Siblings in flex container with gap
+     * - Explicit mt-6 or mt-8 between major sections
+     *
+     * Context-aware exclusions:
+     * - Stack with className (flex column by default)
+     * - Loading/skeleton files (layout handled by skeleton structure)
+     * - Card internal structure (Box after CardContent is card footer)
+     * - Tab content (Box after List in TabPanel is intentional)
+     * - Hero/section components (internal layout is self-contained)
+     * - Error pages (centered content doesn't need top margin)
+     * - Elements with flex-1 (flex children handle their own spacing)
+     * - Elements with padding (py-*, pt-*, p-*) already have spacing
+     */
+    checkSiblingElementSpacing(): Promise<CheckResult>;
+    /**
+     * Card Internal Spacing Consistency - ensures Cards have consistent internal spacing
+     *
+     * Cards should have consistent padding and internal element spacing.
+     * This check finds Cards with ACTUAL inconsistent internal structure.
+     *
+     * BAD patterns (actual issues):
+     * - Card with p-4 containing CardContent with p-4 (DOUBLE padding)
+     * - Card with NO padding AND no CardContent (content touches edges)
+     *
+     * VALID patterns (not flagged):
+     * - Card with className="p-*" (Tailwind padding is valid)
+     * - Card with style={{ padding: "var(--spacing-*)" }} (inline padding is valid)
+     * - Card > CardContent (standard MUI pattern)
+     * - Card > CardMedia (image cards don't need padding)
+     * - Card > CardHeader (header provides its own padding)
+     * - Clickable/interactive cards (often intentionally edge-to-edge)
+     * - Nested Cards (each Card manages its own padding)
+     */
+    checkCardInternalSpacing(): Promise<CheckResult>;
+    /**
+     * Dashboard Layout Double Padding - prevents padding being applied both by DashboardPageLayout
+     * (which already sets paddingTop + paddingLeft/right) and by the page's immediate child wrapper.
+     *
+     * Why:
+     * - Creates inconsistent outer-edge spacing vs internal grid gaps (e.g. gap-4)
+     * - Regressions are easy to introduce when wrapping content in <Stack> / <Box>
+     *
+     * Enforcement:
+     * - If a file uses DashboardPageLayout / SellerPageLayout / AccountPageLayout / AdminPageLayout,
+     *   then any DIRECT child wrapper element (<Stack>, <Box>, <div>, <main>, <section>) must NOT
+     *   apply padding via Tailwind (p-*, px-*, py-*, pt-*, etc.) or inline style (padding*).
+     *
+     * NOTE: This check uses a simplified approach - it only flags the FIRST wrapper element
+     * directly after the layout opening tag, not nested elements.
+     */
+    checkDashboardLayoutDoublePadding(): Promise<CheckResult>;
+    /**
+     * Visual Hierarchy Spacing - ensures proper spacing based on visual hierarchy
+     *
+     * Different types of content need different amounts of spacing:
+     * - Major sections: mt-12 or mt-16
+     * - Sub-sections: mt-8
+     * - Related content: mt-4 or mt-6
+     * - Inline elements: mt-2
+     *
+     * This check identifies spacing that doesn't match the visual hierarchy.
+     */
+    checkVisualHierarchySpacing(): Promise<CheckResult>;
+    /**
+     * Image-to-Content Spacing - ensures proper spacing after images and galleries
+     *
+     * Images and galleries need adequate spacing from content below them.
+     * This is especially important for:
+     * - Product images followed by CTAs
+     * - Gallery thumbnails followed by descriptions
+     * - Hero images followed by content
+     */
+    checkImageToContentSpacing(): Promise<CheckResult>;
+    /**
+     * Card-to-Card Minimum Spacing - ensures Cards have proper separation
+     *
+     * When Card components follow other Cards, they need mt-8 minimum (32px)
+     * for proper visual separation. mt-4 or mt-6 makes Cards feel cramped.
+     *
+     * BAD patterns:
+     * - <Card className="mt-4"> after another Card
+     * - <Card className="mt-6"> after another Card (borderline)
+     * - <Card> with no margin after another Card
+     *
+     * GOOD patterns:
+     * - <Card className="mt-8"> after another Card
+     * - <Card className="mt-10"> or mt-12 for major section breaks
+     * - Cards inside Stack with spacing={4} (32px)
+     * - Cards inside containers with gap-* or gap: var(--spacing-*)
+     * - Cards in different conditional branches (ternary, &&)
+     * - Cards in different return statements (early returns)
+     */
+    checkCardToCardSpacing(): Promise<CheckResult>;
+    /**
+     * Section Component Spacing - ensures named section components have consistent margins
+     *
+     * Components with "Section" in their name (CardDetailsSection, SimilarItems, etc.)
+     * should have consistent top margins when used as page sections.
+     *
+     * Standard: Section components should have mt-8 to mt-12 for visual separation.
+     * Exception: Components inside containers with gap are already spaced.
+     */
+    checkSectionComponentSpacing(): Promise<CheckResult>;
+    /**
+     * Typography Header Spacing - ensures headers have consistent margin-bottom
+     *
+     * Typography headers (h1-h6, variant="h*") should have consistent spacing
+     * before the content that follows them.
+     *
+     * Standard:
+     * - h1/h2: mb-6 or gutterBottom
+     * - h3/h4: mb-4 or gutterBottom
+     * - h5/h6: mb-2 or gutterBottom
+     */
+    checkTypographyHeaderSpacing(): Promise<CheckResult>;
+    /**
+     * Consistent Page Section Margins - detects inconsistent margins in the same file
+     *
+     * Within a single page/component, section margins should be consistent.
+     * If one section uses mt-8, others should too (not a mix of mt-4, mt-6, mt-8, mt-12).
+     */
+    checkConsistentSectionMargins(): Promise<CheckResult>;
+    /**
+     * Stacked Padding Detection - finds redundant padding in nested elements
+     *
+     * Detects patterns where parent and child both have padding, creating
+     * excessive spacing that should be consolidated.
+     *
+     * BAD patterns:
+     * - <Box className="p-2"><Box className="p-2">  (should be p-4 on one)
+     * - <CardContent className="p-4"><Box className="p-4">  (redundant)
+     * - <div className="p-3"><div className="p-3">  (should consolidate)
+     *
+     * GOOD patterns:
+     * - <Box className="p-4"><Box>  (only parent has padding)
+     * - <CardContent><Box className="p-4">  (CardContent has default, child adds more intentionally)
+     * - <Box className="p-4"><Box className="mt-2">  (margin, not padding)
+     * - Table cells with p-2 (siblings, not nested)
+     */
+    checkStackedPadding(): Promise<CheckResult>;
+    /**
+     * Card Container Gap Consistency - STRICT enforcement of gap-6 for card containers
+     *
+     * STANDARD: All containers holding multiple Cards MUST use gap-6 (24px).
+     * This ensures visual consistency across the entire application.
+     *
+     * VIOLATIONS:
+     * - gap-4 (16px) - too tight between cards
+     * - gap-8 (32px) - too loose, wastes space
+     * - mt-* on Cards inside containers with gap - double spacing!
+     * - Mixing gap with mt-* on children
+     *
+     * VALID:
+     * - gap-6 or gap: var(--spacing-6) on container
+     * - Stack spacing={6} for card containers
+     * - Grid with gap-6
+     */
+    checkCardContainerGapConsistency(): Promise<CheckResult>;
+    /**
+     * Card Margin Consistency - ensures Cards don't mix gap with margin
+     *
+     * RULE: If a Card is inside a flex/grid container with gap, it should NOT have mt-*.
+     * If Cards are NOT in a gap container, they MUST have mt-6 between them.
+     */
+    checkCardMarginConsistency(): Promise<CheckResult>;
+    /**
+     * CSS Style Tag Gap Check - catches gaps defined in <style> tags
+     *
+     * ISSUE: CSS Grid gaps defined in <style> tags using --spacing-3 (12px) are too small
+     * for card grids. The standard is --spacing-4 (16px) minimum.
+     *
+     * This check catches patterns like:
+     * - <style>{`.grid { gap: var(--spacing-3); }`}</style>
+     * - style={{ gap: "var(--spacing-3)" }}
+     *
+     * STANDARD: Card grids should use --spacing-4 (16px) minimum
+     * EXCEPTION: Product grids can use gap-3 for dense layouts
+     */
+    checkStyleTagGapSize(): Promise<CheckResult>;
+    /**
+     * KPI Card Grid Gap - enforce tight KPI spacing
+     *
+     * Problem: Stat/KPI cards can feel overly spaced when the grid wraps ("stacked")
+     * on smaller desktop widths.
+     *
+     * Standard: StatCardGrid uses `gap: var(--spacing-3)`.
+     */
+    checkKpiCardGridGap(): Promise<CheckResult>;
+    /**
+     * CardContent Minimum Padding Check - ensures cards have adequate internal padding
+     *
+     * ISSUE: CardContent with p-4 (16px) can make icons/content feel cramped at card edges.
+     * The standard is p-6 (24px) for stat cards and content-heavy cards.
+     *
+     * STANDARD:
+     * - StatCard, KPI cards: p-6 minimum
+     * - Dense data tables: p-4 acceptable
+     * - Simple cards with minimal content: p-4 acceptable
+     */
+    checkCardContentMinimumPadding(): Promise<CheckResult>;
+    /**
+     * Toolbar-to-Content Spacing Consistency
+     *
+     * Goal: keep the gap between filter/search toolbars and the content they control
+     * consistent across the app.
+     *
+     * Regression pattern we want to catch broadly:
+     * - <DataTableToolbar ... />
+     * - Followed by primary content (UnifiedEmptyState, Card/table region, etc.)
+     * - Both are siblings inside a Stack with spacing={4}+ (16px+)
+     *
+     * Standard:
+     * - Toolbar ${chars.arrow} controlled content: Stack spacing={3} (12px)
+     * - Major section → major section remains handled by existing checks
+     *
+     * Heuristic (low-noise):
+     * - Find <DataTableToolbar ...>
+     * - Find the next “content start” within a short window
+     * - If there is no nested <Stack spacing={1|2|3}> between them
+     * - And nearest enclosing <Stack spacing={N}> has N >= 4, warn
+     */
+    checkToolbarToContentSpacing(): Promise<CheckResult>;
+    /**
+     * KPI-to-Toolbar Spacing Consistency
+     *
+     * On seller/dashboard listing pages, the KPI grid (StatCardGrid / ListingStatisticsCards)
+     * is commonly followed by a filter/search toolbar. This relationship should be tight
+     * (spacing={3}) rather than a looser section spacing.
+     *
+     * Detects:
+     * - A KPI block (ListingStatisticsCards or StatCardGrid)
+     * - Followed shortly by a DataTableToolbar
+     * - Enclosed by a Stack spacing={4}+ without an intervening tighter Stack
+     */
+    checkKpiToToolbarSpacing(): Promise<CheckResult>;
+    /**
+     * Nested Stack Same Spacing Detection
+     *
+     * Detects when a Stack with spacing={N} is directly nested inside another
+     * Stack with the same spacing value. This creates redundant/double gaps
+     * and is almost always a mistake.
+     *
+     * Example of issue (from /store/orders):
+     * <Stack spacing={6}>
+     *   <OrderStatsCards />
+     *   <Stack spacing={6}>        <!-- REDUNDANT - creates double gap -->
+     *     <DataTableToolbar />
+     *     <Card>...</Card>
+     *   </Stack>
+     * </Stack>
+     *
+     * Correct pattern:
+     * <Stack spacing={6}>
+     *   <OrderStatsCards />
+     *   <Stack spacing={3}>        <!-- Different spacing for toolbar→content -->
+     *     <DataTableToolbar />
+     *     <Card>...</Card>
+     *   </Stack>
+     * </Stack>
+     *
+     * Or flatten:
+     * <Stack spacing={6}>
+     *   <OrderStatsCards />
+     *   <DataTableToolbar />
+     *   <Card>...</Card>
+     * </Stack>
+     */
+    checkNestedStackSameSpacing(): Promise<CheckResult>;
+    /**
+     * Dashboard Gutter Consistency
+     *
+     * Ensures the seller/account/admin dashboard “outer gutter” is consistent:
+     * - DashboardPageLayout default paddingX is var(--spacing-3)
+     * - UnifiedBreadcrumbs default horizontal padding is var(--spacing-3)
+     * - UnifiedHeader (page variant) uses paddingLeft/right var(--spacing-3)
+     *   and actions inset right var(--spacing-3)
+     */
+    checkDashboardGutterConsistency(): Promise<CheckResult>;
+    /**
+     * Page Rhythm Utility Spacing (page-level only)
+     *
+     * Standard: Page-level vertical rhythm is controlled by Stack spacing tokens
+     * and component defaults (e.g., UnifiedHeader page mb is spacing-3).
+     *
+     * Rule: disallow Tailwind `mt-3` and `mt-6` in page-level layout files.
+     * We intentionally do NOT scan component libraries broadly to avoid false
+     * positives in dialogs/forms/prose components.
+     *
+     * Files scanned:
+     * - app/<any>/page.tsx
+     * - app/<any>PageClient.tsx
+     * - app/<any>Client.tsx that include a page layout wrapper
+     */
+    checkPageRhythmUtilitySpacing(): Promise<CheckResult>;
+    /**
+     * CardContent First-Child Spacing Consistency
+     *
+     * Goal: Ensure consistent top padding inside CardContent by preventing
+     * margin-top classes on first child elements.
+     *
+     * Problem: When Typography or other elements inside CardContent have mt-* classes,
+     * it creates inconsistent spacing between sibling cards in the same grid.
+     * CardContent already provides consistent padding - adding margin-top to the
+     * first child creates uneven visual appearance.
+     *
+     * Standard:
+     * - First child of CardContent should NOT have mt-* classes
+     * - Let CardContent padding handle the top spacing
+     * - Use Stack spacing={} for internal element spacing
+     *
+     * Valid patterns:
+     * - <CardContent><Typography variant="h6">Title</Typography>
+     * - <CardContent className="p-4"><Box>...</Box>
+     *
+     * Invalid patterns:
+     * - <CardContent><Typography className="mt-3" variant="h6">Title</Typography>
+     * - <CardContent><Box className="mt-6">...</Box>
+     */
+    checkCardContentFirstChildSpacing(): Promise<CheckResult>;
+    /**
+     * Subtitle to Content Spacing - ensures proper margin between section subtitles and following content
+     *
+     * PATTERNS DETECTED:
+     *
+     * 1. FORM PATTERN (BLOCKING):
+     *    Typography h6 title ${chars.arrow} Typography body2 subtitle → Stack with form fields
+     *    Without mb-4 on subtitle, TextField labels overlap with subtitle text
+     *
+     * 2. CARD CONTENT PATTERN (BLOCKING):
+     *    Inside CardContent: Typography h6 → Typography body2 subtitle → Stack/Box content
+     *    Without mb-4, content crowds the subtitle
+     *
+     * 3. DIALOG/MODAL PATTERN (BLOCKING):
+     *    DialogContent: Typography title → Typography body2 description → form/content
+     *    Common in confirmation dialogs, settings modals
+     *
+     * Example of issue:
+     * <Typography variant="h6">Account Settings</Typography>
+     * <Typography variant="body2" color="text.secondary">
+     *   Manage your account preferences
+     * </Typography>
+     * <Stack spacing={3}>  <!-- NO margin between subtitle and form! -->
+     *   <TextField label="Email" />
+     *
+     * Correct pattern:
+     * <Typography variant="h6">Account Settings</Typography>
+     * <Typography variant="body2" color="text.secondary" className="mb-4">
+     *   Manage your account preferences
+     * </Typography>
+     * <Stack spacing={3}>
+     *   <TextField label="Email" />
+     *
+     * Why this matters:
+     * - Without margin, content overlaps or crowds the subtitle text
+     * - Creates visual confusion and poor UX
+     * - Standard is mb-4 (16px) between subtitle and content
+     */
+    checkSubtitleToContentSpacing(): Promise<CheckResult>;
+    runAll(): Promise<ModuleResult>;
+    printResults(checks: CheckResult[], totalDuration: number, summary: any, hasBlockingFailure: boolean): void;
+}
+export { UISpacingModule };
+//# sourceMappingURL=ui-spacing.d.ts.map