@salesforce/afv-skills 1.22.0 → 1.23.0

package/skills/building-ui-bundle-app/SKILL.md

@@ -1,350 +0,0 @@
----
-name: building-ui-bundle-app
-description: "MUST activate when the user wants to build, create, or generate a React application, React app, web application, single-page application (SPA), or frontend application — even if no project files exist yet. MUST also activate when the project contains a uiBundles/*/src/ directory or sfdx-project.json and the prompt says create, build, construct, or generate a new app, site, or page from scratch — even if the prompt also describes visual styling. MUST also activate when the task spans more than one ui-bundle skill. Use this skill when building a complete app end-to-end. Do NOT use for Lightning Experience apps with custom objects (use generating-lightning-app). Do NOT use for single-concern edits to an existing page (use building-ui-bundle-frontend)."
-metadata:
-  version: "1.0"
-  related-skills: generating-ui-bundle-metadata, generating-ui-bundle-features, using-ui-bundle-salesforce-data, building-ui-bundle-frontend, implementing-ui-bundle-agentforce-conversation-client, implementing-ui-bundle-file-upload, deploying-ui-bundle, generating-ui-bundle-site, generating-ui-bundle-custom-app
----
-
-# Building a UI Bundle App
-
-## Overview
-
-Build a complete, deployable Salesforce React UI bundle application from a natural language description by orchestrating specialized UI bundle skills in correct dependency order. Each skill **MUST** be explicitly loaded before executing its phase.
-
-## When to Use This Skill
-
-**Use when:**
-
-- User requests a "React app", "UI bundle", "web app", or "full-stack app" on Salesforce
-- User says "build an app", "create an application" and the context implies a non-LWC based frontend (e.g. React)
-- The work produces a complete UI bundle with scaffolding, features, data access, and UI -- not a single component in isolation
-
-**Examples that should trigger this skill:**
-
-- "Build a React app for managing customer cases with Salesforce data"
-- "Create a UI bundle for an employee directory with search and navigation"
-- "I need a full-stack React app with authentication, data tables, and file uploads"
-- "Build a coffee shop ordering app on Salesforce"
-
-**Do NOT use when:**
-
-- Creating a single page or component (use `building-ui-bundle-frontend`)
-- Only installing a feature (use `generating-ui-bundle-features`)
-- Only setting up data access (use `using-ui-bundle-salesforce-data`)
-- Only deploying an existing app (use `deploying-ui-bundle`)
-- Building a Lightning Experience app with custom objects and metadata (use `generating-lightning-app`)
-- Troubleshooting or debugging an existing UI bundle
-
----
-
-## Dependency Graph & Build Order
-
-### Phase 1: Scaffolding (Foundation)
-
-```
-UI Bundle scaffold (sf template generate ui-bundle)
-    v
-Install dependencies (npm install)
-    v
-Bundle metadata (uibundle-meta.xml, ui-bundle.json)
-    v
-CSP Trusted Sites (if external domains needed)
-```
-
-Creates the UI bundle directory structure, meta XML, and optional routing/headers config. All subsequent phases require the scaffold to exist.
-
-### Phase 2: Features (Optional)
-
-```
-Search project code (src/) for existing implementations
-    v
-Install dependencies (npm install)
-    v
-Search, describe, and install features (auth, shadcn, search, navigation, GraphQL)
-    v
-Resolve conflicts (two-pass: --on-conflict error, then --conflict-resolution)
-    v
-Integrate __example__ files into target files, then delete them
-```
-
-Installs pre-built, tested feature packages. Skip if the app requires no pre-built features. Always check for an existing feature before building from scratch. Features provide the foundation that UI components build on top of.
-
-### Phase 3: Data Access (Backend Wiring)
-
-```
-Acquire schema (npm run graphql:schema)
-    v
-Look up entity schema (graphql-search.sh, max 2 runs)
-    v
-Generate queries/mutations (use verified field names, @optional on all record fields)
-    v
-Validate and test (npx eslint, ask user before testing mutations)
-```
-
-Sets up the data layer using `@salesforce/sdk-data`. GraphQL is preferred for record operations; REST for Connect, Apex, or UI API endpoints.
-
-### Phase 4: UI (Frontend)
-
-```
-Layout, navigation, header, and footer (appLayout.tsx)
-    v
-Pages (routed views)
-    v
-Components (widgets, forms, tables)
-```
-
-Builds the React UI. References the data layer from Phase 3 and the features from Phase 2. Must replace all boilerplate and placeholder content.
-
-### Phase 5: Integrations (Optional)
-
-```
-Agentforce chat widget (if requested)
-File upload API (if requested)
-```
-
-These are independent and can be executed in parallel if both are needed.
-
-### Phase 6: Deployment
-
-```
-Org authentication
-    v
-Pre-deploy UI bundle build (npm install + npm run build)
-    v
-Deploy metadata
-    v
-Post-deploy configuration (permissions, profiles, named credentials, connected apps, custom settings, flow activation)
-    v
-Import data (if data plan exists)
-    v
-Fetch GraphQL schema and run codegen
-*(Re-fetches schema from the deployed org -- required because the remote schema may differ from the local one used in Phase 3)*
-    v
-Final UI bundle build (rebuilds with the deployed schema)
-```
-
-Follows the canonical 7-step deployment sequence. Must deploy metadata before fetching schema. Must assign permissions before schema fetch.
-
-### Phase 7: Hosting Target
-
-Choose **one** of the following based on the app's audience:
-
-#### Phase 7a: Experience Site (External)
-
-```
-Resolve site properties (siteName, appDevName, etc.)
-    v
-Generate site metadata (Network, CustomSite, DigitalExperience)
-    v
-Deploy site infrastructure
-```
-
-Creates the Digital Experience site that hosts the UI bundle. Use when the user wants a public-facing or authenticated site URL for external users.
-
-#### Phase 7b: Custom Application (Internal)
-
-```
-Resolve app properties (appName, appNamespace, appLabel)
-    v
-Generate CustomApplication metadata (applications/*.app-meta.xml)
-    v
-Add <target>CustomApplication</target> to .uibundle-meta.xml
-    v
-Deploy custom application
-```
-
-Creates a Custom Application entry in the Lightning App Launcher. Use when the app is for internal users accessing it within Lightning Experience.
-
----
-
-## Execution Workflow
-
-### STEP 1: Requirements Analysis & Planning
-
-**Actions:**
-
-1. Parse the user's natural language request
-2. Identify the app name and purpose
-3. Extract pages and navigation structure
-4. Identify data entities and Salesforce objects needed
-5. Detect feature requirements (authentication, search, file upload, chat)
-6. Determine if an Experience Site is needed
-7. Identify external domains for CSP registration
-
-**Output: Build Plan**
-
-```
-UI Bundle App Build Plan: [App Name]
-
-SCAFFOLDING:
-- App name: [PascalCase name]
-- Routing: [SPA rewrites, trailing slash config]
-- External domains: [domains needing CSP registration]
-
-FEATURES:
-- [list of features to install: auth, shadcn, search, navigation, etc.]
-
-DATA ACCESS:
-- Objects: [Salesforce objects to query/mutate]
-- Queries: [list of GraphQL queries needed]
-- REST endpoints: [Apex REST or Connect API calls, if any]
-
-UI:
-- Layout: [description of app shell/navigation]
-- Pages: [list of pages with routes]
-- Components: [key components per page]
-- Design direction: [aesthetic/style intent]
-
-INTEGRATIONS (if applicable):
-- Agentforce chat: [yes/no, agent ID if known]
-- File upload: [yes/no, record linking pattern]
-
-DEPLOYMENT:
-- Target org: [org alias if known]
-- Hosting target: [Experience Site / Custom Application / none]
-
-SKILL LOAD ORDER:
-1. generating-ui-bundle-metadata
-2. generating-ui-bundle-features (if features needed)
-3. using-ui-bundle-salesforce-data (if data access needed)
-4. building-ui-bundle-frontend
-5a. implementing-ui-bundle-agentforce-conversation-client (if chat requested)
-5b. implementing-ui-bundle-file-upload (if file upload requested)
-6. deploying-ui-bundle
-7a. generating-ui-bundle-site (if Experience Site requested -- external users)
-7b. generating-ui-bundle-custom-app (if Custom Application requested -- internal users)
-```
-
-### STEP 2: Per-Phase Execution
-
-Execute each phase sequentially. Complete all steps within a phase before moving to the next. For each phase:
-
-| Step | What to do | Why |
-|------|-----------|-----|
-| **1. Load skill** | Invoke the skill (e.g., via the Skill tool) for this phase | Gives you the current rules, patterns, constraints, and implementation guides |
-| **2. Execute** | Follow the loaded skill's workflow to generate code/config | The skill defines HOW to do the work correctly |
-| **3. Verify** | Run lint and build from the UI bundle directory | Catch errors before moving to the next phase |
-| **4. Checkpoint** | Confirm phase completion before proceeding | Ensures dependencies are satisfied for the next phase |
-
-**Do NOT skip step 1 (loading the skill).** Even if you remember the skill's content, skills evolve. Always load the current version.
-
----
-
-**Phase 1 -- Scaffolding**
-- 1. Load skill: Invoke `generating-ui-bundle-metadata`
-- 2. Execute: Run `sf template generate ui-bundle`, install dependencies (`npm install`), configure meta XML, ui-bundle.json, and CSP trusted sites
-- 3. Verify: Confirm directory structure and metadata files exist
-- 4. Checkpoint: UI bundle scaffold is ready -- proceed to Phase 2
-
-**Phase 2 -- Features** (skip if no pre-built features needed)
-- 1. Load skill: Invoke `generating-ui-bundle-features`
-- 2. Execute: Install dependencies, search and install features, integrate example files
-- 3. Verify: Run `npm run build` to confirm features integrate cleanly
-- 4. Checkpoint: Features installed -- proceed to Phase 3
-
-**Phase 3 -- Data Access** (skip if no Salesforce data needed)
-- 1. Load skill: Invoke `using-ui-bundle-salesforce-data`
-- 2. Execute: Fetch schema, look up entities, generate queries/mutations, wire into components
-- 3. Verify: Run `npx eslint` on files with GraphQL queries
-- 4. Checkpoint: Data layer ready -- proceed to Phase 4
-
-**Phase 4 -- UI**
-- 1. Load skill: Invoke `building-ui-bundle-frontend`
-- 2. Execute: Build layout, pages, components, navigation. Replace all boilerplate.
-- 3. Verify: Run lint and build -- 0 errors required
-- 4. Checkpoint: UI complete -- proceed to Phase 5
-
-**Phase 5 -- Integrations** (skip if not requested)
-- 1. Load skill(s): Invoke `implementing-ui-bundle-agentforce-conversation-client` (5a) and/or `implementing-ui-bundle-file-upload` (5b). If both are needed, they are independent and can be executed in parallel.
-- 2. Execute: Follow each skill's workflow to add the integration
-- 3. Verify: Run lint and build
-- 4. Checkpoint: Integrations complete -- proceed to Phase 6
-
-**Phase 6 -- Deployment**
-- 1. Load skill: Invoke `deploying-ui-bundle`
-- 2. Execute: Follow the 7-step deployment sequence (auth, build, deploy, permissions, data, schema, final build)
-- 3. Verify: Confirm deployment succeeds and app is accessible
-- 4. Checkpoint: App deployed -- proceed to Phase 7 if needed
-
-**Phase 7a -- Experience Site** (skip if not requested or if Custom Application chosen)
-- 1. Load skill: Invoke `generating-ui-bundle-site`
-- 2. Execute: Resolve properties, generate site metadata, deploy
-- 3. Verify: Confirm site URL is accessible
-- 4. Checkpoint: Site live -- build complete
-
-**Phase 7b -- Custom Application** (skip if not requested or if Experience Site chosen)
-- 1. Load skill: Invoke `generating-ui-bundle-custom-app`
-- 2. Execute: Resolve app properties, generate CustomApplication metadata, add CustomApplication target to meta XML
-- 3. Verify: Confirm app appears in App Launcher
-- 4. Checkpoint: App registered -- build complete
-
-### STEP 3: Final Summary
-
-After all phases complete, present a build summary:
-
-```
-UI Bundle App Build Complete: [App Name]
-
-PHASES COMPLETED:
-[x] Phase 1: Scaffolding -- [app name] UI bundle created
-[x] Phase 2: Features -- [list of features installed, or "skipped"]
-[x] Phase 3: Data Access -- [list of entities wired up]
-[x] Phase 4: UI -- [count] pages, [count] components
-[x] Phase 5: Integrations -- [list or "none"]
-[x] Phase 6: Deployment -- deployed to [org]
-[x] Phase 7: Hosting Target -- [Experience Site URL / Custom Application name / "skipped"]
-
-FILES GENERATED:
-[list key files and their paths]
-
-NEXT STEPS:
-[any manual steps the user should take]
-```
-
----
-
-## Validation
-
-Before presenting the build as complete, verify:
-
-- [ ] **Scaffold exists**: UI bundle directory with valid meta XML and ui-bundle.json
-- [ ] **Dependencies installed**: `node_modules/` exists and `package.json` has expected packages
-- [ ] **Build passes**: `npm run build` produces `dist/` with no errors
-- [ ] **Lint passes**: `npx eslint src/` reports 0 errors
-- [ ] **No boilerplate**: All placeholder text, default titles, and template content has been replaced
-- [ ] **Navigation works**: `appLayout.tsx` has real nav items matching created pages
-- [ ] **Data layer wired**: Components use `@salesforce/sdk-data` (if data access phase was executed)
-- [ ] **CSP registered**: All external domains have CSP Trusted Site metadata (if applicable)
-
----
-
-## Error Handling
-
-### Category 1: Stop and Ask User
-
-- App purpose is too vague to determine pages or data needs
-- User wants features that conflict (e.g., "no authentication" + "show user-specific data")
-- Target org is unknown and deployment is requested
-
-### Category 2: Log Warning, Continue
-
-- A feature install has minor conflicts (resolve and continue)
-- Optional integration setup encounters non-blocking issues
-- Build has non-error warnings
-
----
-
-## Best Practices
-
-### 1. Always Follow Phase Order
-
-Never build UI before installing features. Never deploy before building. Dependencies are strict.
-
-### 2. Replace All Boilerplate
-
-Every generated app must feel purpose-built. Replace "React App" titles, "Vite + React" placeholders, and all default content with real app-specific text and branding.
-
-### 3. Design with Intent
-
-Follow the design thinking and frontend aesthetics guidance from `building-ui-bundle-frontend`. Every app should have a clear visual direction -- not generic defaults.

