@localtech/claude-code-toolkit 1.0.3 → 1.0.5

package/templates/.claude/skills/mobile-ui-ux-master/SKILL.md

@@ -0,0 +1,172 @@
+# Claude Code Skill: Mobile UI/UX Master
+
+## Metadata
+name: mobile-ui-ux-master
+description: Ensures professional, consistent, and mobile-optimized UI/UX across all screens and components. Eliminates common layout issues like uneven card heights, text overflow, padding inconsistencies, and responsive design problems.
+author: Carlos Fadhel
+version: 1.0.0
+tags: mobile, ui, ux, responsive, design-system, layout, consistency
+
+## When to Use This Skill
+Use this skill when creating or modifying:
+- Mobile applications or responsive web apps
+- Component libraries or design systems
+- Screen layouts and navigation
+- Card-based interfaces
+- Grid systems and layouts
+- Any UI that needs to be mobile-optimized
+
+## Instructions for Claude
+
+### CORE PRINCIPLES - NEVER BREAK THESE
+1. **Mobile-First**: Always design for mobile first (320px minimum), then enhance for larger screens
+2. **Consistent Heights**: Cards in the same row/section MUST have identical heights
+3. **Text Containment**: Text must never break into unwanted line breaks that distort layouts
+4. **Proportional Scaling**: All spacing, fonts, and components scale proportionally
+5. **Touch Targets**: Minimum 44px touch targets, optimal 48-56px
+6. **Safe Areas**: Account for notches, navigation bars, and screen edges
+
+### CARD LAYOUT RULES (Your Biggest Pain Point)
+```
+CARD REQUIREMENTS:
+- Fixed height for cards in horizontal grids (same row = same height)
+- Content overflow: ellipsis or scroll, NEVER expand card height
+- Text truncation: max 2 lines, then ellipsis
+- Icons: Fixed container sizes, NEVER distort parent containers
+- Padding: Consistent 16px internal, 8px between cards
+- Border radius: 12px for cards, 8px for buttons
+```
+
+### COMMON PROBLEM SOLUTIONS
+
+#### Problem: Cards with different heights in same row
+**Solution**: Use CSS Grid with `grid-auto-rows: 1fr` or Flexbox with fixed heights
+
+#### Problem: Text breaking causing card expansion
+**Solution**: Use `line-clamp: 2`, `overflow: hidden`, `text-overflow: ellipsis`
+
+#### Problem: Icon containers distorting layouts
+**Solution**: Fixed aspect ratios, `object-fit: contain`, proper container sizing
+
+#### Problem: Inconsistent padding/margins
+**Solution**: Use design tokens, never arbitrary values
+
+#### Problem: Mobile layout breaking on different screens
+**Solution**: Container queries or responsive breakpoints at logical points
+
+### MOBILE OPTIMIZATION CHECKLIST
+- [ ] Screen width ≥320px, height ≥568px (iPhone SE minimum)
+- [ ] Touch targets ≥44px (ideally 48px)
+- [ ] Text readable at 14px minimum on mobile
+- [ ] No horizontal scrolling on mobile
+- [ ] Images have proper aspect ratios and loading states
+- [ ] Forms work with mobile keyboards
+- [ ] Navigation accessible with thumb zone
+
+### COMPONENT PATTERNS
+
+#### Card Grid Layout
+```css
+.card-grid {
+  display: grid;
+  grid-template-columns: repeat(auto-fit, minmax(280px, 1fr));
+  gap: 16px;
+  grid-auto-rows: 1fr; /* EQUAL HEIGHTS */
+}
+
+.card {
+  height: 100%; /* FILL AVAILABLE SPACE */
+  padding: 16px;
+  border-radius: 12px;
+  display: flex;
+  flex-direction: column;
+}
+```
+
+#### Card Content Structure
+```css
+.card-content {
+  flex: 1; /* TAKE REMAINING SPACE */
+  display: flex;
+  flex-direction: column;
+  gap: 12px;
+}
+
+.card-title {
+  font-size: 16px;
+  font-weight: 600;
+  line-height: 1.4;
+  display: -webkit-box;
+  -webkit-line-clamp: 2;
+  -webkit-box-orient: vertical;
+  overflow: hidden;
+}
+
+.card-description {
+  flex: 1; /* FILL SPACE TO MAINTAIN HEIGHT */
+  font-size: 14px;
+  line-height: 1.5;
+  color: var(--text-secondary);
+  display: -webkit-box;
+  -webkit-line-clamp: 3;
+  -webkit-box-orient: vertical;
+  overflow: hidden;
+}
+```
+
+### RESPONSIVE BREAKPOINTS
+- Mobile: 320px - 768px
+- Tablet: 768px - 1024px
+- Desktop: 1024px+
+
+### DESIGN TOKENS (Use These Instead of Random Values)
+```css
+:root {
+  /* Spacing */
+  --space-xs: 4px;
+  --space-sm: 8px;
+  --space-md: 16px;
+  --space-lg: 24px;
+  --space-xl: 32px;
+
+  /* Typography */
+  --font-size-xs: 12px;
+  --font-size-sm: 14px;
+  --font-size-base: 16px;
+  --font-size-lg: 18px;
+  --font-size-xl: 20px;
+
+  /* Layout */
+  --border-radius-sm: 8px;
+  --border-radius-md: 12px;
+  --border-radius-lg: 16px;
+
+  /* Touch targets */
+  --touch-target-min: 44px;
+  --touch-target-optimal: 48px;
+}
+```
+
+### QUALITY ASSURANCE STEPS
+1. Test on actual devices (not just browser dev tools)
+2. Check all screen sizes from 320px to 4K
+3. Verify touch targets with actual fingers
+4. Test with real content (not lorem ipsum)
+5. Check contrast ratios for accessibility
+6. Validate performance on slower connections
+
+## Input Requirements
+- Target platform (iOS, Android, Web, React Native, Flutter)
+- Primary screen size range
+- Component types needed
+- Design system constraints (if any)
+- Specific pain points to address
+
+## Output Format
+Return complete, production-ready code with:
+- Mobile-first CSS with proper breakpoints
+- Accessible markup with ARIA labels
+- Performance-optimized components
+- Consistent design token usage
+- Mobile-specific considerations documented
+- Cross-platform compatibility notes

