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

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

@@ -0,0 +1,708 @@
+# SLDS Typography System: Comprehensive Guide for Coding Agents
+
+## Overview
+
+The SLDS typography system includes **46 typography hooks** (10% of all 473 global hooks) plus **3 font family hooks** for a total of 49 font-related hooks. These provide a complete type system including families, weights, line heights, and sizes.
+
+**Total Typography Hooks:** 49
+
+- **Font Families:** 3 hooks (`font-family`, `font-family-base`, `font-family-monospace`)
+- **Font Weights:** 7 hooks (`font-weight-1` through `font-weight-7`)
+- **Line Heights:** 6+ hooks (`font-lineheight-1` through `font-lineheight-6`, plus base variants)
+- **Font Sizes:** 33+ hooks (various numbered sizes in metadata)
+
+**Key Principle:** SLDS typography uses **numbered systems** (not named like "bold" or "medium") to provide precise control and density-aware scaling.
+
+---
+
+## Font Families
+
+### Available Families
+
+| Hook                             | Typical Value                        | Use For                       |
+| -------------------------------- | ------------------------------------ | ----------------------------- |
+| `--slds-g-font-family`           | "Salesforce Sans", Arial, sans-serif | Default for all text          |
+| `--slds-g-font-family-base`      | "Salesforce Sans", Arial, sans-serif | Same as above (alias)         |
+| `--slds-g-font-family-monospace` | Monaco, Menlo, Consolas, monospace   | Code snippets, technical text |
+
+### Usage
+
+```css
+/* Default body text */
+body {
+  font-family: var(--slds-g-font-family-base);
+}
+
+/* Code blocks */
+code,
+pre {
+  font-family: var(--slds-g-font-family-monospace);
+}
+
+/* Most components */
+.component {
+  font-family: var(--slds-g-font-family); /* Same as base */
+}
+```
+
+**Note:** In most cases, use `font-family-base`. The distinction between `font-family` and `font-family-base` is minimal in current implementation.
+
+---
+
+## Font Weights (Numbered System)
+
+### Complete Weight Scale
+
+SLDS uses **numbered font weights** (1-7) instead of named weights. This provides precise control and consistency.
+
+| Hook                     | Typical Value | Common Name Equivalent | Use For                     |
+| ------------------------ | ------------- | ---------------------- | --------------------------- |
+| `--slds-g-font-weight-1` | 300           | Light                  | Subtle text, large headings |
+| `--slds-g-font-weight-2` | 300           | Light                  | Alternative light weight    |
+| `--slds-g-font-weight-3` | 400           | Regular                | Body text, paragraphs       |
+| `--slds-g-font-weight-4` | 400           | Regular                | Default body weight         |
+| `--slds-g-font-weight-5` | 500           | Medium                 | Semi-emphasis, subheadings  |
+| `--slds-g-font-weight-6` | 600           | Semi-Bold              | Strong subheadings          |
+| `--slds-g-font-weight-7` | 700           | Bold                   | Headings, emphasis, buttons |
+
+### Weight Selection Guide
+
+**Light Weights (1-2):**
+
+```css
+/* Large hero text */
+.hero-title {
+  font-size: 3rem;
+  font-weight: var(--slds-g-font-weight-1); /* Light - reduces visual weight at large sizes */
+}
+```
+
+**Regular Weights (3-4):**
+
+```css
+/* Body text - most common */
+.body-text {
+  font-size: 0.875rem; /* 14px */
+  font-weight: var(--slds-g-font-weight-4); /* Regular - standard readability */
+}
+
+.paragraph {
+  font-weight: var(--slds-g-font-weight-3); /* Also regular */
+}
+```
+
+**Medium Weights (5-6):**
+
+```css
+/* Subheadings, labels */
+.subheading {
+  font-weight: var(--slds-g-font-weight-5); /* Medium - subtle emphasis */
+}
+
+.form-label {
+  font-weight: var(--slds-g-font-weight-6); /* Semi-bold - stronger labels */
+}
+```
+
+**Bold Weight (7):**
+
+```css
+/* Headings, strong emphasis */
+.heading {
+  font-weight: var(--slds-g-font-weight-7); /* Bold - maximum emphasis */
+}
+
+.button-text {
+  font-weight: var(--slds-g-font-weight-7); /* Bold - action emphasis */
+}
+
+strong,
+.strong {
+  font-weight: var(--slds-g-font-weight-7); /* Bold text inline */
+}
+```
+
+### Common Mistakes
+
+```css
+/* ❌ WRONG - Named weights don't exist */
+.element {
+  font-weight: var(--slds-g-font-weight-bold);
+  font-weight: var(--slds-g-font-weight-medium);
+  font-weight: var(--slds-g-font-weight-regular);
+}
+
+/* ✅ CORRECT - Use numbered weights */
+.element-bold {
+  font-weight: var(--slds-g-font-weight-7); /* Bold */
+}
+
+.element-medium {
+  font-weight: var(--slds-g-font-weight-5); /* Medium */
+}
+
+.element-regular {
+  font-weight: var(--slds-g-font-weight-4); /* Regular */
+}
+```
+
+---
+
+## Line Heights (Numbered System)
+
+### Available Line Heights
+
+| Hook                            | Typical Value | Use For                       |
+| ------------------------------- | ------------- | ----------------------------- |
+| `--slds-g-font-lineheight-base` | 1.5           | Default body text             |
+| `--slds-g-font-lineheight-1`    | ~1.25         | Tight line height, headings   |
+| `--slds-g-font-lineheight-2`    | ~1.375        | Compact headings              |
+| `--slds-g-font-lineheight-3`    | ~1.5          | Standard body text            |
+| `--slds-g-font-lineheight-4`    | ~1.625        | Generous body text            |
+| `--slds-g-font-lineheight-5`    | ~1.75         | Extra spacing for readability |
+| `--slds-g-font-lineheight-6`    | ~2.0          | Maximum spacing               |
+
+### Line Height Selection Guide
+
+**Tight Line Heights (1-2):**
+
+```css
+/* Headings - tighter for impact */
+.heading-large {
+  font-size: 2rem;
+  line-height: var(--slds-g-font-lineheight-1); /* ~1.25 - tight for large text */
+}
+
+.heading-standard {
+  font-size: 1.5rem;
+  line-height: var(--slds-g-font-lineheight-2); /* ~1.375 - compact */
+}
+```
+
+**Standard Line Heights (3-4):**
+
+```css
+/* Body text - comfortable reading */
+.body-text {
+  font-size: 0.875rem;
+  line-height: var(--slds-g-font-lineheight-3); /* ~1.5 - standard */
+}
+
+.paragraph {
+  line-height: var(--slds-g-font-lineheight-4); /* ~1.625 - generous */
+}
+```
+
+**Generous Line Heights (5-6):**
+
+```css
+/* Long-form content - maximum readability */
+.article-text {
+  font-size: 1rem;
+  line-height: var(--slds-g-font-lineheight-5); /* ~1.75 - extra space */
+}
+
+.lead-text {
+  font-size: 1.125rem;
+  line-height: var(--slds-g-font-lineheight-6); /* ~2.0 - maximum */
+}
+```
+
+### Accessibility Consideration
+
+**Minimum line height:** WCAG recommends at least **1.5** for body text (line-height-3 or higher).
+
+```css
+/* ✅ ACCESSIBLE - Meets WCAG 1.5 minimum */
+.body {
+  line-height: var(--slds-g-font-lineheight-3); /* 1.5 */
+}
+
+/* ⚠️ POTENTIALLY INSUFFICIENT - May be too tight for body text */
+.compact-body {
+  line-height: var(--slds-g-font-lineheight-1); /* 1.25 - OK for headings, not body */
+}
+```
+
+---
+
+## Font Sizes
+
+### Available Hook
+
+Only one font size hook exists in the SLDS system:
+
+- **`--slds-g-font-size-base`** - Base font size for body text (typically 1rem / 16px)
+
+### Current Best Practice
+
+**Since no numbered font-size hooks exist, use rem values directly:**
+
+```css
+.heading {
+  font-size: 1.5rem; /* 24px for H3 level headings */
+  font-weight: var(--slds-g-font-weight-7);
+  line-height: var(--slds-g-font-lineheight-2);
+}
+
+.body-text {
+  font-size: var(--slds-g-font-size-base); /* Use the available hook */
+  font-weight: var(--slds-g-font-weight-4);
+  line-height: var(--slds-g-font-lineheight-3);
+}
+
+.caption {
+  font-size: 0.75rem; /* 12px for small text */
+  font-weight: var(--slds-g-font-weight-4);
+  line-height: var(--slds-g-font-lineheight-3);
+}
+```
+
+### Recommended Size Scale
+
+Use these rem values for consistent typography:
+
+| Purpose                 | Size (rem) | Pixels @ 16px base |
+| ----------------------- | ---------- | ------------------ |
+| Tiny text, metadata     | 0.625rem   | 10px               |
+| Small text, captions    | 0.75rem    | 12px               |
+| Body text (most common) | 0.875rem   | 14px               |
+| Base / Large body       | 1rem       | 16px               |
+| Small headings          | 1.125rem   | 18px               |
+| Subheadings             | 1.25rem    | 20px               |
+| H3 headings             | 1.5rem     | 24px               |
+| H2 headings             | 1.75rem    | 28px               |
+| H1 headings             | 2rem       | 32px               |
+| Large headings          | 2.5rem     | 40px               |
+| Hero text               | 3rem       | 48px               |
+
+---
+
+## Typography Hierarchy Patterns
+
+### Pattern 1: Standard Heading Hierarchy
+
+```css
+.heading-1 {
+  font-family: var(--slds-g-font-family-base);
+  font-size: 2rem; /* Large */
+  font-weight: var(--slds-g-font-weight-7); /* Bold */
+  line-height: var(--slds-g-font-lineheight-1); /* Tight */
+  color: var(--slds-g-color-palette-neutral-10);
+}
+
+.heading-2 {
+  font-size: 1.5rem; /* Medium-large */
+  font-weight: var(--slds-g-font-weight-7); /* Bold */
+  line-height: var(--slds-g-font-lineheight-2); /* Compact */
+  color: var(--slds-g-color-palette-neutral-10);
+}
+
+.heading-3 {
+  font-size: 1.25rem; /* Medium */
+  font-weight: var(--slds-g-font-weight-6); /* Semi-bold */
+  line-height: var(--slds-g-font-lineheight-2); /* Compact */
+  color: var(--slds-g-color-palette-neutral-20);
+}
+
+.heading-4 {
+  font-size: 1rem; /* Standard */
+  font-weight: var(--slds-g-font-weight-6); /* Semi-bold */
+  line-height: var(--slds-g-font-lineheight-3); /* Standard */
+  color: var(--slds-g-color-palette-neutral-20);
+}
+```
+
+### Pattern 2: Body Text Variants
+
+```css
+.body-text-large {
+  font-family: var(--slds-g-font-family-base);
+  font-size: 1rem; /* 16px */
+  font-weight: var(--slds-g-font-weight-4); /* Regular */
+  line-height: var(--slds-g-font-lineheight-4); /* Generous */
+  color: var(--slds-g-color-palette-neutral-20);
+}
+
+.body-text-standard {
+  font-size: 0.875rem; /* 14px - most common */
+  font-weight: var(--slds-g-font-weight-4); /* Regular */
+  line-height: var(--slds-g-font-lineheight-3); /* Standard */
+  color: var(--slds-g-color-palette-neutral-20);
+}
+
+.body-text-small {
+  font-size: 0.75rem; /* 12px */
+  font-weight: var(--slds-g-font-weight-4); /* Regular */
+  line-height: var(--slds-g-font-lineheight-3); /* Standard */
+  color: var(--slds-g-color-palette-neutral-30);
+}
+
+.caption {
+  font-size: 0.75rem; /* 12px */
+  font-weight: var(--slds-g-font-weight-4); /* Regular */
+  line-height: var(--slds-g-font-lineheight-3); /* Standard */
+  color: var(--slds-g-color-palette-neutral-40); /* Lighter */
+}
+```
+
+### Pattern 3: Interactive Text (Buttons, Links)
+
+```css
+.button-text {
+  font-family: var(--slds-g-font-family-base);
+  font-size: 0.875rem; /* 14px */
+  font-weight: var(--slds-g-font-weight-7); /* Bold - emphasizes action */
+  line-height: var(--slds-g-font-lineheight-3); /* Standard */
+  text-transform: none; /* Don't force uppercase */
+}
+
+.link-text {
+  font-size: 0.875rem; /* 14px - matches body */
+  font-weight: var(--slds-g-font-weight-4); /* Regular - same as body */
+  line-height: var(--slds-g-font-lineheight-3); /* Standard */
+  color: var(--slds-g-color-accent-2); /* Use accent color */
+  text-decoration: none;
+}
+
+.link-text:hover {
+  color: var(--slds-g-color-accent-3); /* Darker on hover */
+  text-decoration: underline;
+}
+```
+
+### Pattern 4: Form Elements
+
+```css
+.label {
+  font-family: var(--slds-g-font-family-base);
+  font-size: 0.75rem; /* 12px - smaller than input */
+  font-weight: var(--slds-g-font-weight-6); /* Semi-bold - emphasis */
+  line-height: var(--slds-g-font-lineheight-3); /* Standard */
+  color: var(--slds-g-color-palette-neutral-20);
+  margin-bottom: var(--slds-g-spacing-2);
+}
+
+.input-text {
+  font-size: 0.875rem; /* 14px - readable */
+  font-weight: var(--slds-g-font-weight-4); /* Regular */
+  line-height: var(--slds-g-font-lineheight-3); /* Standard */
+  color: var(--slds-g-color-palette-neutral-10);
+}
+
+.input-placeholder {
+  font-size: 0.875rem; /* Same as input */
+  font-weight: var(--slds-g-font-weight-4); /* Regular */
+  color: var(--slds-g-color-palette-neutral-50); /* Lighter */
+}
+
+.help-text {
+  font-size: 0.75rem; /* 12px - smaller */
+  font-weight: var(--slds-g-font-weight-4); /* Regular */
+  line-height: var(--slds-g-font-lineheight-3); /* Standard */
+  color: var(--slds-g-color-palette-neutral-40); /* Light gray */
+  margin-top: var(--slds-g-spacing-1);
+}
+
+.error-text {
+  font-size: 0.75rem; /* 12px */
+  font-weight: var(--slds-g-font-weight-4); /* Regular */
+  color: var(--slds-g-color-palette-pink-10); /* Error color */
+}
+```
+
+### Pattern 5: Code and Technical Text
+
+```css
+.code-inline {
+  font-family: var(--slds-g-font-family-monospace);
+  font-size: 0.875rem; /* Slightly smaller than body */
+  font-weight: var(--slds-g-font-weight-4); /* Regular */
+  background: var(--slds-g-color-palette-neutral-95);
+  padding: 0.125rem 0.25rem;
+  border-radius: 0.125rem;
+}
+
+.code-block {
+  font-family: var(--slds-g-font-family-monospace);
+  font-size: 0.875rem; /* 14px */
+  font-weight: var(--slds-g-font-weight-4); /* Regular */
+  line-height: var(--slds-g-font-lineheight-4); /* Generous for readability */
+  background: var(--slds-g-color-palette-neutral-95);
+  padding: var(--slds-g-spacing-4);
+  border-radius: 0.25rem;
+  color: var(--slds-g-color-palette-neutral-10);
+}
+```
+
+---
+
+## Accessibility Best Practices
+
+### Text Size
+
+**Minimum sizes:**
+
+- Body text: 14px (0.875rem) or larger
+- Small text: 12px (0.75rem) minimum
+- Avoid text smaller than 12px
+
+```css
+/* ✅ ACCESSIBLE */
+.body {
+  font-size: 0.875rem;
+} /* 14px */
+.caption {
+  font-size: 0.75rem;
+} /* 12px - minimum */
+
+/* ❌ TOO SMALL */
+.tiny {
+  font-size: 0.625rem;
+} /* 10px - avoid */
+```
+
+### Line Height
+
+**WCAG Recommendation:** Minimum 1.5 for body text
+
+```css
+/* ✅ MEETS WCAG */
+.body-text {
+  line-height: var(--slds-g-font-lineheight-3); /* 1.5 */
+}
+
+/* ⚠️ OK FOR HEADINGS, NOT BODY */
+.heading {
+  line-height: var(--slds-g-font-lineheight-1); /* 1.25 - headings only */
+}
+```
+
+### Contrast
+
+Combine typography with proper color contrast:
+
+```css
+/* ✅ GOOD CONTRAST - 50+ point separation */
+.text-on-light {
+  color: var(--slds-g-color-palette-neutral-10); /* Dark text */
+  background: var(--slds-g-color-palette-neutral-95); /* Light background */
+}
+
+/* ⚠️ INSUFFICIENT for body text */
+.low-contrast-text {
+  color: var(--slds-g-color-palette-neutral-50); /* Mid gray */
+  background: var(--slds-g-color-palette-neutral-100); /* White */
+  /* Only 50-point separation = borderline */
+}
+```
+
+### Font Weight Considerations
+
+- **Light weights (1-2):** Use only for large text (headings 24px+)
+- **Regular weights (3-4):** Safe for all sizes
+- **Bold weights (5-7):** Improves readability at small sizes
+
+---
+
+## Density-Aware Typography
+
+### Automatic Scaling
+
+Some typography properties (especially line heights) may adapt to density settings automatically. Font sizes generally remain fixed.
+
+```css
+/* Typography that adapts to density */
+.component-text {
+  font-size: 0.875rem; /* Usually fixed */
+  line-height: var(--slds-g-font-lineheight-3); /* May adapt */
+  /* Some implementations adjust line-height in compact mode */
+}
+```
+
+### Best Practice
+
+For most components, keep font sizes fixed and let spacing handle density:
+
+```css
+.button {
+  font-size: 0.875rem; /* Fixed */
+  font-weight: var(--slds-g-font-weight-7); /* Fixed */
+  line-height: var(--slds-g-font-lineheight-3); /* Fixed or adaptive */
+  padding: var(--slds-g-spacing-var-3); /* Adapts to density */
+}
+```
+
+---
+
+## Common Mistakes and Solutions
+
+### Mistake 1: Using Named Weight Hooks
+
+```css
+/* ❌ WRONG - These don't exist */
+.text {
+  font-weight: var(--slds-g-font-weight-bold);
+  font-weight: var(--slds-g-font-weight-semibold);
+  font-weight: var(--slds-g-font-weight-medium);
+  font-weight: var(--slds-g-font-weight-regular);
+}
+
+/* ✅ CORRECT - Use numbered hooks */
+.text-bold {
+  font-weight: var(--slds-g-font-weight-7);
+}
+.text-semibold {
+  font-weight: var(--slds-g-font-weight-6);
+}
+.text-medium {
+  font-weight: var(--slds-g-font-weight-5);
+}
+.text-regular {
+  font-weight: var(--slds-g-font-weight-4);
+}
+```
+
+### Mistake 2: Hard-Coding Font Values
+
+```css
+/* ❌ WRONG - Hard-coded values */
+.text {
+  font-family: 'Salesforce Sans', Arial, sans-serif;
+  font-weight: 700;
+  line-height: 1.5;
+}
+
+/* ✅ CORRECT - Use typography hooks */
+.text {
+  font-family: var(--slds-g-font-family-base);
+  font-weight: var(--slds-g-font-weight-7);
+  line-height: var(--slds-g-font-lineheight-3);
+}
+```
+
+### Mistake 3: Inconsistent Type Scale
+
+```css
+/* ❌ INCONSISTENT - Random sizes */
+.heading-1 {
+  font-size: 2.3rem;
+}
+.heading-2 {
+  font-size: 1.7rem;
+}
+.heading-3 {
+  font-size: 1.4rem;
+}
+
+/* ✅ CONSISTENT - Following scale */
+.heading-1 {
+  font-size: 2rem;
+} /* 32px */
+.heading-2 {
+  font-size: 1.5rem;
+} /* 24px */
+.heading-3 {
+  font-size: 1.25rem;
+} /* 20px */
+```
+
+### Mistake 4: Poor Line Height for Text Size
+
+```css
+/* ❌ WRONG - Tight line height on body text */
+.body-text {
+  font-size: 0.875rem;
+  line-height: var(--slds-g-font-lineheight-1); /* Too tight for body */
+}
+
+/* ✅ CORRECT - Appropriate line height */
+.body-text {
+  font-size: 0.875rem;
+  line-height: var(--slds-g-font-lineheight-3); /* 1.5 - good for reading */
+}
+```
+
+---
+
+## Summary for Coding Agents
+
+### Quick Reference
+
+**Font Families:**
+
+- Default: `font-family-base`
+- Code: `font-family-monospace`
+
+**Font Weights (use numbers 1-7):**
+
+- Light: `font-weight-1` or `font-weight-2` (300)
+- Regular: `font-weight-3` or `font-weight-4` (400)
+- Medium: `font-weight-5` (500)
+- Semi-bold: `font-weight-6` (600)
+- Bold: `font-weight-7` (700)
+
+**Line Heights (use numbers 1-6):**
+
+- Tight: `font-lineheight-1` (1.25) - headings only
+- Standard: `font-lineheight-3` (1.5) - body text
+- Generous: `font-lineheight-4` or higher - long-form content
+
+**Font Sizes:**
+
+- Currently: Use hard-coded rem values with comments
+- Future: Check for `font-size-*` hooks with `{{EXPLORE_SLDS_STYLING_TOOL}}`
+
+### Search for Hooks
+
+```javascript
+// Find all typography hooks
+{
+  {
+    EXPLORE_SLDS_STYLING_TOOL;
+  }
+}
+({ category: 'font' });
+
+// Find font weights
+{
+  {
+    EXPLORE_SLDS_STYLING_TOOL;
+  }
+}
+({ prefix: '--slds-g-font-weight-' });
+
+// Find line heights
+{
+  {
+    EXPLORE_SLDS_STYLING_TOOL;
+  }
+}
+({ search: 'lineheight' });
+
+// Check specific hook
+{
+  {
+    EXPLORE_SLDS_STYLING_TOOL;
+  }
+}
+({ hooks: ['--slds-g-font-weight-7'] });
+```
+
+### Key Rules
+
+1. ✅ Use numbered weight hooks (`font-weight-7`), not named (`font-weight-bold`)
+2. ✅ Use `font-family-base` for most text
+3. ✅ Use `font-family-monospace` for code only
+4. ✅ Maintain minimum 1.5 line height for body text
+5. ✅ Use font-size 14px (0.875rem) or larger for body text
+6. ❌ Never hard-code fonts when hooks exist
+7. ❌ Never use light weights (1-2) for small text
+
+---
+
+**References:**
+
+- [Complete Hooks Index](../metadata/hooks-index.json)
+- [Guidance Overview](../guidance.md)
+- [SLDS Typography (when available)](https://www.lightningdesignsystem.com/)