@harness-engineering/cli 1.23.2 → 1.24.0

package/dist/agents/skills/claude-code/css-tailwind-pattern/skill.yaml

@@ -0,0 +1,40 @@
+name: css-tailwind-pattern
+version: '1.0.0'
+description: Apply Tailwind CSS utility-first patterns for consistent, maintainable styling
+cognitive_mode: advisory-guide
+type: knowledge
+tier: 3
+triggers:
+  - manual
+platforms:
+  - claude-code
+  - gemini-cli
+  - cursor
+  - codex
+tools: []
+paths:
+  - 'tailwind.config.*'
+  - '**/*.css'
+  - '**/*.tsx'
+  - '**/*.jsx'
+related_skills:
+  - css-component-variants
+  - css-responsive-design
+  - css-dark-mode
+stack_signals:
+  - tailwind
+  - css
+  - typescript
+keywords:
+  - tailwind
+  - utility-first
+  - utility-classes
+  - styling
+  - className
+metadata:
+  author: community
+  upstream: 'tailwindcss/docs'
+state:
+  persistent: false
+  files: []
+depends_on: []

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