@harness-engineering/cli 1.23.2 → 1.24.0

package/dist/agents/skills/claude-code/design-type-scale/skill.yaml

@@ -0,0 +1,34 @@
+name: design-type-scale
+version: "1.0.0"
+description: Mathematical type scales — modular, major third, perfect fourth, golden ratio, custom scales
+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-visual-hierarchy
+  - design-responsive-type
+stack_signals: []
+keywords:
+  - type scale
+  - modular scale
+  - major third
+  - perfect fourth
+  - golden ratio
+  - font size
+  - scale ratio
+metadata:
+  author: community
+state:
+  persistent: false
+  files: []
+depends_on: []

package/dist/agents/skills/claude-code/design-typographic-hierarchy/SKILL.md

@@ -0,0 +1,187 @@
+# Typographic Hierarchy
+
+> Establishing reading order through type — size, weight, color, spacing, case, and position as hierarchy signals
+
+## When to Use
+
+- Designing a page layout where users must scan and find information quickly
+- Building a component library with heading, body, caption, and label styles
+- Auditing a page that "feels flat" or where everything competes for attention equally
+- Creating dashboard or data-heavy interfaces where information priority is critical
+- Establishing the relationship between HTML heading levels and visual heading styles
+
+## Instructions
+
+1. **Use the 6 hierarchy levers in order of strength.** Each lever creates a different degree of visual separation. Stronger levers create more dramatic hierarchy:
+
+   | Lever        | Strength   | Mechanism                                                 | Example                           |
+   | ------------ | ---------- | --------------------------------------------------------- | --------------------------------- |
+   | **Size**     | Strongest  | Larger text draws the eye first                           | 48px heading vs 16px body         |
+   | **Weight**   | Strong     | Bolder text creates density that attracts attention       | 700 weight heading vs 400 body    |
+   | **Color**    | Strong     | High-contrast text stands out from muted surroundings     | #000000 heading vs #6b7280 body   |
+   | **Spacing**  | Moderate   | Whitespace above an element signals a new section         | 48px margin-top vs 16px           |
+   | **Case**     | Moderate   | ALL CAPS or small-caps differentiates without size change | SECTION LABEL vs Body text        |
+   | **Position** | Contextual | Top-left reads first in LTR; above reads before below     | Page title at top of content area |
+
+   **Decision procedure**: Start with size as the primary differentiator. Add weight if size alone is insufficient. Use color for tertiary distinctions. Reserve case and spacing for labels and section breaks.
+
+2. **Establish exactly 3-4 active hierarchy levels per page.** More than 4 levels force the reader to constantly recalibrate importance. Fewer than 3 levels make the page feel flat.
+
+   **Standard 4-level system:**
+   - **Level 1 — Page title**: largest size, often lightest weight (e.g., Stripe's 300-weight headlines)
+   - **Level 2 — Section heading**: medium-large size, medium weight
+   - **Level 3 — Subsection/label**: body size or slightly larger, bold weight or distinct color
+   - **Level 4 — Body text**: base size, regular weight, standard color
+
+   **Compact 3-level system (for dashboards):**
+   - **Level 1 — Section header**: moderately larger, bold
+   - **Level 2 — Body/data**: base size, regular weight
+   - **Level 3 — Caption/meta**: smaller size or muted color
+
+3. **Apply the squint test.** Zoom your design to 25% or blur your vision. You should still be able to identify:
+   - Which element is the page title
+   - Where sections begin and end
+   - What is primary content vs secondary content
+     If everything blurs into a uniform gray mass, your hierarchy is too flat. If multiple elements compete at the same visual weight, you have hierarchy collision.
+
+4. **Create hierarchy with a single font family.** You do not need multiple typefaces to establish hierarchy. A single variable font with weight and size variation is sufficient:
+
+   ```
+   Page title:     32px, weight 300, color #1a1a1a, letter-spacing -0.5px
+   Section head:   24px, weight 600, color #1a1a1a
+   Subsection:     16px, weight 600, color #374151
+   Body:           16px, weight 400, color #374151
+   Caption:        14px, weight 400, color #6b7280
+   ```
+
+   This 5-style system uses 3 levers (size, weight, color) to create 5 distinguishable levels from one font family.
+
+5. **Separate semantic heading levels from visual hierarchy.** HTML heading levels (h1-h6) represent document structure. Visual hierarchy levels represent visual prominence. These can diverge:
+   - A sidebar `h2` might be styled at visual level 3 (smaller, since sidebars are secondary)
+   - A hero `h1` might be styled at display size (larger than any standard heading level)
+   - Use CSS classes for visual treatment and HTML elements for semantics: `<h2 class="text-lg font-medium">` not `<h4>` to make it smaller
+
+6. **Use whitespace to reinforce hierarchy.** The space above a heading signals its importance:
+   - **Page title**: 48-64px space above (or at page top)
+   - **Section heading**: 32-48px space above, 16-24px space below
+   - **Subsection heading**: 24-32px space above, 8-16px space below
+   - **Body paragraph**: 16px space between paragraphs
+   - **Rule**: space above a heading should always be larger than space below it — this binds the heading to the content it introduces
+
+## Details
+
+### How Leading Design Systems Implement Hierarchy
+
+**Vercel Documentation Hierarchy**
+Vercel achieves crystal-clear hierarchy using only the Geist font family:
+
+- **Level 1 — Page title**: 36px, weight 700, color #000, letter-spacing -0.04em
+- **Level 2 — Section heading (h2)**: 24px, weight 600, color #000, letter-spacing -0.02em
+- **Level 3 — Subsection heading (h3)**: 20px, weight 600, color #000
+- **Level 4 — Body text**: 16px, weight 400, color #444
+- **Level 5 — Caption/meta**: 14px, weight 400, color #666
+- The progression: each level differs from the next by at least 2 properties (size + weight, or size + color)
+
+**Stripe API Documentation Hierarchy**
+Stripe's docs demonstrate role-based hierarchy separation:
+
+- **Page title**: 28px, sohne weight 300, color #1a1a1a — light weight signals confidence
+- **Section heading**: 20px, sohne weight 400, color #1a1a1a — heavier than the title but smaller
+- **Parameter name**: 14px, Source Code Pro weight 600, color #3a3f47 — monospace distinguishes code from prose
+- **Description**: 14px, sohne weight 400, color #697386 — muted color for supporting text
+- **Key insight**: Stripe inverts the typical weight convention — lighter weight for primary headings, heavier for secondary. This works because size does the heavy lifting for hierarchy, freeing weight for tone.
+
+**Apple Marketing Pages**
+Apple's product pages demonstrate extreme hierarchy for scanning:
+
+- **Hero headline**: 96px, SF Pro Display weight 700, color #1d1d1f, letter-spacing -0.015em
+- **Subheadline**: 28px, SF Pro Display weight 600, color #1d1d1f
+- **Body**: 21px, SF Pro Text weight 400, color #1d1d1f, line-height 1.47
+- **Caption**: 17px, SF Pro Text weight 400, color #6e6e73
+- Three tiers with dramatic size ratios: 96 -> 28 -> 21. The hero is 4.6x the body size. Each tier is unmistakable at any viewing distance.
+
+### Weight as a Hierarchy Tool
+
+Weight is the second-strongest hierarchy lever, but it has nuances:
+
+**Conventional approach (bold = important):**
+
+- Headings at 600-700, body at 400. Universal, expected, safe.
+- Used by: Material Design, Tailwind defaults, most documentation sites.
+
+**Inverted approach (light = primary):**
+
+- Primary headings at 300 (thin/light), body at 400 (regular). Counterintuitive but effective — the light weight at large size reads as confident and premium.
+- Used by: Stripe (weight 300 for display headlines), Apple (weight 200-300 for marketing heroes).
+- **Prerequisite**: only works when size difference is dramatic (32px+ headlines). At small sizes, light weight reduces readability.
+
+**Weight contrast minimum:** For two levels to be weight-distinguishable, they need at least a 200-unit difference on a variable font weight axis (e.g., 400 vs 600, or 300 vs 500). A 100-unit difference (400 vs 500) is often imperceptible at body sizes.
+
+### Hierarchy in Data-Dense Interfaces
+
+Dashboards and admin panels present a unique hierarchy challenge: many content blocks compete simultaneously. Solutions:
+
+- **Card-level hierarchy**: each card has its own internal 2-level hierarchy (title + data), and the card container itself creates section separation through borders and spacing
+- **Metric emphasis**: key numbers displayed at 32-48px while labels sit at 12-14px — a 3:1 size ratio within a single component
+- **Muted chrome**: navigation, breadcrumbs, and metadata at low-contrast gray (#9ca3af on #ffffff = 2.7:1), reserving high contrast for primary data
+- **Example**: Stripe Dashboard uses #697386 (muted gray) for labels and #1a1a1a for values — a two-tier color system that separates "what this is" from "what it says"
+
+### Anti-Patterns
+
+1. **Everything is bold.** When headings, labels, navigation items, buttons, and emphasized text are all font-weight 600-700, the weight lever stops functioning. Bold becomes the default, not a signal. Audit your styles: if more than 30% of visible text is bold, you have lost weight as a hierarchy tool. Reserve bold for headings and primary actions only.
+
+2. **Too many hierarchy levels.** A page with 6+ visually distinct text styles (display, h1, h2, h3, h4, body, small, caption, overline, label) forces the reader to decode a complex visual language. Collapse to 3-4 levels. If you need 6 heading levels in HTML for document structure, you do not need 6 visual styles — multiple heading levels can share the same visual treatment.
+
+3. **Size as the only differentiator.** A hierarchy built exclusively on size (48, 36, 28, 24, 20, 16, 14) without weight or color variation creates a monotonous "zoom effect" where text just gets smaller. Each level should differ by at least 2 properties. A 24px regular gray heading is more distinct from 16px regular gray body than a 24px regular black heading is from 16px regular black body.
+
+4. **Heading levels that match visual hierarchy exactly.** Using `h1` for the biggest text, `h2` for the next biggest, all the way down is correct by coincidence, not by principle. A modal dialog's title might be an `h2` visually styled at 20px (smaller than the page h1 at 32px). Decouple semantic levels from visual levels using CSS classes.
+
+### Real-World Examples
+
+**Redesigning a Flat Dashboard**
+Problem: A SaaS dashboard has all text at 14px, weight 400, color #333. Users report "I cannot find anything."
+Solution applied:
+
+- Page title: 24px, weight 600, color #111827 (level 1)
+- Card titles: 16px, weight 600, color #111827 (level 2)
+- Data values: 14px, weight 400, color #111827 (level 3)
+- Labels and meta: 12px, weight 400, color #6b7280 (level 4)
+- Result: 4 levels using 3 sizes, 2 weights, 2 colors. Users can now scan the page and identify sections in under 2 seconds.
+
+**Creating a Blog Typography System**
+Goal: Clear hierarchy for long-form content with minimal styles.
+System:
+
+- Article title: 40px, weight 800, color #0f172a, letter-spacing -0.025em
+- Section heading (h2): 28px, weight 700, color #0f172a
+- Subsection (h3): 22px, weight 600, color #1e293b
+- Body: 18px, weight 400, color #334155, line-height 1.75
+- Image caption: 14px, weight 400, color #64748b, italic
+- Pull quote: 24px, weight 400, color #0f172a, italic, border-left 4px #e2e8f0
+- Six roles, 4 visual levels (title and h2 are distinct; h3 and body share size tier but differ in weight).
+
+## Source
+
+- Lupton, Ellen. _Thinking with Type_, 2nd revised edition — hierarchy and contrast
+- Butterick, Matthew. _Butterick's Practical Typography_ — headings chapter
+- Material Design 3 Typography — https://m3.material.io/styles/typography
+- Nielsen Norman Group — "F-Shaped Pattern for Reading Web Content"
+
+## Process
+
+1. **Evaluate** — Identify how many hierarchy levels the page requires. Audit existing text styles for redundancy and collision. Apply the squint test to check visual separation.
+2. **Apply** — Define 3-4 hierarchy levels using size, weight, and color as primary levers. Assign each text role to a level. Use whitespace to reinforce level transitions.
+3. **Verify** — Confirm each level is visually distinguishable at 25% zoom, no more than 4 active levels compete on any single viewport, and semantic heading levels are correctly separated from visual hierarchy.
+
+## Harness Integration
+
+This is a knowledge skill. When activated, it provides typographic hierarchy principles to guide heading styles, text tokens, and content layout decisions. Use these principles when defining heading component props, text utility classes, or design token hierarchies. Cross-reference with `design-type-scale` for size relationships and `design-visual-hierarchy` for non-typographic hierarchy signals.
+
+## Success Criteria
+
+- The page has exactly 3-4 active visual hierarchy levels
+- Each level differs from adjacent levels by at least 2 properties (size, weight, color)
+- The squint test at 25% zoom reveals clear hierarchy structure
+- Semantic HTML heading levels are independent of visual heading styles
+- No more than 30% of visible text uses bold weight
+- Whitespace above headings is larger than whitespace below them

package/dist/agents/skills/claude-code/design-typographic-hierarchy/skill.yaml

@@ -0,0 +1,34 @@
+name: design-typographic-hierarchy
+version: "1.0.0"
+description: Reading order through type — size, weight, color, spacing, case, and position as hierarchy signals
+cognitive_mode: advisory-guide
+type: knowledge
+tier: 3
+triggers:
+  - manual
+platforms:
+  - claude-code
+  - gemini-cli
+  - cursor
+  - codex
+tools: []
+paths: []
+related_skills:
+  - design-type-scale
+  - design-visual-hierarchy
+  - design-whitespace
+stack_signals: []
+keywords:
+  - typographic hierarchy
+  - reading order
+  - heading levels
+  - weight
+  - emphasis
+  - visual priority
+  - scanning
+metadata:
+  author: community
+state:
+  persistent: false
+  files: []
+depends_on: []

package/dist/agents/skills/claude-code/design-typography-fundamentals/SKILL.md

@@ -0,0 +1,158 @@
+# Typography Fundamentals
+
+> Anatomy of type — x-height, ascenders, descenders, counters, serifs, stroke contrast, optical sizing, and how anatomy affects readability
+
+## When to Use
+
+- Selecting a typeface for a new project or design system
+- Evaluating why a font "feels wrong" at a given size or context
+- Comparing fonts that appear similar but behave differently in layout
+- Debugging rendering issues caused by metric differences between typefaces
+- Deciding between optical sizes (text vs display cuts) of the same family
+
+## Instructions
+
+1. **Learn the vertical metrics.** Every Latin typeface is defined by a vertical scaffold:
+   - **Baseline** — the invisible line letters sit on; descenders drop below it
+   - **X-height** — the height of lowercase `x`; the single most important metric for perceived size and readability
+   - **Cap height** — the top of uppercase letters like `H`; typically 68-72% of the em square
+   - **Ascender line** — the top of tall lowercase letters (`b`, `d`, `h`, `l`); usually exceeds cap height by 2-5%
+   - **Descender line** — the bottom of `g`, `p`, `q`, `y`; typically 20-30% of the em square below baseline
+
+2. **Evaluate x-height ratio before selecting any font.** The x-height-to-cap-height ratio determines perceived size at a given pixel value. Higher x-height = more readable at small sizes, less elegant at large sizes.
+   - **Inter**: 0.756 ratio — designed for screen UI, maximizes legibility at 12-16px
+   - **Helvetica Neue**: 0.714 ratio — slightly more traditional proportions
+   - **Garamond**: 0.630 ratio — smaller x-height, elegant but requires larger sizes for body text
+   - **Georgia**: 0.698 ratio — tall x-height for a serif, deliberately designed for screen reading
+   - **Decision rule**: For UI text at 14-16px, choose fonts with x-height ratio >= 0.70. For editorial/display at 24px+, lower ratios (0.60-0.70) create more refined proportions.
+
+3. **Understand counter and aperture openings.** Counters are the enclosed or partially enclosed spaces within letters (the hole in `o`, `e`, `d`). Apertures are the openings in letters like `c`, `e`, `s`.
+   - **Open apertures** (Inter, SF Pro, Fira Sans) improve legibility at small sizes because letterforms remain distinguishable
+   - **Closed apertures** (Helvetica, Futura) create tighter, more geometric forms but reduce legibility below 14px
+   - **Decision rule**: If body text will be set below 16px on screen, prefer fonts with open apertures
+
+4. **Classify typefaces by their structural attributes, not marketing labels.**
+   - **Serif** — horizontal or angled strokes at letter terminals; subdivided into old-style (Garamond), transitional (Baskerville), modern/didone (Bodoni), slab (Rockwell)
+   - **Sans-serif** — no terminal strokes; subdivided into grotesque (Helvetica), neo-grotesque (Inter), geometric (Futura), humanist (Gill Sans, Fira Sans)
+   - **Monospace** — equal character widths; critical for code (SF Mono, JetBrains Mono, Source Code Pro)
+   - **Display** — optimized for large sizes; thinner strokes, tighter spacing, higher contrast; never use at body sizes
+
+5. **Assess stroke contrast for size-appropriate selection.** Stroke contrast is the ratio between the thickest and thinnest strokes in a letterform.
+   - **High contrast** (Bodoni, Didot): thick/thin ratio of 5:1 or more. Elegant at 36px+, strokes disappear at 12px. Use only for display.
+   - **Medium contrast** (Georgia, Baskerville): ratio of ~2:1 to 3:1. Functional at body sizes 16px+.
+   - **Low contrast** (Inter, Roboto, SF Pro): ratio near 1:1. Optimized for screen rendering at all sizes.
+   - **Decision rule**: Body text on screen requires low to medium contrast. High contrast is display-only.
+
+6. **Use optical sizing when available.** The same letterforms need different treatments at different sizes — this is not merely scaling.
+   - At **text sizes** (9-14px): thicker strokes, wider spacing, larger x-height, open counters
+   - At **display sizes** (24px+): thinner strokes, tighter spacing, more contrast, refined details
+   - **Apple SF Pro** implements this with distinct text and display optical sizes; the cut switches at 20pt
+   - **Inter** uses automatic optical sizing via OpenType `opsz` axis (available in variable font)
+   - **Roboto Flex** provides continuous optical sizing from 8pt to 144pt via its variable font axis
+   - If your font lacks optical sizing, manually adjust letter-spacing: add +0.02em at 12px, remove -0.01em at 48px
+
+## Details
+
+### How Anatomy Affects UI Decisions
+
+Font metrics directly impact layout calculations. Two fonts set at 16px can produce visually different results:
+
+- **Inter at 16px**: x-height of 11.3px (0.756 \* 14.94 UPM-scaled cap height). Ascenders reach ~17.2px. Descenders reach ~-4.3px. Total vertical extent: ~21.5px.
+- **Garamond at 16px**: x-height of 8.6px (0.630 \* 13.65 UPM-scaled cap height). Text appears significantly smaller despite identical font-size value.
+
+This is why switching fonts without adjusting sizes produces layouts that "break" — the visual weight shifts even though the CSS value has not changed. When replacing one typeface with another, always compare x-height ratios and adjust font-size proportionally: `new_size = old_size * (old_x_ratio / new_x_ratio)`.
+
+### Metrics That Matter for Design Systems
+
+When building a design system, document these metrics for your chosen typeface:
+
+| Metric                    | What It Controls               | Typical Range    |
+| ------------------------- | ------------------------------ | ---------------- |
+| x-height ratio            | Perceived size, readability    | 0.63-0.76        |
+| Cap-to-ascender overshoot | Vertical rhythm predictability | 2-8% above cap   |
+| Descender depth           | Line-height requirements       | 15-30% of em     |
+| Average character width   | Characters per line (measure)  | 45-65% of em     |
+| Tabular figure width      | Data table alignment           | Fixed across 0-9 |
+
+### Stripe's Typography Anatomy in Practice
+
+Stripe uses `sohne-var` (a variable font by Klim Type Foundry) with these anatomical characteristics:
+
+- **Weight 300** as the signature headline weight — lighter than convention, projecting confidence and sophistication
+- **Moderate x-height** (~0.71 ratio) balancing elegance with screen readability
+- **OpenType feature `ss01`** activated across all text for alternate character forms
+- **Negative letter-spacing** at display sizes: -1.4px at 56px, progressively relaxing to 0 at body size — compensating for the optical illusion that large text appears more widely spaced
+- **Two-weight simplicity**: 300 (body/headings) and 400 (UI elements/buttons), creating hierarchy through minimal means
+
+### Apple's Optical Sizing System
+
+Apple SF Pro demonstrates best-in-class optical sizing:
+
+- **SF Pro Text** (below 20pt): wider letter spacing, heavier stroke weight, larger x-height proportion, open apertures
+- **SF Pro Display** (20pt and above): tighter letter spacing, refined stroke weight, more contrast in thick/thin strokes
+- **SF Mono** for code: matches SF Pro's x-height and vertical metrics so code and UI text align on the same baseline grid
+- **New York** (serif companion): designed with matching metrics to SF Pro so the two can be mixed without vertical rhythm disruption
+
+### Anti-Patterns
+
+1. **Display fonts at body size.** Decorative or high-contrast typefaces (Playfair Display, Abril Fatface, Bodoni) have thin hairline strokes that become invisible below 18px on screen. The result is broken, unreadable body text that appeared fine in a mockup at 200% zoom. Rule: if the font has "Display" in its name, never use it below 24px.
+
+2. **Ignoring x-height when comparing fonts.** Georgia at 16px reads larger than Futura at 16px because Georgia's x-height ratio is 0.698 vs Futura's 0.653. Designers who swap fonts without adjusting sizes get layouts that "shrink" or "grow" unpredictably. Always compare x-height ratios and compensate: if switching from Inter (0.756) to Garamond (0.630), increase font-size by ~20% to maintain visual equivalence.
+
+3. **Treating all sans-serifs as interchangeable.** Helvetica, Inter, Roboto, and Futura are all "sans-serif" but have fundamentally different anatomies. Helvetica has closed apertures and uniform stroke widths (grotesque); Inter has open apertures and optical sizing (neo-grotesque); Futura has geometric construction based on circles (geometric); Fira Sans has calligraphic stroke variation (humanist). Substituting one for another changes readability, personality, and spacing.
+
+4. **Ignoring variable font axes.** Modern variable fonts like Inter, Roboto Flex, and SF Pro expose `wght`, `opsz`, `wdth`, and `slnt` axes. Using a static 400-weight file when the variable font could provide precise weight tuning (e.g., 350 for a specific hierarchy level) wastes the typeface's capabilities. Check available axes at `fonts.google.com` before defaulting to static files.
+
+### Real-World Examples
+
+**Inter (Rasmus Andersson, 2017-present)**
+Designed specifically for computer screens. Key anatomical decisions:
+
+- X-height ratio of 0.756 — among the tallest in professional sans-serifs
+- Open apertures on `c`, `e`, `s` for character differentiation at 11px+
+- Tabular figures enabled by default for data alignment
+- Variable font with `wght` (100-900) and `opsz` (14-32) axes
+- Used by: GitHub, Figma, Mozilla, thousands of design systems
+
+**Roboto Flex (Google, 2022)**
+The most parametric variable font in production:
+
+- 13 variation axes including `wght`, `wdth`, `opsz`, `GRAD` (grade), `XTRA` (x-axis tracking)
+- Optical size range from 8pt to 144pt — automatically adjusts stroke weight, spacing, and proportions
+- Material Design 3's type system is built entirely on Roboto Flex
+- Demonstrates that one variable font file can replace an entire type specimen
+
+**Vercel Geist (Vercel, 2023)**
+A typeface engineered for developer tooling and dashboard interfaces:
+
+- Geist Sans: neo-grotesque with tight tracking for information-dense UI
+- Geist Mono: monospace companion with identical x-height for seamless code-to-prose mixing
+- Both designed as variable fonts with weight axis 100-900
+- Character set includes programming ligatures in the mono variant
+- Demonstrates the modern trend of companies commissioning typefaces optimized for their specific UI density and context
+
+## Source
+
+- Bringhurst, Robert. _The Elements of Typographic Style_, version 4.0
+- Andersson, Rasmus. Inter typeface design notes — https://rsms.me/inter/
+- Apple Human Interface Guidelines — Typography
+- Google Fonts Knowledge — https://fonts.google.com/knowledge
+- Material Design 3 Type System — https://m3.material.io/styles/typography
+
+## Process
+
+1. **Evaluate** — Examine the typeface selection against the context: screen or print, body or display, data-dense or editorial. Check x-height ratio, aperture openness, stroke contrast, and optical sizing availability.
+2. **Apply** — Set type using the anatomical knowledge: choose optical sizes correctly, compensate for x-height differences when switching fonts, use variable font axes where available.
+3. **Verify** — Confirm readability at the target size on the target device. Check that counters remain open, strokes remain visible, and letterforms remain distinguishable at the smallest intended size.
+
+## Harness Integration
+
+This is a knowledge skill. When activated, it provides typographic anatomy expertise to guide font selection and configuration decisions. It does not modify files directly. Use the principles here when evaluating `font-family`, `font-size`, `font-variation-settings`, and `letter-spacing` values in any design system or component library.
+
+## Success Criteria
+
+- Font selection is justified by measurable anatomy: x-height ratio, aperture type, stroke contrast level
+- Optical sizes are used correctly — text cuts for body, display cuts for headings
+- Variable font axes are leveraged when available instead of loading multiple static files
+- No display or decorative typeface is used at body text sizes (below 24px)
+- Font size changes between typefaces account for x-height ratio differences

package/dist/agents/skills/claude-code/design-typography-fundamentals/skill.yaml

@@ -0,0 +1,36 @@
+name: design-typography-fundamentals
+version: "1.0.0"
+description: Anatomy of type — x-height, ascenders, counters, serifs, stroke contrast, optical sizing
+cognitive_mode: advisory-guide
+type: knowledge
+tier: 3
+triggers:
+  - manual
+platforms:
+  - claude-code
+  - gemini-cli
+  - cursor
+  - codex
+tools: []
+paths: []
+related_skills:
+  - design-type-scale
+  - design-font-pairing
+  - design-readability
+stack_signals: []
+keywords:
+  - typography
+  - x-height
+  - ascender
+  - descender
+  - serif
+  - sans-serif
+  - stroke contrast
+  - optical sizing
+  - typeface anatomy
+metadata:
+  author: community
+state:
+  persistent: false
+  files: []
+depends_on: []

package/dist/agents/skills/claude-code/design-visual-hierarchy/SKILL.md

@@ -0,0 +1,150 @@
+# Visual Hierarchy
+
+> Directing attention through size, color, contrast, position, isolation, and motion — the system that tells the eye where to go first, second, and third
+
+## When to Use
+
+- Designing any page or screen where multiple elements compete for attention
+- Evaluating why a layout feels confusing, flat, or overwhelming
+- Deciding relative sizes, colors, and positions for headings, body text, CTAs, and supporting elements
+- Building a component that must communicate primary, secondary, and tertiary importance levels
+- Reviewing a design to validate that the intended reading order matches the actual visual order
+
+## Instructions
+
+1. **Establish exactly one dominant element per viewport.** Every page needs a clear entry point — the single element the eye hits first. If two elements compete for dominance, the viewer hesitates and the layout feels chaotic:
+   - **Stripe homepage:** The headline "Financial infrastructure for the internet" is the dominant element — ~56px font, bold weight, high contrast (dark on light), positioned in the upper-left quadrant. Everything else is subordinate.
+   - **Apple product page:** The hero product image dominates — it occupies 50-60% of the viewport, is full-color against a neutral background, and is positioned center-screen.
+   - **Test:** Squint at the page. The element that remains visible when everything else blurs is the dominant element. If nothing emerges — or two things emerge equally — the hierarchy is broken.
+
+2. **Use the seven hierarchy tools in combination.** Each tool adds visual weight. The more tools you stack on an element, the more dominant it becomes:
+
+   | Tool               | How It Adds Weight                                   | Example                                             |
+   | ------------------ | ---------------------------------------------------- | --------------------------------------------------- |
+   | **Size**           | Larger = heavier. The most powerful single tool.     | Stripe hero: 56px headline vs. 18px body text       |
+   | **Color**          | Saturated, warm, or brand colors draw attention.     | Vercel: blue "Deploy" CTA against monochrome page   |
+   | **Contrast**       | High contrast foreground/background draws the eye.   | Apple: white text on black hero, gray text for meta |
+   | **Position**       | Top-left (LTR) and center draw first attention.      | Dashboards: key metrics in top-left quadrant        |
+   | **Isolation**      | An element surrounded by whitespace draws attention. | Apple: single product floating in vast empty space  |
+   | **Texture/Detail** | Complex, detailed elements attract over simple ones. | Airbnb: photo-rich listing vs. plain text sidebar   |
+   | **Motion**         | Moving elements override all static hierarchy.       | Stripe: animated gradient draws eye before reading  |
+
+   **Decision procedure:** For your primary element, apply 3-4 tools (large + high contrast + prime position + isolation). For secondary elements, apply 1-2 tools. For tertiary elements, apply none — they should be visually quiet.
+
+3. **Design in three tiers: primary, secondary, tertiary.** Every element on the page belongs to exactly one tier:
+   - **Primary (1-2 elements):** The headline, hero image, or primary CTA. Uses maximum visual weight. Should be identifiable in a 1-second scan.
+   - **Secondary (3-5 elements):** Subheadings, feature descriptions, secondary CTAs, key images. Moderate visual weight. Discovered after the primary element establishes context.
+   - **Tertiary (everything else):** Body text, metadata, navigation, footers, fine print. Minimal visual weight. Available when sought but never competing with primary or secondary.
+
+   **Stripe's pricing page demonstrates this clearly:**
+   - Primary: plan names and prices (large, bold, high contrast)
+   - Secondary: feature lists and "Get started" buttons (medium weight, brand color for CTAs)
+   - Tertiary: footnotes, comparison toggles, trust badges (small, gray, low contrast)
+
+4. **Validate hierarchy with the squint test and blur test.** These are non-negotiable quality checks:
+   - **Squint test:** Squint until the page blurs. The elements visible through the blur are your actual hierarchy. If they match your intended hierarchy, the design works. If metadata is more visible than the headline, something is wrong.
+   - **Blur test (Gaussian blur):** Apply a 5-10px Gaussian blur to a screenshot. Same principle — only high-contrast, large elements survive the blur. In Figma, use a background blur layer at 8px to simulate this.
+   - **5-second test:** Show the design to someone for 5 seconds, then hide it. Ask what they remember. What they recall is your effective primary tier. What they missed is your effective tertiary tier.
+
+5. **Understand F-pattern and Z-pattern scanning.** Eye-tracking research shows consistent scanning patterns:
+   - **F-pattern:** Used for text-heavy pages (articles, documentation, search results). The eye scans the top horizontal line, drops down, scans a shorter horizontal line, then skims down the left edge. Nielsen Norman Group eye-tracking studies confirmed this across 232 users. Implication: put the most important content in the first line and along the left edge.
+   - **Z-pattern:** Used for pages with less text and more visual elements (landing pages, marketing). The eye moves: top-left → top-right → diagonal to bottom-left → bottom-right. Implication: place your logo/headline top-left, CTA top-right or bottom-right.
+   - **Exception:** A strong dominant element overrides scanning patterns. If a centered hero image is large enough, the eye goes there first regardless of F or Z pattern.
+
+6. **Use contrast ratios as a hierarchy system.** Beyond accessibility, contrast is a precision tool for establishing reading priority:
+   - **Primary text:** Maximum contrast. Black on white (#000 on #fff) = 21:1 ratio. Or near-black (#111 on #fff) = 18.6:1.
+   - **Secondary text:** Reduced contrast. Dark gray on white (#555 on #fff) = 7.5:1. Still meets WCAG AA.
+   - **Tertiary text:** Minimum usable contrast. Medium gray on white (#767676 on #fff) = 4.54:1. Just meets WCAG AA for normal text.
+   - **Decorative/disabled:** Below reading threshold. Light gray on white (#aaa on #fff) = 2.32:1. Not meant to be read — signals "inactive" or "background."
+
+   Apple uses this exact system: primary labels at ~17:1, secondary at ~7:1, tertiary at ~4.5:1, and disabled/placeholder at ~2.5:1.
+
+## Details
+
+### Visual Weight Formula
+
+Visual weight is not a single property but a composite. An element's weight is roughly:
+
+```
+weight = size_factor + contrast_factor + saturation_factor + isolation_factor + position_factor
+```
+
+Where each factor is 0-3:
+
+- **Size:** 0 = smallest on page, 3 = largest
+- **Contrast:** 0 = low contrast with background, 3 = maximum contrast
+- **Saturation:** 0 = grayscale, 3 = fully saturated brand/accent color
+- **Isolation:** 0 = surrounded by other elements, 3 = floating in whitespace
+- **Position:** 0 = bottom-right corner, 3 = top-left or dead center
+
+A primary element should score 10-15. A secondary element should score 5-9. A tertiary element should score 0-4. If two elements score within 2 points of each other, they will compete for attention.
+
+### Hierarchy Across Component States
+
+Within a single component, hierarchy applies to states:
+
+- **Default:** Medium weight — visible but not demanding attention
+- **Hover:** Increased weight — color shift, subtle shadow, slight scale (1.02x)
+- **Active/Selected:** High weight — brand color, bold border, filled background
+- **Disabled:** Minimal weight — reduced opacity (0.4-0.5), desaturated, no hover response
+- **Error:** High weight via color — red (#d32f2f) draws immediate attention. Errors should be primary-tier regardless of the element's normal tier.
+
+Material Design's state layers demonstrate this: hover adds 8% opacity overlay, focus adds 12%, pressed adds 12%, dragged adds 16%.
+
+### Anti-Patterns
+
+1. **Competing focal points.** Two elements of equal visual weight fight for attention — a large image AND a large headline at the same size, color, and contrast. The viewer oscillates between them. Fix: make one clearly dominant. Stripe never lets an image compete with a headline — images are always muted, desaturated, or smaller than the text.
+
+2. **Flat hierarchy.** Everything the same size, weight, and color. Common in engineering-driven layouts where every piece of data feels equally important. The result: nothing stands out, so the user must read everything sequentially. Fix: force-rank every element into primary/secondary/tertiary before placing it.
+
+3. **Decoration over content.** Ornamental backgrounds, gradient borders, animated patterns, or decorative icons that carry more visual weight than the actual content. The eye goes to the decoration first. Fix: the squint test — if decorative elements are more visible than content elements, reduce their weight (lower opacity, desaturate, shrink).
+
+4. **Motion abuse.** Animations and transitions that are so prominent they override all static hierarchy. A subtle entrance animation is secondary; a looping animation is primary. If a background animation draws more attention than the headline, it is competing with — not supporting — the hierarchy. Vercel uses motion sparingly: a gradient shift on hover, never a persistent loop.
+
+### Real-World Examples
+
+**Stripe Homepage (3-Tier Hierarchy):**
+
+- Tier 1 (Primary): "Financial infrastructure for the internet" — 56px, bold, #0a2540, top-left. Score: ~14 (size 3, contrast 3, saturation 0, isolation 3, position 3, bold 2).
+- Tier 2 (Secondary): Subheading paragraph — 20px, #425466, below headline. Score: ~7.
+- Tier 3 (Tertiary): Navigation links — 15px, #425466, top bar. Score: ~3.
+- The gradient illustration is visually rich but positioned right-side and uses muted colors — it does not compete with the headline.
+
+**Apple Product Comparison Page:**
+
+- Tier 1: Product images — large, full-color, centered
+- Tier 2: Product names and prices — 21px bold, high contrast
+- Tier 3: Feature specs — 14px, gray, tabular layout
+- Hierarchy survives the blur test: products visible, names partially visible, specs disappear
+
+**Vercel Dashboard:**
+
+- Tier 1: Project name and status — left-aligned, 18px bold, status badge with color coding
+- Tier 2: Deployment list — each entry has timestamp, commit hash, branch name at 14px
+- Tier 3: Settings navigation — sidebar links at 14px, gray, no visual emphasis
+- The active navigation item uses weight + blue accent color to establish "you are here" without competing with content
+
+## Source
+
+- Donis A. Dondis, "A Primer of Visual Literacy" — foundational theory of visual weight and composition
+- Jakob Nielsen and Kara Pernice, "Eyetracking Web Usability" — F-pattern and Z-pattern research
+- Susan Weinschenk, "100 Things Every Designer Needs to Know About People" — cognitive processing of visual hierarchy
+- Material Design 3 documentation on emphasis and visual hierarchy
+
+## Process
+
+1. **Rank** every element on the page into primary (1-2), secondary (3-5), or tertiary (remaining) before touching any visual properties
+2. **Assign** visual weight using the seven hierarchy tools: stack 3-4 tools on primary, 1-2 on secondary, none on tertiary
+3. **Validate** with the squint test and blur test — verify that the intended hierarchy matches the perceived hierarchy
+
+## Harness Integration
+
+This is a knowledge skill. When activated, its content is injected into the system prompt to guide layout and emphasis decisions. It does not execute code or modify files. Use alongside `design-typographic-hierarchy` for text-specific hierarchy, `design-contrast-ratio` for contrast-based emphasis, and `design-whitespace` for isolation-based emphasis.
+
+## Success Criteria
+
+- Every viewport has exactly one dominant element identifiable in a 1-second scan
+- All elements are assigned to primary, secondary, or tertiary tiers with no ambiguity
+- The squint test confirms that intended hierarchy matches perceived hierarchy
+- No two elements within the same viewport have competing visual weight
+- Hierarchy is maintained across all viewport sizes — primary elements remain dominant on mobile

package/dist/agents/skills/claude-code/design-visual-hierarchy/skill.yaml

@@ -0,0 +1,36 @@
+name: design-visual-hierarchy
+version: "1.0.0"
+description: Directing attention — size, color, contrast, position, isolation, motion as hierarchy tools
+cognitive_mode: advisory-guide
+type: knowledge
+tier: 3
+triggers:
+  - manual
+platforms:
+  - claude-code
+  - gemini-cli
+  - cursor
+  - codex
+tools: []
+paths: []
+related_skills:
+  - design-typographic-hierarchy
+  - design-contrast-ratio
+  - design-whitespace
+  - design-gestalt-proximity
+stack_signals: []
+keywords:
+  - visual hierarchy
+  - attention
+  - focal point
+  - emphasis
+  - dominance
+  - subordination
+  - visual weight
+  - scanning
+metadata:
+  author: community
+state:
+  persistent: false
+  files: []
+depends_on: []