@auto-engineer/react-gen 1.134.0

package/skills/emil-design-engineering/component-design.md

@@ -0,0 +1,382 @@
+# Component Design
+
+Best practices for designing React components that are flexible, composable, and maintainable.
+
+## Compound Components
+
+Use compound components when a component has multiple related parts that need to share state.
+
+```jsx
+// Good - compound components
+<Dialog>
+  <Dialog.Trigger>Open</Dialog.Trigger>
+  <Dialog.Content>
+    <Dialog.Title>Are you sure?</Dialog.Title>
+    <Dialog.Description>This action cannot be undone.</Dialog.Description>
+    <Dialog.Close>Cancel</Dialog.Close>
+  </Dialog.Content>
+</Dialog>
+
+// Bad - prop drilling everything
+<Dialog
+  trigger="Open"
+  title="Are you sure?"
+  description="This action cannot be undone."
+  closeText="Cancel"
+/>
+```
+
+### When to Use Compound Components
+
+- Multiple related elements that share implicit state
+- Components with slots (header, body, footer)
+- Components where order/presence of children varies
+- When you need flexible composition
+
+### When NOT to Use
+
+- Simple components with fixed structure
+- Components with 1-3 props
+- When the structure never changes
+
+## Customizability Balance
+
+### The Goldilocks Principle
+
+Too little customization: Users fork your component or add hacky workarounds.
+Too much customization: API becomes confusing, maintenance nightmare.
+
+**Find the middle ground:**
+
+```jsx
+// Too rigid - no customization
+<Button>Click me</Button>
+
+// Too flexible - overwhelming API
+<Button
+  backgroundColor="#000"
+  hoverBackgroundColor="#333"
+  activeBackgroundColor="#111"
+  borderRadius={4}
+  paddingX={16}
+  paddingY={8}
+  fontSize={14}
+  fontWeight={500}
+  // ... 30 more props
+>
+  Click me
+</Button>
+
+// Just right - variants + escape hatch
+<Button variant="primary" size="md" className="custom-override">
+  Click me
+</Button>
+```
+
+### Customization Layers
+
+1. **Variants** - Predefined options (primary, secondary, destructive)
+2. **Size** - Predefined sizes (sm, md, lg)
+3. **className** - Escape hatch for one-off customizations
+4. **asChild** - Render as different element (Radix pattern)
+
+## Props API Design
+
+### Use Consistent Naming
+
+```jsx
+// Good - consistent patterns
+<Input disabled />
+<Button disabled />
+<Select disabled />
+
+// Bad - inconsistent
+<Input disabled />
+<Button isDisabled />
+<Select readonly />
+```
+
+### Boolean Props
+
+Use positive names, avoid double negatives:
+
+```jsx
+// Good
+<Input disabled />
+<Modal open />
+
+// Bad
+<Input notEnabled />
+<Modal isNotClosed />
+```
+
+### Event Handler Naming
+
+Prefix with `on`, use past tense for after-the-fact:
+
+```jsx
+// Good
+<Input onChange={} onBlur={} />
+<Dialog onOpenChange={} onClose={} />
+
+// Bad
+<Input handleChange={} blurHandler={} />
+```
+
+### Render Props vs Children
+
+Prefer children for simple cases, render props for complex:
+
+```jsx
+// Simple - use children
+<Card>
+  <CardContent />
+</Card>
+
+// Complex with data - render prop
+<List
+  items={users}
+  renderItem={(user) => <UserCard user={user} />}
+/>
+```
+
+## Composition Over Configuration
+
+### Prefer Composition
+
+```jsx
+// Good - composable
+<Card>
+  <CardHeader>
+    <CardTitle>Title</CardTitle>
+    <CardDescription>Description</CardDescription>
+  </CardHeader>
+  <CardContent>Content here</CardContent>
+  <CardFooter>
+    <Button>Action</Button>
+  </CardFooter>
+</Card>
+
+// Bad - configuration object
+<Card
+  header={{ title: "Title", description: "Description" }}
+  content="Content here"
+  footer={{ actions: [{ label: "Action", onClick: () => {} }] }}
+/>
+```
+
+### Slot Pattern
+
+For components with optional sections:
+
+```jsx
+function Card({ children, header, footer }) {
+  return (
+    <div className="card">
+      {header && <div className="card-header">{header}</div>}
+      <div className="card-content">{children}</div>
+      {footer && <div className="card-footer">{footer}</div>}
+    </div>
+  );
+}
+
+// Usage
+<Card
+  header={<h2>Title</h2>}
+  footer={<Button>Save</Button>}
+>
+  Main content
+</Card>
+```
+
+## The `asChild` Pattern
+
+Allow rendering as a different element while preserving behavior:
+
+```jsx
+// Render as button (default)
+<Button>Click me</Button>
+
+// Render as link
+<Button asChild>
+  <a href="/page">Click me</a>
+</Button>
+
+// Render as Next.js Link
+<Button asChild>
+  <Link href="/page">Click me</Link>
+</Button>
+```
+
+Implementation using Radix Slot:
+
+```jsx
+import { Slot } from "@radix-ui/react-slot";
+
+function Button({ asChild, ...props }) {
+  const Comp = asChild ? Slot : "button";
+  return <Comp {...props} />;
+}
+```
+
+## Forwarding Refs
+
+Always forward refs for components that wrap DOM elements:
+
+```jsx
+const Button = forwardRef<HTMLButtonElement, ButtonProps>(
+  ({ children, ...props }, ref) => {
+    return (
+      <button ref={ref} {...props}>
+        {children}
+      </button>
+    );
+  }
+);
+```
+
+## Spread Remaining Props
+
+Allow passing arbitrary HTML attributes:
+
+```jsx
+function Button({ variant, size, className, ...props }) {
+  return (
+    <button
+      className={cn(buttonVariants({ variant, size }), className)}
+      {...props}
+    />
+  );
+}
+
+// Now these work:
+<Button data-testid="submit" aria-label="Submit form">
+  Submit
+</Button>
+```
+
+## Default Props
+
+Use sensible defaults that work for 80% of cases:
+
+```jsx
+function Button({
+  variant = "primary",
+  size = "md",
+  type = "button", // Not "submit" - safer default
+  ...props
+}) {
+  // ...
+}
+```
+
+## Controlled vs Uncontrolled
+
+Support both patterns when dealing with state:
+
+```jsx
+function Input({
+  value: controlledValue,
+  defaultValue,
+  onChange,
+  ...props
+}) {
+  const [internalValue, setInternalValue] = useState(defaultValue ?? "");
+
+  const isControlled = controlledValue !== undefined;
+  const value = isControlled ? controlledValue : internalValue;
+
+  function handleChange(e) {
+    if (!isControlled) {
+      setInternalValue(e.target.value);
+    }
+    onChange?.(e);
+  }
+
+  return <input value={value} onChange={handleChange} {...props} />;
+}
+
+// Uncontrolled
+<Input defaultValue="hello" />
+
+// Controlled
+<Input value={value} onChange={setValue} />
+```
+
+## Error Boundaries
+
+Wrap complex components in error boundaries:
+
+```jsx
+function ComponentWithErrorBoundary({ children }) {
+  return (
+    <ErrorBoundary fallback={<ErrorFallback />}>
+      {children}
+    </ErrorBoundary>
+  );
+}
+```
+
+## Component Organization
+
+### File Structure
+
+```
+components/
+├── button/
+│   ├── button.tsx        # Main component
+│   ├── button.test.tsx   # Tests
+│   └── index.ts          # Public exports
+├── card/
+│   ├── card.tsx
+│   ├── card-header.tsx
+│   ├── card-content.tsx
+│   └── index.ts
+```
+
+### Export Patterns
+
+```tsx
+// components/card/index.ts
+export { Card } from "./card";
+export { CardHeader } from "./card-header";
+export { CardContent } from "./card-content";
+
+// Or as compound component
+export { Card, CardHeader, CardContent } from "./card";
+```
+
+## Anti-Patterns to Avoid
+
+### Prop Explosion
+
+```jsx
+// Bad - too many props
+<Button
+  leftIcon={<Icon />}
+  rightIcon={<Arrow />}
+  iconSpacing={8}
+  iconSize={16}
+>
+  Click
+</Button>
+
+// Good - use children/composition
+<Button>
+  <Icon /> Click <Arrow />
+</Button>
+```
+
+### Boolean Prop Variants
+
+```jsx
+// Bad - boolean soup
+<Button primary large rounded>Click</Button>
+
+// Good - explicit variants
+<Button variant="primary" size="lg" radius="full">Click</Button>
+```
+
+### Premature Abstraction
+
+Don't create a component until you've copy-pasted it 2-3 times. Wait until patterns emerge.