package/templates/.claude/skills/mobile-ui-ux-master/card-grid-template.html

@@ -0,0 +1,260 @@
+<!-- MOBILE-OPTIMIZED CARD GRID TEMPLATE -->
+<!-- Solves: Uneven card heights, text overflow, layout distortion -->
+
+<div class="card-grid">
+  <div class="card">
+    <div class="card-header">
+      <div class="icon-container">
+        <svg class="card-icon" viewBox="0 0 24 24" fill="none" stroke="currentColor">
+          <path stroke-linecap="round" stroke-linejoin="round" stroke-width="2" d="M13 10V3L4 14h7v7l9-11h-7z"/>
+        </svg>
+      </div>
+    </div>
+
+    <div class="card-content">
+      <h3 class="card-title">Professional Card Title That Won't Break Layout</h3>
+      <p class="card-description">
+        This description text is properly contained and will never cause the card to expand.
+        It uses line clamping to maintain consistent heights across all cards in the grid.
+      </p>
+    </div>
+
+    <div class="card-footer">
+      <button class="card-action">Action Button</button>
+    </div>
+  </div>
+
+  <div class="card">
+    <div class="card-header">
+      <div class="icon-container">
+        <svg class="card-icon" viewBox="0 0 24 24" fill="none" stroke="currentColor">
+          <circle cx="12" cy="12" r="10"/>
+          <path d="m9 12 2 2 4-4"/>
+        </svg>
+      </div>
+    </div>
+
+    <div class="card-content">
+      <h3 class="card-title">Another Card Title</h3>
+      <p class="card-description">
+        Short description that demonstrates consistent card heights.
+        All cards maintain the same dimensions regardless of content length.
+      </p>
+    </div>
+
+    <div class="card-footer">
+      <button class="card-action">Action Button</button>
+    </div>
+  </div>
+
+  <div class="card">
+    <div class="card-header">
+      <div class="icon-container">
+        <svg class="card-icon" viewBox="0 0 24 24" fill="none" stroke="currentColor">
+          <path d="M14.7 6.3a1 1 0 0 0 0 1.4l1.6 1.6a1 1 0 0 0 1.4 0l3.77-3.77a6 6 0 0 1-7.94 7.94l-6.91 6.91a2.12 2.12 0 0 1-3-3l6.91-6.91a6 6 0 0 1 7.94-7.94l-3.76 3.76z"/>
+        </svg>
+      </div>
+    </div>
+
+    <div class="card-content">
+      <h3 class="card-title">Third Card with Longer Title That Still Fits</h3>
+      <p class="card-description">
+        This card has more content but maintains perfect alignment with its siblings.
+        The layout system prevents any height discrepancies or visual inconsistencies.
+      </p>
+    </div>
+
+    <div class="card-footer">
+      <button class="card-action">Action Button</button>
+    </div>
+  </div>
+</div>
+
+<style>
+/* MOBILE-FIRST CARD GRID SYSTEM */
+.card-grid {
+  display: grid;
+  grid-template-columns: repeat(auto-fit, minmax(280px, 1fr));
+  gap: 16px;
+  grid-auto-rows: 1fr; /* CRITICAL: EQUAL HEIGHTS FOR ALL CARDS */
+  padding: 16px;
+  max-width: 1200px;
+  margin: 0 auto;
+}
+
+/* RESPONSIVE BREAKPOINTS */
+@media (max-width: 480px) {
+  .card-grid {
+    grid-template-columns: 1fr;
+    gap: 12px;
+    padding: 12px;
+  }
+}
+
+@media (min-width: 768px) {
+  .card-grid {
+    grid-template-columns: repeat(2, 1fr);
+  }
+}
+
+@media (min-width: 1024px) {
+  .card-grid {
+    grid-template-columns: repeat(3, 1fr);
+  }
+}
+
+/* CARD STRUCTURE */
+.card {
+  height: 100%; /* FILL GRID ROW HEIGHT */
+  background: white;
+  border-radius: 12px;
+  box-shadow: 0 2px 8px rgba(0, 0, 0, 0.1);
+  display: flex;
+  flex-direction: column;
+  overflow: hidden; /* PREVENT CONTENT OVERFLOW */
+  transition: transform 0.2s ease, box-shadow 0.2s ease;
+}
+
+.card:hover {
+  transform: translateY(-2px);
+  box-shadow: 0 4px 16px rgba(0, 0, 0, 0.15);
+}
+
+/* CARD HEADER WITH ICON */
+.card-header {
+  padding: 16px 16px 0 16px;
+  display: flex;
+  justify-content: flex-start;
+  align-items: center;
+}
+
+.icon-container {
+  width: 48px;
+  height: 48px;
+  border-radius: 8px;
+  background: #f3f4f6;
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  flex-shrink: 0; /* PREVENT ICON DISTORTION */
+}
+
+.card-icon {
+  width: 24px;
+  height: 24px;
+  color: #6b7280;
+}
+
+/* CARD CONTENT - FLEXIBLE AND CONTAINED */
+.card-content {
+  flex: 1; /* TAKE REMAINING SPACE */
+  padding: 12px 16px;
+  display: flex;
+  flex-direction: column;
+  gap: 8px;
+}
+
+.card-title {
+  font-size: 16px;
+  font-weight: 600;
+  line-height: 1.4;
+  color: #111827;
+  margin: 0;
+
+  /* TEXT CONTAINMENT - PREVENTS LAYOUT BREAKAGE */
+  display: -webkit-box;
+  -webkit-line-clamp: 2;
+  -webkit-box-orient: vertical;
+  overflow: hidden;
+  word-break: break-word;
+  hyphens: auto;
+}
+
+.card-description {
+  flex: 1; /* FILL AVAILABLE SPACE TO MAINTAIN HEIGHT */
+  font-size: 14px;
+  line-height: 1.5;
+  color: #6b7280;
+  margin: 0;
+
+  /* TEXT CONTAINMENT */
+  display: -webkit-box;
+  -webkit-line-clamp: 3;
+  -webkit-box-orient: vertical;
+  overflow: hidden;
+}
+
+/* CARD FOOTER */
+.card-footer {
+  padding: 0 16px 16px 16px;
+  margin-top: auto; /* PUSH TO BOTTOM */
+}
+
+.card-action {
+  width: 100%;
+  padding: 12px 16px;
+  background: #3b82f6;
+  color: white;
+  border: none;
+  border-radius: 8px;
+  font-size: 14px;
+  font-weight: 500;
+  cursor: pointer;
+  transition: background-color 0.2s ease;
+  min-height: 44px; /* TOUCH TARGET MINIMUM */
+}
+
+.card-action:hover {
+  background: #2563eb;
+}
+
+.card-action:active {
+  background: #1d4ed8;
+}
+
+/* DARK MODE SUPPORT */
+@media (prefers-color-scheme: dark) {
+  .card {
+    background: #1f2937;
+    box-shadow: 0 2px 8px rgba(0, 0, 0, 0.3);
+  }
+
+  .card-title {
+    color: #f9fafb;
+  }
+
+  .card-description {
+    color: #d1d5db;
+  }
+
+  .icon-container {
+    background: #374151;
+  }
+
+  .card-icon {
+    color: #9ca3af;
+  }
+}
+
+/* HIGH CONTRAST MODE */
+@media (prefers-contrast: high) {
+  .card {
+    border: 2px solid #000;
+  }
+
+  .card-action {
+    border: 2px solid #000;
+  }
+}
+
+/* REDUCED MOTION */
+@media (prefers-reduced-motion: reduce) {
+  .card {
+    transition: none;
+  }
+
+  .card-action {
+    transition: none;
+  }
+}
+</style>

