# 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`).
- **New features and pages are primary by default** → When the user requests a new feature or page, make it the primary navigation tab and initial landing page without asking for confirmation. Give it a `navPage`, place that id first in every applicable navigation app's `pages` list in `src/apps.config.js`, and set each applicable app's `defaultPath` to its app-prefixed route so it appears immediately on page load. Keep existing pages as secondary tabs unless the user explicitly requests different behavior. Apps without primary navigation, such as the Builder app, are exempt.
- **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

---