dees-catalog/readme.plan.md

# Command: cat ~/.claude/CLAUDE.md

# Margin Harmonization Plan for @design.estate/dees-catalog

## Implementation Status: Phase 1 Complete ✅

Phase 1 has been successfully implemented. Buttons now auto-detect form context and apply appropriate spacing.

## Objective
Implement consistent spacing across all form elements using auto-detection and CSS-based approach for buttons while maintaining the existing input spacing system.

## Current Issues
- Buttons have no default margins (inconsistent with inputs)
- Manual spacing required when mixing buttons with inputs in forms
- No unified spacing constants across components

## Implementation Plan (Improved)

### Phase 1: Add Auto-Detected Form Spacing to Buttons ✅
- [x] Update `dees-button.ts`
  - Add `insideForm` property (boolean, reflected) with auto-detection
  - Add connectedCallback for automatic form detection:
    ```typescript
    @property({ type: Boolean, reflect: true })
    public insideForm: boolean = false;
    
    connectedCallback() {
      super.connectedCallback();
      // Auto-detect if inside a form
      if (!this.insideForm && this.closest('dees-form')) {
        this.insideForm = true;
      }
    }
    ```
  - Add margin styles for both vertical and horizontal form contexts:
    ```css
    /* Default vertical form layout */
    :host([inside-form]) {
      display: block;
      margin-bottom: var(--dees-input-vertical-gap);
    }
    :host([inside-form]:last-child) {
      margin-bottom: 0;
    }
    
    /* Horizontal form layout - auto-detected via parent */
    :host([inside-form]):host-context(dees-form[horizontal-layout]) {
      display: inline-block;
      margin-right: var(--dees-input-horizontal-gap);
      margin-bottom: 0;
    }
    :host([inside-form]):host-context(dees-form[horizontal-layout]):last-child {
      margin-right: 0;
    }
    ```
- [x] Update `dees-form-submit.ts`
  - Remove need for manual attribute setting (auto-detection handles it)
  - Verify integration works correctly

### Phase 2: Create Unified Spacing Constants (Optional Enhancement)
- [ ] Add CSS custom properties to `dees-input-base.ts`:
  ```css
  :root {
    --dees-form-gap: 16px;
  }
  ```
- [ ] Update existing `--dees-input-vertical-gap` to use `--dees-form-gap`
- [ ] Update button margins to use the same variable

### Phase 3: Testing and Documentation
- [ ] Test mixed forms with inputs and buttons (both vertical and horizontal)
- [ ] Verify last-child margin removal works
- [ ] Test auto-detection behavior
- [ ] Update demos:
  - `dees-form.demo.ts` - show buttons auto-detecting form context
  - `dees-button.demo.ts` - add form context example with manual override
- [ ] Document the `insideForm` property and auto-detection in readme.md

### Phase 4: Clean Up
- [ ] Ensure all spacing uses consistent values (16px)
- [ ] Verify no breaking changes
- [ ] Update changelog.md

## Technical Details

### Button Form Integration
```typescript
// In dees-button.ts
@property({ type: Boolean, reflect: true })
public insideForm: boolean = false;

connectedCallback() {
  super.connectedCallback();
  // Auto-detect if inside a form
  if (!this.insideForm && this.closest('dees-form')) {
    this.insideForm = true;
  }
}

// CSS addition
/* Default vertical form layout */
:host([inside-form]) {
  display: block;
  margin-bottom: var(--dees-input-vertical-gap);
}
:host([inside-form]:last-child) {
  margin-bottom: 0;
}

/* Horizontal form layout - auto-detected via parent */
:host([inside-form]):host-context(dees-form[horizontal-layout]) {
  display: inline-block;
  margin-right: var(--dees-input-horizontal-gap);
  margin-bottom: 0;
}
:host([inside-form]):host-context(dees-form[horizontal-layout]):last-child {
  margin-right: 0;
}
```

### Usage Example
```html
<!-- Automatic detection - buttons get form spacing automatically -->
<dees-form>
  <dees-input-text label="Name"></dees-input-text>
  <dees-input-email label="Email"></dees-input-email>
  <dees-button>Save Draft</dees-button>  <!-- Auto-detects form context -->
  <dees-form-submit>Submit</dees-form-submit>  <!-- Auto-detects form context -->
</dees-form>

<!-- Manual override if needed -->
<div class="custom-container">
  <dees-button inside-form="true">Standalone button with form spacing</dees-button>
</div>

<!-- Horizontal form - spacing adjusts automatically -->
<dees-form horizontal-layout>
  <dees-input-text label="Search"></dees-input-text>
  <dees-button>Search</dees-button>  <!-- Gets right margin instead of bottom -->
</dees-form>
```

## Success Criteria
1. Buttons automatically detect form context and apply appropriate spacing
2. Manual override available via `insideForm` property
3. Supports both vertical and horizontal form layouts
4. No breaking changes for existing implementations
5. Consistent 16px spacing between all form elements
6. Clear documentation and examples
7. All tests pass

## Benefits of This Approach
- **Automatic behavior** - Works out of the box, no manual attributes needed
- **Consistent with inputs** - Follows the same pattern as existing form elements
- **Layout aware** - Automatically adapts to vertical/horizontal forms
- **Minimal code** - Simple CSS-based solution with light JS detection
- **Backward compatible** - Existing code continues to work
- **Override capability** - Manual control when needed
- **Uses existing variables** - Leverages `--dees-input-vertical-gap` and `--dees-input-horizontal-gap`