package/templates/.claude/skills/mobile-ui-ux-master/mobile-ux-checklist.md

@@ -0,0 +1,140 @@
+# MOBILE UI/UX QUALITY ASSURANCE CHECKLIST
+
+## 🎯 CRITICAL ISSUES (Your Main Pain Points)
+
+### ✅ Card Layout Consistency
+- [ ] **Equal Heights**: All cards in same row have identical heights
+- [ ] **No Expansion**: Cards never grow taller due to content overflow
+- [ ] **Grid Alignment**: Cards align perfectly in horizontal grids
+- [ ] **Responsive Scaling**: Cards maintain proportions across screen sizes
+
+### ✅ Text Management
+- [ ] **No Unwanted Breaks**: Text doesn't break into multiple lines unexpectedly
+- [ ] **Proper Truncation**: Long text uses ellipsis, never breaks layout
+- [ ] **Line Limits**: Titles max 2 lines, descriptions max 3 lines
+- [ ] **Readable Fonts**: Minimum 14px on mobile, proper line heights
+
+### ✅ Icon & Container Issues
+- [ ] **Fixed Containers**: Icon containers have consistent dimensions
+- [ ] **No Distortion**: Parent containers never distort from icon content
+- [ ] **Aspect Ratios**: Icons maintain proper proportions
+- [ ] **Proper Scaling**: Icons scale appropriately across devices
+
+### ✅ Spacing & Padding
+- [ ] **Consistent Padding**: 16px internal, 8px between elements
+- [ ] **Touch Targets**: Minimum 44px, optimal 48-56px
+- [ ] **Safe Areas**: Content avoids notches, navigation bars
+- [ ] **Proportional Scaling**: Spacing scales with screen size
+
+## 📱 MOBILE OPTIMIZATION CHECKLIST
+
+### Screen Size Coverage
+- [ ] **Minimum Support**: 320px width (iPhone SE)
+- [ ] **Content Scaling**: Works from 320px to 4K displays
+- [ ] **Orientation**: Works in both portrait and landscape
+- [ ] **Device Testing**: Tested on actual devices, not just emulators
+
+### Touch & Interaction
+- [ ] **Touch Targets**: All interactive elements ≥44px
+- [ ] **Thumb Zone**: Important actions in easy reach
+- [ ] **Gesture Support**: Swipe, pinch, long-press where appropriate
+- [ ] **Feedback**: Visual feedback for all interactions
+
+### Performance & Loading
+- [ ] **Fast Loading**: Images optimized, lazy loading implemented
+- [ ] **Smooth Scrolling**: No janky animations or transitions
+- [ ] **Memory Efficient**: No memory leaks, proper cleanup
+- [ ] **Offline Support**: Graceful degradation without network
+
+### Accessibility
+- [ ] **Screen Readers**: Proper ARIA labels and semantic HTML
+- [ ] **Keyboard Navigation**: Full keyboard accessibility
+- [ ] **Color Contrast**: WCAG AA compliance (4.5:1 ratio)
+- [ ] **Focus Indicators**: Clear focus states for all elements
+
+## 🛠️ DEVELOPMENT STANDARDS
+
+### Code Quality
+- [ ] **Mobile-First CSS**: Mobile styles first, then enhancements
+- [ ] **Flexbox/Grid**: Modern layout systems, no floats
+- [ ] **CSS Custom Properties**: Design tokens for consistency
+- [ ] **Component Libraries**: Reusable, tested components
+
+### Responsive Design
+- [ ] **Breakpoint Strategy**: Logical breakpoints, not device-specific
+- [ ] **Content Priority**: Most important content visible first
+- [ ] **Progressive Enhancement**: Works without JavaScript
+- [ ] **Cross-Browser**: Consistent across WebKit, Gecko, etc.
+
+### Quality Assurance
+- [ ] **Cross-Device Testing**: iOS Safari, Chrome Mobile, Samsung Internet
+- [ ] **Real Device Testing**: Not just browser dev tools
+- [ ] **Performance Monitoring**: Core Web Vitals tracking
+- [ ] **User Testing**: Real user feedback incorporated
+
+## 🚫 COMMON MISTAKES TO AVOID
+
+### Layout Issues
+- ❌ Cards with different heights in same row
+- ❌ Text overflow breaking card layouts
+- ❌ Fixed pixel values instead of relative units
+- ❌ Not accounting for different screen densities
+
+### Mobile-Specific Problems
+- ❌ Touch targets smaller than 44px
+- ❌ Horizontal scrolling on mobile
+- ❌ Content hidden behind navigation bars
+- ❌ Forms not optimized for mobile keyboards
+
+### Performance Issues
+- ❌ Large images without optimization
+- ❌ Heavy JavaScript blocking rendering
+- ❌ No loading states for slow connections
+- ❌ Memory leaks in single-page applications
+
+### Accessibility Failures
+- ❌ Missing alt text on images
+- ❌ Poor color contrast ratios
+- ❌ No keyboard navigation support
+- ❌ Missing focus indicators
+
+## 📊 MEASUREMENT METRICS
+
+### Performance Metrics
+- **First Contentful Paint**: < 1.5 seconds
+- **Largest Contentful Paint**: < 2.5 seconds
+- **Cumulative Layout Shift**: < 0.1
+- **First Input Delay**: < 100ms
+
+### Quality Metrics
+- **Accessibility Score**: > 90 (Lighthouse)
+- **Performance Score**: > 90 (Lighthouse)
+- **Best Practices Score**: > 90 (Lighthouse)
+- **SEO Score**: > 90 (Lighthouse)
+
+### User Experience Metrics
+- **Task Completion Rate**: > 95%
+- **Error Rate**: < 5%
+- **Time to Complete Tasks**: Within acceptable ranges
+- **User Satisfaction Score**: > 4/5
+
+## 🧪 TESTING PROTOCOL
+
+### Automated Testing
+1. **Visual Regression**: Screenshot comparison across devices
+2. **Accessibility Audit**: Automated WCAG compliance checking
+3. **Performance Testing**: Core Web Vitals monitoring
+4. **Cross-Browser Testing**: Automated browser compatibility
+
+### Manual Testing
+1. **Device Testing**: Physical devices of various sizes
+2. **User Flow Testing**: Complete user journeys
+3. **Edge Case Testing**: Error states, slow connections
+4. **Accessibility Testing**: Screen readers, keyboard navigation
+
+### Quality Gates
+- [ ] All automated tests passing
+- [ ] Manual testing checklist complete
+- [ ] Performance metrics within acceptable ranges
+- [ ] Accessibility audit passing
+- [ ] Cross-browser compatibility verified

