Agentic Workflows for Design Engineers

# .cursor/rules/design-system.mdc
---
description: Design System & GSAP Motion Standards
globs: src/components/**/*.tsx
---
# Animation Rules
- ALWAYS use `useGSAP()` hook for lifecycle management.
- Use `gsap.utils.selector(ref)` to prevent global scope leakage.
- Easing: Default to `expo.out`. Exits must be 30% faster than entrances.

# Token Enforcement
- Spacing: Use `gap-4` (1rem) steps. No arbitrary `mt-[13px]`.
- Colors: Use semantic tokens `text-monokai-pink` over hex codes.

# CLAUDE.md (excerpt)

## Architecture

- We build fluid, optimistic UIs.
- Server components by default. 'use client' only for interactivity.
- All animation via GSAP with `useGSAP()` hook.

## What NOT to do

- Do NOT refactor animation code unless explicitly asked.
- Do NOT add console.log statements for "debugging."
- Do NOT change easing curves. Ever.
- Do NOT "improve" accessibility by removing aria-labels you don't understand.
- Do NOT create new utility functions. Use existing patterns.

claude "I'm building a workflow step editor for the automation builder.
  1. Read the existing WorkflowStep type in src/types/workflow.ts
  2. Read the stepRouter in src/server/routers/steps.ts
  3. Identify the mutation contracts I need to respect
  4. Generate specs/WORKFLOW_STEP_EDITOR.md with:
     - Component hierarchy
     - State management approach for optimistic updates
     - Edge cases (validation, error states, concurrent edits)
  DO NOT write code. Spec only."

# Workflow Step Editor Specification

## Existing Contracts (from stepRouter)

- createStep: { workflowId, type, config } → Step
- updateStep: { stepId, config } → Step (optimistic, revalidates on error)
- reorderSteps: { workflowId, stepIds[] } → void

## Component Hierarchy

- StepEditor (container, manages local state)
  - StepTypeSelector (dropdown, triggers config schema change)
  - StepConfigForm (dynamic form based on step.type)
  - StepActions (save, delete, duplicate)

## State Management

- Local state for draft changes (useReducer)
- Optimistic update on save via tRPC useMutation
- Rollback to server state on 409 Conflict (concurrent edit)

## Edge Cases

- Empty config: Show placeholder, disable save
- Type change mid-edit: Confirm discard of existing config
- Network failure: Toast + retry button, preserve draft

'use client'

import { useGSAP } from '@gsap/react'
import gsap from 'gsap'
import { useRef, useReducer } from 'react'
import { api } from '@/lib/trpc'

export function StepEditor({ step, workflowId }: StepEditorProps) {
  const containerRef = useRef<HTMLDivElement>(null)
  const [draft, dispatch] = useReducer(stepReducer, step)

  const updateStep = api.steps.updateStep.useMutation({
    onMutate: async (newData) => {
      // Optimistic update
      await utils.steps.getStep.cancel()
      const previous = utils.steps.getStep.getData({ stepId: step.id })
      utils.steps.getStep.setData({ stepId: step.id }, newData)
      return { previous }
    },
    onError: (err, _, context) => {
      // Rollback on conflict
      if (context?.previous) {
        utils.steps.getStep.setData({ stepId: step.id }, context.previous)
      }
    },
  })

  useGSAP(
    () => {
      const q = gsap.utils.selector(containerRef)
      gsap.fromTo(
        q('.config-panel'),
        { opacity: 0, x: 12 },
        { opacity: 1, x: 0, duration: 0.25, ease: 'expo.out' },
      )
    },
    { scope: containerRef, dependencies: [draft.type] },
  )

  return (
    <div ref={containerRef} className='flex flex-col gap-4'>
      <StepTypeSelector
        value={draft.type}
        onChange={(type) => dispatch({ type: 'SET_TYPE', payload: type })}
      />
      <div className='config-panel'>
        <StepConfigForm config={draft.config} type={draft.type} />
      </div>
      <StepActions
        onSave={() => updateStep.mutate(draft)}
        disabled={!draft.config}
      />
    </div>
  )
}

claude "Run the test suite for the StepEditor feature.
  If any layout tests or accessibility checks fail:
  1. Read the error logs
  2. Fix the component code
  3. Verify the fix
  Repeat until all tests pass."

- Do NOT remove aria attributes to fix a11y errors. Ask first.

#!/bin/bash
# spec - Generate a feature specification

FEATURE_NAME=$1
[ -z "$FEATURE_NAME" ] && echo "Usage: spec <feature-name>" && exit 1

claude "Create a specification for: $FEATURE_NAME
  Include: data model changes, API routes, component hierarchy,
  state management, edge cases.
  Output to specs/${FEATURE_NAME}.md
  DO NOT write implementation code."

#!/bin/bash
# variant - Create a feature-flagged variant of a component

COMPONENT=$1
VARIANT_NAME=$2
[ -z "$COMPONENT" ] || [ -z "$VARIANT_NAME" ] && \
  echo "Usage: variant src/components/Button.tsx dark-mode" && exit 1

claude "Create a feature-flagged variant of $COMPONENT.
  1. Read the existing component
  2. Create ${COMPONENT%.tsx}.${VARIANT_NAME}.tsx with the variant
  3. Update original to check flag and render variant conditionally
  4. Use existing pattern in src/lib/flags.ts
  Variant is additive—do NOT modify behavior when flag is off."