@julianoczkowski/create-trimble-app 2.0.0

package/templates/angular/.cursor/rules/ux/gestalt-laws-detailed.mdc

@@ -0,0 +1,514 @@
+---
+description: Gestalt Laws implementation guide for UI design with Modus Design System
+globs: ["**/*.ts", "**/*.html", "**/*.scss", "**/*.css"]
+alwaysApply: false
+---
+
+# Gestalt Laws in UI Design
+
+**Scope**: Comprehensive Gestalt Laws with Real-World Examples and Modus Design System Integration for Angular
+
+The Gestalt Laws are fundamental principles of visual perception that explain how humans naturally organize visual elements. When applied to UI design, these laws create intuitive, user-friendly interfaces that feel natural and reduce cognitive load.
+
+---
+
+## 1. Law of Proximity
+
+**Definition:** Elements that are close together are perceived as related or grouped together.
+
+**Real-World Example:** In a contact list, the name, phone number, and email address for each person are grouped closely together with small gaps (`gap-2`), while each contact is separated by larger gaps (`gap-6` to `gap-8`) from other contacts.
+
+**Implementation:**
+
+```html
+<!-- Contact list example -->
+<div class="space-y-6">
+  @for (contact of contacts(); track contact.id) {
+    <div class="flex items-center gap-2 p-4 bg-card border-default rounded-lg">
+      <modus-avatar [name]="contact.name" size="md" />
+      <div class="flex flex-col gap-1">
+        <div class="text-foreground font-medium">{{ contact.name }}</div>
+        <div class="text-foreground-60 text-sm">{{ contact.email }}</div>
+        <div class="text-foreground-60 text-sm">{{ contact.phone }}</div>
+      </div>
+    </div>
+  }
+</div>
+```
+
+**Key Rules:**
+
+- Use `gap-2` for related elements within a group
+- Use `gap-6` to `gap-8` for separation between different groups
+- Group form labels with their inputs using `gap-2`
+- Separate different sections with `gap-6` or larger
+
+---
+
+## 2. Law of Similarity
+
+**Definition:** Elements that look similar (same color, shape, size, or style) are perceived as related or belonging to the same category.
+
+**Real-World Example:** In a dashboard, all primary action buttons use the same `color="primary"` style, all secondary actions use `color="secondary"`, and all destructive actions use `color="danger"`. This creates visual consistency that users can quickly understand.
+
+**Implementation:**
+
+```html
+<!-- Dashboard action buttons -->
+<div class="flex gap-4">
+  <modus-button color="primary" size="md">Save Changes</modus-button>
+  <modus-button color="secondary" size="md">Cancel</modus-button>
+  <modus-button color="danger" size="md">Delete</modus-button>
+</div>
+
+<!-- Status indicators -->
+<div class="flex gap-2">
+  <modus-badge color="success">Active</modus-badge>
+  <modus-badge color="warning">Pending</modus-badge>
+  <modus-badge color="error">Error</modus-badge>
+</div>
+```
+
+**Key Rules:**
+
+- Same purpose = same variant, same size
+- Use consistent color coding for status indicators
+- Maintain visual hierarchy through consistent styling
+- Group similar interactive elements together
+
+---
+
+## 3. Law of Common Region
+
+**Definition:** Elements that are enclosed within the same boundary are perceived as related or grouped together.
+
+**Real-World Example:** In an e-commerce product page, all product details (name, price, description, specifications) are contained within a single card, while customer reviews are in a separate card below. This creates clear visual separation between different types of information.
+
+**Implementation:**
+
+```html
+<!-- Product details card -->
+<modus-card class="p-6 bg-card border-default rounded-lg">
+  <div class="space-y-4">
+    <div class="flex items-start justify-between">
+      <div class="text-2xl font-bold text-foreground">Product Name</div>
+      <div class="text-3xl font-bold text-primary">$99.99</div>
+    </div>
+    <div class="text-foreground-60">Product description goes here...</div>
+    <div class="flex gap-4">
+      <modus-button color="primary">Add to Cart</modus-button>
+      <modus-button color="secondary">Add to Wishlist</modus-button>
+    </div>
+  </div>
+</modus-card>
+
+<!-- Separate reviews card -->
+<modus-card class="p-6 bg-card border-default rounded-lg mt-6">
+  <div class="text-xl font-semibold text-foreground mb-4">Customer Reviews</div>
+  <!-- Reviews content -->
+</modus-card>
+```
+
+**Key Rules:**
+
+- Use `modus-card` with `bg-card` and `border-default` for grouping
+- Apply consistent padding (`p-6`) within cards
+- Use `rounded-lg` for visual containment
+- Separate different content types into different cards
+
+---
+
+## 4. Law of Figure/Ground
+
+**Definition:** The visual system automatically separates elements into foreground (figure) and background (ground). The figure appears to stand out from the background.
+
+**Real-World Example:** In a modal dialog, the modal content (figure) stands out clearly against the darkened background overlay (ground). The modal appears to "float" above the page content, making it the clear focus of attention.
+
+**Implementation:**
+
+```html
+<!-- Modal with figure/ground separation -->
+<modus-modal id="confirm-modal" headline="Confirm Action">
+  <div slot="content" class="text-foreground-60">
+    Are you sure you want to delete this item?
+  </div>
+  <div slot="footer" class="flex gap-4 justify-end">
+    <modus-button color="secondary" (buttonClick)="closeModal()">Cancel</modus-button>
+    <modus-button color="danger" (buttonClick)="handleDelete()">Delete</modus-button>
+  </div>
+</modus-modal>
+
+<!-- Card on background -->
+<div class="bg-background min-h-screen p-6">
+  <modus-card class="p-6 bg-card border-default rounded-lg shadow-sm">
+    <!-- Card content stands out from background -->
+  </modus-card>
+</div>
+```
+
+**Key Rules:**
+
+- Use `bg-card` over `bg-background` for figure/ground separation
+- Apply shadows (`shadow-sm`, `shadow-lg`) to enhance separation
+- Use borders (`border-default`) to define boundaries
+- Ensure sufficient contrast between figure and ground
+
+---
+
+## 5. Law of Continuity
+
+**Definition:** The eye tends to follow continuous lines, curves, or patterns, creating a sense of flow and direction.
+
+**Real-World Example:** In a horizontal navigation menu, the eye naturally follows the line of menu items from left to right. In a form, the eye follows the vertical flow from label to input to the next label-input pair.
+
+**Implementation:**
+
+```html
+<!-- Horizontal navigation with continuity -->
+<div class="flex items-center gap-8 border-bottom-default pb-4">
+  <modus-button variant="borderless">Home</modus-button>
+  <modus-button variant="borderless">Products</modus-button>
+  <modus-button variant="borderless">About</modus-button>
+  <modus-button variant="borderless">Contact</modus-button>
+</div>
+
+<!-- Form with vertical continuity -->
+<div class="space-y-6">
+  <div class="flex flex-col gap-2">
+    <div class="text-sm font-medium text-foreground">First Name</div>
+    <modus-text-input placeholder="Enter first name" />
+  </div>
+  <div class="flex flex-col gap-2">
+    <div class="text-sm font-medium text-foreground">Last Name</div>
+    <modus-text-input placeholder="Enter last name" />
+  </div>
+  <div class="flex flex-col gap-2">
+    <div class="text-sm font-medium text-foreground">Email</div>
+    <modus-text-input type="email" placeholder="Enter email" />
+  </div>
+</div>
+```
+
+**Key Rules:**
+
+- Maintain alignment using `flex`, `items-start`, `justify-between`
+- Use consistent spacing (`space-y-6`, `gap-2`) for flow
+- Align related elements along common axes
+- Create clear visual paths for the eye to follow
+
+---
+
+## 6. Hick's Law
+
+**Definition:** The time it takes to make a decision increases with the number and complexity of choices available.
+
+**Real-World Example:** A toolbar with 15 different buttons creates decision paralysis. Instead, show only the 3 most important actions (Save, Cancel, Delete) and move secondary actions to a dropdown menu or secondary toolbar.
+
+**Implementation:**
+
+```html
+<!-- Good: Limited primary actions -->
+<div class="flex items-center justify-between gap-4">
+  <div class="flex items-center gap-2">
+    <i class="modus-icons text-lg">filter_list</i>
+    <modus-select placeholder="Filter by" [options]="filterOptions()" />
+  </div>
+  <div class="flex gap-2">
+    <modus-button color="primary">Save</modus-button>
+    <modus-button color="secondary">Cancel</modus-button>
+    <modus-dropdown-menu [menuVisible]="menuVisible()" (itemSelect)="handleAction($event)">
+      <modus-button slot="trigger" variant="borderless" (buttonClick)="toggleMenu()">
+        More Actions
+      </modus-button>
+      <modus-menu-item value="edit">Edit</modus-menu-item>
+      <modus-menu-item value="copy">Copy</modus-menu-item>
+      <modus-menu-item value="archive">Archive</modus-menu-item>
+    </modus-dropdown-menu>
+  </div>
+</div>
+
+<!-- Bad: Too many choices -->
+<div class="flex gap-2">
+  <modus-button color="primary">Save</modus-button>
+  <modus-button color="secondary">Cancel</modus-button>
+  <modus-button variant="borderless">Edit</modus-button>
+  <modus-button variant="borderless">Copy</modus-button>
+  <modus-button variant="borderless">Move</modus-button>
+  <modus-button variant="borderless">Share</modus-button>
+  <modus-button variant="borderless">Archive</modus-button>
+  <modus-button color="danger">Delete</modus-button>
+</div>
+```
+
+**Key Rules:**
+
+- Maximum 3 visible CTAs per context
+- Move secondary actions to dropdown menus
+- Use progressive disclosure for complex interfaces
+- Prioritize actions by frequency of use
+
+---
+
+## 7. Fitts's Law
+
+**Definition:** The time required to move to a target is a function of the distance to the target and the size of the target.
+
+**Real-World Example:** In a text editor, the "Save" button should be large and positioned near the text area where users are working. A small "Save" button in the top-right corner requires more precision and time to click.
+
+**Implementation:**
+
+```html
+<!-- Good: Large, accessible buttons near content -->
+<div class="flex flex-col gap-4">
+  <modus-textarea
+    placeholder="Write your content here..."
+    [rows]="6"
+  />
+  <div class="flex gap-2">
+    <modus-button color="primary" size="lg">Save</modus-button>
+    <modus-button color="secondary" size="lg">Cancel</modus-button>
+  </div>
+</div>
+
+<!-- Good: Floating action button for primary action -->
+<div class="fixed bottom-6 right-6">
+  <modus-button
+    color="primary"
+    size="lg"
+    icon="add"
+    iconPosition="only"
+    ariaLabel="Add new item"
+    class="rounded-full shadow-lg"
+  />
+</div>
+```
+
+**Key Rules:**
+
+- Keep primary CTAs near edited content
+- Minimum 44×44px touch targets
+- Use `size="lg"` for important actions
+- Position frequently used controls within easy reach
+
+---
+
+## 8. Serial Position Effect
+
+**Definition:** Users best remember the first and last items in a series, with the first item having the strongest recall (primacy effect) and the last item having good recall (recency effect).
+
+**Real-World Example:** In a navigation menu, place the most important item (like "Dashboard") first, and the least important item (like "Settings") last. In a form, put the most critical field first and the submit button last.
+
+**Implementation:**
+
+```html
+<!-- Navigation with serial position consideration -->
+<div class="flex flex-col gap-1">
+  <modus-button color="primary" class="justify-start">Dashboard</modus-button>
+  <modus-button variant="borderless" class="justify-start">Projects</modus-button>
+  <modus-button variant="borderless" class="justify-start">Tasks</modus-button>
+  <modus-button variant="borderless" class="justify-start">Reports</modus-button>
+  <modus-button variant="borderless" class="justify-start">Settings</modus-button>
+</div>
+
+<!-- Form with serial position -->
+<div class="space-y-6">
+  <div class="flex flex-col gap-2">
+    <div class="text-sm font-medium text-foreground">Email *</div>
+    <modus-text-input type="email" [required]="true" />
+  </div>
+  <div class="flex flex-col gap-2">
+    <div class="text-sm font-medium text-foreground">Password *</div>
+    <modus-text-input type="password" [required]="true" />
+  </div>
+  <div class="flex flex-col gap-2">
+    <div class="text-sm font-medium text-foreground">Confirm Password *</div>
+    <modus-text-input type="password" [required]="true" />
+  </div>
+  <div class="flex gap-4 pt-4">
+    <modus-button color="primary" (buttonClick)="createAccount()">Create Account</modus-button>
+    <modus-button color="secondary" (buttonClick)="cancel()">Cancel</modus-button>
+  </div>
+</div>
+```
+
+**Key Rules:**
+
+- Place primary actions at start or end of flow
+- Put most important information first
+- Position secondary actions in the middle
+- Use visual hierarchy to reinforce importance
+
+---
+
+## 9. Law of Prägnanz (Simplicity)
+
+**Definition:** People tend to perceive the simplest, most stable interpretation of visual elements. The mind prefers simplicity over complexity.
+
+**Real-World Example:** A clean, minimal interface with plenty of white space is easier to understand than a cluttered interface with many borders, colors, and decorative elements. Users can focus on the content rather than being distracted by visual noise.
+
+**Implementation:**
+
+```html
+<!-- Good: Clean, simple design -->
+<div class="bg-background min-h-screen p-6">
+  <div class="max-w-4xl mx-auto space-y-8">
+    <div class="text-center space-y-4">
+      <div class="text-4xl font-bold text-foreground">Welcome</div>
+      <div class="text-xl text-foreground-60">Get started with your project</div>
+    </div>
+
+    <modus-card class="p-8 bg-card border-default rounded-lg">
+      <div class="space-y-6">
+        <div class="text-2xl font-semibold text-foreground">Create New Project</div>
+        <div class="space-y-4">
+          <modus-text-input placeholder="Project name" />
+          <modus-textarea placeholder="Project description" />
+        </div>
+        <div class="flex gap-4">
+          <modus-button color="primary">Create Project</modus-button>
+          <modus-button color="secondary">Cancel</modus-button>
+        </div>
+      </div>
+    </modus-card>
+  </div>
+</div>
+
+<!-- Bad: Cluttered, complex design -->
+<div class="bg-background min-h-screen p-6">
+  <div class="max-w-4xl mx-auto space-y-8">
+    <div class="text-center space-y-4 border-thick-primary rounded-lg p-6 bg-primary-20">
+      <div class="text-4xl font-bold text-foreground">Welcome</div>
+      <div class="text-xl text-foreground-60">Get started with your project</div>
+    </div>
+
+    <modus-card class="p-8 bg-card border-thick rounded-lg shadow-lg">
+      <div class="space-y-6 border-top-default border-bottom-default py-4">
+        <div class="text-2xl font-semibold text-foreground">Create New Project</div>
+        <div class="space-y-4">
+          <div class="border-default rounded p-2">
+            <modus-text-input placeholder="Project name" />
+          </div>
+          <div class="border-default rounded p-2">
+            <modus-textarea placeholder="Project description" />
+          </div>
+        </div>
+        <div class="flex gap-4 border-top-default pt-4">
+          <modus-button color="primary">Create Project</modus-button>
+          <modus-button color="secondary">Cancel</modus-button>
+        </div>
+      </div>
+    </modus-card>
+  </div>
+</div>
+```
+
+**Key Rules:**
+
+- Remove unnecessary divs, borders, or text
+- Prefer whitespace over visual elements
+- Use consistent spacing and alignment
+- Focus on content hierarchy over decoration
+- Apply the "less is more" principle
+
+---
+
+## Implementation Checklist
+
+When applying Gestalt Laws to your UI design:
+
+- [ ] **Proximity**: Group related elements with `gap-2`, separate groups with `gap-6`+
+- [ ] **Similarity**: Use consistent variants and sizes for similar purposes
+- [ ] **Common Region**: Use `modus-card` with `bg-card` and `border-default` for grouping
+- [ ] **Figure/Ground**: Create clear separation with `bg-card` over `bg-background`
+- [ ] **Continuity**: Maintain alignment and flow with consistent spacing
+- [ ] **Hick's Law**: Limit to 3 visible CTAs, use dropdowns for secondary actions
+- [ ] **Fitts's Law**: Keep primary actions near content, use 44×44px minimum targets
+- [ ] **Serial Position**: Place important items first and last
+- [ ] **Prägnanz**: Remove unnecessary elements, prefer whitespace
+
+---
+
+## Real-World Application Examples
+
+### E-commerce Product Page
+
+- **Proximity**: Product details grouped in one card, reviews in another
+- **Similarity**: All "Add to Cart" buttons use same color
+- **Common Region**: Product info contained within card boundaries
+- **Figure/Ground**: Product card stands out from page background
+- **Continuity**: Eye flows from image to title to price to buttons
+- **Hick's Law**: Primary action (Add to Cart) prominent, secondary actions in dropdown
+- **Fitts's Law**: Large, accessible "Add to Cart" button
+- **Serial Position**: Product name first, price last in header
+- **Prägnanz**: Clean layout with minimal visual noise
+
+### Dashboard Interface
+
+- **Proximity**: Related metrics grouped together
+- **Similarity**: All status indicators use consistent badge colors
+- **Common Region**: Each widget contained in its own card
+- **Figure/Ground**: Widgets stand out from dashboard background
+- **Continuity**: Consistent grid layout creates visual flow
+- **Hick's Law**: Main actions in toolbar, secondary in menus
+- **Fitts's Law**: Important controls large and accessible
+- **Serial Position**: Most important widget in top-left
+- **Prägnanz**: Clean, uncluttered dashboard design
+
+---
+
+## Angular-Specific Patterns
+
+### Signal-Based Component Example
+
+```typescript
+@Component({
+  selector: 'app-contact-card',
+  template: `
+    <div class="space-y-6">
+      @for (contact of contacts(); track contact.id) {
+        <div class="flex items-center gap-2 p-4 bg-card border-default rounded-lg">
+          <modus-avatar [name]="contact.name" size="md" />
+          <div class="flex flex-col gap-1">
+            <div class="text-foreground font-medium">{{ contact.name }}</div>
+            <div class="text-foreground-60 text-sm">{{ contact.email }}</div>
+          </div>
+          <div class="ml-auto">
+            <modus-button
+              color="primary"
+              size="sm"
+              (buttonClick)="selectContact(contact)"
+            >
+              View
+            </modus-button>
+          </div>
+        </div>
+      }
+    </div>
+  `,
+  changeDetection: ChangeDetectionStrategy.OnPush,
+})
+export class ContactCardComponent {
+  readonly contacts = input.required<Contact[]>();
+  readonly contactSelected = output<Contact>();
+
+  selectContact(contact: Contact): void {
+    this.contactSelected.emit(contact);
+  }
+}
+```
+
+### Using Wrapper Components
+
+Always use Modus wrapper components (`modus-button`, `modus-card`, etc.) instead of web components directly:
+
+```html
+<!-- Correct: Use Angular wrapper -->
+<modus-button color="primary" (buttonClick)="save()">Save</modus-button>
+
+<!-- Wrong: Don't use web component directly -->
+<modus-wc-button color="primary">Save</modus-wc-button>
+```
+
+---
+
+This comprehensive guide provides the foundation for creating intuitive, user-friendly interfaces that follow established principles of visual perception and human-computer interaction in Angular applications.