create-dstack 0.1.0 → 0.1.2

package/templates/.cursor/skills/make-interfaces-feel-better/animations.md

@@ -1,381 +0,0 @@
-# Animations
-
-Interruptible animations, enter/exit transitions, and contextual icon animations.
-
-## Interruptible Animations
-
-Users change intent mid-interaction. If animations aren't interruptible, the interface feels broken.
-
-### CSS Transitions vs. Keyframes
-
-|                   | CSS Transitions                                       | CSS Keyframe Animations                                    |
-| ----------------- | ----------------------------------------------------- | ---------------------------------------------------------- |
-| **Behavior**      | Interpolate toward latest state                       | Run on a fixed timeline                                    |
-| **Interruptible** | Yes — retargets mid-animation                         | No — restarts from beginning                               |
-| **Use for**       | Interactive state changes (hover, toggle, open/close) | Staged sequences that run once (enter animations, loading) |
-| **Duration**      | Adapts to remaining distance                          | Fixed regardless of state                                  |
-
-```css
-/* Good — interruptible transition for a toggle */
-.drawer {
-  transform: translateX(-100%);
-  transition: transform 200ms ease-out;
-}
-.drawer.open {
-  transform: translateX(0);
-}
-
-/* Clicking again mid-animation smoothly reverses — no jank */
-```
-
-```css
-/* Bad — keyframe animation for interactive element */
-.drawer.open {
-  animation: slideIn 200ms ease-out forwards;
-}
-
-/* Closing mid-animation snaps or restarts — feels broken */
-```
-
-**Rule:** Always prefer CSS transitions for interactive elements. Reserve keyframes for one-shot sequences.
-
-## Enter Animations: Split and Stagger
-
-Don't animate a single large container. Break content into semantic chunks and animate each individually.
-
-### Step by Step
-
-1. **Split** into logical groups (title, description, buttons)
-2. **Stagger** with ~100ms delay between groups
-3. **For titles**, consider splitting into individual words with ~80ms stagger
-4. **Combine** `opacity`, `blur`, and `translateY` for the enter effect
-
-### Code Example
-
-```tsx
-// Motion (Framer Motion) — staggered enter
-function PageHeader() {
-  return (
-    <motion.div
-      initial="hidden"
-      animate="visible"
-      variants={{
-        visible: { transition: { staggerChildren: 0.1 } }
-      }}
-    >
-      <motion.h1
-        variants={{
-          hidden: { opacity: 0, y: 12, filter: "blur(4px)" },
-          visible: { opacity: 1, y: 0, filter: "blur(0px)" }
-        }}
-      >
-        Welcome
-      </motion.h1>
-
-      <motion.p
-        variants={{
-          hidden: { opacity: 0, y: 12, filter: "blur(4px)" },
-          visible: { opacity: 1, y: 0, filter: "blur(0px)" }
-        }}
-      >
-        A description of the page.
-      </motion.p>
-
-      <motion.div
-        variants={{
-          hidden: { opacity: 0, y: 12, filter: "blur(4px)" },
-          visible: { opacity: 1, y: 0, filter: "blur(0px)" }
-        }}
-      >
-        <Button>Get started</Button>
-      </motion.div>
-    </motion.div>
-  );
-}
-```
-
-### CSS-Only Stagger
-
-```css
-.stagger-item {
-  opacity: 0;
-  transform: translateY(12px);
-  filter: blur(4px);
-  animation: fadeInUp 400ms ease-out forwards;
-}
-
-.stagger-item:nth-child(1) {
-  animation-delay: 0ms;
-}
-.stagger-item:nth-child(2) {
-  animation-delay: 100ms;
-}
-.stagger-item:nth-child(3) {
-  animation-delay: 200ms;
-}
-
-@keyframes fadeInUp {
-  to {
-    opacity: 1;
-    transform: translateY(0);
-    filter: blur(0);
-  }
-}
-```
-
-## Exit Animations
-
-Exit animations should be softer and less attention-grabbing than enter animations. The user's focus is moving to the next thing — don't fight for attention.
-
-### Subtle Exit (Recommended)
-
-```tsx
-// Small fixed translateY — indicates direction without drama
-<motion.div
-  exit={{
-    opacity: 0,
-    y: -12,
-    filter: "blur(4px)",
-    transition: { duration: 0.15, ease: "easeIn" }
-  }}
->
-  {content}
-</motion.div>
-```
-
-### Full Exit (When Context Matters)
-
-```tsx
-// Slide fully out — use when spatial context is important
-// (e.g., a card returning to a list, a drawer closing)
-<motion.div
-  exit={{
-    opacity: 0,
-    x: "-100%",
-    transition: { duration: 0.2, ease: "easeIn" }
-  }}
->
-  {content}
-</motion.div>
-```
-
-### Good vs. Bad
-
-```css
-/* Good — subtle exit */
-.item-exit {
-  opacity: 0;
-  transform: translateY(-12px);
-  transition:
-    opacity 150ms ease-in,
-    transform 150ms ease-in;
-}
-
-/* Bad — dramatic exit that steals focus */
-.item-exit {
-  opacity: 0;
-  transform: translateY(-100%) scale(0.5);
-  transition: all 400ms ease-in;
-}
-
-/* Bad — no exit animation at all (element just vanishes) */
-.item-exit {
-  display: none;
-}
-```
-
-**Key points:**
-
-- Use a small fixed `translateY` (e.g., `-12px`) instead of the full container height
-- Keep some directional movement to indicate where the element went
-- Exit duration should be shorter than enter duration (150ms vs 300ms)
-- Don't remove exit animations entirely — subtle motion preserves context
-
-## Contextual Icon Animations
-
-When icons appear or disappear contextually (on hover, on state change), animate them with `opacity`, `scale`, and `blur` rather than just toggling visibility.
-
-### Motion Example
-
-```tsx
-import { AnimatePresence, motion } from "motion/react";
-
-function IconButton({ isActive, icon: Icon }) {
-  return (
-    <button>
-      <AnimatePresence mode="popLayout">
-        <motion.span
-          key={isActive ? "active" : "inactive"}
-          initial={{ opacity: 0, scale: 0.25, filter: "blur(4px)" }}
-          animate={{ opacity: 1, scale: 1, filter: "blur(0px)" }}
-          exit={{ opacity: 0, scale: 0.25, filter: "blur(4px)" }}
-          transition={{ type: "spring", duration: 0.3, bounce: 0 }}
-        >
-          <Icon />
-        </motion.span>
-      </AnimatePresence>
-    </button>
-  );
-}
-```
-
-### CSS Transition Approach (No Motion)
-
-If the project doesn't use Motion (Framer Motion), keep both icons in the DOM and cross-fade them with CSS transitions. Because neither icon unmounts, both enter and exit animate smoothly.
-
-The trick: one icon is absolutely positioned on top of the other. Toggling state cross-fades them — the entering icon scales up from `0.25` while the exiting icon scales down to `0.25`, both with opacity and blur.
-
-```tsx
-function IconButton({ isActive, ActiveIcon, InactiveIcon }) {
-  return (
-    <button>
-      <div className="relative">
-        <div
-          className={cn(
-            "absolute inset-0 flex items-center justify-center",
-            "transition-[opacity,filter,scale] duration-300",
-            "cubic-bezier(0.2, 0, 0, 1)",
-            isActive ? "scale-100 opacity-100 blur-0" : "scale-[0.25] opacity-0 blur-xs"
-          )}
-        >
-          <ActiveIcon />
-        </div>
-        <div
-          className={cn(
-            "transition-[opacity,filter,scale] duration-300",
-            "cubic-bezier(0.2, 0, 0, 1)",
-            isActive ? "scale-[0.25] opacity-0 blur-xs" : "scale-100 opacity-100 blur-0"
-          )}
-        >
-          <InactiveIcon />
-        </div>
-      </div>
-    </button>
-  );
-}
-```
-
-The non-absolute icon (InactiveIcon) defines the layout size. The absolute icon (ActiveIcon) overlays it without affecting flow.
-
-### Choosing Between Motion and CSS
-
-|                     | Motion (Framer Motion)              | CSS transitions (both icons in DOM)                    |
-| ------------------- | ----------------------------------- | ------------------------------------------------------ |
-| **Enter animation** | Yes                                 | Yes                                                    |
-| **Exit animation**  | Yes (via `AnimatePresence`)         | Yes (cross-fade — icon never unmounts)                 |
-| **Spring physics**  | Yes                                 | No — use `cubic-bezier(0.2, 0, 0, 1)` as approximation |
-| **When to use**     | Project already uses `motion/react` | No motion dependency, or keeping bundle small          |
-
-**Rule:** Check the project's `package.json` for `motion` or `framer-motion`. If present, use the Motion approach. If not, use the CSS cross-fade pattern — don't add a dependency just for icon transitions.
-
-### When to Animate Icons
-
-| Animate                                         | Don't animate                   |
-| ----------------------------------------------- | ------------------------------- |
-| Icons that appear on hover (action buttons)     | Static navigation icons         |
-| State change icons (play → pause, like → liked) | Decorative icons                |
-| Icons in contextual toolbars                    | Icons that are always visible   |
-| Loading/success state indicators                | Icon labels (text next to icon) |
-
-**Important:** Always use exactly these values for contextual icon animations — do not deviate:
-
-- `scale`: `0.25` → `1` (never use `0.5` or `0.6`)
-- `opacity`: `0` → `1`
-- `filter`: `"blur(4px)"` → `"blur(0px)"`
-- `transition`: `{ type: "spring", duration: 0.3, bounce: 0 }` — **bounce must always be `0`**, never `0.1` or any other value
-
-## Scale on Press
-
-A subtle scale-down on click gives buttons tactile feedback. Always use `scale(0.96)`. Never use a value smaller than `0.95` — anything below feels exaggerated. Use CSS transitions for interruptibility — if the user releases mid-press, it should smoothly return.
-
-Not every button needs this. Add a `static` prop to your button component that disables the scale effect when the motion would be distracting.
-
-### CSS Example
-
-```css
-.button {
-  transition-property: scale;
-  transition-duration: 150ms;
-  transition-timing-function: ease-out;
-}
-
-.button:active {
-  scale: 0.96;
-}
-```
-
-### Tailwind Example
-
-```tsx
-<button className="transition-transform duration-150 ease-out active:scale-[0.96]">Click me</button>
-```
-
-### Motion Example
-
-```tsx
-<motion.button whileTap={{ scale: 0.96 }}>Click me</motion.button>
-```
-
-### Static Prop Pattern
-
-Extract the scale class into a variable and conditionally apply it based on a `static` prop:
-
-```tsx
-const tapScale = "active:not-disabled:scale-[0.96]";
-
-function Button({ static: isStatic, className, children, ...props }) {
-  return (
-    <button
-      className={cn(
-        "transition-transform duration-150 ease-out",
-        !isStatic && tapScale,
-        className,
-      )}
-      {...props}
-    >
-      {children}
-    </button>
-  );
-}
-
-// Usage
-<Button>Click me</Button>           {/* scales on press */}
-<Button static>Submit</Button>       {/* no scale */}
-```
-
-## Skip Animation on Page Load
-
-Use `initial={false}` on `AnimatePresence` to prevent enter animations from firing on first render. Elements that are already in their default state shouldn't animate in on page load — only on subsequent state changes.
-
-### When It Works
-
-```tsx
-// Good — icon doesn't animate in on mount, only on state change
-<AnimatePresence initial={false} mode="popLayout">
-  <motion.span
-    key={isActive ? "active" : "inactive"}
-    initial={{ opacity: 0, scale: 0.25, filter: "blur(4px)" }}
-    animate={{ opacity: 1, scale: 1, filter: "blur(0px)" }}
-    exit={{ opacity: 0, scale: 0.25, filter: "blur(4px)" }}
-  >
-    <Icon />
-  </motion.span>
-</AnimatePresence>
-```
-
-Works well for: icon swaps, toggles, tabs, segmented controls — anything that has a default state on page load.
-
-### When It Breaks
-
-Don't use `initial={false}` when the component relies on its `initial` prop to set up a first-time enter animation, like a staggered page hero or a loading state. In those cases, removing the initial animation skips the entire entrance.
-
-```tsx
-// Bad — initial={false} would skip the staggered page enter entirely
-<AnimatePresence initial={false}>
-  <motion.div initial="hidden" animate="visible" variants={...}>
-    ...
-  </motion.div>
-</AnimatePresence>
-```
-
-Verify the component still looks right on a full page refresh before applying this.

