devflow-kit 0.8.1 → 1.0.0

package/plugins/devflow-core-skills/skills/frontend-design/SKILL.md

@@ -0,0 +1,254 @@
+---
+name: frontend-design
+description: This skill should be used when the user asks to "design a component", "pick colors", "improve typography", "fix spacing", "choose a layout", or discusses visual design, CSS, styling decisions, or responsive interfaces. Provides patterns for typography scales, color systems, spacing, and production-grade UI design.
+user-invocable: false
+allowed-tools: Read, Grep, Glob
+activation:
+  file-patterns:
+    - "**/*.tsx"
+    - "**/*.jsx"
+    - "**/*.css"
+    - "**/*.scss"
+    - "**/tailwind.config.*"
+  exclude:
+    - "node_modules/**"
+    - "**/*.test.*"
+    - "**/*.spec.*"
+---
+
+# Frontend Design Patterns
+
+Reference for intentional visual design, following Anthropic's 4 Dimensions framework. Focus on deliberate aesthetic choices over default slop.
+
+## Iron Law
+
+> **AESTHETICS MUST HAVE INTENT**
+>
+> Every visual choice must be justified. Default styles, copied gradients, and
+> "looks modern" are not justifications. If you cannot explain why a specific
+> font, color, or animation exists, it's design debt. Good design is invisible
+> because it serves purpose, not because it copies trends.
+
+## When This Skill Activates
+
+- Creating or styling UI components
+- Reviewing CSS, Tailwind, or styled-components
+- Discussing typography, color schemes, or layouts
+- Building design systems or component libraries
+- Evaluating visual consistency
+
+---
+
+## 1. Typography Intent
+
+### Font Personality Must Match Product
+
+```css
+/* CORRECT: Deliberate choice with rationale */
+/* Product: Developer documentation - needs readability */
+font-family: 'IBM Plex Mono', 'JetBrains Mono', monospace;
+
+/* VIOLATION: Inter because "everyone uses it" */
+font-family: 'Inter', sans-serif; /* Why? What does it communicate? */
+```
+
+### Clear Hierarchy
+
+```css
+/* CORRECT: Distinct visual hierarchy */
+.heading-1 { font-size: 2.5rem; font-weight: 700; letter-spacing: -0.02em; }
+.heading-2 { font-size: 1.75rem; font-weight: 600; letter-spacing: -0.01em; }
+.body { font-size: 1rem; font-weight: 400; line-height: 1.6; }
+.caption { font-size: 0.875rem; font-weight: 400; color: var(--text-muted); }
+
+/* VIOLATION: No hierarchy - everything similar */
+.text { font-size: 1rem; }
+.text-big { font-size: 1.1rem; }
+```
+
+### Line Height Tuning
+
+```css
+/* CORRECT: Context-appropriate line height */
+.heading { line-height: 1.2; }  /* Tight for short headings */
+.body { line-height: 1.6; }     /* Comfortable for reading */
+.code { line-height: 1.4; }     /* Balanced for code */
+
+/* VIOLATION: Universal line height */
+* { line-height: 1.5; }
+```
+
+---
+
+## 2. Color and Theme
+
+### Deliberate Palette
+
+```css
+/* CORRECT: Semantic color system with clear purpose */
+:root {
+  --color-primary: #0066cc;     /* Actions, links - trust/stability */
+  --color-success: #0a6640;     /* Positive outcomes */
+  --color-warning: #b35900;     /* Attention needed */
+  --color-error: #c41e3a;       /* Errors, destructive */
+  --color-neutral-900: #1a1a1a; /* Primary text */
+  --color-neutral-500: #6b7280; /* Secondary text */
+  --color-neutral-100: #f5f5f5; /* Backgrounds */
+}
+
+/* VIOLATION: Random hex values without system */
+.button { background: #4f46e5; }
+.link { color: #3b82f6; }
+.alert { background: #ef4444; }
+```
+
+### Light/Dark as First-Class
+
+```css
+/* CORRECT: Design for both modes intentionally */
+:root {
+  --bg-primary: #ffffff;
+  --text-primary: #1a1a1a;
+}
+
+@media (prefers-color-scheme: dark) {
+  :root {
+    --bg-primary: #0f0f0f;
+    --text-primary: #f5f5f5;
+  }
+}
+
+/* VIOLATION: Dark mode as afterthought */
+.dark-mode { filter: invert(1); }
+```
+
+---
+
+## 3. Motion and Animation
+
+### State Communication
+
+```css
+/* CORRECT: Animation communicates state change */
+.button {
+  transition: transform 0.1s ease-out, background 0.15s ease;
+}
+.button:active {
+  transform: scale(0.98); /* Feedback: "I received your click" */
+}
+
+/* VIOLATION: Animation for decoration */
+.button {
+  animation: pulse 2s infinite; /* Why is it pulsing? */
+}
+```
+
+### Consistent Timing
+
+```css
+/* CORRECT: Timing scale for consistency */
+:root {
+  --duration-fast: 100ms;   /* Micro-interactions */
+  --duration-normal: 200ms; /* Standard transitions */
+  --duration-slow: 300ms;   /* Complex animations */
+  --easing-default: cubic-bezier(0.4, 0, 0.2, 1);
+}
+
+/* VIOLATION: Random durations */
+.modal { transition: 0.35s; }
+.dropdown { transition: 0.2s; }
+.tooltip { transition: 0.15s; }
+```
+
+### Appropriate Duration
+
+| Element | Duration | Rationale |
+|---------|----------|-----------|
+| Hover states | 100-150ms | Immediate feedback |
+| Dropdowns | 150-200ms | Quick but perceptible |
+| Modals | 200-300ms | Significant context change |
+| Page transitions | 300-500ms | Major navigation |
+
+---
+
+## 4. Spatial Composition
+
+### Consistent Spacing Scale
+
+```css
+/* CORRECT: Mathematical spacing system */
+:root {
+  --space-1: 0.25rem;  /* 4px */
+  --space-2: 0.5rem;   /* 8px */
+  --space-3: 0.75rem;  /* 12px */
+  --space-4: 1rem;     /* 16px */
+  --space-6: 1.5rem;   /* 24px */
+  --space-8: 2rem;     /* 32px */
+  --space-12: 3rem;    /* 48px */
+}
+
+/* VIOLATION: Magic numbers */
+.card { padding: 18px 22px; margin-bottom: 13px; }
+```
+
+### Whitespace With Purpose
+
+```css
+/* CORRECT: Whitespace creates visual grouping */
+.section { margin-bottom: var(--space-12); }
+.section-header { margin-bottom: var(--space-6); }
+.paragraph { margin-bottom: var(--space-4); }
+
+/* VIOLATION: Uniform spacing (no hierarchy) */
+* + * { margin-top: 1rem; }
+```
+
+---
+
+## AI Slop Detection
+
+Flag these patterns - they indicate thoughtless defaults:
+
+| Pattern | Problem |
+|---------|---------|
+| Purple-to-pink gradient | Copied from templates without brand justification |
+| `font-family: Inter` without rationale | Default choice, not intentional |
+| Everything centered | No visual hierarchy or flow |
+| `rounded-xl` on everything | Border radius should vary by context |
+| Shadows on everything | Elevation should be meaningful |
+| Generic "hero section" with gradient | Template copy, not designed |
+| `animate-pulse` on buttons | Meaningless attention grab |
+| Glassmorphism everywhere | Trend following, not purpose |
+
+---
+
+## Extended References
+
+For additional patterns and examples:
+- `references/violations.md` - Extended design anti-patterns
+- `references/patterns.md` - Extended correct patterns
+- `references/detection.md` - Grep patterns for finding issues
+
+---
+
+## Severity Guidelines
+
+| Severity | Criteria |
+|----------|----------|
+| CRITICAL | No design system (random values everywhere) |
+| HIGH | Inconsistent spacing/typography, broken dark mode |
+| MEDIUM | Missing hover states, poor visual hierarchy |
+| LOW | Could improve animation timing, minor inconsistencies |
+
+---
+
+## Checklist
+
+- [ ] Typography choices have documented rationale
+- [ ] Color palette is semantic (not arbitrary hex)
+- [ ] Dark/light modes both intentionally designed
+- [ ] Spacing follows consistent scale
+- [ ] Animations communicate state (not decoration)
+- [ ] No "AI slop" patterns present
+- [ ] Visual hierarchy is clear
+- [ ] Responsive behavior is intentional

