@julianoczkowski/create-trimble-app 2.0.0

package/templates/react/.cursor/skills/integrate-modus-icons/SKILL.md

@@ -0,0 +1,300 @@
+---
+name: integrate-modus-icons
+description: Help with correct Modus icon usage patterns including naming conventions, sizing, and accessibility
+---
+
+# Integrate Modus Icons
+
+Help with correct Modus icon usage patterns including naming conventions, sizing, and accessibility.
+
+## When to Use
+
+Use this skill when:
+- Adding icons to components or buttons
+- Choosing the right icon name
+- Sizing icons correctly
+- Ensuring proper accessibility
+- Integrating icons with Modus components
+
+## Icon Naming Convention
+
+**CRITICAL**: Modus icons use **UNDERSCORES (_)**, not hyphens (-)
+
+### Correct Icon Names
+
+```tsx
+// ✅ CORRECT: Use underscores
+<i className="modus-icons">save_disk</i>
+<i className="modus-icons">arrow_left</i>
+<i className="modus-icons">add_circle</i>
+<i className="modus-icons">user_permissions</i>
+
+// ❌ WRONG: Don't use hyphens
+<i className="modus-icons">save-disk</i>
+<i className="modus-icons">arrow-left</i>
+```
+
+## Usage Patterns
+
+### Pattern 1: Using ModusIcon Component
+
+```tsx
+import ModusIcon from "./components/ModusIcon";
+
+// Informational icon (announced by screen reader)
+<ModusIcon
+  name="user_add"
+  size="lg"
+  decorative={false}
+  ariaLabel="Add user"
+/>
+
+// Decorative icon (not announced)
+<ModusIcon
+  name="chevron_right"
+  size="md"
+  decorative={true}
+/>
+```
+
+Reference: `src/components/ModusIcon.tsx`
+
+### Pattern 2: Using Bare `<i>` Element
+
+```tsx
+// Decorative icon
+<i className="modus-icons text-lg" aria-hidden="true">
+  user_add
+</i>
+
+// Informational icon
+<i
+  className="modus-icons text-md"
+  role="img"
+  aria-label="Settings"
+>
+  settings
+</i>
+```
+
+### Pattern 3: Icons in Buttons
+
+```tsx
+import ModusButton from "./components/ModusButton";
+
+// Icon with text (left position)
+<ModusButton
+  icon="save_disk"
+  iconPosition="left"
+>
+  Save File
+</ModusButton>
+
+// Icon with text (right position)
+<ModusButton
+  icon="download"
+  iconPosition="right"
+>
+  Download
+</ModusButton>
+
+// Icon only (requires aria-label)
+<ModusButton
+  icon="settings"
+  iconPosition="only"
+  ariaLabel="Open settings"
+/>
+```
+
+Reference: `src/components/ModusButton.tsx:149-206` for icon rendering logic
+
+## Icon Sizing
+
+### Tailwind Text Classes
+
+Use Tailwind text utilities for sizing:
+
+```tsx
+// Small icon
+<i className="modus-icons text-sm">info</i>
+
+// Base icon (Modus default 14px)
+<i className="modus-icons text-base">warning</i>
+
+// Large icon (16px)
+<i className="modus-icons text-lg">error</i>
+
+// Extra large icon (18px)
+<i className="modus-icons text-xl">success</i>
+```
+
+### Modus Font Size Scale
+
+| Tailwind Class | Size | Usage |
+|----------------|------|-------|
+| `text-2xs` | 8px | Micro icons, badges |
+| `text-xs` | 10px | Small labels, captions |
+| `text-sm` | 12px | Secondary icons |
+| `text-base` | 14px | **Modus default size** |
+| `text-lg` | 16px | Body text icons |
+| `text-xl` | 18px | Large icons |
+| `text-2xl` | 20px | Prominent icons |
+| `text-3xl` | 24px | Display icons |
+
+### Button Icon Sizing
+
+Icons in buttons automatically scale based on button size:
+
+```tsx
+// Icons scale with button size
+<ModusButton size="xs" icon="star" iconPosition="left">Extra Small</ModusButton>
+<ModusButton size="sm" icon="star" iconPosition="left">Small</ModusButton>
+<ModusButton size="md" icon="star" iconPosition="left">Medium</ModusButton>
+<ModusButton size="lg" icon="star" iconPosition="left">Large</ModusButton>
+
+// Icon-only buttons use larger icons
+<ModusButton size="md" icon="settings" iconPosition="only" ariaLabel="Settings" />
+```
+
+Automatic sizing rules:
+- **Icons with text**: Scale with button size (`text-xs` for xs, `text-lg` for md)
+- **Icon-only buttons**: Get larger icons (`text-sm` for xs, `text-xl` for md)
+
+Reference: `src/components/ModusButton.tsx:98-134`
+
+## Icon Colors
+
+Use design system colors:
+
+```tsx
+// Primary color
+<i className="modus-icons text-primary">info</i>
+
+// Success color
+<i className="modus-icons text-success">check_circle</i>
+
+// Warning color
+<i className="modus-icons text-warning">warning</i>
+
+// Error color
+<i className="modus-icons text-error">error</i>
+
+// Muted text
+<i className="modus-icons text-muted-foreground">help</i>
+```
+
+## Accessibility
+
+### Decorative Icons
+
+For purely decorative icons, use `aria-hidden="true"`:
+
+```tsx
+<button>
+  <i className="modus-icons mr-2" aria-hidden="true">save_disk</i>
+  Save Document
+</button>
+```
+
+### Informational Icons
+
+For icons that convey meaning, provide proper labels:
+
+```tsx
+// Using role="img" and aria-label
+<i className="modus-icons" role="img" aria-label="Warning">
+  warning
+</i>
+
+// Using aria-label on parent element
+<button aria-label="Delete item">
+  <i className="modus-icons" aria-hidden="true">delete</i>
+</button>
+```
+
+### Icon-Only Buttons
+
+Always provide accessible labels:
+
+```tsx
+<ModusButton
+  icon="settings"
+  iconPosition="only"
+  ariaLabel="Open settings menu"
+/>
+```
+
+## Common Icon Names
+
+### Navigation & UI
+
+- `arrow_left`, `arrow_right`, `arrow_up`, `arrow_down`
+- `chevron_left`, `chevron_right`
+- `menu`, `close`, `home`, `settings`, `search`
+
+### Actions & Operations
+
+- `add`, `remove`, `edit_combination`, `delete`
+- `save_disk`, `download`, `upload`, `copy_content`
+
+### Status & Feedback
+
+- `check`, `check_circle`, `error`, `warning`, `alert`, `info`, `help`
+
+### Files & Documents
+
+- `file`, `file_upload`, `file_download`
+- `folder_open`, `folder_closed`, `document`, `image`, `video`
+
+### User & Account
+
+- `person`, `people_group`, `user_account`, `user_add`
+- `key`, `lock`, `lock_open`
+
+## Validating Icon Names
+
+Check icon names against the complete list in:
+- `.cursor/rules/modus-icon-names.mdc` - Complete list of 700+ valid icon names
+
+Common mistakes:
+- Using hyphens instead of underscores
+- Wrong capitalization (all lowercase)
+- Typos in icon names
+
+## Testing Icons
+
+### Visual Verification
+
+Icons should display as glyphs, not text. If you see text like "save_disk" instead of an icon:
+
+1. Check font CSS is loaded in `index.html`
+2. Verify icon name uses underscores
+3. Confirm `modus-icons` class is applied
+4. Check network tab for font file download
+
+### Browser DevTools Check
+
+```javascript
+// Check if font is loaded
+const testElement = document.createElement('span');
+testElement.className = 'modus-icons';
+document.body.appendChild(testElement);
+const fontFamily = window.getComputedStyle(testElement).fontFamily;
+console.log('Font loaded:', fontFamily.includes('modus-icons'));
+document.body.removeChild(testElement);
+```
+
+## Common Mistakes
+
+1. **Wrong naming**: Using hyphens instead of underscores
+2. **Wrong sizing**: Using pixel values instead of Tailwind classes
+3. **Missing accessibility**: Not providing aria-label for informational icons
+4. **Wrong icon name**: Not checking against valid icon list
+5. **Font not loaded**: Missing CSS import for Modus icons
+
+## Related Files
+
+- `src/components/ModusIcon.tsx` - Icon component wrapper
+- `src/components/ModusButton.tsx` - Button icon integration
+- `.cursor/rules/modus-icon-names.mdc` - Complete icon name list
+- `.cursor/rules/modus-icons-react.mdc` - Detailed icon documentation

