@harness-engineering/cli 1.23.2 → 1.24.0

package/dist/agents/skills/gemini-cli/design-affordances/SKILL.md

@@ -0,0 +1,157 @@
+# Affordances
+
+> Perceived actionability — signifiers, constraints, mappings (Don Norman), flat design's affordance problem, touch targets, hover states as affordance
+
+## When to Use
+
+- Designing interactive elements (buttons, links, form controls, draggable items) that must communicate their actionability
+- Auditing an interface where users are confused about what is clickable and what is static
+- Evaluating a flat or minimal design for sufficient interactive cues
+- Building touch interfaces where target sizes directly affect usability
+- Designing drag-and-drop, resize, or gesture-based interactions that need discoverability
+- Reviewing a design system's interactive component library for consistent affordance language
+- Diagnosing user testing results where participants could not find interactive elements
+- Adapting a desktop interface for touch or vice versa
+
+## Instructions
+
+1. **Distinguish affordances from signifiers.** Don Norman clarified this in the 2013 revision of _The Design of Everyday Things_: an affordance is a relationship between an object and an agent — a button affords pressing whether or not you can see it. A signifier is a perceivable indicator of the affordance — the raised shape, the color, the label that tells you "this is pressable." In digital design, you cannot manipulate true affordances (pixels do not physically press), so you are always designing signifiers that communicate perceived affordances. Every interactive element needs at least one signifier.
+
+2. **Apply the Signifier Stack for interactive elements.** Each interactive element should carry multiple layered signifiers for redundancy. The stack, in order of strength:
+
+   | Signifier Type  | Example                                          | Strength |
+   | --------------- | ------------------------------------------------ | -------- |
+   | Shape           | Rounded rectangle suggests tappability           | High     |
+   | Color contrast  | Blue text among black text signals linkhood      | High     |
+   | Depth/elevation | Shadow beneath a card suggests liftability       | Medium   |
+   | Cursor change   | `pointer` cursor on hover signals clickable      | Medium   |
+   | Label/icon      | "Submit" text, pencil icon for edit              | High     |
+   | State change    | Background shift on hover confirms interactivity | Medium   |
+   | Motion          | Subtle pulse drawing attention to CTA            | Low      |
+
+   A well-designed button uses at least 3: shape (pill/rounded rect), color (distinct from body text), and label (action verb). Stripe's primary buttons use 5: shape (rounded rectangle), color (brand purple fill), label ("Pay $49.00"), depth (subtle shadow), and cursor (pointer on hover).
+
+3. **Respect Norman's four principles: affordance, signifier, constraint, mapping.**
+   - **Affordance:** What actions are possible? A text input affords typing. A slider affords dragging.
+   - **Signifier:** How does the user discover the affordance? The blinking cursor in an input. The handle on a slider.
+   - **Constraint:** What prevents incorrect actions? A date picker that grays out invalid dates. A slider that stops at min/max bounds. A dropdown that limits selection to valid options.
+   - **Mapping:** How does the control relate spatially to its effect? A vertical slider that controls volume should move up for louder (natural mapping). A set of light switches should match the spatial layout of the lights they control. In digital UI, the most common mapping failure is placing a control far from the content it affects.
+
+4. **Size touch targets to minimum 44x44 CSS pixels (48x48dp on Android).** Apple's Human Interface Guidelines specify 44pt minimum. Material Design specifies 48dp minimum with the touch target extending beyond the visual element if needed. These are not suggestions — they are ergonomic requirements based on the average adult fingertip contact area of 8-10mm. Common violations: icon-only buttons at 24x24px (too small by half), inline text links in mobile views (target height equals line-height of 16-20px, far below minimum), close/dismiss buttons in the corner of modals (often 20x20px).
+
+5. **Design hover states as progressive disclosure of affordance.** Desktop hover is a privileged moment: the user has expressed interest but not commitment. Use it to reveal additional information about the affordance. GitHub's repository file list uses hover to reveal the "last commit message" tooltip and a subtle background highlight — the hover state teaches "this row is interactive and will take you somewhere." Stripe's pricing cards use hover to elevate the card (shadow increases) and reveal a "Select Plan" button — the hover progressively discloses the primary action.
+
+6. **Solve flat design's affordance crisis with reliable signifier patterns.** The shift from skeuomorphic to flat design (2012-2015) stripped most depth-based signifiers. The result: users cannot distinguish interactive from decorative elements. Research by Nielsen Norman Group (2015) found that users spent 22% more time on flat designs trying to determine what was clickable. The solutions that work:
+   - **Consistent color coding:** Reserve one color exclusively for interactive elements. All links, buttons, and tappable items use that color. Nothing non-interactive uses it. Material Design reserves primary brand color for interactive elements only.
+   - **Underline links in body text.** Without underlines, links in paragraphs are indistinguishable from bold or colored text. GitHub underlines all links in markdown-rendered content. Medium does not underline links and user testing consistently shows link discovery failures.
+   - **Container signifiers for buttons.** Text-only buttons (no fill, no border) are the weakest button signifier. Outlined buttons add a border. Filled buttons add background color. Use the hierarchy: filled for primary, outlined for secondary, text-only for tertiary — but never use text-only buttons as the sole action in a view.
+
+7. **Map controls to their effects through spatial proximity and visual connection.** A toggle that controls a feature should be adjacent to that feature's description — not in a separate settings panel three screens away. When spatial proximity is impossible (control panel affecting a canvas, remote settings), use visual connection: highlight the affected area when the control is hovered or focused. Figma draws a blue highlight on the canvas element when you hover its corresponding layer in the sidebar — the mapping is made explicit through visual connection.
+
+8. **Use constraints to prevent errors, not just signal them.** A constraint that grays out an invalid option is better than an error message after selection. A date picker that only shows valid dates is better than a text input that rejects invalid dates after typing. Airbnb's date picker disables check-in dates before today and check-out dates before the selected check-in — the constraint is visible in the UI, preventing the error entirely. The strongest affordance design makes the wrong action impossible rather than merely discouraged.
+
+## Details
+
+### The Affordance Spectrum
+
+Affordances exist on a spectrum from obvious to hidden:
+
+**Explicit affordances** are immediately apparent. A button labeled "Submit" with a filled background, rounded corners, and a pointer cursor is explicitly interactive. No discovery required. These are appropriate for primary actions, critical controls, and first-time user experiences.
+
+**Pattern-based affordances** rely on learned conventions. A hamburger menu icon (three horizontal lines) affords opening a navigation menu — but only because users have learned this convention. A user encountering it for the first time would have no idea. Pattern-based affordances are efficient for experienced users but must be paired with explicit alternatives for novices. GitHub's repository page uses pattern-based affordances extensively: the code icon tab, the issues counter badge, the fork button — all rely on learned GitHub conventions.
+
+**Hidden affordances** are not discoverable without exploration. Right-click context menus, long-press actions, keyboard shortcuts, and gesture-based interactions are hidden. They are powerful for expert users but must never be the only path to a function. Every hidden affordance must have an explicit or pattern-based equivalent. Linear's keyboard shortcuts (C to create, X to select) are hidden affordances — but every action is also available through visible menu items and buttons.
+
+**Negative affordances (anti-affordances)** communicate "you cannot do this." Disabled buttons, grayed-out options, and `not-allowed` cursors are negative affordances. They are essential for preventing errors and must be visually distinct from both active affordances and static content. The visual hierarchy: active (full color, pointer cursor) > static (body color, default cursor) > disabled (muted color, not-allowed cursor).
+
+### Touch Target Geometry
+
+Touch targets involve two separate measurements: the **visual target** (what the user sees) and the **hit area** (the actual tappable region). The hit area must meet minimum size requirements even when the visual target is smaller. A 24x24px icon button must have a 44x44px (or 48x48dp) hit area — achieved with padding, an invisible expanded tap zone, or CSS `min-height`/`min-width` on the interactive wrapper.
+
+**Spacing between touch targets** matters as much as size. Two 48dp buttons placed 2dp apart will cause constant mis-taps. Minimum spacing between touch targets: 8dp (Material Design). Adjacent targets should ideally have 12-16dp separation. Fitts's Law governs this: the time to acquire a target is proportional to the distance divided by the target width. Larger, more spaced targets are faster to hit.
+
+**Edge and corner targets** are special cases. Targets at screen edges benefit from the "infinite edge" effect — the user can throw their cursor/finger toward the edge without precision, because the edge stops the movement. macOS exploits this with the menu bar at the top edge and the Dock at the bottom edge. Targets in corners benefit even more — two infinite edges converge. This is why Windows places the Start button at the bottom-left corner and Close button at the top-right corner. In mobile design, bottom-edge targets are easiest to reach with the thumb (Hoober's thumb zone research, 2017).
+
+### Cursor States as Signifier System
+
+On desktop, the cursor is one of the strongest affordance signifiers because it changes dynamically based on context:
+
+| Cursor      | CSS Value             | Communicates                                |
+| ----------- | --------------------- | ------------------------------------------- |
+| Pointer     | `cursor: pointer`     | This element is clickable                   |
+| Text        | `cursor: text`        | You can select or edit text here            |
+| Grab        | `cursor: grab`        | This element can be dragged                 |
+| Grabbing    | `cursor: grabbing`    | You are currently dragging this element     |
+| Col-resize  | `cursor: col-resize`  | This boundary can be dragged horizontally   |
+| Not-allowed | `cursor: not-allowed` | This action is not available                |
+| Progress    | `cursor: progress`    | The system is working, but you can interact |
+| Wait        | `cursor: wait`        | The system is working, please wait          |
+
+A common violation: using `cursor: pointer` on non-interactive elements (decorative cards, static text, non-linked images). This teaches users that the pointer cursor is unreliable, undermining the entire signifier system. Reserve `pointer` exclusively for elements that do something on click.
+
+### Mappings in Digital Interfaces
+
+**Natural mapping** aligns the spatial arrangement of controls with the spatial arrangement of their effects. A volume slider that moves right to increase follows the Western reading direction metaphor for "more." A brightness slider that moves up to brighten follows the natural light metaphor (sun is up). These feel intuitive because they match pre-existing mental models.
+
+**Arbitrary mapping** has no spatial or metaphorical relationship between control and effect. A dropdown menu at position X that changes content at position Y with no visual connection is arbitrary. The user must learn and remember the mapping. Minimize arbitrary mappings — every arbitrary mapping adds cognitive load.
+
+**The proximity principle for mapping:** The control should be as close as possible to the thing it controls. Inline editing (click text to edit in place) has perfect mapping — the control IS the content. A separate edit button has one degree of separation. An "Edit" page reached via navigation has multiple degrees. Each degree of separation weakens the mapping and increases the chance the user loses context. This is why inline editing has become the dominant pattern in modern interfaces — GitHub's inline file editing, Notion's click-to-type blocks, Linear's inline issue title editing.
+
+### Anti-Patterns
+
+1. **The Flat Design Guessing Game.** A page where text, icons, images, and interactive elements all share the same visual weight, color, and treatment. Users hover randomly trying to discover what is clickable. Diagnosis: observe users on a heat map tool — random, scattered click patterns indicate affordance failure. Fix: establish a strict interactive color (used only for clickable elements), add hover state changes to all interactive elements, and underline body text links.
+
+2. **Ghost Buttons on Critical Paths.** Using outlined/ghost buttons (transparent background, thin border) as the primary CTA. Ghost buttons have the weakest affordance signal of any button style — they are nearly invisible against busy backgrounds and are easily confused with decorative borders. Fix: filled buttons with strong color contrast for any primary action. Reserve ghost buttons for secondary or tertiary actions only. Apple's landing pages infamously use ghost buttons — they rely on brand recognition and massive CTAs to compensate, a luxury most products do not have.
+
+3. **Touch Target Roulette.** Interactive elements sized below 44x44px on touch devices: 16px icon-only buttons, thin rule-line separators that are secretly tappable, close buttons rendered as 12px "X" characters. Users tap repeatedly in the general area, missing each time. Fix: audit every interactive element against the 44x44px minimum. Use padding to expand hit areas without changing visual size. Test on actual touch devices — emulators mask this problem because mouse cursors are pixel-precise.
+
+4. **Mystery Meat Navigation.** Icon-only navigation with no labels, tooltips, or contextual help. The user must click each icon to discover what it does — the interaction relies entirely on trial and error. Common in minimalist sidebars. Fix: always pair icons with labels. If space is constrained, add persistent labels on hover/focus and use `aria-label` for screen readers. Linear's sidebar uses icon + label for all navigation items; collapse mode shows icons only but with tooltips on hover.
+
+5. **Inconsistent Cursor Signals.** Using `cursor: pointer` on cards that navigate, static cards that do nothing, images that open lightboxes, and decorative icons — the pointer cursor becomes meaningless. Fix: audit `cursor: pointer` usage and restrict it to elements with click handlers that perform a meaningful action. Static, decorative, and informational elements use `cursor: default`.
+
+### Real-World Examples
+
+**Material Design Elevation System.** Material Design uses elevation (shadow depth) as a systematic affordance signifier. Elements at `elevation-0` (no shadow) are the background surface — non-interactive. Elements at `elevation-1` (1dp shadow) are cards — potentially interactive. Elements at `elevation-2` (3dp shadow) are raised buttons and app bars — definitely interactive. FABs sit at `elevation-3` (6dp). Modals at `elevation-5` (24dp). The elevation hierarchy creates a consistent, learnable affordance language: higher = more interactive. On press, interactive elements increase by one elevation level, confirming the affordance through state change.
+
+**Stripe Checkout Form.** Stripe's payment form demonstrates layered affordance design. The card number input has: a text cursor signifier, a placeholder format hint ("1234 1234 1234 1234"), a card brand icon that updates as you type (Visa, Mastercard — confirming the input is being processed), an inline error state with red border (constraint signifier), and a focus ring with brand blue (active state signifier). Five signifiers for a single input field, each serving a different discovery moment.
+
+**Apple iOS Swipe Affordances.** iOS uses a subtle "peek" pattern to signal swipe affordances. In Mail, the very first time you encounter a message, a brief auto-swipe animation reveals the colored action buttons underneath, then snaps back. This one-time affordance disclosure teaches the gesture without requiring a tutorial. After that, the affordance is pattern-based — users remember the swipe convention. The auto-reveal animation is 300ms total (150ms open, 150ms close) and plays only once per user.
+
+**GitHub Code Review Affordances.** In pull request diffs, GitHub uses multiple signifiers to indicate line-level commenting: (1) hovering over the gutter reveals a blue "+" icon (progressive disclosure), (2) the gutter background highlights on hover (state change), (3) clicking opens a comment form inline (natural mapping — the comment appears exactly where you clicked). The affordance is hidden until the user demonstrates interest (hover), then becomes explicit (icon + highlight), then confirms through interaction (inline form).
+
+### Affordance Audit Checklist
+
+When auditing an interface for affordance quality, check each interactive element against these criteria:
+
+1. **Can a first-time user identify this as interactive without clicking?** Show a screenshot to someone unfamiliar with the product. Can they point to all clickable elements within 5 seconds? If they miss an interactive element, its signifiers are insufficient.
+2. **Does the element have at least 2 signifier types?** Single-signifier elements (color only, shape only) fail when that one signifier is ambiguous. Two or more signifiers create redundancy that survives ambiguity.
+3. **Does the element meet touch target minimums?** Measure the actual hit area (not just the visual size) against 44x44px (iOS) or 48x48dp (Android). Use browser DevTools to verify padding and click areas.
+4. **Does the cursor change on hover (desktop)?** Every clickable element must show `cursor: pointer`. Every draggable element must show `cursor: grab` (and `cursor: grabbing` while dragging). Every non-interactive element must use `cursor: default`.
+5. **Is there a visible state change on hover/focus?** The element must visually respond to hover (desktop) and focus (keyboard). If hovering over an element produces no visual change, users will not recognize it as interactive.
+6. **Are disabled states visually distinct from both active and static elements?** Disabled (muted, `not-allowed` cursor) must look different from active (full color, `pointer` cursor) AND from static text (body color, `default` cursor). If disabled and static look the same, users will not know a control exists.
+7. **Does the affordance work without color?** Test in grayscale. If the only signifier is color (blue text for links against black text), colorblind users will miss it. Pair color with another signifier (underline, icon, shape).
+
+## Source
+
+- Norman, D. — _The Design of Everyday Things_ (revised 2013), affordances, signifiers, constraints, and mappings
+- Norman, D. — "Affordances and Design" (jnd.org, 2008), clarification of affordance vs signifier
+- Nielsen Norman Group — "Flat Design: Its Origins, Its Problems, and Why Flat 2.0 Is Better for Users" (2015)
+- Apple Human Interface Guidelines — Touch targets and hit testing, https://developer.apple.com/design/human-interface-guidelines
+- Material Design — Interaction states, https://m3.material.io/foundations/interaction/states
+- Fitts, P.M. — "The Information Capacity of the Human Motor System" (1954), target acquisition law
+
+## 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/gemini-cli/design-affordances/skill.yaml

@@ -0,0 +1,35 @@
+name: design-affordances
+version: "1.0.0"
+description: Perceived actionability — signifiers, constraints, mappings (Don Norman), flat design's affordance problem, touch targets, hover states as affordance
+cognitive_mode: advisory-guide
+type: knowledge
+tier: 3
+triggers:
+  - manual
+platforms:
+  - claude-code
+  - gemini-cli
+  - cursor
+  - codex
+tools: []
+paths: []
+related_skills:
+  - design-feedback-patterns
+  - design-form-ux
+  - design-navigation-ux
+stack_signals: []
+keywords:
+  - affordances
+  - signifiers
+  - constraints
+  - mappings
+  - Don-Norman
+  - touch-targets
+  - hover
+  - actionability
+metadata:
+  author: community
+state:
+  persistent: false
+  files: []
+depends_on: []

package/dist/agents/skills/gemini-cli/design-alignment/SKILL.md

@@ -0,0 +1,148 @@
+# Alignment
+
+> Visual order through edge alignment, center alignment, optical alignment, and the invisible structure that consistent alignment creates across a page
+
+## When to Use
+
+- Laying out any page or component where multiple elements must relate to each other spatially
+- Evaluating why a layout feels "sloppy" or "off" despite having correct content and hierarchy
+- Deciding between left-aligned, center-aligned, or right-aligned text and elements
+- Aligning elements that are different shapes or sizes (icons with text, images with headings)
+- Building design systems where components must align consistently across contexts
+
+## Instructions
+
+1. **Prefer left-edge alignment as the default.** Left-edge alignment (in LTR languages) creates the strongest visual structure because it establishes a single vertical line that the eye can follow down the page:
+   - **Why it works:** The eye returns to the same x-coordinate after each line, creating a predictable rhythm. Nielsen Norman Group eye-tracking studies show that the left edge receives 69% of viewing time on text-heavy pages.
+   - **Stripe's entire dashboard** is left-edge aligned: navigation labels, section headings, table columns, form labels — all share a common left edge. This creates a strong vertical axis that organizes the entire interface.
+   - **Apple's developer documentation** uses left-edge alignment for all body text, code blocks, and headings. The left edge is the single most consistent visual element on the page.
+   - **Rule:** When in doubt, left-align. Center alignment and right alignment are special-purpose tools (see below).
+
+2. **Use center alignment only for short, isolated content.** Center alignment creates no strong edge — the left and right sides of each line are ragged. This makes it unsuitable for body text but effective for:
+   - **Hero headlines** — 1-3 lines, centered on the page. Vercel's homepage: "Develop. Preview. Ship." is centered, 3 words, maximum impact.
+   - **Card titles** — Short labels centered within a contained card. Stripe's pricing cards center plan names ("Starter," "Scale," "Enterprise").
+   - **Single-line captions** — Photo captions, attribution lines, copyright notices.
+   - **Never center:** Body paragraphs (more than 2 lines), form labels, navigation items, table headers, list items. These require the strong left edge for scanning.
+
+   **Specific threshold:** If the text exceeds 3 lines, switch from center to left alignment. Three centered lines are scannable; four begin to feel adrift.
+
+3. **Minimize the number of distinct alignment axes.** Every unique alignment point adds visual complexity. Fewer axes = cleaner design:
+   - **1-2 axes:** Clean, structured, professional. A single left edge with content at two indent levels (headings flush left, body indented 24px).
+   - **3-4 axes:** Acceptable for complex layouts with distinct zones (sidebar left edge + content left edge + right-aligned metadata).
+   - **5+ axes:** Almost certainly messy. Each axis is a line the eye must track. Audit by drawing vertical lines at every alignment point — if the lines look chaotic, reduce them.
+
+   **Stripe's pricing page** uses exactly 3 alignment axes: left edge of card content, center of card headers, and right edge of the price amount. Three axes for an entire complex page.
+
+4. **Understand optical vs. mathematical alignment.** Mathematical alignment (pixel-perfect coordinates) does not always look aligned to the human eye. Certain shapes require optical correction:
+   - **Triangles and pointed shapes:** A play button (triangle) mathematically centered in a circle looks shifted left because the triangle's visual mass is concentrated on the left side. Shift it 1-3px right. Spotify's play button is offset ~2px right from mathematical center.
+   - **Rounded shapes:** A circle mathematically aligned with a square's top edge looks too high because the curve starts tapering before the edge. Shift the circle down 1-2px. Material Design icon guidelines specify optical alignment rules for circular vs. rectangular icons.
+   - **Text baseline vs. bounding box:** Aligning text by its bounding box (the CSS box) rather than its baseline creates misalignment — letters with descenders (g, p, y) push the visual center up. Always align text to baseline, not to the container edge.
+   - **Overshooting:** Round letters (O, C, S) and pointed letters (A, V, W) must extend slightly beyond the baseline and cap-height to look the same size as flat letters (H, E, T). Professional typefaces build this in, but when setting custom sizes or creating logos, expect to adjust by 1-3%.
+
+5. **Use cross-element alignment to create cohesion.** Elements in different sections that share an alignment axis feel related, even across significant vertical distance:
+   - **Stripe's homepage:** The left edge of the hero headline aligns with the left edge of feature section headings 800px below. This invisible vertical line ties the entire page together.
+   - **Apple's comparison pages:** Spec values in different product columns are baseline-aligned across rows. The eye can scan horizontally and compare values because they sit on the same line.
+   - **Material Design's list items:** Leading icons (40px from left edge), primary text (72px from left edge), and trailing actions (16px from right edge) create three consistent rails that persist across every list in the app.
+
+   **Implementation:** In CSS, this means using consistent margin-left/padding-left values across components, not per-component values. A design token like `--content-inset: 72px` applied to headings, paragraphs, and list items creates automatic cross-element alignment.
+
+6. **Align related elements across cards and containers.** When displaying multiple cards, tiles, or panels side by side, their internal elements should align horizontally:
+   - **Stripe's pricing cards:** Feature names at the same y-coordinate across all three cards. Prices at the same y-coordinate. CTA buttons at the same y-coordinate. This creates a visual grid within the cards that facilitates comparison.
+   - **Airbnb listing cards:** Photo tops align, titles align, price lines align. Even though card content varies in length, the key comparison points (photo, title, price) are at consistent positions.
+   - **When content varies:** Use a fixed-height zone for variable content (description text) and pin the comparison elements (price, CTA) to absolute positions within the card. This sacrifices some vertical space for alignment clarity.
+
+## Details
+
+### Alignment Strength Hierarchy
+
+Not all alignment types create equal visual order:
+
+1. **Left edge (strongest in LTR)** — Creates a hard vertical line. Used for body text, navigation, form layouts. The eye returns here after every line.
+2. **Top edge** — Creates a horizontal line across elements. Critical for card grids, inline elements, and tab bars.
+3. **Baseline (text)** — Aligns the invisible line that letters sit on. Stronger than bounding-box alignment for mixed-size text.
+4. **Right edge** — Creates a vertical line on the right. Useful for numbers (right-align for easy comparison), metadata, timestamps.
+5. **Center (weakest)** — Creates no edge at all. The alignment point is invisible. Use sparingly and only for isolated, short content.
+
+### Alignment Audit Procedure
+
+To evaluate alignment in an existing design:
+
+1. **Draw vertical lines** at every left edge, right edge, and center point. In Figma, use layout grids or guide lines.
+2. **Count unique x-coordinates.** A well-aligned page has 2-4 distinct vertical axes. More than 6 indicates alignment chaos.
+3. **Check for near-misses.** Elements that are 2-4px off from a shared alignment axis look worse than elements that are intentionally offset by 24px+. Near-misses read as errors. Either snap to the axis or move far enough away to look intentional.
+4. **Verify text baseline alignment.** Mixed-size text on the same line (e.g., a 24px heading next to a 14px badge) should share a baseline, not a top edge.
+5. **Test cross-section alignment.** Scroll through the page — do section headings share a left edge? Do content blocks maintain consistent indentation?
+
+### Anti-Patterns
+
+1. **Centered everything.** Centering all text and elements because it "looks balanced." In practice, center alignment creates no strong edge, making the layout feel floating and unanchored. Center-aligned body text is particularly harmful — the ragged left edge forces the eye to search for the start of each line. Apple centers hero headlines (2-3 words) but left-aligns all body text, feature descriptions, and navigation. Follow the same rule.
+
+2. **Approximate alignment.** Elements that are 2-5px off from true alignment. This is worse than no alignment at all — the near-miss tells the viewer's subconscious that the designer was trying for alignment and failed. At 20px+ offset, it reads as an intentional design choice. At 3px offset, it reads as a bug. Snap to the grid or offset by a full grid unit (24px, 32px).
+
+3. **Mixing alignment systems.** A left-aligned heading, center-aligned body paragraph, and right-aligned caption on the same page with no structural justification. Each alignment system creates different visual lines — mixing them randomly creates visual noise. Stripe uses left-edge alignment for 95% of its interface and reserves center alignment exclusively for pricing plan names and hero text.
+
+4. **Bounding-box text alignment.** Aligning mixed-size text by the top of its CSS bounding box rather than by its baseline. A 32px heading and a 14px label aligned to their top edges will have misaligned baselines — the smaller text appears to float above the line. CSS `align-items: baseline` fixes this in flex containers. Verify visually with a horizontal guide line.
+
+### Real-World Examples
+
+**Apple Product Comparison Tables:**
+
+- Every spec row is baseline-aligned across product columns
+- Product names top-aligned at the same y-coordinate
+- Prices right-aligned within their column (right alignment makes numerical comparison easy)
+- The entire table uses exactly 4 alignment axes: row label left edge, and one center axis per product column
+- Result: complex data feels organized and scannable
+
+**Stripe's Pricing Page:**
+
+- 3 cards side-by-side with cross-card alignment:
+  - Plan name: centered within each card, y-aligned across cards
+  - Price: centered, y-aligned across cards, right-aligned for numerical comparison
+  - Feature list: left-aligned within each card, y-aligned per row across cards
+  - CTA button: centered within card, y-aligned across cards
+- Internal structure: all feature text shares a single left edge within each card (16px from card edge)
+- The alignment creates an implicit grid that makes plan comparison effortless
+
+**Material Design List Items (Spec):**
+
+- Leading element: 16px from left edge
+- Primary text: 56px from left edge (when leading is icon), 72px (when leading is avatar)
+- Supporting text: same left edge as primary text
+- Trailing element: 24px from right edge
+- These 3-4 alignment rails are consistent across every list type (single-line, two-line, three-line)
+- Result: lists feel uniform even when content varies dramatically
+
+**Vercel Dashboard Navigation:**
+
+- Sidebar items left-aligned at 16px from sidebar edge
+- Active item highlighted with a 2px left border — visually reinforcing the alignment axis
+- Nested items indented 16px (one grid unit), creating a secondary alignment axis
+- Content area headings align to the content left edge, which is independent of the sidebar — two clean alignment systems
+
+## Source
+
+- Robin Williams, "The Non-Designer's Design Book" — alignment as one of the four fundamental design principles
+- Josef Muller-Brockmann, "Grid Systems in Graphic Design" — systematic alignment through grid structures
+- Apple Human Interface Guidelines — alignment specifications for iOS and macOS layouts
+- Material Design 3 layout documentation — alignment rails and spacing specifications
+
+## Process
+
+1. **Choose** a primary alignment axis (left-edge for most layouts) and commit to it for all main content
+2. **Limit** total alignment axes to 2-4 per page; audit by drawing vertical lines at every unique x-coordinate
+3. **Verify** optical alignment for non-rectangular shapes and mixed-size text; adjust 1-3px as needed for visual correctness
+
+## Harness Integration
+
+This is a knowledge skill. When activated, its content is injected into the system prompt to guide element placement decisions. It does not execute code or modify files. Use alongside `design-grid-systems` for structural grid definition and `design-consistency` for system-wide alignment patterns.
+
+## Success Criteria
+
+- All body text and form elements share a common left-edge alignment axis
+- Center alignment is used only for isolated, short content (3 lines or fewer)
+- Total unique alignment axes per page is 4 or fewer
+- No near-miss alignments (elements within 1-4px of an axis are snapped to it)
+- Cross-card and cross-section elements share alignment axes for comparison
+- Optical corrections are applied to non-rectangular shapes and mixed-size text
+- Mixed-size text on the same line uses baseline alignment, not top-edge alignment
+- Related cards or panels have their key comparison elements (titles, prices, CTAs) y-aligned

package/dist/agents/skills/gemini-cli/design-alignment/skill.yaml

@@ -0,0 +1,33 @@
+name: design-alignment
+version: "1.0.0"
+description: Visual order — edge, center, optical vs. mathematical alignment, alignment as invisible structure
+cognitive_mode: advisory-guide
+type: knowledge
+tier: 3
+triggers:
+  - manual
+platforms:
+  - claude-code
+  - gemini-cli
+  - cursor
+  - codex
+tools: []
+paths: []
+related_skills:
+  - design-grid-systems
+  - design-consistency
+stack_signals: []
+keywords:
+  - alignment
+  - edge alignment
+  - center alignment
+  - optical alignment
+  - mathematical alignment
+  - visual order
+  - invisible structure
+metadata:
+  author: community
+state:
+  persistent: false
+  files: []
+depends_on: []

package/dist/agents/skills/gemini-cli/design-apple-hig/SKILL.md

@@ -0,0 +1,237 @@
+# Apple Human Interface Guidelines
+
+> Apple's design philosophy covering clarity/deference/depth, vibrancy and material effects, SF Symbols integration, semantic color system, safe area management, and platform-specific navigation patterns across iOS, iPadOS, macOS, watchOS, and visionOS.
+
+## When to Use
+
+- Building native Apple platform apps where adherence to HIG conventions affects App Store review outcomes
+- Implementing a SwiftUI or UIKit component library that must integrate with system-provided materials, vibrancy, and semantic colors
+- Designing navigation architecture for an app targeting multiple Apple platforms (iPhone, iPad, Mac Catalyst, visionOS)
+- Handling safe areas for devices with notches, Dynamic Island, home indicators, and rounded display corners
+- Choosing SF Symbols and configuring their rendering modes, weight matching, and variable color behavior
+
+## Instructions
+
+Apple's HIG is organized around three foundational principles: **clarity** (text is legible at every size, icons are precise, adornments are subtle), **deference** (content is the focus, UI chrome recedes through materials and vibrancy), and **depth** (visual layers and transitions convey hierarchy and position). Unlike Material Design's generative token system, Apple's design language relies on semantic system resources that adapt automatically to appearance (light/dark), accessibility settings (increased contrast, reduced transparency), and device context.
+
+**Key architectural rule:** Never hardcode colors, font sizes, or layout constants. Apple provides semantic resources (`UIColor.systemBackground`, `Font.body`, `safeAreaInsets`) that automatically adapt. Hardcoding `#FFFFFF` for a background means your app breaks in Dark Mode, ignores Increased Contrast, and fails to adapt to platform-specific surface tints.
+
+**Platform divergence is intentional.** A `NavigationSplitView` on iPhone shows a single column with push navigation. On iPad, it shows two or three columns. On Mac, it adds a toolbar. The same semantic component renders differently per platform. Designing for Apple means designing for adaptive presentation, not fixed layouts.
+
+## Details
+
+### Clarity, Deference, and Depth
+
+**Clarity** dictates that every element serves a communicative purpose. Apply the San Francisco (SF Pro) system font at Dynamic Type sizes, not arbitrary point values. SF Pro's optical sizes adjust weight and spacing automatically: at 20pt, SF Pro uses wider letter-spacing than at 11pt, ensuring legibility without manual kerning.
+
+**Dynamic Type scale (default sizes, not accessibility sizes):**
+
+```
+.largeTitle     34pt   weight: regular
+.title1         28pt   weight: regular
+.title2         22pt   weight: regular
+.title3         20pt   weight: regular
+.headline       17pt   weight: semibold
+.body           17pt   weight: regular
+.callout        16pt   weight: regular
+.subheadline    15pt   weight: regular
+.footnote       13pt   weight: regular
+.caption1       12pt   weight: regular
+.caption2       11pt   weight: regular
+```
+
+When the user increases Dynamic Type to AX5 (the largest accessibility size), `.body` scales from 17pt to 53pt. Your layout must accommodate this without truncation. Use `ScrollView` instead of fixed-height containers for text regions.
+
+**Deference** means the UI fades behind content. Apple achieves this through materials -- translucent layers that blur and tint the content behind them. A navigation bar in iOS uses `.regularMaterial` (or `.bar` in UIKit), not an opaque color. The material samples the colors beneath it, creating a contextual background that shifts as the user scrolls.
+
+**Depth** uses layering with distinct z-planes. iOS defines three depth planes: the base content, a raised overlay (sheets, popovers), and an alert level (alerts, action sheets). Each plane has its own material weight: base uses `.systemBackground`, overlays use `.systemGroupedBackground` or `.secondarySystemBackground`, and alerts use `.thickMaterial` for maximum separation.
+
+### Vibrancy and Materials
+
+Materials are translucent layers defined by their blur radius, saturation, and tint. Apple provides five material weights:
+
+```
+.ultraThinMaterial    Minimal blur, maximum transparency    (widgets)
+.thinMaterial         Light blur, high transparency          (inactive overlays)
+.regularMaterial      Balanced blur and tint                 (navigation bars, tab bars)
+.thickMaterial        Heavy blur, reduced transparency       (alerts, action sheets)
+.ultraThickMaterial   Maximum blur, minimal transparency     (full-screen overlays)
+```
+
+**Vibrancy** is a label rendering mode that makes text and icons vibrant against material backgrounds. It amplifies the luminance of content placed on translucent materials so text remains legible regardless of what is behind the blur.
+
+Three vibrancy levels exist:
+
+```
+.primary              Full vibrancy    (titles, primary labels)
+.secondary            Muted vibrancy   (subtitles, secondary text)
+.tertiary             Faint vibrancy   (disabled text, placeholders)
+```
+
+**Concrete implementation in SwiftUI:**
+
+```swift
+ZStack {
+    Image("background")
+        .resizable()
+    VStack {
+        Text("Title")
+            .foregroundStyle(.primary)    // vibrant white/black
+        Text("Subtitle")
+            .foregroundStyle(.secondary)  // muted vibrancy
+    }
+    .padding()
+    .background(.regularMaterial)
+}
+```
+
+**Fallback in Increased Contrast mode:** When the user enables "Increase Contrast" in Accessibility settings, materials become opaque. `.regularMaterial` renders as solid `systemBackground` with no blur. Your layout must not depend on seeing content through the material -- all essential information must be on the foreground layer.
+
+### SF Symbols
+
+SF Symbols is a library of 5,000+ vector icons designed to align with SF Pro text. Every symbol has 9 weights (ultralight through black) and 3 scales (small, medium, large) that automatically match the surrounding text.
+
+**Rendering modes:**
+
+```
+.monochrome        Single color, inherits foreground       (toolbar icons)
+.hierarchical      Single tint, automatic opacity layers   (multi-part icons)
+.palette           2-3 explicit colors you assign          (tab bar, badges)
+.multicolor        Fixed colors defined by Apple           (weather, file types)
+```
+
+**Weight matching rule:** An SF Symbol adjacent to `.body` text (regular weight) renders at regular weight. Adjacent to `.headline` (semibold) it renders semibold. This matching is automatic in SwiftUI when using `Label("Text", systemImage: "icon.name")`. Manual `Image(systemName:)` requires explicit `.fontWeight()` to match.
+
+**Variable color:** Some symbols support continuous fill levels (0.0 to 1.0). `speaker.wave.3` at value 0.33 fills one wave, at 0.66 fills two, at 1.0 fills all three. This enables smooth animations for volume, signal strength, and progress.
+
+```swift
+Image(systemName: "wifi", variableValue: signalStrength)
+    .symbolRenderingMode(.hierarchical)
+    .foregroundStyle(.blue)
+```
+
+**Custom symbol creation:** Export from SF Symbols app as SVG template. The template defines 3 layers (background, base, accent) and 9 weight variants. Each weight variant must be a distinct path -- interpolation between weights is not supported for custom symbols.
+
+### Semantic Colors
+
+Apple defines colors by purpose, not value. The exact hex value changes across platform, appearance, and accessibility setting.
+
+**System background colors (light / dark / increased contrast dark):**
+
+```
+.systemBackground              #FFFFFF / #000000 / #000000
+.secondarySystemBackground     #F2F2F7 / #1C1C1E / #2C2C2E
+.tertiarySystemBackground      #FFFFFF / #2C2C2E / #3A3A3C
+```
+
+**System content colors:**
+
+```
+.label                         #000000 / #FFFFFF
+.secondaryLabel                #3C3C43 at 60% / #EBEBF5 at 60%
+.tertiaryLabel                 #3C3C43 at 30% / #EBEBF5 at 30%
+.quaternaryLabel               #3C3C43 at 18% / #EBEBF5 at 18%
+```
+
+**Tint colors** are the seven system-provided accent colors:
+
+```
+.systemRed       #FF3B30 / #FF453A
+.systemOrange    #FF9500 / #FF9F0A
+.systemYellow    #FFCC00 / #FFD60A
+.systemGreen     #34C759 / #30D158
+.systemBlue      #007AFF / #0A84FF
+.systemIndigo    #5856D6 / #5E5CE6
+.systemPurple    #AF52DE / #BF5AF2
+```
+
+Dark mode tint variants are slightly brighter (higher luminance) than their light mode equivalents. `systemBlue` shifts from `#007AFF` (L*=48) to `#0A84FF` (L*=53) to maintain the same perceived contrast against a dark background.
+
+**Platform differences:** macOS `systemBackground` resolves to `#ECECEC` (a warm gray), not `#FFFFFF`. macOS windows have distinct content backgrounds (`windowBackgroundColor`) that differ from iOS backgrounds. Never assume cross-platform color parity.
+
+### Safe Areas
+
+Safe areas define the region of the screen guaranteed to be unobstructed by hardware (notch, Dynamic Island, rounded corners, home indicator) and system UI (status bar, navigation bar, tab bar).
+
+**iPhone 15 Pro safe area insets:**
+
+```
+Top:      59pt   (status bar + Dynamic Island)
+Bottom:   34pt   (home indicator)
+Leading:  0pt
+Trailing: 0pt
+```
+
+**iPad Pro 12.9" safe area insets (no hardware obstructions):**
+
+```
+Top:      24pt   (status bar only)
+Bottom:   20pt   (home indicator)
+Leading:  0pt
+Trailing: 0pt
+```
+
+**Keyboard safe area:** When the keyboard appears, `safeAreaInset(edge: .bottom)` expands to include the keyboard height (~336pt on iPhone). Use `.safeAreaInset(edge: .bottom)` in SwiftUI or `keyboardLayoutGuide` in UIKit to push content above the keyboard.
+
+**When to ignore safe areas:** Full-bleed images and backgrounds should extend into the unsafe region using `.ignoresSafeArea()`. Content (text, buttons, interactive elements) must never extend into unsafe areas. A common pattern: background ignores safe area, content respects it.
+
+```swift
+ZStack {
+    Color.blue.ignoresSafeArea()        // extends behind notch
+    VStack {
+        Text("Content stays safe")       // respects safe area
+    }
+}
+```
+
+### Platform-Specific Navigation
+
+**iPhone:** `NavigationStack` with push/pop. Tab bar at bottom (maximum 5 tabs). No visible back button label on small screens -- the chevron and swipe-back gesture suffice.
+
+**iPad:** `NavigationSplitView` with 2 or 3 columns. Sidebar collapses in compact width. Tab bar transforms into a sidebar in iPadOS 18+. Popovers replace action sheets.
+
+**Mac (Catalyst / native):** `NavigationSplitView` with toolbar. Menu bar integration. Window resizing. `Settings` scene replaces the iOS settings bundle. Hover states on all interactive elements -- mandatory because Mac has a cursor.
+
+**visionOS:** Ornaments replace toolbars. Content floats in a window at `z: 0`. Modals push to `z: 50pt` depth. Navigation uses tab bars rendered as ornaments below the window. Eye tracking drives hover states -- interactive targets minimum 60pt diameter (larger than iOS 44pt) because eye fixation is less precise than finger touch.
+
+### Anti-Patterns
+
+**Hardcoding hex colors instead of using semantic system colors.** Setting `background: #F2F2F7` works in light mode but becomes invisible in dark mode. Use `.secondarySystemBackground` which resolves to `#F2F2F7` in light and `#1C1C1E` in dark. This also handles Increased Contrast mode automatically. Hardcoded colors fail four adaptations: light/dark, standard/increased contrast.
+
+**Using fixed font sizes instead of Dynamic Type text styles.** Setting `font-size: 17px` ignores the user's preferred content size. When a visually impaired user sets AX3, your text stays at 17pt while system apps scale to 40pt. Use `.font(.body)` which maps to the user's chosen size. Fixed font sizes can also cause App Store review rejection under accessibility guidelines.
+
+**Placing interactive content in unsafe areas.** A "Skip" button at the absolute top of the screen is obscured by the Dynamic Island on iPhone 15 Pro. A floating action button at the absolute bottom overlaps the home indicator. All interactive elements must be within `safeAreaLayoutGuide`. Background decorations may extend outside; buttons, text fields, and links must not.
+
+**Using opaque navigation bars on scrollable content.** iOS navigation bars use `.regularMaterial` by default -- translucent with blur. Overriding with an opaque background color breaks the deference principle and creates a harsh visual boundary. Users expect to see content scroll behind the bar. The exception is when the bar contains complex content (search fields, segmented controls) where blur would reduce legibility.
+
+**Ignoring platform-specific navigation conventions.** Showing a bottom tab bar on macOS (where the convention is a sidebar or toolbar), or using a hamburger menu on iOS (where tab bars are standard), violates user expectations built from using the platform. Each Apple platform has distinct navigation paradigms. A single navigation approach forced across all platforms signals non-native design.
+
+### Real-World Examples
+
+**Apple Weather** exemplifies deference: the background is a full-screen animated weather condition, and all UI elements sit on materials of varying thickness. The hourly forecast uses `.thinMaterial`, the daily forecast uses `.regularMaterial`, and alert banners use `.thickMaterial`. Each layer's legibility is maintained through vibrancy-rendered text.
+
+**Apple Maps** demonstrates safe area handling across every iPhone variant. The floating search card respects bottom safe area insets, expanding upward. On iPad, the same search card becomes a sidebar panel. On Mac, it transforms into a toolbar search field. One semantic component, three platform presentations.
+
+**Fantastical** uses SF Symbols with variable color for event indicators: a circle symbol at `variableValue: 0.5` indicates a half-day event, `1.0` a full-day event. Their calendar icons match the surrounding text weight automatically, scaling from ultralight in the month header to regular in the day cells.
+
+**Things 3** demonstrates the depth principle: the task list sits at base depth, a new-task sheet slides up at overlay depth with `.regularMaterial`, and a delete confirmation alert appears at alert depth with `.thickMaterial`. Each depth transition uses a spring animation (`response: 0.35, dampingFraction: 0.86`) matching the system default.
+
+## Source
+
+Apple Human Interface Guidelines (developer.apple.com/design/human-interface-guidelines, 2024). Apple Developer Documentation for UIKit and SwiftUI. WWDC sessions: "What's new in SF Symbols" (2023), "Design for spatial computing" (2023), "Get started with Dynamic Type" (2022). Apple Design Resources Figma/Sketch libraries.
+
+## 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.