@salesforce/mcp-provider-lwc-experts 0.6.3 → 0.6.4

package/knowledge/slds/styling-hooks/categories/radius.md

@@ -0,0 +1,526 @@
+# SLDS Border Radius Styling Hooks
+
+**Category:** Layout / Visual Treatment  
+**Total Hooks:** 6 radius hooks  
+**Purpose:** Control corner curvature and component softness
+
+---
+
+## Overview
+
+Border radius styling hooks manage the curvature of UI elements' corners, impacting the perceived softness or hardness of components. Consistent radius usage creates visual cohesion and reinforces the design system's aesthetic.
+
+**Key Principles:**
+
+- Use progressive radius values (1→4) for increasing curvature
+- Special values (circle, pill) for specific shape requirements
+- Maintain consistency within component families
+- Consider accessibility when using extreme radius values
+
+---
+
+## Available Hooks
+
+| Hook                            | Value            | Description             | Common Use                   |
+| ------------------------------- | ---------------- | ----------------------- | ---------------------------- |
+| `--slds-g-radius-border-1`      | `0.25rem` (4px)  | Subtle rounding         | Buttons, inputs, cards       |
+| `--slds-g-radius-border-2`      | `0.5rem` (8px)   | Medium rounding         | Modals, large cards          |
+| `--slds-g-radius-border-3`      | `0.75rem` (12px) | Prominent rounding      | Hero sections, feature cards |
+| `--slds-g-radius-border-4`      | `1.25rem` (20px) | Maximum corner rounding | Special components           |
+| `--slds-g-radius-border-circle` | `100%`           | Perfect circle          | Avatars, icon buttons        |
+| `--slds-g-radius-border-pill`   | `15rem` (240px)  | Pill shape              | Pill buttons, tags, badges   |
+
+---
+
+## Usage Guidance
+
+### Radius-Border-1: Subtle Rounding (0.25rem / 4px)
+
+**Most Common** - Default radius for standard UI elements
+
+#### Use For:
+
+- Standard buttons
+- Input fields
+- Small cards
+- Chips and tags
+- Tooltips
+- Dropdown items
+
+```css
+.button-default {
+  border-radius: var(--slds-g-radius-border-1);
+}
+
+.input-field {
+  border-radius: var(--slds-g-radius-border-1);
+}
+
+.card-small {
+  border-radius: var(--slds-g-radius-border-1);
+}
+```
+
+---
+
+### Radius-Border-2: Medium Rounding (0.5rem / 8px)
+
+**Standard** - Balanced rounding for prominent elements
+
+#### Use For:
+
+- Large cards
+- Modal dialogs
+- Content panels
+- Navigation containers
+- Prominent buttons
+
+```css
+.card-large {
+  border-radius: var(--slds-g-radius-border-2);
+}
+
+.modal {
+  border-radius: var(--slds-g-radius-border-2);
+}
+
+.panel {
+  border-radius: var(--slds-g-radius-border-2);
+}
+```
+
+---
+
+### Radius-Border-3: Prominent Rounding (0.75rem / 12px)
+
+**Expressive** - More pronounced curvature
+
+#### Use For:
+
+- Hero sections
+- Feature cards
+- Marketing content
+- Highlight panels
+- Special callouts
+
+```css
+.hero-card {
+  border-radius: var(--slds-g-radius-border-3);
+}
+
+.feature-section {
+  border-radius: var(--slds-g-radius-border-3);
+}
+```
+
+---
+
+### Radius-Border-4: Maximum Rounding (1.25rem / 20px)
+
+**Distinctive** - Highest corner rounding
+
+#### Use For:
+
+- Special design treatments
+- Brand-specific components
+- Decorative elements
+- Unique interactive elements
+
+```css
+.special-component {
+  border-radius: var(--slds-g-radius-border-4);
+}
+```
+
+**Note:** Use sparingly to maintain visual consistency
+
+---
+
+### Radius-Border-Circle: Perfect Circle (100%)
+
+**Circular** - Creates perfect circles
+
+#### Use For:
+
+- Avatar images
+- Icon-only buttons
+- Status indicators
+- Badge dots
+- Circular progress indicators
+
+```css
+.avatar {
+  width: 2.5rem;
+  height: 2.5rem;
+  border-radius: var(--slds-g-radius-border-circle);
+}
+
+.icon-button {
+  width: 2rem;
+  height: 2rem;
+  border-radius: var(--slds-g-radius-border-circle);
+}
+
+.status-indicator {
+  width: 0.5rem;
+  height: 0.5rem;
+  border-radius: var(--slds-g-radius-border-circle);
+}
+```
+
+**Important:** Element must have equal width and height for perfect circle
+
+---
+
+### Radius-Border-Pill: Pill Shape (15rem / 240px)
+
+**Pill-shaped** - Fully rounded ends
+
+#### Use For:
+
+- Pill buttons
+- Tags and labels
+- Badges
+- Search bars
+- Status pills
+
+```css
+.pill-button {
+  padding: var(--slds-g-spacing-2) var(--slds-g-spacing-4);
+  border-radius: var(--slds-g-radius-border-pill);
+}
+
+.tag {
+  padding: var(--slds-g-spacing-1) var(--slds-g-spacing-3);
+  border-radius: var(--slds-g-radius-border-pill);
+}
+
+.badge {
+  padding: var(--slds-g-spacing-1) var(--slds-g-spacing-2);
+  border-radius: var(--slds-g-radius-border-pill);
+}
+```
+
+---
+
+## Best Practices
+
+### ✅ DO:
+
+1. **Use consistent radius within component families**
+
+   ```css
+   /* All standard buttons use radius-border-1 */
+   .button-primary,
+   .button-secondary,
+   .button-tertiary {
+     border-radius: var(--slds-g-radius-border-1);
+   }
+   ```
+
+2. **Match radius to component size**
+
+   ```css
+   /* Small components use smaller radius */
+   .chip {
+     border-radius: var(--slds-g-radius-border-1);
+   }
+
+   /* Large components can use larger radius */
+   .hero-card {
+     border-radius: var(--slds-g-radius-border-2);
+   }
+   ```
+
+3. **Use pill shape for pill-like elements**
+
+   ```css
+   .status-badge {
+     padding: 0.25rem 0.75rem;
+     border-radius: var(--slds-g-radius-border-pill);
+   }
+   ```
+
+4. **Ensure perfect circles have equal dimensions**
+   ```css
+   .avatar {
+     width: 3rem;
+     height: 3rem; /* Same as width */
+     border-radius: var(--slds-g-radius-border-circle);
+   }
+   ```
+
+### ❌ DON'T:
+
+1. **Don't mix radius values randomly**
+
+   ```css
+   /* Bad: Inconsistent radius in related components */
+   .card-header {
+     border-radius: var(--slds-g-radius-border-1);
+   }
+   .card-body {
+     border-radius: var(--slds-g-radius-border-3);
+   }
+   ```
+
+2. **Don't use circle on non-square elements**
+
+   ```css
+   /* Bad: Rectangle with circle radius */
+   .button {
+     width: 5rem;
+     height: 2rem;
+     border-radius: var(--slds-g-radius-border-circle);
+   }
+   ```
+
+3. **Don't hard-code radius values**
+
+   ```css
+   /* Bad */
+   border-radius: 4px;
+
+   /* Good */
+   border-radius: var(--slds-g-radius-border-1);
+   ```
+
+4. **Don't overuse large radius values**
+   ```css
+   /* Bad: Everything shouldn't use radius-border-4 */
+   .button,
+   .input,
+   .card {
+     border-radius: var(--slds-g-radius-border-4);
+   }
+   ```
+
+---
+
+## Common Patterns
+
+### Pattern 1: Standard Button
+
+```css
+.button {
+  background: var(--slds-g-color-accent-container-1);
+  color: var(--slds-g-color-on-accent-1);
+  padding: var(--slds-g-spacing-2) var(--slds-g-spacing-4);
+  border-radius: var(--slds-g-radius-border-1);
+  border: 1px solid var(--slds-g-color-border-accent-1);
+}
+```
+
+### Pattern 2: Card Component
+
+```css
+.card {
+  background: var(--slds-g-color-surface-container-1);
+  padding: var(--slds-g-spacing-4);
+  border-radius: var(--slds-g-radius-border-2);
+  box-shadow: var(--slds-g-shadow-2);
+}
+```
+
+### Pattern 3: Avatar
+
+```css
+.avatar {
+  width: 2.5rem;
+  height: 2.5rem;
+  border-radius: var(--slds-g-radius-border-circle);
+  object-fit: cover;
+}
+
+.avatar-small {
+  width: 1.5rem;
+  height: 1.5rem;
+  border-radius: var(--slds-g-radius-border-circle);
+}
+
+.avatar-large {
+  width: 4rem;
+  height: 4rem;
+  border-radius: var(--slds-g-radius-border-circle);
+}
+```
+
+### Pattern 4: Pill Button
+
+```css
+.pill-button {
+  padding: var(--slds-g-spacing-2) var(--slds-g-spacing-5);
+  border-radius: var(--slds-g-radius-border-pill);
+  background: var(--slds-g-color-accent-container-1);
+  color: var(--slds-g-color-on-accent-1);
+  border: none;
+}
+```
+
+### Pattern 5: Tag/Badge
+
+```css
+.tag {
+  display: inline-flex;
+  align-items: center;
+  padding: var(--slds-g-spacing-1) var(--slds-g-spacing-3);
+  border-radius: var(--slds-g-radius-border-pill);
+  background: var(--slds-g-color-surface-container-2);
+  color: var(--slds-g-color-on-surface-2);
+  font-size: 0.75rem;
+}
+```
+
+### Pattern 6: Input Field
+
+```css
+.input {
+  padding: var(--slds-g-spacing-2) var(--slds-g-spacing-3);
+  border: 1px solid var(--slds-g-color-border-1);
+  border-radius: var(--slds-g-radius-border-1);
+  background: var(--slds-g-color-surface-container-1);
+  font-family: var(--slds-g-font-family-base);
+  font-size: var(--slds-g-font-size-base);
+}
+
+.input:focus {
+  border-color: var(--slds-g-color-accent-1);
+  box-shadow: var(--slds-g-shadow-outline-focus-1);
+}
+```
+
+### Pattern 7: Modal Dialog
+
+```css
+.modal {
+  background: var(--slds-g-color-surface-1);
+  border-radius: var(--slds-g-radius-border-2);
+  box-shadow: var(--slds-g-shadow-4);
+  padding: var(--slds-g-spacing-6);
+  max-width: 40rem;
+}
+```
+
+### Pattern 8: Icon Button (Circular)
+
+```css
+.icon-button {
+  width: 2.5rem;
+  height: 2.5rem;
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  border-radius: var(--slds-g-radius-border-circle);
+  background: var(--slds-g-color-surface-container-1);
+  border: 1px solid var(--slds-g-color-border-1);
+}
+
+.icon-button:hover {
+  background: var(--slds-g-color-surface-container-2);
+}
+```
+
+---
+
+## Directional Radius
+
+For partial radius application (specific corners):
+
+```css
+/* Top corners only */
+.modal-header {
+  border-top-left-radius: var(--slds-g-radius-border-2);
+  border-top-right-radius: var(--slds-g-radius-border-2);
+}
+
+/* Bottom corners only */
+.modal-footer {
+  border-bottom-left-radius: var(--slds-g-radius-border-2);
+  border-bottom-right-radius: var(--slds-g-radius-border-2);
+}
+
+/* Single corner */
+.callout-arrow {
+  border-top-left-radius: var(--slds-g-radius-border-1);
+}
+```
+
+---
+
+## Accessibility Considerations
+
+### Touch Targets
+
+Radius doesn't affect touch target size - ensure adequate padding:
+
+```css
+.button {
+  padding: var(--slds-g-spacing-2) var(--slds-g-spacing-4); /* Ensures 44px height */
+  border-radius: var(--slds-g-radius-border-1);
+}
+```
+
+### Visual Clarity
+
+Maintain adequate contrast between rounded elements and backgrounds:
+
+```css
+.button {
+  background: var(--slds-g-color-accent-container-1);
+  border: 1px solid var(--slds-g-color-border-accent-1);
+  border-radius: var(--slds-g-radius-border-1);
+}
+```
+
+### Reduced Motion
+
+Radius changes should be instant, not animated (for motion sensitivity):
+
+```css
+/* Good - instant radius change */
+.button {
+  border-radius: var(--slds-g-radius-border-1);
+}
+
+.button:hover {
+  border-radius: var(--slds-g-radius-border-1); /* No animation */
+}
+```
+
+---
+
+## Quick Decision Guide
+
+**Choose radius based on component type:**
+
+| Component Type     | Recommended Radius     | Why                      |
+| ------------------ | ---------------------- | ------------------------ |
+| Buttons (standard) | `radius-border-1`      | Subtle, professional     |
+| Input fields       | `radius-border-1`      | Consistency with buttons |
+| Small cards        | `radius-border-1`      | Subtle separation        |
+| Large cards        | `radius-border-2`      | More prominent           |
+| Modals             | `radius-border-2`      | Softer appearance        |
+| Pills/badges       | `radius-border-pill`   | Pill shape               |
+| Avatars            | `radius-border-circle` | Circular                 |
+| Icon buttons       | `radius-border-circle` | Circular                 |
+| Hero sections      | `radius-border-3`      | Expressive               |
+
+---
+
+## Complete Hook Reference
+
+**All 6 Radius Hooks:**
+
+1. `--slds-g-radius-border-1` - 0.25rem (4px) - Subtle
+2. `--slds-g-radius-border-2` - 0.5rem (8px) - Medium
+3. `--slds-g-radius-border-3` - 0.75rem (12px) - Prominent
+4. `--slds-g-radius-border-4` - 1.25rem (20px) - Maximum
+5. `--slds-g-radius-border-circle` - 100% - Perfect circle
+6. `--slds-g-radius-border-pill` - 15rem (240px) - Pill shape
+
+---
+
+**References:**
+
+- Source: `/source-data/sds-metadata/styling-hooks/globalstylinghooks.metadata.json`
+- SLDS Documentation: [Border Radius](https://www.lightningdesignsystem.com/2e1ef8501/)