package/templates/.claude/skills/professional-documentation-writer/SKILL.md

@@ -0,0 +1,42 @@
+# Claude Code Skill: Professional Documentation Writer
+
+## Metadata
+name: professional-documentation-writer
+description: Creates comprehensive, well-structured documentation for codebases, APIs, and projects with consistent formatting and professional tone
+author: Your Name
+version: 1.0.0
+tags: documentation, writing, markdown, professional
+
+## When to Use This Skill
+Use this skill when you need to:
+- Generate README files for new projects
+- Create API documentation
+- Write user guides and tutorials
+- Document code functions and classes
+- Create project documentation
+
+## Instructions for Claude
+When using this skill, follow these guidelines:
+
+1. **Structure**: Always use clear headings, subheadings, and proper markdown formatting
+2. **Tone**: Professional yet approachable - avoid overly technical jargon unless explaining technical concepts
+3. **Completeness**: Include all necessary sections (installation, usage, examples, API reference, etc.)
+4. **Consistency**: Use consistent formatting throughout the document
+5. **Examples**: Provide practical code examples where relevant
+6. **Navigation**: Include a table of contents for longer documents
+
+## Input Requirements
+- Project type (library, API, web app, CLI tool, etc.)
+- Key features/functionality to document
+- Target audience (developers, end users, administrators)
+- Any specific sections to include or exclude
+
+## Output Format
+Return the documentation in clean markdown format with:
+- Header with title and description
+- Table of contents (for documents > 500 words)
+- Installation/Setup section
+- Usage examples
+- API reference (if applicable)
+- Contributing guidelines
+- License information