@fr0mpy/component-system 2.0.0

package/templates/skills/styling.md

@@ -0,0 +1,173 @@
+# Styling System
+
+Apply this skill when generating, modifying, or reviewing UI components.
+
+## When to Apply
+
+- Creating new UI components (buttons, cards, inputs, modals, etc.)
+- Modifying existing component styles
+- Reviewing code for styling consistency
+- User asks about design tokens or component patterns
+
+## Configuration Loading
+
+Before generating any UI code:
+
+1. **Check for config** at `.claude/styling-config.json`
+2. **Check for recipes** in `.claude/component-recipes/`
+3. If neither exists, suggest running `/setup-styling` to configure the design system
+
+## Token Usage
+
+When `.claude/styling-config.json` exists, use semantic tokens instead of hardcoded values:
+
+| Instead of | Use |
+|------------|-----|
+| `bg-blue-500` | `bg-primary` |
+| `#3b82f6` | Token from config |
+| `rounded-lg` (assumed) | `{tokens.radius}` from config |
+| `shadow-md` (assumed) | `{tokens.shadow}` from config |
+
+### Token Reference
+
+```
+tokens.colors.primary         → bg-primary, text-primary, border-primary
+tokens.colors.secondary       → bg-secondary, text-secondary
+tokens.colors.destructive     → bg-destructive, text-destructive
+tokens.colors.muted           → bg-muted, text-muted-foreground
+tokens.colors.surface         → bg-surface (cards, panels)
+tokens.colors.background      → bg-background (page)
+tokens.colors.foreground      → text-foreground
+tokens.colors.border          → border-border
+tokens.radius                 → border radius class
+tokens.shadow                 → shadow class
+tokens.spacing.tight/normal/loose → padding values
+tokens.typography.family      → font family class
+```
+
+## Recipe Compliance
+
+If a recipe exists in `.claude/component-recipes/[component].md`:
+
+1. Read the recipe first
+2. Follow the defined structure
+3. Use the exact variants specified
+4. Apply the Tailwind classes from the recipe
+5. Include all required states (hover, focus, disabled)
+
+## Interactive Element Rules
+
+All interactive elements MUST have `cursor: pointer`:
+
+- Buttons (`<button>`, `role="button"`)
+- Clickable cards or list items
+- Links styled as buttons
+- Toggle switches, checkboxes, radio buttons
+- Dropdown triggers
+- Tab buttons
+- Any element with an `onClick` handler
+
+```tsx
+// Correct
+<button className="cursor-pointer ...">Click me</button>
+
+// Incorrect - missing cursor pointer
+<button className="...">Click me</button>
+```
+
+## Mobile-First Design (REQUIRED)
+
+All components MUST be built mobile-first. This means:
+
+1. **Default styles target mobile** - Base classes without breakpoint prefixes are for mobile
+2. **Progressive enhancement** - Add `sm:`, `md:`, `lg:`, `xl:` prefixes for larger screens
+3. **Touch-friendly targets** - Minimum 44x44px touch targets on interactive elements
+4. **Responsive typography** - Use responsive text sizes (`text-sm md:text-base lg:text-lg`)
+5. **Flexible layouts** - Use `flex-col` by default, `sm:flex-row` for larger screens
+6. **Full-width on mobile** - Components should be `w-full` on mobile, constrained on larger screens
+
+### Mobile-First Pattern Examples
+
+```tsx
+// CORRECT - Mobile first
+<div className="flex flex-col gap-2 sm:flex-row sm:gap-4">
+<div className="p-4 md:p-6 lg:p-8">
+<button className="w-full sm:w-auto px-4 py-3 min-h-[44px]">
+<h1 className="text-lg md:text-xl lg:text-2xl">
+
+// INCORRECT - Desktop first (never do this)
+<div className="flex flex-row gap-4 max-sm:flex-col max-sm:gap-2">
+<div className="p-8 max-md:p-6 max-lg:p-4">
+```
+
+### Responsive Breakpoint Reference
+
+| Prefix | Min Width | Typical Device |
+|--------|-----------|----------------|
+| (none) | 0px | Mobile phones |
+| `sm:` | 640px | Large phones / small tablets |
+| `md:` | 768px | Tablets |
+| `lg:` | 1024px | Laptops |
+| `xl:` | 1280px | Desktops |
+| `2xl:` | 1536px | Large desktops |
+
+## Component Generation Checklist
+
+Before delivering any UI component:
+
+- [ ] **MOBILE-FIRST: Base styles target mobile (no breakpoint prefix)**
+- [ ] **MOBILE-FIRST: Larger screen styles use sm:/md:/lg: prefixes**
+- [ ] **MOBILE-FIRST: Touch targets are minimum 44x44px**
+- [ ] **MOBILE-FIRST: Layout is flexible (flex-col → sm:flex-row pattern)**
+- [ ] Loaded styling config (if exists)
+- [ ] Checked for component recipe (if exists)
+- [ ] Using token-based colors (not hardcoded)
+- [ ] Radius matches config personality
+- [ ] Shadow matches config personality
+- [ ] Spacing matches config density
+- [ ] All interactive states included
+- [ ] Interactive elements have `cursor-pointer`
+- [ ] Accessible (focus-visible, aria labels where needed)
+
+## Auditing (when asked to review/audit)
+
+Scan UI files for violations:
+
+### Critical Violations
+- **Desktop-first responsive patterns** (using `max-sm:`, `max-md:` instead of `sm:`, `md:`)
+- **Missing responsive breakpoints** for layout/spacing/typography
+- **Touch targets smaller than 44x44px** on interactive elements
+- Hardcoded hex colors (`#[0-9a-fA-F]{3,8}`)
+- Hardcoded rgb/rgba values
+- Inline styles with color/spacing values
+- Non-semantic Tailwind colors (`bg-blue-500` instead of `bg-primary`)
+- Interactive elements missing `cursor-pointer`
+
+### Warnings
+- Inconsistent border radius across components
+- Inconsistent shadow depth
+- Spacing that doesn't match density setting
+
+### Audit Output Format
+
+```
+Styling Audit Report
+====================
+Configuration: [loaded | not found]
+Files scanned: [count]
+
+CRITICAL:
+- file.tsx:24 → Hardcoded `#3b82f6` → Use `bg-primary`
+
+WARNINGS:
+- file.tsx:12 → `rounded-xl` but config is `rounded-lg`
+
+Compliance: [X]%
+```
+
+## Fallback Behavior
+
+If no styling config exists:
+- Use sensible defaults: `rounded-md`, `shadow-sm`, system font
+- Warn about inconsistency risk
+- Suggest: "Run `/setup-styling` to define your project's design tokens"