package/skills/building-ui-bundle-frontend/SKILL.md

@@ -1,135 +0,0 @@
----
-name: building-ui-bundle-frontend
-description: "MUST activate before editing ANY file under uiBundles/*/src/ for visual or UI changes to an EXISTING app — pages, components, sections, layout, styling, colors, fonts, navigation, animations, or any look-and-feel change. Use this skill when modifying pages, components, layout, styling, or navigation in an existing UI bundle app. Activate when the project contains appLayout.tsx, routes.tsx, src/pages/, src/components/, or global.css. This skill contains critical project-specific conventions (appLayout.tsx shell, shadcn/ui components, Tailwind CSS, Salesforce base-path routing, module restrictions) that override general knowledge. Without this skill, generated code will use wrong imports, break routing, or ignore project structure. Do NOT use when creating a new app from scratch (use building-ui-bundle-app instead)."
-metadata:
-  version: "1.0"
----
-
-# UI Bundle UI
-
-## Identify the Task
-
-Determine which category the request falls into:
-
-| Category | Examples | Implementation Guide |
-|----------|----------|---------------------|
-| **Page** | New routed page (contacts, dashboard, settings) | `implementation/page.md` |
-| **Header / Footer** | Site-wide nav bar, footer, branding | `implementation/header-footer.md` |
-| **Component** | Widget, card, table, form, dialog | `implementation/component.md` |
-
----
-
-## Layout and Navigation
-
-`appLayout.tsx` is the source of truth for navigation and layout. Every page shares this shell.
-
-When making any change that affects navigation, header, footer, sidebar, theme, or layout:
-
-1. Edit `src/appLayout.tsx` — the layout used by `routes.tsx`
-2. Replace all default/template nav items and labels with app-specific links and names
-3. Replace placeholder app name everywhere: header, nav brand, footer, `<title>` in `index.html`
-
-Before finishing, confirm: Did I update `appLayout.tsx` with real nav items and branding?
-
-| What | Where |
-|------|-------|
-| Layout, nav, branding | `src/appLayout.tsx` |
-| Document title | `index.html` |
-| Root page content | Component at root route in `routes.tsx` |
-
----
-
-## React and TypeScript Standards
-
-### Routing
-
-Use a single router package. With `createBrowserRouter` / `RouterProvider`, all imports must come from `react-router` (not `react-router-dom`).
-
-If the app uses a client-side router (React Router, Remix Router, Vue Router, etc.), always derive basename / basepath / base from the document's `<base href>` tag at runtime. Never hardcode the basename:
-
-```js
-const basename = document.querySelector('base')
-  ? new URL(document.querySelector('base').href).pathname.replace(/\/$/, '')
-  : '/';
-const router = createBrowserRouter(routes, { basename });
-```
-
-### Component Library and Styling
-
-- **shadcn/ui** for components: `import { Button } from '@/components/ui/button';`
-- **Tailwind CSS** utility classes
-
-### URL and Path Handling
-
-Apps run behind dynamic base paths. Router navigation (`<Link to>`, `navigate()`) uses absolute paths (`/x`). Non-router attributes (`<img src>`) use dot-relative (`./x`). Prefer Vite `import` for static assets.
-
-### TypeScript
-
-- Never use `any` — use proper types, generics, or `unknown` with type guards
-- Event handlers: `(event: React.FormEvent<HTMLFormElement>): void`
-- State: `useState<User | null>(null)` — always provide the type parameter
-- No unsafe assertions (`obj as User`) — use type guards instead
-
-### Module Restrictions
-
-React UI bundles must not import Salesforce platform modules like `lightning/*` or `@wire` (LWC-only). For data access, use the `using-ui-bundle-salesforce-data` skill.
-
----
-
-## Design Thinking
-
-Before coding, commit to a bold aesthetic direction:
-
-- **Purpose:** What problem does this interface solve? Who uses it?
-- **Tone:** Pick a clear direction — brutally minimal, maximalist, retro-futuristic, organic, luxury, playful, editorial, brutalist, art deco, soft/pastel, industrial. Use these as inspiration but design one true to the context.
-- **Differentiation:** What makes this unforgettable? What's the one thing someone will remember?
-
-Choose a clear conceptual direction and execute it with precision. Bold maximalism and refined minimalism both work — the key is intentionality, not intensity.
-
----
-
-## Frontend Aesthetics
-
-- **Typography:** Choose distinctive, characterful fonts. Pair a display font with a refined body font. Never default to Inter, Roboto, Arial, Space Grotesk, or system fonts.
-- **Color:** Commit to a cohesive palette using CSS variables. Dominant colors with sharp accents outperform timid, evenly-distributed palettes. Avoid cliched purple gradients on white.
-- **Motion:** Focus on high-impact moments — one well-orchestrated page load with staggered reveals (`animation-delay`) creates more delight than scattered micro-interactions. Use scroll-triggering and hover states that surprise. Prefer CSS-only solutions; use Motion library for React when available.
-- **Spatial Composition:** Unexpected layouts — asymmetry, overlap, diagonal flow, grid-breaking elements. Generous negative space OR controlled density.
-- **Backgrounds & Depth:** Create atmosphere rather than defaulting to solid colors. Gradient meshes, noise textures, geometric patterns, layered transparencies, dramatic shadows, decorative borders, grain overlays.
-
-- **Mobile Responsiveness:** All generated UI MUST be mobile-responsive. Use Tailwind responsive prefixes (`sm:`, `md:`, `lg:`) to adapt layouts across breakpoints. Stack columns on small screens, use flexible grids, and ensure touch targets are at least 44px. Test that navigation, typography, and spacing work on mobile viewports.
-
-Match implementation complexity to the aesthetic vision. Maximalist designs need elaborate animations and effects. Minimalist designs need restraint, precision, and careful spacing/typography. No two designs should look the same — vary themes, fonts, and aesthetics across generations.
-
----
-
-## Clarifying Questions
-
-Ask one question at a time and stop when you have enough context.
-
-### For a Page
-1. Name and purpose?
-2. URL path?
-3. Should it appear in navigation?
-4. Access control? (public, authenticated via `PrivateRoute`, or unauthenticated via `AuthenticationRoute`)
-5. Content sections? (list, form, table, detail view)
-6. Data fetching needs?
-
-### For a Header / Footer
-1. Header, footer, or both?
-2. Contents? (logo, nav links, user avatar, copyright, social icons)
-3. Sticky header?
-4. Color scheme or style direction?
-
-### For a Component
-1. What should it do?
-2. Which page does it belong to?
-3. Shared/reusable or specific to one feature?
-4. Data or props needed?
-5. Internal state? (loading, toggle, form state)
-6. Specific shadcn components to use?
-
----
-
-## Verification
-
-Before completing, run lint and build from the UI bundle directory. Lint must result in 0 errors and build must succeed.

