@localtech/claude-code-toolkit 1.0.3 → 1.0.4

package/templates/.claude/skills/mobile-ui-ux-master/MobileCardGrid.tsx

@@ -0,0 +1,270 @@
+// MOBILE-OPTIMIZED CARD GRID COMPONENT
+// Solves all your UI/UX pain points: consistent heights, text containment, responsive design
+
+import React from 'react';
+import styled from 'styled-components';
+
+// Define theme interface for styled-components
+declare module 'styled-components' {
+  export interface DefaultTheme {
+    colors: {
+      surface: string;
+      surfaceSecondary: string;
+      textPrimary: string;
+      textSecondary: string;
+      primary: string;
+      primaryHover: string;
+      primaryActive: string;
+      icon: string;
+      focus: string;
+      disabled: string;
+    };
+  }
+}
+
+// Default theme with professional colors
+export const defaultTheme = {
+  colors: {
+    surface: '#ffffff',
+    surfaceSecondary: '#f3f4f6',
+    textPrimary: '#111827',
+    textSecondary: '#6b7280',
+    primary: '#3b82f6',
+    primaryHover: '#2563eb',
+    primaryActive: '#1d4ed8',
+    icon: '#6b7280',
+    focus: '#3b82f6',
+    disabled: '#9ca3af'
+  }
+};
+
+interface CardData {
+  id: string;
+  title: string;
+  description: string;
+  icon: React.ReactNode;
+  actionLabel?: string;
+  onAction?: () => void;
+}
+
+interface MobileCardGridProps {
+  cards: CardData[];
+  columns?: {
+    mobile: number;
+    tablet: number;
+    desktop: number;
+  };
+}
+
+const MobileCardGrid: React.FC<MobileCardGridProps> = ({
+  cards,
+  columns = { mobile: 1, tablet: 2, desktop: 3 }
+}) => {
+  return (
+    <GridContainer columns={columns}>
+      {cards.map((card) => (
+        <Card key={card.id}>
+          <CardHeader>
+            <IconContainer>
+              {card.icon}
+            </IconContainer>
+          </CardHeader>
+
+          <CardContent>
+            <CardTitle>{card.title}</CardTitle>
+            <CardDescription>{card.description}</CardDescription>
+          </CardContent>
+
+          {card.actionLabel && (
+            <CardFooter>
+              <ActionButton onClick={card.onAction}>
+                {card.actionLabel}
+              </ActionButton>
+            </CardFooter>
+          )}
+        </Card>
+      ))}
+    </GridContainer>
+  );
+};
+
+// STYLED COMPONENTS WITH MOBILE-FIRST DESIGN
+const GridContainer = styled.div<{ columns: { mobile: number; tablet: number; desktop: number } }>`
+  display: grid;
+  gap: 16px;
+  padding: 16px;
+
+  /* MOBILE FIRST: Single column by default */
+  grid-template-columns: 1fr;
+
+  /* TABLET: 2 columns minimum */
+  @media (min-width: 768px) {
+    grid-template-columns: repeat(${props => props.columns.tablet}, 1fr);
+  }
+
+  /* DESKTOP: 3 columns */
+  @media (min-width: 1024px) {
+    grid-template-columns: repeat(${props => props.columns.desktop}, 1fr);
+  }
+
+  /* CRITICAL: EQUAL HEIGHTS FOR ALL CARDS */
+  grid-auto-rows: 1fr;
+`;
+
+const Card = styled.div`
+  height: 100%; /* FILL GRID ROW HEIGHT */
+  background: ${props => props.theme.colors.surface || '#ffffff'};
+  border-radius: 12px;
+  box-shadow: 0 2px 8px rgba(0, 0, 0, 0.1);
+  display: flex;
+  flex-direction: column;
+  overflow: hidden;
+  transition: transform 0.2s ease, box-shadow 0.2s ease;
+
+  /* HOVER EFFECTS - SAFE FOR TOUCH DEVICES */
+  @media (hover: hover) and (pointer: fine) {
+    &:hover {
+      transform: translateY(-2px);
+      box-shadow: 0 4px 16px rgba(0, 0, 0, 0.15);
+    }
+  }
+`;
+
+const CardHeader = styled.div`
+  padding: 16px 16px 0 16px;
+  display: flex;
+  justify-content: flex-start;
+  align-items: center;
+`;
+
+const IconContainer = styled.div`
+  width: 48px;
+  height: 48px;
+  border-radius: 8px;
+  background: ${props => props.theme.colors.surfaceSecondary || '#f3f4f6'};
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  flex-shrink: 0; /* PREVENT ICON DISTORTION */
+
+  /* ICON STYLING */
+  svg {
+    width: 24px;
+    height: 24px;
+    color: ${props => props.theme.colors.icon || '#6b7280'};
+  }
+`;
+
+const CardContent = styled.div`
+  flex: 1; /* TAKE REMAINING SPACE */
+  padding: 12px 16px;
+  display: flex;
+  flex-direction: column;
+  gap: 8px;
+`;
+
+const CardTitle = styled.h3`
+  font-size: 16px;
+  font-weight: 600;
+  line-height: 1.4;
+  color: ${props => props.theme.colors.textPrimary || '#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;
+`;
+
+const CardDescription = styled.p`
+  flex: 1; /* FILL AVAILABLE SPACE TO MAINTAIN HEIGHT */
+  font-size: 14px;
+  line-height: 1.5;
+  color: ${props => props.theme.colors.textSecondary || '#6b7280'};
+  margin: 0;
+
+  /* TEXT CONTAINMENT */
+  display: -webkit-box;
+  -webkit-line-clamp: 3;
+  -webkit-box-orient: vertical;
+  overflow: hidden;
+`;
+
+const CardFooter = styled.div`
+  padding: 0 16px 16px 16px;
+  margin-top: auto; /* PUSH TO BOTTOM */
+`;
+
+const ActionButton = styled.button`
+  width: 100%;
+  padding: 12px 16px;
+  background: ${props => props.theme.colors.primary || '#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 */
+
+  /* HOVER EFFECTS - SAFE FOR TOUCH */
+  @media (hover: hover) and (pointer: fine) {
+    &:hover {
+      background: ${props => props.theme.colors.primaryHover || '#2563eb'};
+    }
+  }
+
+  &:active {
+    background: ${props => props.theme.colors.primaryActive || '#1d4ed8'};
+  }
+
+  /* FOCUS ACCESSIBILITY */
+  &:focus {
+    outline: 2px solid ${props => props.theme.colors.focus || '#3b82f6'};
+    outline-offset: 2px;
+  }
+
+  /* DISABLED STATE */
+  &:disabled {
+    background: ${props => props.theme.colors.disabled || '#9ca3af'};
+    cursor: not-allowed;
+  }
+`;
+
+export default MobileCardGrid;
+
+// USAGE EXAMPLE:
+/*
+import MobileCardGrid, { defaultTheme } from './MobileCardGrid';
+import { ThemeProvider } from 'styled-components';
+
+const cards = [
+  {
+    id: '1',
+    title: 'Professional Card Title',
+    description: 'This description will never break the layout or cause height inconsistencies.',
+    icon: <SomeIcon />,
+    actionLabel: 'Learn More',
+    onAction: () => console.log('Action clicked')
+  }
+  // ... more cards
+];
+
+// Optional: Wrap with ThemeProvider for custom theming
+<ThemeProvider theme={defaultTheme}>
+  <MobileCardGrid
+    cards={cards}
+    columns={{ mobile: 1, tablet: 2, desktop: 3 }}
+  />
+</ThemeProvider>
+
+// Or use with default theme (built-in fallbacks)
+<MobileCardGrid
+  cards={cards}
+  columns={{ mobile: 1, tablet: 2, desktop: 3 }}
+/>
+*/

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>