package/plugins/devflow-core-skills/skills/frontend-design/references/detection.md

@@ -0,0 +1,184 @@
+# Frontend Design Detection Patterns
+
+Grep and regex patterns for detecting design issues. Use with `Grep` tool.
+
+## Typography Issues
+
+```bash
+# Font-family without rationale (look for undocumented choices)
+rg "font-family:" --type css --type scss
+
+# Flat heading sizes (minimal difference between levels)
+rg "h[1-6]\s*\{" --type css -A3 | rg "font-size"
+
+# Hardcoded font sizes (not using scale)
+rg "font-size:\s*\d+px" --type css
+
+# Line-height issues
+rg "line-height:\s*[01]\.[0-3]" --type css  # Too tight
+rg "line-height:\s*[2-9]" --type css         # Too loose
+```
+
+## Color Issues
+
+```bash
+# Random hex values (not using variables)
+rg "#[a-fA-F0-9]{3,6}" --type css | rg -v "var\(--"
+
+# AI slop gradients (purple-pink patterns)
+rg "gradient.*#(667e|764b|8b5c|ec48|f974)" --type css -i
+rg "from-purple.*to-pink" --type tsx
+
+# Inline style colors
+rg "style=.*color:" --type tsx
+rg "style=.*background:" --type tsx
+
+# filter: invert (dark mode hack)
+rg "filter:\s*invert" --type css
+```
+
+## Motion Issues
+
+```bash
+# Decorative animations
+rg "animation:.*infinite" --type css
+rg "animation:.*pulse" --type css
+
+# "all" transition (animates layout)
+rg "transition:\s*all" --type css
+
+# Random durations (not using system)
+rg "transition:.*\d+\.\d+s" --type css
+rg "animation-duration:.*\d+\.\d+s" --type css
+
+# Linear easing for UI
+rg "transition:.*linear" --type css
+
+# Missing reduced motion support
+rg "@media.*prefers-reduced-motion" --type css -c
+```
+
+## Spacing Issues
+
+```bash
+# Magic number padding/margin
+rg "(padding|margin):\s*\d{2,}px" --type css
+rg "(padding|margin):.*\d+px\s+\d+px\s+\d+px\s+\d+px" --type css
+
+# Hardcoded Tailwind spacing (not using scale)
+rg "class=.*p-\[.*px\]" --type tsx
+rg "class=.*m-\[.*px\]" --type tsx
+
+# Inconsistent gap usage
+rg "gap:\s*\d+px" --type css
+```
+
+## Layout Issues
+
+```bash
+# Everything centered
+rg "text-align:\s*center" --type css -c
+
+# Border-radius overuse (same value everywhere)
+rg "border-radius:\s*12px" --type css -c
+rg "rounded-xl" --type tsx -c
+
+# Shadow on everything
+rg "box-shadow:" --type css -c
+
+# Bento grid patterns
+rg "grid-column:\s*span" --type css -c
+```
+
+## AI Slop Patterns
+
+```bash
+# Generic hero sections
+rg "class=.*hero.*gradient" --type tsx
+rg "<section.*hero" --type tsx
+
+# Glassmorphism patterns
+rg "backdrop-filter:\s*blur" --type css
+rg "rgba.*0\.[12]" --type css  # Low opacity backgrounds
+
+# Trending patterns
+rg "animate-bounce|animate-pulse" --type tsx
+rg "hover:scale-" --type tsx
+
+# Template-like code
+rg "Welcome to|Get Started|Learn More" --type tsx
+```
+
+## Dark Mode Issues
+
+```bash
+# Dark mode not defined
+rg "prefers-color-scheme:\s*dark" --type css -c
+
+# Only background swap
+rg "\.dark\s*\{" --type css -A5 | rg -v "color:"
+
+# Same shadows in dark mode
+rg "\.dark.*box-shadow" --type css
+```
+
+## Component Issues
+
+```bash
+# Inline styles (not using design system)
+rg "style=\{\{" --type tsx -c
+
+# Hardcoded colors in components
+rg "color:\s*['\"]#" --type tsx
+rg "background:\s*['\"]#" --type tsx
+
+# Non-token spacing
+rg "padding:\s*['\"].*px" --type tsx
+rg "margin:\s*['\"].*px" --type tsx
+```
+
+## Testing Commands
+
+```bash
+# Full design audit on CSS files
+echo "=== Typography Issues ==="
+rg "font-size:\s*\d+px" --type css -c
+
+echo "=== Color Issues ==="
+rg "#[a-fA-F0-9]{6}" --type css | rg -v "var\(--" | wc -l
+
+echo "=== Motion Issues ==="
+rg "animation:.*infinite" --type css -c
+
+echo "=== Spacing Issues ==="
+rg "(padding|margin):\s*\d+px" --type css | wc -l
+
+echo "=== Design System Usage ==="
+rg "var\(--" --type css -c
+```
+
+## Tailwind-Specific Issues
+
+```bash
+# Arbitrary values (bypassing design system)
+rg "\[#[a-fA-F0-9]+\]" --type tsx
+rg "\[\d+px\]" --type tsx
+rg "\[\d+rem\]" --type tsx
+
+# Inconsistent responsive prefixes
+rg "md:|lg:|xl:" --type tsx | sort | uniq -c
+
+# Excessive utility classes (consider extraction)
+rg "className=\"[^\"]{200,}\"" --type tsx
+```
+
+## CSS-in-JS Issues
+
+```bash
+# Hardcoded values in styled-components
+rg "styled\." --type tsx -A10 | rg "\d+px"
+rg "styled\." --type tsx -A10 | rg "#[a-fA-F0-9]"
+
+# Missing theme usage
+rg "styled\." --type tsx -A10 | rg -v "theme\."
+```