package/skills/building-ui-bundle-frontend/implementation/component.md

@@ -1,78 +0,0 @@
-# Implementation — Component
-
-### Rules
-
-1. **Always use shadcn components** from `@/components/ui` — never build raw HTML equivalents for buttons, inputs, cards, alerts, tabs, tables, or labels.
-2. **All styling via Tailwind** — utility classes only. No inline `style={{}}`, CSS Modules, or other styling systems.
-3. **Use design tokens** — prefer `bg-background`, `text-foreground`, `text-muted-foreground`, `border`, `bg-primary`, `text-destructive`, `rounded-lg` over hardcoded colors.
-4. **Use `cn()`** from `@/lib/utils` for conditional or composable class names.
-5. **TypeScript** — functional components with typed props interface; always accept `className?: string`.
-
-### File Location — Component
-
-| Component type                                 | Location                                 | Export                                   |
-| ---------------------------------------------- | ---------------------------------------- | ---------------------------------------- |
-| Shared UI primitive (reusable across features) | `src/components/ui/` — add to `index.ts` | Named export                             |
-| Feature-specific (e.g., dashboard widget)      | `src/components/<feature>/`              | Named export, import directly where used |
-| Page-level layout element                      | `src/components/layout/`                 | Named export                             |
-
-### Component Structure
-
-```tsx
-import { Card, CardHeader, CardTitle, CardContent } from "@/components/ui";
-import { cn } from "@/lib/utils";
-
-interface MyComponentProps {
-  title: string;
-  value: string;
-  className?: string;
-}
-
-export function MyComponent({ title, value, className }: MyComponentProps) {
-  return (
-    <Card className={cn("border", className)}>
-      <CardHeader>
-        <CardTitle className="text-sm font-medium">{title}</CardTitle>
-      </CardHeader>
-      <CardContent>
-        <p className="text-2xl font-semibold text-foreground">{value}</p>
-      </CardContent>
-    </Card>
-  );
-}
-```
-
-### State and Hooks
-
-- **Local state only:** keep `useState`, `useReducer`, `useRef` inside the component.
-- **Shared or complex state:** extract to a custom hook in `src/hooks/` (prefix with `use`, e.g. `useFormData`). Do this when more than one component needs the state, or when multiple hooks are composed together.
-
-### Adding the Component to a Page
-
-```tsx
-// In the target page file, e.g. src/pages/HomePage.tsx
-import { MyComponent } from "@/components/<feature>/MyComponent";
-
-export default function HomePage() {
-  return (
-    <div className="max-w-7xl mx-auto px-4 sm:px-6 lg:px-8 py-12">
-      <MyComponent title="Status" value="Active" />
-    </div>
-  );
-}
-```
-
-### Useful Patterns — Component
-
-- **Programmatic navigation:** use `useNavigate` from `react-router`; call `navigate(path)` — consistent with GlobalSearchInput, SearchResultCard, MaintenanceTable, and other components in the UI bundle.
-- **Page container:** `max-w-7xl mx-auto px-4 sm:px-6 lg:px-8 py-12`
-- **Icons:** `lucide-react`; add `aria-hidden="true"` on decorative icons
-- **Focus styles:** use `focus-visible:` variants
-- **Multiple visual variants:** use CVA (`cva`) and `VariantProps`
-- **shadcn import barrel:** `import { Button, Card, Input } from "@/components/ui"`
-
-### Confirm — Component
-
-- Imports use path aliases (`@/`, not deep relative paths)
-- No raw `<button>`, `<input>`, or styled `<div>` where shadcn equivalents exist
-- No inline `style={{}}` — Tailwind only