package/templates/.cursor/skills/make-interfaces-feel-better/performance.md

@@ -1,88 +0,0 @@
-# Performance
-
-Transition specificity and GPU compositing hints.
-
-## Transition Only What Changes
-
-Never use `transition: all` or Tailwind's `transition` shorthand (which maps to `transition-property: all`). Always specify the exact properties that change.
-
-### Why
-
-- `transition: all` forces the browser to watch every property for changes
-- Causes unexpected transitions on properties you didn't intend to animate (colors, padding, shadows)
-- Prevents browser optimizations
-
-### CSS Example
-
-```css
-/* Good — only transition what changes */
-.button {
-  transition-property: scale, background-color;
-  transition-duration: 150ms;
-  transition-timing-function: ease-out;
-}
-
-/* Bad — transition everything */
-.button {
-  transition: all 150ms ease-out;
-}
-```
-
-### Tailwind
-
-```tsx
-// Good — explicit properties
-<button className="transition-[scale,background-color] duration-150 ease-out">
-
-// Bad — transition all
-<button className="transition duration-150 ease-out">
-```
-
-### Tailwind `transition-transform` Note
-
-`transition-transform` in Tailwind maps to `transition-property: transform, translate, scale, rotate` — it covers all transform-related properties, not just `transform`. Use this when you're only animating transforms. For multiple non-transform properties, use the bracket syntax: `transition-[scale,opacity,filter]`.
-
-## Use `will-change` Sparingly
-
-`will-change` hints the browser to pre-promote an element to its own GPU compositing layer. Without it, the browser promotes the element only when the animation starts — that one-time layer promotion can cause a micro-stutter on the first frame.
-
-This particularly helps when an element is changing `scale`, `rotation`, or moving around with `transform`. For other properties, it doesn't help much — the browser can't composite them on the GPU anyway.
-
-### Rules
-
-```css
-/* Good — specific property that benefits from GPU compositing */
-.animated-card {
-  will-change: transform;
-}
-
-/* Good — multiple compositor-friendly properties */
-.animated-card {
-  will-change: transform, opacity;
-}
-
-/* Bad — never use will-change: all */
-.animated-card {
-  will-change: all;
-}
-
-/* Bad — properties that can't be GPU-composited anyway */
-.animated-card {
-  will-change: background-color, padding;
-}
-```
-
-### Useful Properties
-
-| Property                         | GPU-compositable | Worth using `will-change` |
-| -------------------------------- | ---------------- | ------------------------- |
-| `transform`                      | Yes              | Yes                       |
-| `opacity`                        | Yes              | Yes                       |
-| `filter` (blur, brightness)      | Yes              | Yes                       |
-| `clip-path`                      | Yes              | Yes                       |
-| `top`, `left`, `width`, `height` | No               | No                        |
-| `background`, `border`, `color`  | No               | No                        |
-
-### When to Skip
-
-Modern browsers are already good at optimizing on their own. Only add `will-change` when you notice first-frame stutter — Safari in particular benefits from it. Don't add it preemptively to every animated element; each extra compositing layer costs memory.

