@harness-engineering/cli 1.23.2 → 1.24.0

package/dist/agents/skills/cursor/design-form-ux/SKILL.md

@@ -0,0 +1,156 @@
+# Form UX
+
+> Form design beyond labels — progressive disclosure, inline validation timing, smart defaults, forgiving formats, single-column superiority, error recovery
+
+## When to Use
+
+- Designing any form that collects user input: registration, checkout, settings, search filters, data entry
+- Optimizing an existing form with high abandonment rates or frequent validation errors
+- Choosing validation timing: on blur, on submit, on keystroke, or hybrid
+- Implementing multi-step forms, wizards, or progressive disclosure patterns
+- Setting smart defaults that reduce user effort and error rates
+- Designing error recovery flows that help users fix problems rather than just flag them
+- Building accessible forms that work with screen readers, keyboard navigation, and assistive technology
+- Reviewing a form for compliance with WCAG 2.1 AA input assistance requirements (1.3.5, 3.3.1-3.3.4)
+
+## Instructions
+
+1. **Use single-column layout.** Research by the CXL Institute (Baymard Institute corroborated) demonstrates that single-column forms have 15.4 seconds faster completion times than multi-column forms of equivalent field count. The eye moves straight down without horizontal scanning. The only exception: short, logically paired fields that form a natural unit (City + State, First Name + Last Name on wide desktop views, credit card Expiry + CVC). Even in these cases, the pairs should stack to single-column on viewports below 768px. Stripe's checkout form is single-column at every viewport width — they tested multi-column and measured lower conversion.
+
+2. **Validate on blur for most fields, with specific exceptions.** The optimal validation timing, validated by research from Luke Wroblewski (2009) and confirmed by Baymard Institute (2023):
+   - **On blur (when the user leaves the field):** Default for most fields. The user has finished entering their value, so validation is timely and non-interruptive. Stripe validates card numbers on blur — the error appears only after the user moves to the next field.
+   - **On keystroke (real-time):** Only for format-constrained fields where real-time feedback aids entry: password strength meters, character count limits, username availability. Never use keystroke validation for fields where the value is incomplete mid-typing (email, phone, credit card number) — showing "Invalid email" while the user is still typing "@" is hostile.
+   - **On submit:** For fields that depend on cross-field validation (password confirmation must match password) or server-side validation (checking if a username is taken when local validation is insufficient). On submit, validate all fields simultaneously and scroll to the first error.
+   - **Premature validation trap:** Never show an error before the user has had a chance to provide input. An empty required field should not show "Required" until the user has visited and left the field (blur) or attempted to submit. Showing errors on page load for empty required fields is an anti-pattern.
+
+3. **Write error messages that diagnose AND prescribe.** Every error message must contain two parts: (a) what is wrong, and (b) how to fix it. "Invalid email" fails — it diagnoses but does not prescribe. "Enter an email address (e.g., name@example.com)" succeeds — it both diagnoses and prescribes. Stripe's error messages are the benchmark:
+   - Card number: "Your card number is incomplete" (not "Invalid card")
+   - Expiry: "Your card's expiration date is in the past" (not "Invalid date")
+   - CVC: "Your card's security code is incomplete" (not "Invalid CVC")
+
+   Each message tells the user exactly what is wrong in their terms, not in system terms.
+
+4. **Implement smart defaults to reduce cognitive load.** Every field with a statistically dominant answer should be pre-filled with that answer. The user can change it if needed, but the common case requires no action. Decision procedure for defaults:
+   - **Country:** Default to the user's detected locale (via Accept-Language header or IP geolocation). Airbnb defaults the country to the user's browsing location with 95%+ accuracy.
+   - **Date fields:** Default to today's date for "start date" fields. Default to one week from today for "end date" fields. Airbnb defaults check-in to the next weekend and check-out to 2 nights later — matching the most common booking pattern.
+   - **Currency:** Default to the user's locale currency.
+   - **Toggles/checkboxes:** Default to the most common/recommended setting. If 85% of users enable a setting, default it to on.
+   - **Quantity fields:** Default to 1, not 0 or empty. A quantity of 0 is almost never the intended starting value.
+
+5. **Accept forgiving input formats and normalize silently.** Users should not be forced to match a specific input format. Phone numbers should accept `(555) 123-4567`, `555-123-4567`, `5551234567`, and `+1 555 123 4567` — all normalized to the same stored value. Credit card numbers should accept spaces, dashes, or no separators. Dates should accept `3/14`, `03/14`, `March 14`, and `2024-03-14`. The principle: parse generously, store canonically, display formatted. Stripe's card input accepts any spacing — `4242 4242 4242 4242` and `4242424242424242` are both valid entries, and the display auto-formats to groups of four.
+
+6. **Use progressive disclosure for complex forms.** Do not show all 20 fields at once when 5 are sufficient to start. Reveal additional fields only when the user's previous answers require them. The patterns:
+   - **Conditional fields:** Show field B only when field A's value triggers it. Selecting "Other" from a dropdown reveals a text input. Selecting "Business" account type reveals company name and tax ID fields. Airbnb's booking form reveals guest count, trip purpose, and special requests progressively — each section appears only after the previous is completed.
+   - **Multi-step wizard:** Split a long form into 3-5 focused steps with a progress indicator. Each step should have 3-5 fields maximum. Stripe's onboarding wizard splits account setup into Business Info, Personal Details, Bank Account, and Review — each step is focused and completable in under 60 seconds.
+   - **Expandable sections:** Group optional fields under collapsible sections labeled "Advanced Options" or "Additional Details." Default to collapsed. Users who need them expand; users who do not skip them entirely.
+
+7. **Design error recovery as a first-class flow, not an afterthought.** When a form submission fails:
+   - Preserve all user input — never clear the form on error. Losing entered data is the single most frustrating form experience.
+   - Scroll to the first error field and focus it.
+   - Show all errors simultaneously (not one at a time — the user should see the full scope of problems).
+   - Use inline error placement: the error message appears directly below the offending field, in red (#D32F2F or equivalent semantic error color), with an error icon for colorblind users.
+   - Provide a summary at the top of the form: "Please fix 3 errors below" with anchor links to each error field.
+   - When the user corrects a field, remove the error immediately (on blur or on keystroke if the value becomes valid).
+
+8. **Label every field with a visible, persistent label.** Placeholder text is not a label. Placeholders disappear when the user starts typing, removing the context for what they are entering. Research by NNGroup (2014) found that placeholder-only forms had 12% more errors than labeled forms. The pattern: visible label above the field (not inside it), optional placeholder as a format hint, and optional helper text below the field for additional context. Material Design's text fields always show a label — in the "filled" variant, the label floats above the input on focus, remaining visible throughout editing.
+
+## Details
+
+### Field Type Selection Guide
+
+Choosing the wrong input type is a common form design failure. The decision matrix:
+
+| Data Type           | Best Control              | Reason                                          | Example                           |
+| ------------------- | ------------------------- | ----------------------------------------------- | --------------------------------- |
+| Yes/No              | Toggle switch             | Binary choice, immediate effect                 | Enable notifications              |
+| One of 2-5 options  | Radio buttons             | All options visible, easy comparison            | Shipping speed                    |
+| One of 6-15 options | Dropdown / Select         | Conserves space, options still scannable        | Country (if common ones promoted) |
+| One of 15+ options  | Searchable dropdown       | Too many to scan, search is faster              | Country (full list)               |
+| Multiple of 2-7     | Checkboxes                | Multi-select, all visible                       | Notification preferences          |
+| Multiple of 7+      | Multi-select with search  | Too many to display, search narrows             | Tag selection                     |
+| Free text (short)   | Text input                | Unconstrained input, single line                | Name, email                       |
+| Free text (long)    | Textarea                  | Multi-line, expandable                          | Description, comments             |
+| Date                | Date picker               | Prevents format errors, shows calendar          | Appointment date                  |
+| Date range          | Dual date picker          | Visual range selection, constraint display      | Check-in to check-out             |
+| Number              | Number input with stepper | Constrained to valid range, increment/decrement | Quantity, age                     |
+| File                | Drag-and-drop zone        | Supports drag and click, shows preview          | Profile photo, document upload    |
+
+### Inline Validation Visual Specification
+
+The visual treatment of validation states must be consistent and accessible:
+
+- **Default state:** Border color `#E0E0E0` (neutral gray), label in body text color.
+- **Focus state:** Border color changes to primary blue (`#1976D2` or brand primary), 2px border width (up from 1px), subtle shadow or glow. The focus state must be visible without relying on color alone — the border width change ensures accessibility.
+- **Valid state (after blur):** Green checkmark icon at the right edge of the field. Border optionally turns green (`#388E3C`). Keep this subtle — over-celebrating valid fields creates visual noise.
+- **Error state (after blur):** Red border (`#D32F2F`), red error icon (!) at the right edge, error message text in red below the field. Error message must be associated with the field via `aria-describedby` for screen readers. The error message should use `role="alert"` or `aria-live="assertive"` to announce when it appears.
+- **Disabled state:** Background `#F5F5F5` (light gray fill), text at 60% opacity, `cursor: not-allowed`. Label remains at full opacity with "(disabled)" or explanation text.
+
+### Multi-Step Form Architecture
+
+Multi-step forms (wizards) require careful state management and navigation design:
+
+**Progress indicator.** Show step labels (not just numbers) so the user knows what is ahead: "1. Business Info > 2. Personal Details > 3. Bank Account > 4. Review." Completed steps should be clickable, allowing the user to go back and edit. The current step is highlighted. Future steps are visible but not clickable (prevents skipping validation). Stripe's onboarding wizard uses this exact pattern.
+
+**Step validation.** Validate the current step completely before allowing navigation to the next step. If validation fails, the user stays on the current step with errors displayed. Do not allow "Next" to proceed with errors — this creates a deferred error problem where the user discovers at the Review step that Step 1 had issues.
+
+**Data persistence.** Save form state after each step completion. If the user closes the browser and returns, they should resume at the last completed step with their data intact. Use `localStorage`, session storage, or server-side draft persistence. Airbnb persists incomplete booking forms for 24 hours — returning users find their dates, guest count, and payment details intact.
+
+**Back navigation.** The "Back" button must preserve all entered data from the current step. No data loss on backward navigation, ever. The back button should not require re-validation of the current (incomplete) step.
+
+### Autofill and Autocomplete Optimization
+
+Browser autofill is one of the most powerful form completion tools, but only if forms are coded correctly:
+
+- Use standard `autocomplete` attribute values: `name`, `email`, `tel`, `address-line1`, `address-line2`, `address-level2` (city), `address-level1` (state), `postal-code`, `country`, `cc-number`, `cc-exp`, `cc-csc`, `cc-name`.
+- Use `<input type="email">` for email fields (triggers email keyboard on mobile and validates format).
+- Use `<input type="tel">` for phone fields (triggers numeric keyboard on mobile).
+- Group address fields in a single `<fieldset>` or `<address>` element so autofill recognizes them as a unit.
+- Do not use `autocomplete="off"` on fields where autofill is appropriate — this frustrates users and violates WCAG 1.3.5.
+- Stripe's checkout form is optimized for autofill: a single click fills name, address, card number, and email from the browser's stored payment methods.
+
+### Anti-Patterns
+
+1. **Placeholder-as-Label.** Using placeholder text as the only indication of what a field expects, with no visible label. When the user starts typing, the placeholder disappears and they forget what field they are filling out. Multi-field forms become impossible to review because filled fields have no labels. Fix: always use a visible label above or beside the field. Placeholders are optional format hints ("e.g., john@example.com"), not labels.
+
+2. **Premature Validation.** Showing validation errors before the user has finished entering their value. Typing "j" into an email field and immediately seeing "Invalid email address" in red is hostile — the user has typed one character. Fix: validate on blur (when the user leaves the field), not on keystroke. The exception: real-time feedback that helps (password strength, character count) — but never show errors mid-entry.
+
+3. **Clear-on-Error.** Clearing the entire form when submission fails, forcing the user to re-enter all data. This is the single most frustrating form experience and causes immediate abandonment. Fix: preserve all user input on error, highlight only the problematic fields, and let the user correct just the errors.
+
+4. **The Wall of Fields.** Showing 15+ fields on a single page with no grouping, progressive disclosure, or section breaks. The form feels overwhelming before the user begins. Cognitive load research (Hick's Law) shows that completion rates drop logarithmically with visible field count. Fix: group related fields under section headings, hide optional fields behind "Show more" toggles, and consider a multi-step wizard for forms exceeding 7 fields.
+
+5. **Format Enforcement Without Guidance.** Requiring a specific input format (e.g., phone must be "XXX-XXX-XXXX") but not telling the user the required format until they fail validation. The user enters "5551234567," submits, sees "Invalid phone number format," and must guess the expected format. Fix: either accept any reasonable format and normalize (preferred) or show the expected format as placeholder text and helper text before the user types.
+
+### Real-World Examples
+
+**Stripe Checkout Form.** Stripe's payment form is the most studied checkout form in the industry. Single-column layout at all viewport widths. Card number field auto-detects card brand (Visa, Mastercard, Amex) and displays the brand icon as the user types — providing real-time feedback without validation errors. Expiry and CVC fields are sized proportionally to their expected content (expiry gets 60% width, CVC gets 40% on the same row — the one acceptable multi-column exception). Validation errors appear on blur with specific, diagnostic messages. The entire form supports autofill from browser-stored payment methods, completing all fields with a single interaction.
+
+**Airbnb Multi-Step Booking.** Airbnb's booking flow uses progressive disclosure across multiple pages: (1) Select dates and guests (2 fields), (2) Review price breakdown and house rules, (3) Add payment and confirm. Each step is focused — never more than 4-5 fields visible. Smart defaults pre-fill: dates default to the next weekend, guest count defaults to 1 adult, country defaults to detected locale. The date picker disables past dates and dates beyond the host's availability — constraints prevent errors. Returning users find their payment method pre-filled from previous bookings.
+
+**GitHub Issue Creation.** GitHub's issue form demonstrates progressive disclosure. The minimal form has two fields: title and description (markdown). Below, optional fields appear: labels, assignees, projects, milestones — each is a collapsed dropdown that expands only when clicked. The description field supports real-time markdown preview (toggle between Write and Preview tabs). The form auto-saves drafts to `localStorage` — closing the browser and returning finds the draft intact. Submit validation is minimal: only the title is required.
+
+**Material Design Text Field Specification.** Material Design defines three text field variants with precise visual specifications: (1) Filled — a background fill with a bottom border line, label floats above on focus. (2) Outlined — a full border with the label breaking the top border on focus. (3) Standard — a bottom border only (deprecated in M3 for insufficient affordance). The filled variant is recommended for most forms because the background fill creates a clear container signifier. All variants support: leading/trailing icons, helper text, character counter, error text, and prefix/suffix text. The specifications include exact spacing values: 16dp horizontal padding, 20dp top padding (with floating label), 16dp bottom padding, 4dp between field and helper text.
+
+## Source
+
+- Wroblewski, L. — _Web Form Design: Filling in the Blanks_ (2008), foundational form design research
+- Baymard Institute — "Checkout Usability" (2023), 18 years of checkout form research, 150+ usability guidelines
+- Nielsen Norman Group — "Placeholders in Form Fields Are Harmful" (2014)
+- CXL Institute — "Single Column vs Multi-Column Form Layouts" (2019), completion time research
+- Material Design — Text fields specification, https://m3.material.io/components/text-fields
+- Stripe — Checkout form design patterns and validation timing
+
+## Process
+
+1. Read the instructions and examples in this document.
+2. Apply the patterns to your implementation, adapting to your specific context.
+3. Verify your implementation against the details and edge cases listed above.
+
+## Harness Integration
+
+- **Type:** knowledge — this skill is a reference document, not a procedural workflow.
+- **No tools or state** — consumed as context by other skills and agents.
+
+## Success Criteria
+
+- The patterns described in this document are applied correctly in the implementation.
+- Edge cases and anti-patterns listed in this document are avoided.

package/dist/agents/skills/cursor/design-form-ux/skill.yaml

@@ -0,0 +1,35 @@
+name: design-form-ux
+version: "1.0.0"
+description: Form design beyond labels — progressive disclosure, inline validation timing, smart defaults, forgiving formats, single-column superiority, error recovery
+cognitive_mode: advisory-guide
+type: knowledge
+tier: 3
+triggers:
+  - manual
+platforms:
+  - claude-code
+  - gemini-cli
+  - cursor
+  - codex
+tools: []
+paths: []
+related_skills:
+  - design-affordances
+  - design-state-design
+  - design-gestalt-proximity
+  - a11y-form-patterns
+stack_signals: []
+keywords:
+  - form-design
+  - validation
+  - progressive-disclosure
+  - smart-defaults
+  - error-recovery
+  - single-column
+  - inline-validation
+metadata:
+  author: community
+state:
+  persistent: false
+  files: []
+depends_on: []

package/dist/agents/skills/cursor/design-gestalt-closure-continuity/SKILL.md

@@ -0,0 +1,182 @@
+# Gestalt Closure and Continuity
+
+> Pattern completion — the brain fills gaps in incomplete shapes (closure) and follows smooth paths over abrupt changes (continuity), with implications for icons, progress indicators, and visual flow
+
+## When to Use
+
+- Designing icons that must be recognizable at small sizes with minimal detail
+- Building progress indicators, step wizards, or completion meters
+- Creating visual flow through a page — guiding the eye along a reading path
+- Designing charts, graphs, or data visualizations with connected data points
+- Evaluating why an icon reads poorly, a progress indicator feels ambiguous, or a layout lacks directional flow
+- Implementing breadcrumbs, timelines, or sequential navigation patterns
+
+## Instructions
+
+1. **Understand closure.** The Gestalt principle of closure states that the brain automatically completes incomplete shapes, perceiving whole forms from partial information. A circle with a gap is still perceived as a circle. A square missing a corner is still perceived as a square. This principle is foundational to icon design — icons work because the brain fills in detail that pixels cannot provide at small sizes.
+
+   **Critical implication:** Closure means you can remove visual information without losing meaning, as long as enough structural cues remain. This is the basis of minimalist design — show less, mean the same.
+
+2. **Apply closure to icon design.** Icons are closure in action. At 24x24px or 16x16px, there is insufficient resolution for photorealistic representation. Icons succeed by providing just enough visual structure for the brain to complete the pattern.
+
+   **Worked example — Apple's SF Symbols:**
+   - The "phone" icon is not a photograph of a phone — it is a curved rectangle with a speaker bump
+   - The "envelope" icon is a rectangle with a V-shaped fold — two lines represent an entire object
+   - The "magnifying glass" icon is a circle with a diagonal line — the brain completes the handle, the glass, the concept of "search"
+   - SF Symbols remove detail until only the essential geometric structure remains, then rely on closure for recognition
+
+   **Decision procedure for icon simplification:**
+   1. Start with the most detailed version of the object
+   2. Remove one detail at a time
+   3. After each removal, test: is the object still recognizable without its label?
+   4. Stop removing when the next removal breaks recognition
+   5. The icon should be 1-2 removals above the recognition threshold — just enough redundancy for confidence
+
+3. **Apply closure to progress indicators.** Progress rings, step indicators, and loading animations all exploit closure. An incomplete ring is perceived as "a ring that is partially filled" rather than "an arc" — the brain supplies the complete circle and interprets the gap as "remaining."
+
+   **Worked example — circular progress indicators (Material Design):**
+   - A 270-degree arc on a 360-degree track reads as "75% complete"
+   - The track (the remaining 90 degrees) is rendered as a faint gray arc — providing the closure target
+   - Without the track, the same 270-degree arc reads ambiguously: is it a C-shape, or a partial circle?
+   - The track is the closure scaffold — it tells the brain "this is meant to be a circle, and here is how much is filled"
+   - Track color: `rgba(0,0,0,0.08)` on light backgrounds, `rgba(255,255,255,0.12)` on dark — visible enough to complete the shape, faint enough not to compete with the filled portion
+
+   **Worked example — step indicators (Stripe onboarding):**
+   - Steps displayed as numbered circles connected by a line: (1)----(2)----(3)----(4)
+   - Completed steps: filled circle. Current step: outlined circle with bold number. Future steps: faint outlined circle
+   - The connecting line is the continuity cue — it tells the brain "these circles form a sequence"
+   - The partially-complete sequence exploits closure: the user perceives the full 4-step journey and their position within it
+
+4. **Understand continuity.** The Gestalt principle of continuity states that the eye follows smooth, continuous paths over abrupt direction changes. When two lines cross, the brain perceives two straight lines passing through each other rather than four lines meeting at a point. The eye prefers the interpretation that maintains smooth trajectory.
+
+   **Critical implication:** Continuity governs how users scan a page. The eye follows alignment axes, baselines, and directional cues. If elements are arranged along a smooth path, the eye will follow that path. If the path has a sharp break, the eye stops or gets confused.
+
+5. **Apply continuity to layout flow.** Continuity dictates that content should follow predictable reading paths. In Western interfaces, the primary axis is top-to-bottom, left-to-right (Z-pattern or F-pattern).
+
+   **Worked example — Stripe's marketing page flow:**
+   - Hero section: headline left-aligned, CTA aligned to the same left edge
+   - Feature section below: text block left-aligned to the same grid column
+   - The consistent left-edge alignment creates a vertical continuity line — the eye follows it downward without searching
+   - When an element breaks this alignment (e.g., a centered testimonial), it creates an intentional continuity break that signals "this is different" — use this deliberately, not accidentally
+
+   **Worked example — dashboard data flow:**
+   - KPI cards arranged in a horizontal row: the shared top edge creates a horizontal continuity line
+   - Below the cards, a chart starts at the same left edge as the first card — the eye flows from cards to chart along the left alignment axis
+   - If the chart were offset 20px to the right, the continuity would break, and the eye would pause to re-orient
+
+6. **Apply continuity to data visualization.** Line charts, flow diagrams, and Sankey charts depend entirely on continuity. The eye follows the line, interpreting it as a single continuous data stream.
+
+   **Worked example — GitHub contribution graph:**
+   - The green squares form a grid, but the eye reads horizontal rows as continuous timelines (weeks) due to the left-to-right continuity cue
+   - Darker squares along a row create an implicit line that the eye traces — "this person was active in January, quiet in February, active again in March"
+   - The grid structure provides the continuity scaffold; the color variation provides the data
+
+   **Decision procedure for visual flow:**
+   1. Identify the primary reading path (top-to-bottom, left-to-right for most Western UIs)
+   2. Align key elements along this path — shared left edge, shared top edge, or shared center axis
+   3. Verify that no element breaks the alignment without a deliberate design reason
+   4. Use alignment breaks only to signal content type changes (e.g., shift from text to testimonial)
+
+## Details
+
+### Closure Threshold and Recognition
+
+Not all shapes tolerate the same degree of incompleteness. Recognition depends on the object's gestalt strength — how strong its internal structure is:
+
+- **High gestalt strength (tolerates 40-50% removal):** Circles, squares, triangles, common symbols (heart, star, arrow). A circle with half its outline removed is still perceived as a circle.
+- **Medium gestalt strength (tolerates 20-30% removal):** Letters, numbers, familiar icons (house, car, phone). The letter "A" with its crossbar removed is still readable in context.
+- **Low gestalt strength (tolerates <10% removal):** Abstract shapes, unfamiliar symbols, complex illustrations. A custom logo with pieces removed may become unrecognizable.
+
+**Implication for icon design:** Use geometrically simple base shapes (circles, squares, triangles) as the foundation. These tolerate more simplification and reproduce cleanly at all sizes.
+
+### Continuity in Navigation Patterns
+
+**Breadcrumbs** exploit continuity. The chain `Home > Products > Shoes > Running` creates a left-to-right continuity line that the eye follows. The separator characters (>, /, arrows) serve as continuity connectors — they tell the brain "this is one path, read it as a sequence."
+
+- Effective separator: `>` or `chevron-right` icon — implies direction and flow
+- Weak separator: `/` — implies hierarchy but not direction
+- Anti-pattern: no separator, relying only on spacing — breaks continuity; items read as independent links
+
+**Timelines** exploit vertical continuity. A connecting line between events creates an unambiguous time-flow axis:
+
+- GitHub's activity feed: events connected by a vertical line on the left
+- The line is the continuity cue — without it, events are a disconnected list
+- The line transforms "a list of things that happened" into "a story with sequence"
+
+### Closure in Loading States
+
+Skeleton screens exploit closure. A gray rectangle where a text block will appear triggers closure — the brain completes the pattern: "this is text that has not loaded yet." The skeleton must match the structural layout of the real content closely enough for the brain to complete the prediction.
+
+**Worked example — Facebook/Meta skeleton screens:**
+
+- Avatar placeholder: gray circle, exact size of the real avatar (40px)
+- Name placeholder: gray rectangle, approximate width of a name (120px x 14px)
+- Content placeholder: two gray rectangles, approximate width of a paragraph
+- The structural similarity to real content triggers closure — users perceive "a post is loading" rather than "gray shapes are on screen"
+- If the skeleton deviates too much from the real layout (wrong sizes, wrong positions), closure fails and the skeleton reads as arbitrary visual noise
+
+### Anti-Patterns
+
+1. **Broken closure targets in progress indicators.** A progress ring without a track (just an arc floating in space). The brain cannot determine the total — is this 75% of a circle or just a curved line? Always provide the complete shape as a track, scaffold, or background so the brain knows what is being "filled." Material Design specifies both determinate (with track) and indeterminate (animated arc) variants — the indeterminate variant uses continuous animation to signal "in progress" since static closure cues would mislead.
+
+2. **Jagged continuity in layouts.** Elements at inconsistent left margins — a heading at 24px, a paragraph at 32px, a list at 40px, then back to 24px. Each shift breaks the vertical continuity line and forces the eye to re-orient. The fix is a grid: define column edges and snap every element to one. Stripe's marketing pages use exactly three alignment points: left column edge, center, and right column edge. Nothing falls between.
+
+3. **False continuity between unrelated sequences.** A connecting line between steps that are not sequential, or breadcrumbs that show a path the user did not actually take. Continuity creates a powerful narrative implication — "these are connected in order." Using continuity connectors between unrelated items misleads users into seeing a false sequence. Shopping sites that show `Home > Sale > Product` when the user arrived from a search (not through the Sale page) create false continuity.
+
+4. **Over-simplified icons (below closure threshold).** Reducing an icon until it loses its essential geometric cues. A "settings gear" icon simplified to a plain circle has crossed the closure threshold — the brain cannot complete "gear" from a circle alone. Test icons at their smallest rendered size (typically 16px) and verify recognition without labels.
+
+### Real-World Examples
+
+**Apple SF Symbols — Closure Mastery:**
+
+- SF Symbols use consistent 1.5pt stroke weight across all 5,000+ icons, ensuring closure works at every size
+- At 44pt (iOS touch target), icons show fine detail. At 17pt (tab bar), the same icons lose detail but the brain completes them via closure
+- The "person.crop.circle" icon at 17pt is barely 6 distinguishable pixels of detail — yet it is instantly recognized as "profile" because the circle + head bump triggers closure from a known archetype
+- SF Symbols provide 9 weight variants: heavier weights for small sizes (more ink = stronger closure cues), lighter weights for large sizes
+
+**Material Design Step Indicators — Closure + Continuity Combined:**
+
+- Horizontal stepper: numbered circles connected by lines
+- Active step: filled circle, bold connector line to completed steps
+- Future steps: outlined circle, faint connector line
+- The outline circles trigger closure ("this will be filled when I get there")
+- The connector line triggers continuity ("these steps form a single journey")
+- Together: the user perceives a complete journey with their current position marked
+
+**Spotify's Progress Bar:**
+
+- Track progress: a filled green bar on a gray track
+- The gray track is the closure target — it shows the total song length
+- The green fill shows current position — the ratio is instantly readable because closure supplies the "total"
+- Scrubbing: when the user hovers, a circle handle appears at the fill edge — adding a focal point to the continuity line
+
+**GitHub Contribution Graph — Continuity in Data:**
+
+- 52 columns (weeks) x 7 rows (days) of colored squares
+- The eye reads left-to-right across rows (continuity along the horizontal axis)
+- Color intensity variations within a row create an implicit data line that the eye traces
+- Column alignment creates vertical continuity — "every Sunday is the top row" — enabling day-of-week pattern recognition
+- The grid provides double continuity (horizontal for time, vertical for weekday), making patterns visible that would be invisible in a table of numbers
+
+## Source
+
+- Max Wertheimer, "Laws of Organization in Perceptual Forms" (1923) — original closure and continuity principles
+- Gaetano Kanizsa, "Subjective Contours" (1976) — illusory contours as closure evidence
+- "Interaction Design: Beyond Human-Computer Interaction" by Preece, Rogers, and Sharp — application to interface design
+- Colin Ware, "Information Visualization: Perception for Design" — continuity in data visualization
+
+## Process
+
+1. Read the instructions and examples in this document.
+2. Apply the patterns to your implementation, adapting to your specific context.
+3. Verify your implementation against the details and edge cases listed above.
+
+## Harness Integration
+
+- **Type:** knowledge — this skill is a reference document, not a procedural workflow.
+- **No tools or state** — consumed as context by other skills and agents.
+
+## Success Criteria
+
+- The patterns described in this document are applied correctly in the implementation.
+- Edge cases and anti-patterns listed in this document are avoided.

package/dist/agents/skills/cursor/design-gestalt-closure-continuity/skill.yaml

@@ -0,0 +1,33 @@
+name: design-gestalt-closure-continuity
+version: "1.0.0"
+description: Pattern completion — the brain fills gaps in incomplete shapes (closure) and follows smooth paths over abrupt changes (continuity), implications for icons, progress indicators, and visual flow
+cognitive_mode: advisory-guide
+type: knowledge
+tier: 3
+triggers:
+  - manual
+platforms:
+  - claude-code
+  - gemini-cli
+  - cursor
+  - codex
+tools: []
+paths: []
+related_skills:
+  - design-gestalt-figure-ground
+  - design-iconography
+stack_signals: []
+keywords:
+  - gestalt
+  - closure
+  - continuity
+  - pattern-completion
+  - visual-flow
+  - icons
+  - progress-indicators
+metadata:
+  author: community
+state:
+  persistent: false
+  files: []
+depends_on: []

package/dist/agents/skills/cursor/design-gestalt-common-fate/SKILL.md

@@ -0,0 +1,214 @@
+# Gestalt Common Fate
+
+> Motion grouping — elements that move or change together are perceived as a unit, with implications for animation, loading states, and batch operations
+
+## When to Use
+
+- Designing animations where multiple elements should feel like a single group
+- Building loading states, skeleton screens, and shimmer effects
+- Implementing batch operations (select all, bulk delete, multi-drag)
+- Creating carousel, slider, and horizontal scroll interactions
+- Designing coordinated state transitions (page transitions, tab switches, expand/collapse)
+- Evaluating why an animation feels disconnected or a batch operation feels like separate actions
+
+## Instructions
+
+1. **Understand the law.** The Gestalt principle of common fate states that elements moving in the same direction, at the same speed, at the same time are perceived as a single group. This principle extends beyond literal motion to any synchronized change: opacity transitions, color shifts, scale transforms. If elements change together, they are perceived as a unit. If one element changes while others remain static, it is perceived as separate from the group.
+
+   **Why this matters for interfaces:** Digital interfaces are temporal — they change over time. Every animation, transition, and state change is an opportunity to communicate grouping through common fate. A well-designed animation tells the user "these things belong together" just as powerfully as proximity or similarity.
+
+2. **Synchronize grouped elements in animations.** When elements belong to the same group, their animations must share timing parameters: same duration, same easing curve, same delay. Any deviation breaks common fate and makes the elements read as independent.
+
+   **Worked example — Spotify horizontal card carousel:**
+   - When the user swipes, all visible cards translate horizontally by the same distance, at the same speed, with the same easing curve (`cubic-bezier(0.25, 0.1, 0.25, 1.0)`)
+   - This synchronized horizontal movement makes 5-6 cards feel like a single ribbon of content
+   - If one card moved faster than the others (even by 50ms), it would "detach" from the group perceptually
+   - New cards entering from the edge share the same velocity — they are immediately perceived as part of the group
+
+   **Worked example — Material Design container transform:**
+   - When a card expands to a detail view, the card's content (title, image, description) transforms together
+   - All child elements share the same timing: `duration: 300ms`, `easing: emphasized-decelerate`
+   - The content does not "fly in separately" — it scales and repositions as a unit
+   - This common fate during the transition tells the user "the detail view IS the card, expanded"
+
+   **Decision procedure for animation synchronization:**
+   1. Identify which elements form a group
+   2. Assign identical `duration`, `easing`, and `delay` values to all elements in the group
+   3. If using staggered entrance (elements appearing one by one), the stagger is the delay offset — but once visible, all elements must animate identically
+   4. Test by recording the animation and stepping through frame-by-frame — any visual separation between group members indicates a timing mismatch
+
+3. **Use staggered animation to imply sequence, not grouping.** Stagger (different delay values) creates an ordered sequence. This is the opposite of common fate — it makes elements feel sequential rather than grouped. Use stagger deliberately.
+
+   **Worked example — list item entrance animations:**
+   - Each item fades in with a 50ms stagger: item 1 at 0ms, item 2 at 50ms, item 3 at 100ms
+   - During the entrance, the items feel sequential — "item 1 leads, the others follow"
+   - After the entrance, all items are static and grouping reverts to proximity and similarity
+   - The stagger communicates: "these items have an order" (list, timeline, priority)
+
+   **When to stagger vs. synchronize:**
+   - Synchronize: items that form a single unit (cards in a carousel, filters in a bar, tabs in a row)
+   - Stagger: items that form a sequence (list entries, timeline events, step indicators)
+   - Never stagger elements that should read as a simultaneous group — a staggered navigation menu makes each item feel independent rather than part of a unified nav
+
+4. **Apply common fate to loading states.** Loading indicators that animate together signal "this is one loading process." Separate animations signal "these are independent processes."
+
+   **Worked example — skeleton screen shimmer (Facebook/Meta pattern):**
+   - Multiple placeholder rectangles (avatar, name, content lines) all share a single shimmer gradient animation
+   - The shimmer moves left-to-right across ALL placeholders simultaneously — same direction, same speed
+   - This common fate makes the entire skeleton feel like "one thing loading" rather than "six independent loading indicators"
+   - Implementation: a single `linear-gradient` animation on a parent element, with children using `overflow: hidden` to clip the gradient to their shapes. One animation, shared by all.
+
+   **Worked example — individual spinners (anti-pattern comparison):**
+   - Dashboard with 4 widget cards, each showing its own independent spinner
+   - Each spinner rotates at its own pace (started at different times, so they are out of phase)
+   - Result: 4 separate loading states competing for attention, each demanding its own "wait" from the user
+   - Fix: Use a single page-level skeleton shimmer, or synchronize all spinners to the same rotation phase
+
+5. **Apply common fate to batch operations.** When a user selects multiple items and performs a batch action, the selected items must respond as a group.
+
+   **Worked example — Gmail bulk email actions:**
+   - User selects 5 emails using checkboxes
+   - Clicks "Archive" — all 5 emails slide left simultaneously with the same duration (200ms) and easing
+   - The synchronized exit animation confirms "these 5 items were a group, and they all moved to the archive"
+   - If emails archived one by one (staggered by 100ms each), the user would perceive 5 separate archive actions, undermining the "batch" mental model
+
+   **Worked example — Figma multi-select drag:**
+   - User selects 3 design elements and drags them
+   - All 3 elements move with the cursor at exactly the same delta (same x/y offset from the drag origin)
+   - This rigid common fate makes 3 separate objects feel like a single compound object
+   - If one element lagged behind (frame rate issue), it would "detach" perceptually, creating anxiety about whether the operation is working correctly
+
+6. **Use broken common fate to signal state divergence.** When an element leaves a group (deselection, error, completion), breaking its common fate signals the departure.
+
+   **Worked example — Trello card drag between lists:**
+   - Cards in a list sit in a vertical column — static, grouped by proximity
+   - When a card is dragged, it gains elevation (shadow increases) and moves with the cursor
+   - The remaining cards animate to close the gap — they move together (common fate within the list)
+   - The dragged card moves independently from all lists — its unique motion signals "I have left the group"
+   - When dropped into a new list, the card's motion synchronizes with the target list's reflow — joining the new group through common fate
+
+   **Worked example — multi-step form with validation errors:**
+   - User submits a form. Valid fields transition smoothly to a confirmation state (fade to green check, 200ms)
+   - Invalid fields shake horizontally (150ms, 4px amplitude) — a motion completely different from the valid fields
+   - The divergent motion instantly communicates which fields need attention without reading any error messages
+   - Valid fields moved together (common fate = "these are fine"). Invalid fields moved together but differently (common fate within the error group, divergent from the success group).
+
+## Details
+
+### Timing Parameters for Common Fate
+
+Animation timing must be precise for common fate to work. Approximate values create subtle unease.
+
+**Synchronized motion — required parameters:**
+
+- **Duration:** Identical for all group members (e.g., all 200ms, not 200ms for some and 250ms for others)
+- **Easing:** Identical curve (e.g., all `cubic-bezier(0.4, 0, 0.2, 1)`, not different curves per element)
+- **Start time:** Must be within one frame (16.67ms at 60fps) of each other. Use `requestAnimationFrame` batching or CSS animation on a shared parent to guarantee synchronization.
+- **Direction:** Same vector. If the group moves right, all members move right. One element moving right while another moves down breaks common fate instantly.
+
+**Staggered sequence — acceptable parameters:**
+
+- **Delay offset:** 30-80ms between items for smooth cascade. Under 30ms, stagger is imperceptible (items feel synchronized). Over 100ms, items feel disconnected (too much gap between entries).
+- **Duration and easing:** Still identical for all items — only the delay differs.
+
+### Common Fate in Micro-Interactions
+
+Common fate operates at the micro-interaction level too:
+
+**Hover effects on grouped elements:**
+
+- A nav item with icon + text: on hover, both icon and text change color simultaneously (common fate = "these are one button")
+- If only the text changes color on hover, the icon appears to be a separate element
+
+**Toggle state changes:**
+
+- A switch component: the thumb slides right AND the track changes color AND the label updates — all in 150ms with the same easing
+- If the thumb moves in 150ms but the track color transitions in 300ms, they feel like separate components
+
+**Button press feedback:**
+
+- A button depresses: scale to 0.97, shadow reduces, background darkens — all simultaneously
+- These three property changes, occurring in common fate, create a single "press" perception
+- If the scale happens instantly but the shadow fades over 200ms, the button feels glitchy
+
+### Common Fate and Performance
+
+Synchronized animation requires consistent frame rates. If the browser drops frames on one element but not another, their common fate breaks.
+
+**Implementation strategies for reliable synchronization:**
+
+- **CSS approach:** Animate a parent container and let children inherit the transform. One animation = guaranteed synchronization.
+- **JavaScript approach:** Use `requestAnimationFrame` and update all elements in the same frame callback. Never use separate `setTimeout` or `setInterval` calls for elements that should move together.
+- **Web Animations API:** Use `element.animate()` with a shared timeline to ensure frame-level synchronization.
+- **GPU compositing:** Use `transform` and `opacity` (GPU-composited properties) rather than `top`, `left`, `width`, `height` (layout-triggering). Layout recalculation can delay one element's render relative to another, breaking common fate at the pixel level.
+
+### Anti-Patterns
+
+1. **Desynchronized loading indicators.** Multiple spinners, progress bars, or shimmer effects running at different speeds or phases. Three cards each with their own spinner, started at different times, create three independent "loading" signals. The user must track three separate processes. Fix: use a single shared animation (one shimmer gradient, one skeleton, one progress indicator) or synchronize all indicators to the same phase using a shared CSS `animation-delay: 0s`.
+
+2. **Inconsistent batch animation.** Selecting 5 items and archiving them, but each item exits with a slightly different duration or easing because the animation was applied per-element without shared timing. Fix: calculate all target positions first, then apply the animation to all elements in a single `requestAnimationFrame` tick with identical timing parameters.
+
+3. **False common fate on unrelated elements.** Two unrelated UI elements that happen to animate at the same time with the same parameters. A sidebar closing while a toast appears — if both happen to use a 200ms slide animation, they feel related when they are not. Fix: use different timing for unrelated simultaneous animations. Give the sidebar 250ms and the toast 150ms. The timing difference breaks the false common fate.
+
+4. **Breaking common fate during scroll.** Elements in a scrollable container that do not scroll together. A "sticky" header inside a scroll container that stutters (jumps between frames) appears to detach from the scrolling content, breaking the common fate of the scroll group. Fix: use CSS `position: sticky` (GPU-composited) rather than JavaScript-based scroll listeners that can lag by one or more frames.
+
+### Real-World Examples
+
+**Spotify Horizontal Carousel:**
+
+- Cards scroll as a single unit — all cards share the same translateX animation per frame
+- The scroll is momentum-based: after the user releases, all cards decelerate together using the same friction curve
+- Snap points: when the scroll settles, all cards snap to alignment simultaneously — the snap does not move one card at a time
+- This creates the perception of a continuous ribbon that the user is sliding through a viewport window
+
+**Apple iOS Page Transitions:**
+
+- When pushing a new view controller, the outgoing view translates left AND fades while the incoming view translates from right AND fades in
+- Both views use the same 350ms duration with the same spring curve
+- All elements within each view move with their parent — no element is independently animated during the transition
+- This creates a single "page turn" perception rather than "a bunch of elements rearranging"
+
+**Material Design Shared Element Transitions:**
+
+- A list item transforms into a detail view: the image scales up, the title repositions, the card boundary expands
+- All transforming elements use a single 300ms duration with `emphasized-decelerate` easing
+- Non-transforming elements fade out (list) or fade in (detail) with the same 300ms timing
+- The shared timing creates one fluid transformation rather than a disconnected disappear-and-appear
+
+**Airbnb Map Pin Clustering:**
+
+- When zooming out, nearby map pins animate toward each other and merge into a cluster pin
+- The merging pins share a common trajectory (toward the cluster centroid) and timing
+- This common fate signals "these individual listings are becoming a group"
+- When zooming in, the cluster pin splits and pins animate outward — the outward common fate signals "this group is separating into individuals"
+- The synchronized split creates a "bloom" effect that feels organic because all pins move simultaneously
+
+**Linear's Batch Operations:**
+
+- Select multiple issues, drag to a new status column
+- All selected issues lift (shadow increase) simultaneously, move with the cursor as a unit, and drop into the target column together
+- The remaining issues in the source column reflow to fill the gap — their upward movement shares common fate, signaling "we are the remaining group"
+- The dropped issues settle into the target column with a shared bounce animation, signaling "we are now part of this group"
+
+## Source
+
+- Max Wertheimer, "Experimental Studies on Seeing Motion" (1912) — foundational motion perception and grouping
+- Gunnar Johansson, "Visual Perception of Biological Motion" (1973) — common fate in motion perception
+- Material Design motion documentation (m3.material.io/styles/motion)
+- "Animation at Work" by Rachel Nabors — web animation principles and timing
+
+## Process
+
+1. Read the instructions and examples in this document.
+2. Apply the patterns to your implementation, adapting to your specific context.
+3. Verify your implementation against the details and edge cases listed above.
+
+## Harness Integration
+
+- **Type:** knowledge — this skill is a reference document, not a procedural workflow.
+- **No tools or state** — consumed as context by other skills and agents.
+
+## Success Criteria
+
+- The patterns described in this document are applied correctly in the implementation.
+- Edge cases and anti-patterns listed in this document are avoided.