# Salesforce UI Guidelines

---

## TEMPLATE STRUCTURE (where to add components)

- **Route-level views** → `src/modules/page/<name>/` → tag `page-<name>`. Register in `src/routes.config.js` and in `shell/app/app.js` (`ROUTE_COMPONENTS`).
- **Child routes** (e.g. `/contacts/:id` under a `/contacts` tab) → set `navHighlight: '<parentNavPage>'` instead of `navPage`. This highlights the parent tab without creating a separate nav entry. Only routes with `navPage` create tabs; `navHighlight` is for active-state only.
- **Reusable UI** → `src/modules/ui/<name>/` → tag `ui-<name>`. Use inside pages or other components.
- **App shell** → `src/modules/shell/<name>/` → tag `shell-<name>`. Do not put feature UI here—use **`page/`** or **`ui/`**.
- **Do not** add custom components under **`src/modules/lightning/`** or under **`src/build/lightning-icon/shims/`** except the checked-in icon overrides.

---

## UI CODE GUIDELINES

### Modular Component Design

**Decouple your UI into independent, single-responsibility components.** 
Focus on creating a highly reusable and maintainable codebase by breaking complex layouts into smaller "atomic" or "molecular" LWCs.

### Formatting Rules

* Always prioritize readability and standard Salesforce design patterns.
* Never use `!important`. 
* Never override SLDS classes in your CSS.
* Do not use inline style attributes - use utility classes or component CSS files.

### LWC Framework

If you run into errors with the LWC framework or LWR runtime, use the MCP server and selectively use tools to best address your issue.

---

## DESIGN SYSTEM CONTEXT

This project uses two complementary design system indexes:

**Lightning Base Components (LBCs)** – Prebuilt LWC implementations of SLDS components (e.g., `<lightning-button>`, `<lightning-card>`). These include built-in JavaScript functionality, events, and props. **Always use LBCs first** when available—they are the preferred method for building UI.

**Lightning Design System Components** – The underlying CSS framework including:
- **Styling Hooks**: CSS variables for theming (e.g., `--slds-g-color-surface-1`)
- **Utility Classes**: Layout and spacing classes (e.g., `slds-m-around_small`)
- **Component Classes**: CSS-only component patterns (e.g., `.slds-button`)
- **Component Blueprints**: HTML/CSS markup patterns for when LBCs don't exist

Use SLDS (styling hooks, utility classes, component blueprints) to customize LBCs or build components when no LBC exists.

---

## UI CODE CHECKLIST

Before writing ANY UI code, complete this checklist **IN ORDER**:

1. **[ ] Search Lightning Base Components index** – Does a component exist for this?
          - Reference: Lightning Base Components
          **If YES** → Use it.
          **If NO** → Proceed to step 2.

2. **[ ] Search SLDS Component Blueprints** – Does a blueprint exist for this?
          - **Use the MCP tool `explore_slds_blueprints`** to search by name, category, or keyword. Use `guide_slds_blueprints` for general blueprint guidance and a full index of all available blueprints.
          **If YES** → Create a new LWC that implements this component blueprint.
          **If NO** → Proceed to step 3.

3. **[ ] Check SLDS Utility Classes** – Does one exist for this styling need?
          - Reference: Lightning Design System Components
          - Common utilities: spacing (`slds-m-*`, `slds-p-*`), layout (`slds-grid`, `slds-size_*`), text (`slds-text-*`)
          **If YES** → Use it. 
          **If NO** → Proceed to step 4.

4. **[ ] Use Custom CSS with Styling Hooks** - Does one exist for this CSS property?
          - Reference: Lightning Design System Components
          **If YES** → Use it (with fallback value). 
          **If NO** → Proceed to step 5.

5. **[ ] Use a hard-coded CSS value** - Only when no component, utility class, or styling hook exists.

### Lightning Base Component and Component Blueprints

Before writing any HTML, CSS, or JavaScript, determine if an existing component can achieve the desired appearance.