package/templates/.cursor/skills/make-interfaces-feel-better/surfaces.md

@@ -1,245 +0,0 @@
-# Surfaces
-
-Border radius, optical alignment, shadows, and image outlines.
-
-## Concentric Border Radius
-
-When nesting rounded elements, the outer radius must equal the inner radius plus the padding between them:
-
-```
-outerRadius = innerRadius + padding
-```
-
-This rule is most useful when nested surfaces are close together. If padding is larger than `24px`, treat the layers as separate surfaces and choose each radius independently instead of forcing strict concentric math.
-
-### Example
-
-```css
-/* Good — concentric radii */
-.card {
-  border-radius: 20px; /* 12 + 8 */
-  padding: 8px;
-}
-.card-inner {
-  border-radius: 12px;
-}
-
-/* Bad — same radius on both */
-.card {
-  border-radius: 12px;
-  padding: 8px;
-}
-.card-inner {
-  border-radius: 12px;
-}
-```
-
-### Tailwind Example
-
-```tsx
-// Good — outer radius accounts for padding
-<div className="rounded-2xl p-2">       {/* 16px radius, 8px padding */}
-  <div className="rounded-lg">          {/* 8px radius = 16 - 8 ✓ */}
-    ...
-  </div>
-</div>
-
-// Bad — same radius on both
-<div className="rounded-xl p-2">
-  <div className="rounded-xl">          {/* same radius, looks off */}
-    ...
-  </div>
-</div>
-```
-
-Mismatched border radii on nested elements is one of the most common things that makes interfaces feel off. Always calculate concentrically.
-
-## Optical Alignment
-
-When geometric centering looks off, align optically instead.
-
-### Buttons with Text + Icon
-
-Use slightly less padding on the icon side to make the button feel balanced. A reliable rule of thumb is:
-`icon-side padding = text-side padding - 2px`.
-
-```css
-/* Good — less padding on icon side */
-.button-with-icon {
-  padding-left: 16px;
-  padding-right: 14px; /* icon side = text side - 2px */
-}
-
-/* Bad — equal padding looks like icon is pushed too far right */
-.button-with-icon {
-  padding: 0 16px;
-}
-```
-
-```tsx
-// Tailwind
-<button className="pl-4 pr-3.5 flex items-center gap-2">
-  <span>Continue</span>
-  <ArrowRightIcon />
-</button>
-```
-
-### Play Button Triangles
-
-Play icons are triangular and their geometric center is not their visual center. Shift slightly right:
-
-```css
-/* Good — optically centered */
-.play-button svg {
-  margin-left: 2px; /* shift right to account for triangle shape */
-}
-
-/* Bad — geometrically centered but looks off */
-.play-button svg {
-  /* no adjustment */
-}
-```
-
-### Asymmetric Icons (Stars, Arrows, Carets)
-
-Some icons have uneven visual weight. The best fix is adjusting the SVG directly so no extra margin/padding is needed in the component code.
-
-```tsx
-// Best — fix in the SVG itself
-// Adjust the viewBox or path to visually center the icon
-
-// Fallback — adjust with margin
-<span className="ml-px">
-  <StarIcon />
-</span>
-```
-
-## Shadows Instead of Borders
-
-For **buttons, cards, and containers** that use a border for depth or elevation, prefer replacing it with a subtle `box-shadow`. Shadows adapt to any background since they use transparency; solid borders don't. This also helps when using images or multiple colors as backgrounds — solid border colors don't work well on backgrounds other than the ones they were designed for.
-
-**Do not apply this to dividers** (`border-b`, `border-t`, side borders) or any border whose purpose is layout separation rather than element depth. Those should stay as borders.
-
-### Shadow as Border (Light Mode)
-
-The shadow is comprised of three layers. The first acts as a 1px border ring, the second adds subtle lift, and the third provides ambient depth:
-
-```css
-:root {
-  --shadow-border:
-    0px 0px 0px 1px rgba(0, 0, 0, 0.06), 0px 1px 2px -1px rgba(0, 0, 0, 0.06),
-    0px 2px 4px 0px rgba(0, 0, 0, 0.04);
-  --shadow-border-hover:
-    0px 0px 0px 1px rgba(0, 0, 0, 0.08), 0px 1px 2px -1px rgba(0, 0, 0, 0.08),
-    0px 2px 4px 0px rgba(0, 0, 0, 0.06);
-}
-```
-
-### Shadow as Border (Dark Mode)
-
-In dark mode, simplify to a single white ring — layered depth shadows aren't visible on dark backgrounds:
-
-```css
-/* Dark mode — adapt to whatever setup the project uses
-   (prefers-color-scheme, class, data attribute, etc.) */
---shadow-border: 0 0 0 1px rgba(255, 255, 255, 0.08);
---shadow-border-hover: 0 0 0 1px rgba(255, 255, 255, 0.13);
-```
-
-### Usage with Hover Transition
-
-Apply the variable and add `transition-[box-shadow]` for a smooth hover:
-
-```css
-.card {
-  box-shadow: var(--shadow-border);
-  transition-property: box-shadow;
-  transition-duration: 150ms;
-  transition-timing-function: ease-out;
-}
-
-.card:hover {
-  box-shadow: var(--shadow-border-hover);
-}
-```
-
-### When to Use Shadows vs. Borders
-
-| Use shadows                           | Use borders                             |
-| ------------------------------------- | --------------------------------------- |
-| Cards, containers with depth          | Dividers between list items             |
-| Buttons with bordered styles          | Table cell boundaries                   |
-| Elevated elements (dropdowns, modals) | Form input outlines (for accessibility) |
-| Elements on varied backgrounds        | Hairline separators in dense UI         |
-| Hover/focus states for lift effect    |                                         |
-
-## Image Outlines
-
-Add a subtle `1px` outline with low opacity to images. This creates consistent depth, especially in design systems where other elements use borders or shadows.
-
-### Light Mode
-
-```css
-img {
-  outline: 1px solid rgba(0, 0, 0, 0.1);
-  outline-offset: -1px; /* inset so it doesn't add to layout */
-}
-```
-
-### Dark Mode
-
-```css
-img {
-  outline: 1px solid rgba(255, 255, 255, 0.1);
-  outline-offset: -1px;
-}
-```
-
-### Tailwind with Dark Mode
-
-```tsx
-<img
-  className="outline -outline-offset-1 outline-black/10 dark:outline-white/10"
-  src={src}
-  alt={alt}
-/>
-```
-
-**Why outline instead of border?** `outline` doesn't affect layout (no added width/height), and `outline-offset: -1px` keeps it inset so images stay their intended size.
-
-## Minimum Hit Area
-
-Interactive elements should have a minimum hit area of 44×44px (WCAG) or at least 40×40px. If the visible element is smaller (e.g., a 20×20 checkbox), extend the hit area with a pseudo-element.
-
-### CSS Example
-
-```css
-/* Small checkbox with expanded hit area */
-.checkbox {
-  position: relative;
-  width: 20px;
-  height: 20px;
-}
-
-.checkbox::after {
-  content: "";
-  position: absolute;
-  top: 50%;
-  left: 50%;
-  transform: translate(-50%, -50%);
-  width: 40px;
-  height: 40px;
-}
-```
-
-### Tailwind Example
-
-```tsx
-<button className="relative size-5 after:absolute after:top-1/2 after:left-1/2 after:size-10 after:-translate-1/2">
-  <CheckIcon />
-</button>
-```
-
-### Collision Rule
-
-If the extended hit area overlaps another interactive element, shrink the pseudo-element — but make it as large as possible without colliding. Two interactive elements should never have overlapping hit areas.