package/templates/react/.cursor/skills/run-lint-checks/SKILL.md

@@ -0,0 +1,235 @@
+---
+name: run-lint-checks
+description: Run comprehensive lint checks for React + Vite project to ensure design system compliance, type safety, and code quality. Use when making code changes, before completing tasks, or when the user requests lint checks.
+---
+
+# Run Lint Checks
+
+Automatically run all linting and quality checks for the React + Vite project to ensure design system compliance, type safety, and code quality.
+
+## When to Use
+
+- **Before completing any task** - Always run lint checks before marking tasks as complete
+- **After making code changes** - Run checks after modifying TypeScript, TSX, or CSS files
+- **Before committing code** - Ensure all quality gates pass before committing
+- **When user requests** - Run checks when explicitly requested by the user
+- **During code review** - Verify code quality and design system compliance
+
+## Instructions
+
+### Mandatory Pre-Completion Checklist
+
+**CRITICAL**: Before marking any development task as complete, you MUST:
+
+1. Run all lint checks using `npm run lint:all`
+2. Fix any violations found
+3. Verify TypeScript type checking passes
+4. Ensure all design system compliance checks pass
+
+### Running Lint Checks
+
+Execute the comprehensive lint check command:
+
+```bash
+npm run lint:all
+```
+
+This command runs all checks in sequence:
+- TypeScript type checking (`npm run type-check`)
+- Modus icons validation (`npm run lint:icons`)
+- Semantic HTML compliance (`npm run lint:semantic`)
+- Color compliance (`npm run lint:colors`)
+- Inline styles validation (`npm run lint:styles`)
+- Border violations (`npm run lint:borders`)
+- Opacity utilities (`npm run lint:opacity`)
+- Icon name validation (`npm run lint:icon-names`)
+
+### Individual Lint Commands
+
+If you need to run checks individually:
+
+```bash
+# ESLint (React/TypeScript)
+npm run lint
+
+# TypeScript type checking
+npm run type-check
+
+# Modus icons library validation
+npm run lint:icons
+
+# Semantic HTML compliance
+npm run lint:semantic
+
+# Design system color compliance
+npm run lint:colors
+
+# Inline styles validation
+npm run lint:styles
+
+# Border pattern violations
+npm run lint:borders
+
+# Opacity utilities validation
+npm run lint:opacity
+
+# Icon name validation
+npm run lint:icon-names
+```
+
+### Handling Violations
+
+When violations are found:
+
+1. **Read the error messages carefully** - Each lint script provides specific file locations and violation details
+2. **Fix violations immediately** - Don't proceed until all violations are resolved
+3. **Re-run checks** - After fixing, run `npm run lint:all` again to verify
+4. **Document fixes** - If a fix requires architectural changes, explain the reasoning
+
+### Common Violations to Fix
+
+#### Inline Styles
+```tsx
+// ❌ VIOLATION
+<div style={{ backgroundColor: 'var(--modus-wc-color-base-page)' }}>
+<div style={{ marginRight: '8px' }}>
+
+// ✅ CORRECT
+<div className="bg-background mr-2 text-foreground">
+```
+
+#### Color Usage
+```tsx
+// ❌ VIOLATION
+<div style={{ backgroundColor: '#ffffff' }}>
+<div className="bg-blue-500 text-red-400">
+
+// ✅ CORRECT
+<div className="bg-background text-foreground">
+```
+
+#### Icon Usage
+```tsx
+// ❌ VIOLATION
+<i className="fa fa-home"></i>
+<i className="material-icons">home</i>
+
+// ✅ CORRECT
+<i className="modus-icons">home</i>
+```
+
+#### Semantic HTML
+```tsx
+// ❌ VIOLATION
+<h1>Title</h1>
+<p>Content</p>
+<section>Section</section>
+
+// ✅ CORRECT (use div elements only)
+<div className="text-4xl font-bold">Title</div>
+<div className="text-base">Content</div>
+<div className="bg-card">Section</div>
+```
+
+#### Border Violations
+```tsx
+// ❌ VIOLATION
+<div className="border border-red-500">Error message</div>
+
+// ✅ CORRECT
+<div className="border-destructive">Error message</div>
+```
+
+#### Opacity Violations
+```tsx
+// ❌ VIOLATION
+<div className="text-foreground/80">Text with opacity</div>
+
+// ✅ CORRECT
+<div className="text-foreground-80">Text with opacity</div>
+```
+
+## Quality Gates
+
+All of these must pass before code is considered complete:
+
+- [ ] `npm run lint` - 0 ESLint errors
+- [ ] `npm run type-check` - 0 TypeScript errors
+- [ ] `npm run lint:icons` - 0 icon violations
+- [ ] `npm run lint:semantic` - 0 semantic HTML violations
+- [ ] `npm run lint:colors` - 0 color violations
+- [ ] `npm run lint:styles` - 0 inline style violations
+- [ ] `npm run lint:borders` - 0 border violations
+- [ ] `npm run lint:opacity` - 0 opacity violations
+- [ ] `npm run lint:icon-names` - 0 invalid icon names
+
+## Integration with Development Workflow
+
+This skill integrates with the project's development workflow:
+
+1. **During Development**: Run checks periodically to catch issues early
+2. **Before Completion**: Always run `npm run lint:all` before marking tasks complete
+3. **Pre-Commit**: All checks must pass before committing code
+4. **CI/CD**: These same checks run in CI/CD pipelines
+
+## Error Handling
+
+If lint checks fail:
+
+1. **Don't skip or ignore violations** - All violations must be fixed
+2. **Provide clear error messages** - Show the user exactly what failed and where
+3. **Suggest fixes** - When possible, provide specific guidance on how to fix violations
+4. **Re-run after fixes** - Always verify fixes by running checks again
+
+## React-Specific Patterns
+
+### Component Patterns
+- Use wrapper components from `src/components/` not web components directly
+- Use `useRef` + `useEffect` for event listeners with proper cleanup
+- Let Modus components manage their own state (don't control from React state)
+
+### Event Handling
+```tsx
+// ✅ CORRECT: Event listener pattern
+useEffect(() => {
+  const component = componentRef.current;
+  if (!component) return;
+
+  const handleEvent = (event: Event) => {
+    onEvent?.(event as CustomEvent<EventDetailType>);
+  };
+
+  if (onEvent) {
+    component.addEventListener('eventName', handleEvent);
+  }
+
+  return () => {
+    if (onEvent) {
+      component.removeEventListener('eventName', handleEvent);
+    }
+  };
+}, [onEvent]);
+```
+
+### Conditional Props
+```tsx
+// ✅ CORRECT: Conditional spreading
+<ModusWcComponent
+  {...(color && { color })}
+  {...(variant && { variant })}
+/>
+
+// ❌ WRONG: Passing undefined
+<ModusWcComponent
+  color={color} // May be undefined
+/>
+```
+
+## Notes
+
+- Lint checks are fast and should be run frequently during development
+- Some violations may require architectural changes - discuss these with the user if needed
+- The `lint:all` command stops on first failure - fix issues sequentially
+- All lint scripts are located in `scripts/` directory
+- These checks enforce the Modus Design System compliance requirements
+- React-specific patterns (hooks, event handling) are validated through ESLint