**Two Types of Components:**

#### A. Lightning Base Components (`<lightning-*>`)
Salesforce's official LWC components with JavaScript APIs, props, and events.

**How to Find Lightning Base Components:**
- Lightning Base Components index

**Common Lightning Base Components:**
* `<lightning-button>` - Interactive buttons with variants
* `<lightning-input>` - Form inputs (text, email, date, checkbox, etc.)
* `<lightning-textarea>` - Multi-line text input
* `<lightning-card>` - Container with header, body, footer slots
* `<lightning-combobox>` - Dropdown selection
* `<lightning-datatable>` - Data tables with sorting
* LightningModal (extend from `lightning/modal`) - Modal dialogs. **Use `src/modules/ui/demoModal/` as the reference:** extend LightningModal; compose with `lightning-modal-header`, `lightning-modal-body`, `lightning-modal-footer`; open via `MyModal.open({ size, label })`. Do not build modals from raw `slds-modal` markup.

#### B. Component Blueprints (HTML/CSS Patterns)
Vanilla HTML markup with SLDS CSS classes for when LBCs don't exist or aren't suitable.
If a lightning base component is not available, create a _new LWC_ that implements the component blueprint.

**How to Find Component Blueprints:**
- **Use the MCP tool `explore_slds_blueprints`** to search and retrieve full blueprint specs. You can search by `name`, `category`, `search` keyword, `lightning_component`, `slds_class`, or `styling_hook`.
- **Use the MCP tool `guide_slds_blueprints`** for a comprehensive overview of all 85 available blueprints organized by category, and general guidance on how to use them.

---

### Utility Classes

When composing modular components on a page, or styling existing components, check for an SLDS utility class.

**Principle:** Always use SLDS utility classes for spacing, alignment, text, and sizing. Avoid custom classes for these purposes.

**Utility Class Resources:**
- Lightning Design System Components
- Common utility categories:
  - **Spacing**: `slds-m-around_*`, `slds-p-horizontal_*`, `slds-p-around_small`
  - **Layout/Grid**: `slds-grid`, `slds-size_1-of-1`, `slds-medium-size_1-of-2`
  - **Text**: `slds-text-align_center`, `slds-text-heading_medium`
  - **Display**: `slds-show`, `slds-hide`

---

### Custom CSS with Styling Hooks

If no utility class exists that meets your styling need, create custom CSS referencing the correct global styling hook.

**Usage Guidelines:**
- Global styling hooks are CSS variables: `background: var(--slds-g-color-surface-1, #fff);`
- **Always provide a fallback value** for backwards compatibility
- Use the Cosmos theme value as the fallback (reference the token .mdx files)
- **Semantic Usage Only:** Never use a hook for an unintended purpose
  - ❌ WRONG: `width: var(--slds-g-radius-border-circle)`
  - ✅ CORRECT: `background-color: var(--slds-g-color-surface-1, #fff)`

**Example Hook Categories:**
- **Surface**: `--slds-g-color-surface-1`, `--slds-g-color-surface-2`
- **Container**: `--slds-g-color-surface-container-1`, `--slds-g-color-surface-container-2`
- **On-Surface**: `--slds-g-color-on-surface-1` (text/icons on surfaces)
- **Accent**: `--slds-g-color-accent-1`, `--slds-g-color-accent-container-1`
- **Border**: `--slds-g-color-border-1`, `--slds-g-color-border-accent-1`
- **Feedback**: `--slds-g-color-error-1`, `--slds-g-color-success-1`, `--slds-g-color-warning-1`

**Global Styling Hook Resources:**
1. **Semantic Usage Guide** and **Token Value Reference** in Lightning Design System Components
   
---

### Hard-Coded CSS Values

Only use hard-coded values when no component, utility class, or styling hook exists.

**Examples of acceptable hard-coded values:**
- `height: 100%` (no utility class or styling hook available)
- Percentages for custom layouts
- Transform or animation values
- Z-index

---