@harness-engineering/cli 1.23.1 → 1.24.0

package/dist/agents/skills/codex/design-font-pairing/SKILL.md

@@ -0,0 +1,161 @@
+# Font Pairing
+
+> Combining typefaces — contrast principles, superfamilies, serif+sans pairing rules, pairing by x-height and proportion, limiting to 2-3 families
+
+## When to Use
+
+- Selecting a headline and body typeface combination for a new project
+- Adding a monospace companion to an existing design system
+- Evaluating whether two typefaces work together or create visual conflict
+- Deciding between a single-family strategy and a multi-family approach
+- Replacing a licensed font with a free alternative that pairs with the remaining system fonts
+
+## Instructions
+
+1. **Apply the concord/contrast/conflict model.** Every font pairing falls into one of three relationships:
+   - **Concord** — fonts share similar traits (two humanist sans-serifs). Creates quiet harmony but risks monotony. Works for single-family systems.
+   - **Contrast** — fonts differ in classification but share structural DNA (serif headlines + sans body). Creates visual interest and clear role separation. This is the most reliable pairing strategy.
+   - **Conflict** — fonts differ slightly but not enough (two grotesque sans-serifs with similar proportions). Creates visual tension without purpose — the eye notices something is "off" but cannot identify what.
+   - **Decision rule**: If two fonts are not clearly in concord or contrast, they are in conflict. Replace one.
+
+2. **Match x-height and vertical proportions.** Two fonts paired at the same pixel size must appear the same visual size. The mechanism is x-height ratio:
+   - **Good pair**: Inter (x-height 0.756) + Merriweather (x-height 0.750) — virtually identical perceived size at 16px
+   - **Problematic pair**: Inter (0.756) + Garamond (0.630) — Garamond appears ~17% smaller at the same font-size, requiring size compensation
+   - **Test method**: Set both fonts at 16px side by side with the text "Handgloves" — if one appears noticeably smaller, compensate with a larger font-size or choose a different pairing
+
+3. **Enforce the 2-3 family maximum.** Every additional typeface increases visual complexity, file size, and decision burden:
+   - **1 family**: Maximum consistency, minimum expression. Works for developer tools and data-dense UIs. Example: Vercel uses Geist exclusively.
+   - **2 families**: The standard for most projects — one for headings, one for body, or one sans and one mono. Example: Stripe uses sohne (UI) + Source Code Pro (code).
+   - **3 families**: Maximum for any project. Typically sans + serif + mono. Example: Apple uses SF Pro (UI) + New York (editorial) + SF Mono (code).
+   - **4+ families**: Almost always a mistake. Each additional family fragments visual identity and adds load time.
+
+4. **Use superfamilies for guaranteed harmony.** A superfamily is a type family designed with serif, sans-serif, and sometimes mono variants that share identical metrics:
+   - **Roboto + Roboto Slab + Roboto Mono** (Google) — same x-height, cap height, and vertical metrics across all three
+   - **Source Sans Pro + Source Serif Pro + Source Code Pro** (Adobe) — designed as a matched triplet
+   - **PT Sans + PT Serif + PT Mono** (ParaType) — Russian-origin superfamily with full Cyrillic support
+   - **IBM Plex Sans + IBM Plex Serif + IBM Plex Mono** (IBM) — corporate superfamily with 8 weights each
+   - Superfamilies eliminate x-height matching problems entirely — they are designed to pair.
+
+5. **Pair by classification contrast, not quality contrast.** The goal is fonts that differ in _kind_ (serif vs sans, geometric vs humanist) but match in _quality_ (similar level of refinement, similar era of design thinking):
+   - **Good**: Playfair Display (refined didone serif) + Source Sans Pro (refined humanist sans) — both are polished, contemporary designs
+   - **Bad**: Playfair Display (refined didone serif) + Comic Sans (casual humanist sans) — wildly different refinement levels
+   - **Good**: Inter (geometric-influenced neo-grotesque) + Lora (contemporary old-style serif) — both designed for screen, similar quality
+   - **Bad**: Inter + Times New Roman — Times was designed for newspaper columns in 1931; the design philosophy clash is visible
+
+6. **Evaluate pairings with real content, not specimen text.** "The quick brown fox" tells you nothing about how fonts behave in your actual UI:
+   - Set a real page layout: navigation, headings, body paragraphs, buttons, form labels, captions
+   - Check at 3 sizes: mobile (375px), tablet (768px), desktop (1440px)
+   - View at actual distance (arm's length for desktop, hand-held for mobile)
+   - Print a screenshot at 100% scale and evaluate from 2 feet away — this reveals hierarchy problems that on-screen viewing misses
+
+## Details
+
+### Single-Family Strategies
+
+Using one typeface for everything is not a limitation — it is a deliberate design strategy used by some of the most sophisticated systems:
+
+**Weight Variation** — Create hierarchy through weight alone:
+
+- Headlines: 700 (bold) or 300 (light, Stripe-style)
+- Body: 400 (regular)
+- Captions: 400 at smaller size or 300
+- Example: Stripe uses sohne-var at only weights 300 and 400, achieving all hierarchy through size, weight, and letter-spacing
+
+**Width Variation** — Variable fonts with `wdth` axis allow condensed headings and normal body:
+
+- Headlines: width 85% (condensed) at weight 600
+- Body: width 100% (normal) at weight 400
+- Example: Roboto Flex supports width from 75% to 125%, enabling a complete typographic system from one file
+
+**Style Variation** — Italic and small caps create emphasis without adding a second family:
+
+- Block quotes: italic at same size and weight
+- Labels: small caps at slightly smaller size
+- Code: switch to the mono companion (most design systems treat mono as a functional requirement, not a pairing choice)
+
+### Stripe's Pairing Approach
+
+Stripe demonstrates a minimal two-family strategy:
+
+- **Primary**: sohne-var (Klim Type Foundry) — a refined neo-grotesque variable font with OpenType feature `ss01` enabled globally
+- **Code**: Source Code Pro — Adobe's open-source monospace designed for programming contexts
+- **Strategy**: sohne handles all UI text (navigation, headings, body, buttons, form labels) using only weights 300 and 400. Source Code Pro appears only in code blocks and API references.
+- **Why it works**: sohne's variable font axes provide enough internal variation (weight, optical size) that a second text face is unnecessary. The monospace companion serves a purely functional role.
+
+### Apple's Three-Family System
+
+Apple's pairing is the gold standard for a three-family system:
+
+- **SF Pro** (sans-serif): all UI text, navigation, buttons, labels. Has text and display optical sizes.
+- **New York** (serif): editorial content, long-form reading, marketing headlines. Designed with metrics that match SF Pro — both share identical x-height ratios and vertical metrics, so they can coexist on the same baseline grid without adjustment.
+- **SF Mono** (monospace): code, terminal output, tabular data. Matches SF Pro's x-height.
+- **Why it works**: All three were designed as a family — not a superfamily in the traditional sense, but a coordinated system where metrics align by intention.
+
+### Material Design's Superfamily Approach
+
+Material Design 3 defaults to the Roboto superfamily:
+
+- **Roboto Flex**: primary UI typeface with 13 variation axes
+- **Roboto Serif**: editorial and display content
+- **Roboto Mono**: code and tabular data
+- All three share the same core vertical metrics, ensuring any combination produces aligned baselines
+- Google's recommendation: start with Roboto, customize only when brand requires differentiation
+
+### Anti-Patterns
+
+1. **Two similar sans-serifs.** Pairing Helvetica with Arial, or Inter with Roboto, creates conflict — they are similar enough to look like a mistake but different enough to create visual noise. The eye detects "these are not the same font" without understanding why. If you need variation within sans-serif, use weight/width variation within one family, not two families.
+
+2. **More than 3 families.** Loading Montserrat for headings, Open Sans for body, Lato for navigation, Fira Code for code, and Playfair Display for pull quotes produces visual cacophony. Each font brings different proportions, letter spacing, and personality. Consolidate to 2-3 families and use weight/style variation for differentiation.
+
+3. **Pairing without checking x-height compatibility.** Futura (x-height ratio ~0.653) paired with Georgia (x-height ratio ~0.698) at the same pixel size will look mismatched — Georgia appears ~7% larger. At 16px this is subtle; at 24px it is obvious. Always compare x-height ratios before committing to a pairing. If the ratio difference exceeds 0.05, compensate with font-size adjustment or choose a better match.
+
+4. **Pairing based on "feel" without structural analysis.** "These two fonts feel right together" is not a pairing rationale. Document why: Do they share x-height proportions? Do they contrast in classification? Are they from the same era of design thinking? If you cannot articulate the structural reason, the pairing is likely coincidental and will break under different content conditions.
+
+### Real-World Examples
+
+**GitHub: System Fonts + Custom Marketing**
+
+- UI: `-apple-system, BlinkMacSystemFont, 'Segoe UI', Noto Sans, Helvetica, Arial, sans-serif` — pure system font stack for zero-load-time UI
+- Marketing/landing pages: Mona Sans (custom variable font) for headlines, system fonts for body
+- Code: SFMono-Regular, Consolas, Liberation Mono, Menlo, monospace
+- Strategy: performance-first for the application, brand expression only on marketing surfaces
+
+**Airbnb: Cereal as Single Family**
+
+- Airbnb Cereal: custom geometric sans-serif in weights Book, Medium, Bold, Extra Bold
+- Used exclusively across all surfaces — app UI, marketing, documentation
+- Paired only with a system monospace for developer-facing content
+- Demonstrates that a strong single-family choice eliminates pairing decisions entirely
+
+**Spotify: Circular as Brand Anchor**
+
+- Spotify Circular: custom geometric sans-serif (based on Lineto's Circular)
+- Weights: Book (400), Bold (700), Black (900) — three weights handle all hierarchy
+- Paired with system fonts for body text in embedded web views for performance
+- The single display typeface carries brand recognition across all platforms (mobile, desktop, TV, car displays)
+- Monospace needs handled by platform defaults since code display is not a product requirement
+
+## Source
+
+- Bringhurst, Robert. _The Elements of Typographic Style_ — on combining typefaces (chapter 6)
+- Heck, Bethany. Font Review Journal — https://fontreviewjournal.com
+- Google Fonts Knowledge: Choosing Type — https://fonts.google.com/knowledge/choosing_type
+- Butterick, Matthew. _Butterick's Practical Typography_ — font recommendations chapter
+
+## Process
+
+1. **Evaluate** — Identify the roles that need distinct typographic treatment (headings, body, code, captions). Determine whether a single family with weight variation can fulfill all roles or whether multiple families are needed.
+2. **Apply** — Select fonts using the contrast principle. Verify x-height compatibility. Test with real content at multiple viewport sizes. Limit to 2-3 families maximum.
+3. **Verify** — Confirm that paired fonts are visually distinguishable by role, proportionally compatible (x-height ratio difference < 0.05), and that total font file size is acceptable for the performance budget.
+
+## Harness Integration
+
+This is a knowledge skill. When activated, it provides typeface combination expertise to guide font-family selections in design tokens and CSS. Use these principles when defining `--font-family-*` custom properties or evaluating existing font stacks. Cross-reference with `design-typography-fundamentals` for anatomy comparisons and `design-web-fonts` for loading strategy.
+
+## Success Criteria
+
+- The project uses no more than 3 typeface families
+- Every font pairing has a documented structural rationale (classification contrast, x-height match)
+- X-height ratios of paired fonts differ by no more than 0.05 (or size compensation is applied)
+- No two fonts from the same classification are paired (no two grotesque sans-serifs)
+- Font roles are clearly assigned: each family has a defined purpose (UI, editorial, code)

package/dist/agents/skills/codex/design-font-pairing/skill.yaml

@@ -0,0 +1,34 @@
+name: design-font-pairing
+version: "1.0.0"
+description: Combining typefaces — contrast principles, superfamilies, serif+sans rules, limiting to 2-3 families
+cognitive_mode: advisory-guide
+type: knowledge
+tier: 3
+triggers:
+  - manual
+platforms:
+  - claude-code
+  - gemini-cli
+  - cursor
+  - codex
+tools: []
+paths: []
+related_skills:
+  - design-typography-fundamentals
+  - design-type-scale
+  - design-brand-consistency
+stack_signals: []
+keywords:
+  - font pairing
+  - typeface combination
+  - serif sans-serif
+  - superfamily
+  - contrast
+  - concord
+  - font stack
+metadata:
+  author: community
+state:
+  persistent: false
+  files: []
+depends_on: []

package/dist/agents/skills/codex/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/codex/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/codex/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/codex/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: []