get-shit-pretty 0.2.0 → 0.4.0

package/references/trends/micro-interactions.md

@@ -0,0 +1,307 @@
+# Micro-Interactions
+
+> Small, specific UI responses to user actions — hover, click, scroll, focus. The invisible details that make an interface feel alive and polished.
+
+Last verified: 2026-03-04
+
+---
+
+## Visual Characteristics
+
+- Subtle motion responses tied to specific user input
+- State-transition feedback: hover, active, focus, loading, success/error
+- Timing precision in the 80-300ms range
+- Natural easing curves that match human expectation
+- 75% of customer-facing apps will incorporate micro-interactions as standard (Gartner, 2025)
+
+---
+
+## Timing Guidelines
+
+| Interaction | Duration | Rationale |
+|-------------|----------|-----------|
+| Button press feedback | 80-120ms | Must feel instant — finger-to-response |
+| Hover feedback | 100-150ms | Quick enough to feel responsive, slow enough to perceive |
+| State transitions | 200-300ms | Visible change without feeling sluggish |
+| Page transitions | 300-500ms | Enough time for spatial orientation |
+| Micro-interaction (general) | 120-220ms | UX research sweet spot (NN/g, Material Design) |
+
+---
+
+## CSS Implementation
+
+### Button Hover Lift
+
+```css
+.micro-button {
+  transition: transform 0.15s ease-out, box-shadow 0.15s ease-out;
+}
+.micro-button:hover {
+  transform: translateY(-2px);
+  box-shadow: 0 4px 12px rgba(0, 0, 0, 0.15);
+}
+.micro-button:active {
+  transform: translateY(0px) scale(0.98);
+  transition-duration: 0.08s;
+}
+```
+
+### Card Hover
+
+```css
+.micro-card {
+  transition: transform 0.2s ease-out, box-shadow 0.2s ease-out;
+}
+.micro-card:hover {
+  transform: translateY(-4px);
+  box-shadow: 0 12px 24px rgba(0, 0, 0, 0.1);
+}
+```
+
+### Checkbox Tick Animation
+
+```css
+.checkmark path {
+  stroke-dasharray: 24;
+  stroke-dashoffset: 24;
+  transition: stroke-dashoffset 0.3s cubic-bezier(0.65, 0, 0.35, 1);
+}
+.checkbox:checked + .checkmark path {
+  stroke-dashoffset: 0;
+}
+```
+
+### Toggle Switch
+
+```css
+.toggle-thumb {
+  transition: transform 0.2s cubic-bezier(0.34, 1.56, 0.64, 1);
+}
+.toggle:checked .toggle-thumb {
+  transform: translateX(24px);
+}
+```
+
+### Skeleton Shimmer (Loading)
+
+```css
+.skeleton {
+  background: linear-gradient(90deg,
+    rgba(0, 0, 0, 0.06) 25%,
+    rgba(0, 0, 0, 0.1) 50%,
+    rgba(0, 0, 0, 0.06) 75%);
+  background-size: 200% 100%;
+  animation: shimmer 1.5s linear infinite;
+}
+@keyframes shimmer {
+  from { background-position: 200% 0; }
+  to   { background-position: -200% 0; }
+}
+```
+
+### Interactive Cursor
+
+```css
+.cursor-follower {
+  width: 32px;
+  height: 32px;
+  border-radius: 50%;
+  border: 2px solid currentColor;
+  transition: width 0.2s ease, height 0.2s ease;
+  pointer-events: none;
+}
+.cursor-follower.hovering-link {
+  width: 64px;
+  height: 64px;
+  mix-blend-mode: difference;
+}
+```
+
+### Easing Reference
+
+| Feel | Cubic-Bezier | Use |
+|------|-------------|-----|
+| Snappy | `cubic-bezier(0.2, 0, 0, 1)` | General UI transitions |
+| Bouncy | `cubic-bezier(0.34, 1.56, 0.64, 1)` | Toggles, playful elements |
+| Smooth exit | `cubic-bezier(0.16, 1, 0.3, 1)` | Elements leaving viewport |
+| Elastic | `cubic-bezier(0.68, -0.55, 0.27, 1.55)` | Attention-grabbing moments |
+| Linear | `linear` | Progress bars, continuous motion |
+
+---
+
+## Implementation Guide
+
+### Step-by-step
+
+1. Identify every interactive element: buttons, cards, inputs, toggles, links
+2. Define the interaction trigger: hover, click/tap, focus, scroll, state change
+3. Choose the appropriate timing from the guidelines table above
+4. Select an easing curve matching the desired feel (snappy for UI, bouncy for playful)
+5. Animate only `transform` and `opacity` — avoid `width`, `height`, `top`, `left`
+6. Add `:active` state for press feedback (scale down or translate)
+7. Test on both mouse (hover) and touch (tap) — touch devices skip hover
+
+### Progressive Enhancement
+
+```css
+/* Baseline: instant state changes */
+.micro-button {
+  /* No transition — works in all browsers */
+}
+
+/* Enhanced: smooth transitions when motion is acceptable */
+@media (prefers-reduced-motion: no-preference) {
+  .micro-button {
+    transition: transform 0.15s ease-out, box-shadow 0.15s ease-out;
+  }
+}
+```
+
+### Framework Notes
+
+#### React + Framer Motion
+
+```tsx
+import { motion } from 'framer-motion';
+
+export function MicroButton({ children, onClick }) {
+  return (
+    <motion.button
+      onClick={onClick}
+      whileHover={{ y: -2, boxShadow: '0 4px 12px rgba(0,0,0,0.15)' }}
+      whileTap={{ y: 0, scale: 0.98 }}
+      transition={{ duration: 0.15, ease: 'easeOut' }}
+      className="px-6 py-3 bg-indigo-600 text-white rounded-xl"
+    >
+      {children}
+    </motion.button>
+  );
+}
+```
+
+#### React + Tailwind CSS
+
+```tsx
+export function MicroCard({ children }) {
+  return (
+    <div className="transition-all duration-200 ease-out hover:-translate-y-1 hover:shadow-lg active:translate-y-0 active:scale-[0.98] active:duration-75 rounded-2xl bg-white p-6 shadow-md">
+      {children}
+    </div>
+  );
+}
+```
+
+#### React Native
+
+```tsx
+import Animated, { useAnimatedStyle, useSharedValue, withSpring } from 'react-native-reanimated';
+import { Pressable } from 'react-native';
+
+export function MicroButton({ title, onPress }) {
+  const scale = useSharedValue(1);
+  const animatedStyle = useAnimatedStyle(() => ({
+    transform: [{ scale: scale.value }],
+  }));
+
+  return (
+    <Pressable
+      onPressIn={() => { scale.value = withSpring(0.96, { damping: 15 }); }}
+      onPressOut={() => { scale.value = withSpring(1, { damping: 15 }); }}
+      onPress={onPress}
+    >
+      <Animated.View style={[styles.button, animatedStyle]}>
+        <Text>{title}</Text>
+      </Animated.View>
+    </Pressable>
+  );
+}
+```
+
+### Common Pitfalls
+
+1. **Hover-only interactions**: touch devices don't have hover. Always pair hover effects with active/tap states for mobile parity.
+2. **Animating layout properties**: `width`, `height`, `top`, `left`, `margin`, `padding` trigger layout recalculation. Stick to `transform` and `opacity`.
+3. **Too slow**: micro-interactions above 300ms feel sluggish. The "micro" means fast — 100-200ms for most.
+4. **Too many at once**: if every element bounces, glows, and scales simultaneously, the UI feels chaotic. Apply micro-interactions selectively to primary interactive elements.
+5. **No active/press state**: a button that hovers but doesn't respond to click feels broken. Always include `:active` feedback.
+
+---
+
+## Examples Gallery
+
+| Site | What They Do Well | Screenshot Description |
+|------|-------------------|----------------------|
+| Stripe | Precise hover states on pricing cards — subtle lift, shadow expansion, gradient border glow | Pricing page with elevated hovered card |
+| Linear | Toggle, checkbox, and dropdown animations with spring physics — every element feels tactile | Settings panel with bouncy toggle switches |
+| Vercel | Skeleton shimmer loading states and smooth page transitions | Dashboard with skeleton placeholders resolving to content |
+| Apple | iOS-quality button press feedback (scale 0.97) and page transition choreography on web | Product page with precise interaction states |
+| Awwwards — Locomotive Scroll | Custom cursor interactions, magnetic buttons, and parallax micro-effects | Agency site with cursor that morphs over interactive elements |
+
+---
+
+## Accessibility
+
+- **Reduced motion**: wrap all transitions in `@media (prefers-reduced-motion: no-preference)`. For `reduce`: instant state changes, no animation.
+- **Focus indicators**: animated focus rings must still meet 3:1 contrast ratio. Use `outline` (not `box-shadow`) for reliable focus visibility.
+- **Timing**: ensure animations complete before the next interaction is expected — don't delay functionality behind animation.
+- **Touch targets**: hover-lift effects can visually move elements. Ensure tap targets remain at least 44x44px regardless of visual position.
+- **Loading states**: skeleton shimmer should eventually resolve. Add `aria-busy="true"` to loading containers.
+
+---
+
+## Performance
+
+- **Transform + opacity only**: these are GPU-composited and stay off the main thread
+- **`will-change` sparingly**: apply to elements that will animate, not globally. Remove after animation completes for long-lived elements.
+- **Frame budget**: 16ms per frame at 60fps. Micro-interactions at 100-200ms use 6-12 frames — keep each frame under budget.
+- **Batch transitions**: if multiple elements animate simultaneously, ensure total compositing cost stays low. Profile with Chrome DevTools Performance panel.
+- **Mobile**: reduce hover animations (they don't apply anyway) and ensure tap feedback runs at 60fps.
+
+---
+
+## When to Use / When to Avoid
+
+### Use When
+- Every interactive element benefits from some micro-interaction
+- Loading states, form validation feedback, navigation transitions
+- Success/error confirmation animations
+- Hover states on cards, buttons, and links
+
+### Avoid When
+- Decorative-only motion with no functional purpose
+- Dense data displays where motion adds cognitive load
+- High-frequency actions (typing, scrolling) where animation would create lag
+- Accessibility-critical interfaces where motion could trigger vestibular disorders
+
+---
+
+## Design Tokens
+
+```json
+{
+  "micro": {
+    "duration-instant": "80ms",
+    "duration-fast": "120ms",
+    "duration-normal": "200ms",
+    "duration-slow": "300ms",
+    "duration-page": "400ms",
+    "ease-snappy": "cubic-bezier(0.2, 0, 0, 1)",
+    "ease-bouncy": "cubic-bezier(0.34, 1.56, 0.64, 1)",
+    "ease-smooth-exit": "cubic-bezier(0.16, 1, 0.3, 1)",
+    "ease-elastic": "cubic-bezier(0.68, -0.55, 0.27, 1.55)",
+    "hover-lift": "-2px",
+    "hover-shadow": "0 4px 12px rgba(0,0,0,0.15)",
+    "active-scale": "0.98",
+    "card-lift": "-4px",
+    "card-shadow": "0 12px 24px rgba(0,0,0,0.1)"
+  }
+}
+```
+
+---
+
+## Related
+
+- [Kinetic Typography](./kinetic-typography.md) — complementary animation system for text
+- [Bento Grid](./bento-grid.md) — card hover and entrance animations pair well
+- [Claymorphism](./claymorphism.md) — tactile squish feedback enhances the clay feel

package/references/trends/neubrutalism.md

@@ -0,0 +1,276 @@
+# Neubrutalism (Neo-Brutalism)
+
+> Bold, flat, high-contrast aesthetic with thick borders and hard-offset shadows — intentionally raw but usable. Anti-polish meets modern UX.
+
+Last verified: 2026-03-04
+
+---
+
+## Visual Characteristics
+
+- Flat colors — no gradients, no blur, no transparency
+- Thick black borders (2-4px)
+- Hard-offset box shadows with zero blur radius
+- High contrast — pure black + bright saturated accent
+- Geometric shapes, sharp corners or intentionally chunky radius (8-12px)
+- Monospaced or grotesque sans-serif typography
+- Popularized by Gumroad, Figma, Notion Calendar
+
+---
+
+## CSS Implementation
+
+```css
+/* Neubrutalist card */
+.neu-card {
+  background: #ffffff;
+  border: 3px solid #000000;
+  border-radius: 12px;
+  box-shadow: 4px 4px 0px 0px #000000;
+  padding: 24px;
+}
+
+/* Neubrutalist button */
+.neu-button {
+  background: #FFD700;
+  color: #000000;
+  border: 3px solid #000000;
+  border-radius: 8px;
+  box-shadow: 4px 4px 0px 0px #000000;
+  padding: 12px 24px;
+  font-weight: 700;
+  font-family: 'Space Grotesk', 'Inter', sans-serif;
+  cursor: pointer;
+  transition: transform 0.1s ease, box-shadow 0.1s ease;
+}
+
+.neu-button:hover {
+  transform: translate(2px, 2px);
+  box-shadow: 2px 2px 0px 0px #000000;
+}
+
+.neu-button:active {
+  transform: translate(4px, 4px);
+  box-shadow: 0px 0px 0px 0px #000000;
+}
+
+/* Neubrutalist input */
+.neu-input {
+  border: 3px solid #000000;
+  border-radius: 8px;
+  padding: 12px 16px;
+  font-size: 16px;
+  box-shadow: 3px 3px 0px 0px #000000;
+  outline: none;
+}
+
+.neu-input:focus {
+  box-shadow: 3px 3px 0px 0px #4169E1;
+  border-color: #4169E1;
+}
+```
+
+### Shadow Scale
+
+| Token | Value | Use |
+|-------|-------|-----|
+| sm | `2px 2px 0px 0px #000` | Small elements, tags, chips |
+| md | `4px 4px 0px 0px #000` | Cards, buttons, inputs |
+| lg | `6px 6px 0px 0px #000` | Featured cards, hero elements |
+| xl | `8px 8px 0px 0px #000` | Modals, popovers |
+
+### Color Palette Pattern
+- Background: `#FFFFFF` or warm off-white `#FFF8F0`
+- Text: `#000000`
+- Accents: `#FFD700` (yellow), `#FF6B6B` (red), `#4169E1` (blue), `#50C878` (green), `#FF69B4` (pink)
+- No gradients, no opacity, no blur
+
+### Typography
+- Primary: Space Grotesk, Space Mono, Inter, or DM Sans
+- Headings: Bold/Black weight, 48-96px for hero
+- Body: Regular weight, 16-18px
+- Monospaced accent: JetBrains Mono, IBM Plex Mono
+
+---
+
+## Implementation Guide
+
+### Step-by-step
+
+1. Set a flat background — white or warm off-white (`#FFF8F0`)
+2. Apply thick borders: `3px solid #000000` to all interactive elements
+3. Add hard-offset box-shadow: `4px 4px 0px 0px #000000` (zero blur is essential)
+4. Choose 1-2 bright accent colors for CTAs and highlights
+5. Set typography: grotesque sans-serif for headings, monospace for accents
+6. Implement shadow-collapse interaction: hover reduces offset, active collapses to zero
+7. Ensure all interactive states (hover, active, focus, disabled) are visually distinct
+
+### Progressive Enhancement
+
+Neubrutalism works in all browsers with no progressive enhancement needed — it uses only basic CSS properties (border, box-shadow, background-color). No `@supports` queries required.
+
+### Framework Notes
+
+#### React + Tailwind CSS
+
+Tailwind doesn't ship hard-offset shadows by default. Add custom shadow utilities:
+
+```js
+// tailwind.config.js
+module.exports = {
+  theme: {
+    extend: {
+      boxShadow: {
+        'neu-sm': '2px 2px 0px 0px #000000',
+        'neu-md': '4px 4px 0px 0px #000000',
+        'neu-lg': '6px 6px 0px 0px #000000',
+        'neu-xl': '8px 8px 0px 0px #000000',
+      }
+    }
+  }
+}
+```
+
+```tsx
+export function NeuButton({ children }: { children: React.ReactNode }) {
+  return (
+    <button className="bg-yellow-400 text-black border-[3px] border-black rounded-lg shadow-neu-md px-6 py-3 font-bold font-[Space_Grotesk] transition-all duration-100 hover:translate-x-[2px] hover:translate-y-[2px] hover:shadow-neu-sm active:translate-x-1 active:translate-y-1 active:shadow-none">
+      {children}
+    </button>
+  );
+}
+```
+
+#### React Native
+
+Neubrutalism translates well to React Native since it uses no advanced CSS:
+
+```tsx
+import { Pressable, Text, StyleSheet } from 'react-native';
+
+export function NeuButton({ title, onPress }) {
+  return (
+    <Pressable
+      onPress={onPress}
+      style={({ pressed }) => [
+        styles.button,
+        pressed && { transform: [{ translateX: 4 }, { translateY: 4 }], shadowOffset: { width: 0, height: 0 } }
+      ]}
+    >
+      <Text style={styles.text}>{title}</Text>
+    </Pressable>
+  );
+}
+
+const styles = StyleSheet.create({
+  button: {
+    backgroundColor: '#FFD700',
+    borderWidth: 3,
+    borderColor: '#000000',
+    borderRadius: 8,
+    paddingVertical: 12,
+    paddingHorizontal: 24,
+    shadowColor: '#000000',
+    shadowOffset: { width: 4, height: 4 },
+    shadowOpacity: 1,
+    shadowRadius: 0,
+    elevation: 4,
+  },
+  text: { color: '#000000', fontWeight: '700', fontSize: 16 },
+});
+```
+
+#### Vanilla CSS
+
+The CSS implementation section above is already vanilla CSS. No additional tooling needed.
+
+### Common Pitfalls
+
+1. **Adding blur to shadows**: the entire aesthetic depends on `0px` blur radius in box-shadow. Any blur softens the hard offset and breaks the brutalist look.
+2. **Mixing with glassmorphism**: these trends clash fundamentally — glass needs transparency and blur, neubrutalism demands flatness and opacity.
+3. **Inconsistent border width**: mixing 2px and 3px borders within the same UI breaks visual rhythm. Pick one and stick with it.
+4. **Shadow not collapsing on press**: the shadow-to-zero interaction pattern is what makes neubrutalism feel physical. Without it, buttons feel static and the hard shadow looks like a decoration.
+5. **Too many accent colors**: limit to 2-3 bright accents max. More than that reads as chaotic rather than intentionally bold.
+
+---
+
+## Examples Gallery
+
+| Site | What They Do Well | Screenshot Description |
+|------|-------------------|----------------------|
+| Gumroad | The canonical neubrutalist product — thick borders, hard shadows, bright yellow accent on every CTA | Product pages with bold cards and shadow-collapse buttons |
+| Figma Community | Bold flat cards with chunky radius and monospace accents — neubrutalism at scale | Community file browser with high-contrast cards |
+| Notion Calendar | Soft neubrutalism variant — slightly rounded, pastel accents with hard shadows | Calendar grid with event chips using hard offsets |
+| Poolsuite | Full commitment — retro-brutalist with monospace type, hot pink/green accents, and zero visual softness | App landing page with maximum contrast |
+| The Whimsical Web (Awwwards) | Experimental neubrutalism with animated shadow offsets and color-shifting accents | Portfolio site with interactive card states |
+
+---
+
+## Accessibility
+
+- **High contrast by default**: neubrutalism's pure black + white base exceeds WCAG AAA (21:1 ratio). Colored accents on white also tend to pass AA.
+- **Focus indicators**: replace the shadow-collapse focus state with a distinct visual — color-shifted shadow (`3px 3px 0px 0px #4169E1`) plus `border-color` change
+- **Color alone**: don't rely on accent color alone to convey state — combine with shadow offset changes, border changes, or text labels
+- **Motion**: the shadow-collapse animation is brief (100ms) and subtle — generally safe for `prefers-reduced-motion`, but provide instant state change as alternative
+
+---
+
+## Performance
+
+- **Minimal GPU cost**: neubrutalism uses only basic CSS properties (border, box-shadow, background-color). No compositing layers, no blur, no filters.
+- **Most performant trend**: flat colors + hard shadows = zero GPU overhead beyond standard rendering
+- **Safe for low-end devices**: works identically on all hardware tiers
+- **Shadow transition**: `transform` + `box-shadow` transition at 100ms is well within 16ms frame budget
+
+---
+
+## When to Use / When to Avoid
+
+### Use When
+- SaaS products, developer tools, creative platforms
+- Landing pages, marketing sites with personality
+- Products targeting young/creative audiences
+- Brands that want to stand out against the polished-glass mainstream
+
+### Avoid When
+- Luxury brands — hard shadows read as cheap/raw
+- Healthcare, fintech — clashes with trust/security signals
+- Enterprises expecting conservative visual language
+- Products already using glassmorphism — the trends clash fundamentally
+
+---
+
+## Design Tokens
+
+```json
+{
+  "neubrutalism": {
+    "border-width": "3px",
+    "border-color": "#000000",
+    "radius-sm": "8px",
+    "radius-md": "12px",
+    "shadow-sm": "2px 2px 0px 0px #000000",
+    "shadow-md": "4px 4px 0px 0px #000000",
+    "shadow-lg": "6px 6px 0px 0px #000000",
+    "shadow-xl": "8px 8px 0px 0px #000000",
+    "bg-primary": "#FFFFFF",
+    "bg-warm": "#FFF8F0",
+    "text": "#000000",
+    "accent-yellow": "#FFD700",
+    "accent-red": "#FF6B6B",
+    "accent-blue": "#4169E1",
+    "accent-green": "#50C878",
+    "accent-pink": "#FF69B4",
+    "transition-duration": "100ms",
+    "transition-easing": "ease"
+  }
+}
+```
+
+---
+
+## Related
+
+- [Kinetic Typography](./kinetic-typography.md) — great pairing for bold text effects
+- [Micro-Interactions](./micro-interactions.md) — shadow collapse on press is the signature interaction
+- [Bento Grid](./bento-grid.md) — compatible layout structure for neubrutalist cards