SalesforceCommerceCloud · yhsieh1 · Jul 14, 2025 · Jul 10, 2025 · Jul 10, 2025 · Jul 10, 2025
@@ -1,3 +1,6 @@
+## v3.12.0-dev.0
+- Add development guidelines and create page Cursor rules for generated project [2786](https://github.com/SalesforceCommerceCloud/pwa-kit/pull/2786)
+
 ## v3.11.0-dev.0 (May 23, 2025)
 - Fix exiting before `program.json` content can be flushed [#2699](https://github.com/SalesforceCommerceCloud/pwa-kit/pull/2699)
 - Add `program.json` + Support for Agent-Friendly CLI Input via stdio [#2662](https://github.com/SalesforceCommerceCloud/pwa-kit/pull/2662)

@@ -0,0 +1,40 @@
+---
+description: Salesforce Commerce Composable Storefront Development Guidelines
+globs: 
+alwaysApply: false
+---
+
+# Commerce Composable Storefront Development Guidelines
+
+## Overview
+Guidelines for Salesforce Commerce Composable Storefront development using PWA Kit, Retail React App, and Chakra UI.
+
+## Core Principles
+- Analyze requirements and existing codebase thoroughly
+- Use existing components and hooks when possible
+- Plan before implementing
+- Test comprehensively with Jest
+
+## PWA Kit Essentials
+
+### Architecture
+- Server-side rendering (SSR) for initial loads
+- Client-side rendering (CSR) for interactions
+- Isomorphic code (works on server and client)
+- Proxy requests via `/mobify/proxy/<PROXY_PATH>`
+
+### Special Components
+- Components starting with `_` are special PWA Kit components
+- `_app-config`: Top-level app configuration
+- `_app`: Persistent layout (header, footer, sidebar)
+- `_error`: 404 and error pages
+
+## Development Rules
+- Use kebab-case for file names (except special components with `_`)
+- Use Chakra UI and existing components
+- Create modular, reusable components
+- Use React Hooks for state management
+- Access data via commerce-sdk-react hooks
+- Ensure mobile-friendly and accessible components
+- Maintain consistent code formatting using project standards
+- Write comprehensive test coverage
@@ -0,0 +1,16 @@
+---
+description: Page Creation Rule - automatically apply when user asks to create new page, add page, make page, build page, generate page
+globs:
+alwaysApply: false
+---
+USE WHEN create a new page, add a new page, make a new page, build a new page, generate a new page, create page, add page, make page, build page, generate page
+
+**Mandatory**
+- DO ask user to clarify page name and page route before proceed
+- ONLY Create a bare minimum page component
+- Do NOT include other project components or hooks unless specifically requested
+- Do NOT add extra styling, layout, or features unless explicitly asked
+
+## Implementation Steps
+1. Create simple component in `app/pages/[page-name]/index.jsx`
+2. Add route to `app/routes.jsx`
@@ -6,103 +6,40 @@
  */
 import {EmptyJsonSchema} from './utils'
 
-const guidelinesText = `# Salesforce Commerce Composable Storefront Development Guidelines
+const guidelinesText = `# Commerce Composable Storefront Development Guidelines
 
 ## Overview
-This document offers guidelines in the development of Salesforce Commerce Composable Storefront applications using PWA Kit. The AI should possess a comprehensive understanding of the PWA Kit architecture, sample Retail React App, Chakra UI, and standard React application practices.
+Guidelines for Salesforce Commerce Composable Storefront development using PWA Kit, Retail React App, and Chakra UI.
 
 ## Core Principles
-
-### Project Understanding
-- Thoroughly analyze requests and the existing project for successful implementation.
-- Promptly clarify ambiguous requirements.
-
-### Development Workflow
-- **Analyze Requirements** - Clearly define the objectives and functionalities required.
-- **Review Existing Code** - Examine the current codebase to identify similar solutions and potentially reusable components.
-- **Understand Existing Hooks and Utilities** - Familiarize with hooks and utility functions available within the project, including those from commerce-sdk-react and template-retail-react-app modules.
-- **Plan Implementation** - Design component structure before coding.
-- **Implement Incrementally** - Develop and test the service in small, manageable steps.
-- **Test Thoroughly** - Ensure comprehensive testing, including the use of Jest.
-
-## Technical Stack
-
-### Core Technologies
-- **React** - UI components and SPA architecture
-- **Express** - Server-side rendering and backend
-- **@salesforce/commerce-sdk-react** - Commerce Cloud API integration (hooks)
-- **PWA Kit** - SSR, routing, config, Salesforce integration
-- **Chakra UI V2** - UI components and theming
-- **Emotion** - CSS-in-JS styling
-- **React Router** - Routing
-- **React Intl** - Localization
-- **React Query** - Data fetching/caching
-- **Webpack** - Bundling
-- **React Testing Library, Jest** - Testing libraries
-- **react-helmet, framer-motion, etc.** - Utilities, animation, head management
-- **ESLint/Prettier** - Code formatting and linting
-
-## PWK Kit Architecture
-
-### Configuration Files
-- PWA Kit apps are customized using configuration files for API access, URL formatting, and server-side rendering.
-- These files support JavaScript, YAML, and JSON formats, with default.js being the standard.
-- Configuration values are serialized for isomorphic rendering, so secrets must not be included.
-- Environment-specific configuration files can replace or complement default.js.
-- File precedence is .js > .yml > .yaml > .json if base names are the same.
-
-### Proxy Requests
-- Managed Runtime's proxy feature routes API requests through the storefront domain to avoid CORS issues and improve performance.
-- Local proxy configurations are set in config/default.js, while Managed Runtime deployments use Runtime Admin or the Managed Runtime API.
-- Requests use the /mobify/proxy/<PROXY_PATH> pattern.
-- Proxied requests and responses are modified for transparent operation.
-- Proxied requests are uncached by default but can be cached using a caching path prefix.
-
-### Rendering
-- PWA Kit uses server-side rendering (SSR) for fast initial page loads, leveraging CDN caching.
-- After the first load, client-side rendering (CSR) takes over for fluid user interactions.
-- Application code must be isomorphic, functioning in both server and client environments, often with conditional logic.
-- Props from API requests are serialized into the page source during SSR for client-side hydration.
-- A correlation ID is provided on each page for tracking requests across PWA Kit and other systems.
-
-### Routing
-- PWA Kit uses Express.js and React Router for handling requests and rendering components.
-- Routes are defined in app/routes.jsx as an array of objects with 'path' and 'component' properties.
-- You can use both withReactQuery and withLegacyGetProps at the same time.
-- getProps and shouldGetProps were removed from the default template of pages of the Retail React App, but aren't deprecated. Long-term support for these methods remains.
-
-### PWA Kit Special Components
-- Customize your storefront by overriding default special components that start with an underscore (_), such as app/components/_app-config/index.jsx.
-- app/components/_app-config: The top-level component for app-wide configurations like theme providers and state management.
-- app/components/_app: The child of _app-config. Use it for layout and UI that persist throughout your React app, such as the header, footer, and sidebar.
-- app/components/_error: Renders when a page or its data isn't found, or when an error occurs, returning a 404 status.
-
-### State Management
-- PWA Kit applications support various state management approaches, including simple prop-passing or React's Context API.
-- The React Context API can be used with useReducer and useContext for shared global state.
-- The AppConfig special component is the primary place to initialize a state management system.
-- When integrating libraries like Redux, AppConfig methods such as restore, freeze, extraGetPropsArgs, and render are utilized.
-
-### PWA Kit Extensibility
-- In PWA Kit v3, you can extend a base template (@salesforce/retail-react-app) by replacing specific files using a local "overrides directory."
-- Extensibility is configured in package.json with the base template (ccExtensibility.extends) and your overrides directory (ccExtensibility.overridesDir).
-- To override a file, recreate its exact path and filename in your overrides directory.
-
-### PWA Kit Storefront Development
-- Start development with Retail React App sample codebase and tooling.
-- Use included npm scripts for automating development tasks like build, test, and lint.
-- Access Shopper data through the commerce-sdk-react hooks to fetch, cache, and mutate utilizing Salesforce Commerce API (SLAS) and OCAPI.
-- Use Chakra UI and existing components when available.
-- Create simple, functional, modular, reusable components.
-- Use the React Helmet library to modify the HTML tags in Document, such as <head>.
-- Use kebab-case for file names. Only start with an underscore (_) if they are special components.
-- Use React Hooks (e.g., useState, useEffect, useContext, useMemo, useCallback) for state management and side effects. 
-
-## Quality Standards
-- Maintain consistent code formatting using project standards.
-- Write comprehensive test coverage.
-- Ensure components are accessible and mobile-friendly.
-- Follow security best practices for all code.
+- Analyze requirements and existing codebase thoroughly
+- Use existing components and hooks when possible
+- Plan before implementing
+- Test comprehensively with Jest
+
+## PWA Kit Essentials
+
+### Architecture
+- Server-side rendering (SSR) for initial loads
+- Client-side rendering (CSR) for interactions
+- Isomorphic code (works on server and client)
+- Proxy requests via \`/mobify/proxy/<PROXY_PATH>\`
+
+### Special Components
+- Components starting with \`_\` are special PWA Kit components
+- \`_app-config\`: Top-level app configuration
+- \`_app\`: Persistent layout (header, footer, sidebar)
+- \`_error\`: 404 and error pages
+
+## Development Rules
+- Use kebab-case for file names (except special components with \`_\`)
+- Use Chakra UI and existing components
+- Create modular, reusable components
+- Use React Hooks for state management
+- Access data via commerce-sdk-react hooks
+- Ensure mobile-friendly and accessible components
+- Maintain consistent code formatting using project standards
+- Write comprehensive test coverage
 `
 
 export default {

@@ -27,7 +27,7 @@ describe('PWA Development Guidelines', () => {
                     {
                         type: 'text',
                         text: expect.stringContaining(
-                            'Salesforce Commerce Composable Storefront Development Guidelines'
+                            'Commerce Composable Storefront Development Guidelines'
                         )
                     }
                 ]
@@ -41,9 +41,8 @@ describe('PWA Development Guidelines', () => {
             const requiredSections = [
                 'Overview',
                 'Core Principles',
-                'Technical Stack',
-                'PWK Kit Architecture',
-                'Quality Standards'
+                'PWA Kit Essentials',
+                'Development Rules'
             ]
 
             requiredSections.forEach((section) => {

@@ -0,0 +1,8 @@
+---
+description: Check and verify accessibility on local project
+globs: 
+alwaysApply: false
+---
+To check accessibility of a project, use the accessibility rules defined in PROJECT_ROOT/.cursor/rules/cursor-accessibility-mdc/ directory.
+Run an automated scan for the entire codebase within the project and check for any violations.
+Show the scanned results in summary and detailed violations if any.
@@ -0,0 +1,26 @@
+---
+description: When accessibility is checked. Check if Buttons must have a discernible name using text or aria attributes
+globs: 
+alwaysApply: false
+---
+
+# Rule: accessibility-button-name
+
+Buttons must have a discernible name using text or aria attributes
+
+## 🔍 Pattern
+
+```regex
+<button(?![^>]*\b(aria-label|aria-labelledby|title|name)=)
+```
+
+## 📍 Examples
+
+```tsx
+// ❌ Bad
+<button></button>
+// ✅ Good
+<button>Submit</button>
+// ✅ Good
+<button aria-label="Close dialog"><XIcon /></button>
+```
@@ -0,0 +1,26 @@
+---
+description: When accessibility is checked. Check if heading levels should increase sequentially for semantic structure
+globs: 
+alwaysApply: false
+---
+
+# Rule: accessibility-heading-order
+
+Heading levels should increase sequentially for semantic structure
+
+## 🔍 Pattern
+
+```regex
+<h([3-6])>
+```
+
+## 📍 Examples
+
+```tsx
+// ❌ Bad
+<h1>Main Title</h1>
+<h4>Subsection</h4>
+// ✅ Good
+<h1>Main Title</h1>
+<h2>Subsection</h2>
+```
@@ -0,0 +1,24 @@
+---
+description: When accessibility is checked. Ensure all <img> tags include descriptive alt attributes
+globs: 
+alwaysApply: false
+---
+
+# Rule: accessibility-image-alt
+
+Ensure all <img> tags include descriptive alt attributes
+
+## 🔍 Pattern
+
+```regex
+<img(?![^>]*\balt=)
+```
+
+## 📍 Examples
+
+```tsx
+// ❌ Bad
+<img src="photo.jpg" />
+// ✅ Good
+<img src="photo.jpg" alt="Company logo" />
+```
@@ -0,0 +1,27 @@
+---
+description: When accessibility is checked. Check if Input fields must have a label or aria-label for screen readers
+globs: 
+alwaysApply: false
+---
+
+# Rule: accessibility-input-label
+
+Input fields must have a label or aria-label for screen readers
+
+## 🔍 Pattern
+
+```regex
+<input(?![^>]*(aria-label|aria-labelledby|id=))
+```
+
+## 📍 Examples
+
+```tsx
+// ❌ Bad
+<input type="text" />
+// ✅ Good
+<input aria-label="Search" />
+// ✅ Good with label
+<label htmlFor="email">Email</label>
+<input id="email" type="text" />
+```
@@ -0,0 +1,26 @@
+---
+description: When accessibility is checked. Check if Anchor tags must have accessible names
+globs: 
+alwaysApply: false
+---
+
+# Rule: accessibility-link-name
+
+Anchor tags must have accessible names
+
+## 🔍 Pattern
+
+```regex
+<a(?![^>]*\b(aria-label|aria-labelledby|title)=)(?![^>]*>\s*\w+\s*</a>)
+```
+
+## 📍 Examples
+
+```tsx
+// ❌ Bad
+<a href="/profile"></a>
+// ✅ Good
+<a href="/profile">Your Profile</a>
+// ✅ Good
+<a href="/profile" aria-label="Profile page"><UserIcon /></a>
+```