package/skills/emil-design-engineering/forms-controls.md

@@ -0,0 +1,261 @@
+# Forms & Controls
+
+Inputs, buttons, forms, and interactive controls.
+
+## Inputs
+
+### Labels
+
+Clicking the input label should focus the input field. Always associate labels with inputs:
+
+```html
+<label for="email">Email</label>
+<input id="email" type="email" />
+
+<!-- Or wrap the input -->
+<label>
+  Email
+  <input type="email" />
+</label>
+```
+
+### Input Types
+
+Use appropriate `type` attributes:
+
+```html
+<input type="email" />
+<input type="password" />
+<input type="tel" />
+<input type="url" />
+<input type="number" />
+<input type="search" />
+```
+
+### Autocomplete and Spellcheck
+
+Disable `spellcheck` and `autocomplete` most of the time for cleaner UX:
+
+```html
+<input
+  type="text"
+  spellcheck="false"
+  autocomplete="off"
+/>
+```
+
+### 1Password Integration
+
+Disable 1Password autocomplete when not needed:
+
+```html
+<input data-lpignore="true" data-1p-ignore />
+```
+
+### Input Decorations
+
+Prefix and suffix decorations (icons, labels) should be:
+- Absolutely positioned on top of the text input with padding
+- Not placed next to the input as siblings
+- Should trigger focus on the input when clicked
+
+```css
+.input-wrapper {
+  position: relative;
+}
+
+.input-icon {
+  position: absolute;
+  left: 12px;
+  top: 50%;
+  transform: translateY(-50%);
+  pointer-events: none;
+}
+
+.input-field {
+  padding-left: 40px;
+}
+```
+
+For clickable icons (like clear button):
+
+```jsx
+<button
+  className="input-icon-button"
+  onClick={() => inputRef.current?.focus()}
+>
+  <SearchIcon />
+</button>
+```
+
+### Font Size (iOS)
+
+Ensure input font size is at least 16px to prevent zooming on iOS:
+
+```css
+input, textarea, select {
+  font-size: 16px;
+}
+```
+
+Inputs smaller than 16px cause iOS Safari to zoom in on focus.
+
+### Autofocus
+
+- Autofocus on inputs when a modal opens (if an input exists in the modal)
+- Do NOT autofocus inputs on touch devices—it opens the keyboard unexpectedly
+
+```jsx
+// Check for touch device before autofocus
+const isTouchDevice = 'ontouchstart' in window;
+
+<input autoFocus={!isTouchDevice} />
+```
+
+## Forms
+
+### Form Wrapper
+
+Inputs should be wrapped with a `<form>` to submit by pressing Enter:
+
+```html
+<form onSubmit={handleSubmit}>
+  <input type="text" />
+  <button type="submit">Submit</button>
+</form>
+```
+
+### Keyboard Submission
+
+Ensure `Cmd+Enter` (Mac) / `Ctrl+Enter` (Windows) submits the form, especially for textareas:
+
+```jsx
+function handleKeyDown(e) {
+  if ((e.metaKey || e.ctrlKey) && e.key === 'Enter') {
+    handleSubmit();
+  }
+}
+```
+
+### Prefilling Forms
+
+- Use logged-in user's data to prefill forms when possible
+- When linking to a form, prefill content based on the request context
+
+Example: If a user clicks "Change username", prefill with:
+> "I'd like to change my username to:"
+
+If you can prefill any user data based on the logged-in user, do that.
+
+## Buttons
+
+### Semantic Elements
+
+A button should always be a `<button>`. Don't add click events on elements that aren't buttons:
+
+```html
+<!-- Good -->
+<button onClick={handleClick}>Click me</button>
+
+<!-- Bad -->
+<div onClick={handleClick}>Click me</div>
+<span onClick={handleClick}>Click me</span>
+```
+
+### Disabled After Submission
+
+Disable buttons after submission to avoid duplicate network requests:
+
+```jsx
+const [isSubmitting, setIsSubmitting] = useState(false);
+
+<button
+  disabled={isSubmitting}
+  onClick={async () => {
+    setIsSubmitting(true);
+    await submitForm();
+    setIsSubmitting(false);
+  }}
+>
+  {isSubmitting ? 'Submitting...' : 'Submit'}
+</button>
+```
+
+### Button Shortcuts
+
+If a button's action can also be performed with a keyboard shortcut, show that shortcut as a tooltip on the button:
+
+```jsx
+<Tooltip content="Save (Cmd+S)">
+  <button onClick={save}>Save</button>
+</Tooltip>
+```
+
+### Button Press Feel
+
+Add `transform: scale(0.97)` on `:active` to make buttons feel responsive:
+
+```css
+.button:active {
+  transform: scale(0.97);
+}
+```
+
+## Checkboxes and Controls
+
+### Dead Zones
+
+Avoid dead zones on checkboxes and controls. The space between label and control should also be clickable:
+
+```css
+.checkbox-wrapper {
+  display: flex;
+  align-items: center;
+  gap: 8px;
+  cursor: pointer;
+}
+
+/* Make the entire row clickable, not just the checkbox */
+.checkbox-wrapper label {
+  cursor: pointer;
+  flex: 1;
+}
+```
+
+Or use a label that wraps everything:
+
+```html
+<label class="checkbox-row">
+  <input type="checkbox" />
+  <span>Remember me</span>
+</label>
+```
+
+## Destructive Actions
+
+Ensure destructive actions require confirmation:
+
+```jsx
+function handleDelete() {
+  if (confirm('Are you sure you want to delete this?')) {
+    deleteItem();
+  }
+}
+```
+
+For better UX, use a proper confirmation modal instead of `confirm()`.
+
+## Component Libraries
+
+Use Base UI for accessible component primitives. If it doesn't fit the codebase, use whatever else fits, but ensure accessibility is maintained.
+
+## Error Handling
+
+Colocate errors—show error messages close to the field that caused them:
+
+```jsx
+<div className="field">
+  <input type="email" aria-invalid={!!error} />
+  {error && <span className="error">{error}</span>}
+</div>
+```