@harness-engineering/cli 1.23.2 → 1.24.1

package/dist/agents/skills/claude-code/design-web-fonts/SKILL.md

@@ -0,0 +1,251 @@
+# Web Fonts
+
+> Font loading strategy — performance vs. FOUT/FOIT, variable fonts, subsetting, system font stacks, and font-display options
+
+## When to Use
+
+- Adding custom fonts to a web project for brand differentiation
+- Optimizing font loading to reduce Largest Contentful Paint (LCP) and Cumulative Layout Shift (CLS)
+- Deciding between self-hosting fonts and using a CDN (Google Fonts, Adobe Fonts)
+- Evaluating whether to adopt variable fonts for an existing design system
+- Building a system font stack as a zero-cost baseline or permanent solution
+- Debugging invisible text (FOIT) or text reflow (FOUT) during page load
+
+## Instructions
+
+1. **Choose a font-display strategy.** The `font-display` CSS descriptor controls what happens while a web font is loading. This is the single most impactful decision for font-related performance:
+
+   | Value      | Behavior                                            | Block Period      | Swap Period       | Best For                                     |
+   | ---------- | --------------------------------------------------- | ----------------- | ----------------- | -------------------------------------------- |
+   | `swap`     | Shows fallback immediately, swaps when loaded       | ~100ms            | Infinite          | Body text — user sees content instantly      |
+   | `optional` | Shows fallback; may never swap if load is slow      | ~100ms            | None              | Performance-critical sites — no layout shift |
+   | `fallback` | Brief invisible, then fallback, limited swap window | ~100ms            | ~3s               | Balance between swap and optional            |
+   | `block`    | Invisible text for up to 3 seconds                  | ~3s               | Infinite          | Icon fonts only (never for text)             |
+   | `auto`     | Browser decides (usually `block`)                   | Browser-dependent | Browser-dependent | Never use — behavior is unpredictable        |
+
+   **Decision procedure:**
+   - For body text: use `swap` (guarantees content is always visible)
+   - For headings on performance-critical pages: use `optional` (prevents layout shift; font loads from cache on subsequent visits)
+   - For icon fonts: use `block` (invisible squares are better than showing raw ligature text)
+   - Never use `auto` or omit `font-display` — the browser default is effectively `block`, creating 3 seconds of invisible text
+
+2. **Understand FOUT and FOIT.** These are the two failure modes of web font loading:
+   - **FOIT (Flash of Invisible Text)**: text is invisible until the web font loads. Caused by `font-display: block` or browser default. Users see a blank page or missing content for up to 3 seconds. This is the worse failure mode — it hides content.
+   - **FOUT (Flash of Unstyled Text)**: text appears in the fallback font, then swaps to the web font when loaded. Caused by `font-display: swap`. Users see a brief reflow. This is the better failure mode — content is always visible.
+   - **Modern best practice**: accept FOUT (use `swap`) and minimize its visual impact by choosing a fallback font with similar metrics to your web font.
+
+3. **Use WOFF2 exclusively for modern browsers.** Font file formats in order of preference:
+   - **WOFF2**: compressed (Brotli), smallest file size, supported by all modern browsers (97%+ global support). Use this.
+   - **WOFF**: compressed (zlib), ~20% larger than WOFF2. Only needed for IE11 (effectively dead).
+   - **TTF/OTF**: uncompressed, 2-3x larger than WOFF2. Never serve these to browsers.
+   - **EOT**: Internet Explorer only. Dead format.
+
+   ```css
+   @font-face {
+     font-family: 'Inter';
+     src: url('/fonts/inter-var.woff2') format('woff2');
+     font-weight: 100 900;
+     font-display: swap;
+   }
+   ```
+
+4. **Subset fonts aggressively.** Most projects use only Latin characters. Loading a full Unicode font wastes bandwidth:
+   - **Inter full**: ~300KB (all Unicode blocks)
+   - **Inter Latin-only subset**: ~20KB (Latin, Latin Extended)
+   - **Inter Latin Basic**: ~12KB (ASCII + common accented characters)
+   - Use `unicode-range` in `@font-face` to load character sets on demand:
+
+   ```css
+   /* Latin characters only */
+   @font-face {
+     font-family: 'Inter';
+     src: url('/fonts/inter-latin.woff2') format('woff2');
+     unicode-range:
+       U+0000-00FF, U+0131, U+0152-0153, U+02BB-02BC, U+02C6, U+02DA, U+02DC, U+0304, U+0308,
+       U+0329, U+2000-206F, U+2074, U+20AC, U+2122, U+2191, U+2193, U+2212, U+2215, U+FEFF, U+FFFD;
+     font-display: swap;
+   }
+   ```
+
+   Tools: `glyphhanger` (npm) analyzes which characters your site actually uses. `pyftsubset` (Python fonttools) creates subsets from any font file.
+
+5. **Evaluate variable fonts for multi-weight systems.** A variable font contains all weights (and potentially widths, optical sizes) in a single file. The tradeoff:
+   - **Single static weight** (e.g., Inter Regular 400): ~20KB WOFF2
+   - **Two static weights** (400 + 700): ~40KB WOFF2
+   - **Variable font** (100-900 weight axis): ~95KB WOFF2
+   - **Breakeven point**: if you use 3+ weights from the same family, the variable font is smaller than individual static files (~60KB for 3 static weights vs ~95KB for one variable file)
+   - **Bonus**: variable fonts enable intermediate weights (350, 550) for fine-tuned hierarchy without additional file requests
+   - **Decision rule**: Using 1-2 weights? Static files. Using 3+ weights or need intermediate values? Variable font.
+
+6. **Preload critical fonts.** Add `<link rel="preload">` for fonts that appear above the fold:
+
+   ```html
+   <link rel="preload" href="/fonts/inter-var.woff2" as="font" type="font/woff2" crossorigin />
+   ```
+
+   - Preload only 1-2 font files (the primary text font and possibly one heading font)
+   - The `crossorigin` attribute is required even for same-origin fonts (browser specification requirement)
+   - Excessive preloading (3+ fonts) competes with other critical resources and can slow LCP
+
+7. **Build a system font stack as baseline or permanent solution.** System fonts load in 0ms — they are already on the user's device:
+
+   ```css
+   font-family:
+     -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, Oxygen-Sans, Ubuntu, Cantarell,
+     'Helvetica Neue', sans-serif;
+   ```
+
+   **Platform resolution:**
+   - macOS/iOS: SF Pro (via `-apple-system`)
+   - Windows: Segoe UI
+   - Android: Roboto
+   - Linux: Ubuntu or Cantarell (depending on distribution)
+
+   System font stacks are not a compromise — GitHub uses system fonts for their entire application UI. The only drawback is loss of brand-specific typography.
+
+## Details
+
+### Self-Hosting vs. CDN
+
+**Self-hosting** (recommended for most projects):
+
+- Full control over caching headers, subsetting, and file optimization
+- No third-party DNS lookup or connection overhead
+- No privacy concerns (Google Fonts CDN was ruled a GDPR violation in some EU jurisdictions)
+- Can be served from the same domain, eliminating cross-origin overhead
+
+**Google Fonts CDN**:
+
+- Easy setup (`<link href="https://fonts.googleapis.com/css2?...">`)
+- Automatic format negotiation and subsetting
+- Previously had a cache-sharing advantage (browser cached Google Fonts across sites) — this was eliminated when browsers partitioned third-party caches (Chrome 86+, 2020)
+- **Current recommendation**: download from Google Fonts and self-host. The CDN's cache advantage no longer exists, and self-hosting is faster, more private, and more controllable.
+
+### Next.js Font Optimization
+
+Next.js provides automatic font optimization via `next/font`:
+
+```typescript
+import { Inter } from 'next/font/google';
+
+const inter = Inter({
+  subsets: ['latin'],
+  display: 'swap',
+  variable: '--font-inter',
+});
+```
+
+This automatically:
+
+- Self-hosts the font (no Google Fonts CDN request)
+- Subsets to the specified character ranges
+- Generates CSS `@font-face` with `font-display: swap`
+- Creates a CSS custom property for use in Tailwind or CSS
+- Adjusts fallback font metrics to minimize CLS during swap
+- Inlines the CSS to avoid render-blocking requests
+
+### Font File Size Budget
+
+A practical budget for font loading:
+
+| Category              | Budget    | Example                                          |
+| --------------------- | --------- | ------------------------------------------------ |
+| Total font payload    | < 100KB   | 1 variable font (80KB) + 1 monospace (20KB)      |
+| Per-font file         | < 50KB    | Single static weight: ~20KB; Variable: ~80-100KB |
+| Critical (above fold) | < 50KB    | Preloaded primary font only                      |
+| Fonts per page        | 1-3 files | Primary text + optional heading + optional mono  |
+
+If your font payload exceeds 200KB, you are loading too many families, weights, or character sets. Audit with Chrome DevTools Network panel filtered to "Font."
+
+### Matching Fallback Font Metrics
+
+To minimize FOUT layout shift, configure the fallback font to match the web font's metrics:
+
+```css
+@font-face {
+  font-family: 'Inter Fallback';
+  src: local('Arial');
+  ascent-override: 90.49%;
+  descent-override: 22.56%;
+  line-gap-override: 0%;
+  size-adjust: 107.64%;
+}
+
+body {
+  font-family: 'Inter', 'Inter Fallback', sans-serif;
+}
+```
+
+The `size-adjust`, `ascent-override`, `descent-override`, and `line-gap-override` descriptors align the fallback font's metrics to the web font, reducing visual shift when the swap occurs. Tools like `fontaine` (npm) and `next/font` calculate these values automatically.
+
+### Anti-Patterns
+
+1. **Loading 6+ font files on initial page load.** Each font file is a network request that blocks text rendering. Loading Regular, Italic, Bold, Bold Italic, Light, and Medium variants separately produces 6 requests and 120-180KB of font data. Fix: use a single variable font file, or limit to 2 static weights maximum.
+
+2. **No fallback font specified.** A `font-family: 'CustomBrandFont'` declaration with no fallback produces invisible text if the font fails to load, or defaults to the browser's serif (Times New Roman on most systems) which likely has completely different proportions. Always provide a complete fallback stack.
+
+3. **Using font-display: block for body text.** This hides all body text for up to 3 seconds while the font loads. On slow connections (3G mobile), users see a blank content area. The font may never load if the connection drops. Fix: use `font-display: swap` for all text content.
+
+4. **Loading full character sets for Latin-only content.** A full Unicode build of Inter includes Greek, Cyrillic, Vietnamese, and other scripts. If your content is English-only, 90% of the font file is unused data. Fix: subset to Latin Basic (U+0000-00FF) plus any accent characters your content uses.
+
+5. **Google Fonts CDN without privacy audit.** Google Fonts transmits the user's IP address to Google servers. In the EU, this has been ruled a GDPR violation (Munich Regional Court, January 2022). Even outside the EU, the unnecessary data transmission is a liability. Fix: download fonts and self-host them.
+
+### Real-World Examples
+
+**GitHub's System Font Strategy**
+GitHub uses system fonts exclusively for the application UI:
+
+```css
+font-family:
+  -apple-system, BlinkMacSystemFont, 'Segoe UI', 'Noto Sans', Helvetica, Arial, sans-serif,
+  'Apple Color Emoji', 'Segoe UI Emoji';
+```
+
+Result: zero font-loading overhead, zero FOUT/FOIT, instant text rendering. Font payload: 0KB. GitHub reserves custom fonts (Mona Sans, Hubot Sans) only for marketing pages where brand expression justifies the performance cost.
+
+**Vercel's Geist Font Implementation**
+Vercel self-hosts Geist as a variable font via `next/font`:
+
+- Single WOFF2 variable file (~80KB) covering weights 100-900
+- Subset to Latin characters
+- Preloaded with `<link rel="preload">`
+- `font-display: swap` for immediate text visibility
+- Geist Mono loaded separately (~35KB) only on pages with code blocks
+- Total font budget: 80-115KB depending on page type
+
+**Stripe's Font Loading**
+Stripe loads sohne-var (variable) self-hosted:
+
+- Single variable font file covering weights 300-400 (the only weights they use)
+- Custom subset: Latin + select currency symbols
+- Preloaded on all pages
+- Source Code Pro loaded only on API documentation pages
+- `font-display: swap` with carefully tuned fallback metrics to minimize CLS
+
+## Source
+
+- web.dev — "Best practices for fonts" (Google Chrome team)
+- MDN Web Docs — `font-display` descriptor, `@font-face` at-rule
+- Zach Leatherman — "A Comprehensive Guide to Font Loading Strategies"
+- Chrome DevTools — Network panel font analysis
+- WCAG 2.1 SC 1.4.12 — Text Spacing (font rendering implications)
+
+## Process
+
+1. **Evaluate** — Audit the current font loading strategy. Measure total font payload, count font file requests, check `font-display` values, and identify whether subsetting is applied. Run Lighthouse to check CLS from font swap.
+2. **Apply** — Implement the optimal loading strategy: WOFF2 format, aggressive subsetting, `font-display: swap` for text, preload critical fonts, self-host rather than CDN. Consider variable fonts if using 3+ weights.
+3. **Verify** — Confirm total font payload is under 100KB, no FOIT occurs on throttled connections (Chrome DevTools slow 3G), CLS from font swap is under 0.01, and fallback fonts have matched metrics.
+
+## Harness Integration
+
+This is a knowledge skill. When activated, it provides font loading performance expertise to guide `@font-face` declarations, preload hints, and font file optimization. Use these principles when configuring `next/font`, adding custom fonts to any web framework, or auditing Core Web Vitals related to font loading. Cross-reference with `design-typography-fundamentals` for font selection and `design-responsive-type` for viewport-adaptive type.
+
+## Success Criteria
+
+- Total font payload is under 100KB for a typical page load
+- All text fonts use `font-display: swap` or `font-display: optional`
+- Fonts are served as WOFF2 only (no TTF, OTF, or WOFF fallbacks for modern browsers)
+- Fonts are subsetted to only the character ranges the content requires
+- No more than 3 font files are loaded on initial page render
+- Fallback fonts have metric overrides to minimize CLS during swap
+- Fonts are self-hosted (no third-party CDN for production)

package/dist/agents/skills/claude-code/design-web-fonts/skill.yaml

@@ -0,0 +1,36 @@
+name: design-web-fonts
+version: "1.0.0"
+description: Font loading strategy — performance vs. FOUT/FOIT, variable fonts, subsetting, system font stacks
+stability: static
+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-responsive-type
+stack_signals: []
+keywords:
+  - web fonts
+  - font loading
+  - FOUT
+  - FOIT
+  - variable fonts
+  - subsetting
+  - system fonts
+  - font-display
+  - woff2
+metadata:
+  author: community
+state:
+  persistent: false
+  files: []
+depends_on: []

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

@@ -0,0 +1,150 @@
+# Whitespace
+
+> Space as a design element — macro vs. micro whitespace, breathing room, density control, and whitespace as a signal of quality and luxury
+
+## When to Use
+
+- Deciding padding, margin, and spacing values for any UI component or page section
+- Evaluating why a layout feels cramped, cluttered, or disorganized
+- Setting up a spacing scale for a design system
+- Balancing information density against readability and visual comfort
+- Communicating brand positioning through spatial treatment (premium vs. utilitarian)
+
+## Instructions
+
+1. **Distinguish macro and micro whitespace.** These are fundamentally different design decisions:
+   - **Macro whitespace** — The large spaces between major elements: page margins, section padding, space between content blocks. Controls the overall density and feel of a page. Apple's product pages use 80-120px between sections (10-15 x 8px base unit), creating a one-idea-per-viewport cadence that feels unhurried and premium.
+   - **Micro whitespace** — The small spaces within and between elements: padding inside buttons, space between a label and its input, gap between list items, letter-spacing. Controls readability and component density. Stripe's buttons use 12px vertical / 24px horizontal padding — the horizontal padding is 2x the vertical, giving text room to breathe without making the button feel oversized.
+
+   You can have generous macro whitespace with tight micro whitespace (Stripe's dashboard: spacious sections, dense data tables) or vice versa. They are independent variables.
+
+2. **Use whitespace as a grouping mechanism (Gestalt proximity).** Elements with less space between them are perceived as related. Elements with more space are perceived as separate. This is the most powerful layout tool you have — no borders, lines, or boxes needed:
+   - **Tight grouping (4-8px):** Label + input field, icon + text, avatar + username
+   - **Medium grouping (12-24px):** Items within a card, form fields within a section, list items
+   - **Loose grouping (32-64px):** Sections within a page, card groups, major content blocks
+   - **Separation (64-128px):** Distinct page zones, hero-to-content transition, footer separation
+
+   **Decision procedure:** If two elements are related, the space between them should be less than the space between either element and the next unrelated element. Airbnb's listing cards use 16px internal padding but 24px between cards — the tighter internal space signals "these items belong together."
+
+3. **Build a spacing scale.** Never use arbitrary spacing values. Define a scale based on a base unit and use only values from that scale:
+   - **4px base scale:** 4, 8, 12, 16, 20, 24, 32, 40, 48, 64, 80, 96, 128
+   - **8px base scale:** 8, 16, 24, 32, 48, 64, 96, 128, 192 (Stripe, Material Design, Shopify Polaris)
+   - **Naming convention (Tailwind-style):** xs=4px, sm=8px, md=16px, lg=24px, xl=32px, 2xl=48px, 3xl=64px, 4xl=96px
+
+   Stripe's entire marketing site uses an 8px scale. Section padding is 96px (12x base). Card padding is 32px (4x base). Inline element gaps are 8px (1x base). Every value is a multiple — no exceptions. This consistency is why Stripe's layouts feel effortless despite being complex.
+
+4. **Understand whitespace as a luxury signal.** Space is the most expensive resource in design — it costs content area. Premium brands spend it generously:
+   - **Apple:** Product hero images float in massive whitespace. A single product photo might occupy 40% of a viewport, with the remaining 60% as empty space. This communicates "we have nothing to prove — the product speaks for itself."
+   - **Vercel:** Homepage sections use 120-160px vertical padding. A section that could be 200px tall is given 500px. The generosity signals confidence and sophistication.
+   - **Bloomberg Terminal:** The opposite — extreme density communicates "every pixel carries information, we respect your expertise." Minimal padding, tight line-height, no decorative whitespace.
+
+   **Decision procedure:** Where does your product sit on the utility-to-luxury spectrum? Dashboards and tools should use tighter spacing (high utility). Marketing and brand pages should use generous spacing (high luxury). The same product can use different densities for different pages.
+
+5. **Differentiate active and passive whitespace.** Active whitespace is an intentional design decision. Passive whitespace is leftover space that nobody planned:
+   - **Active:** Stripe's 96px section padding. It is deliberate — tested at 64px, 80px, 96px, 112px, and 96px was chosen because it creates exactly the right reading rhythm.
+   - **Passive:** A sidebar that is 300px wide because the developer set `width: 300px`, leaving 47px of unexplained space at the bottom. Nobody designed that space — it just happened.
+   - **Diagnosis:** If you cannot explain why a particular space is that size, it is passive whitespace. Either make it intentional (assign it a value from your spacing scale) or eliminate it.
+
+6. **Apply the spacing paradox.** Adding whitespace often makes a layout feel more organized even though it contains less content per viewport. This is counterintuitive but consistently true:
+   - A card with 16px padding and 12px gaps between elements feels cluttered. The same card with 24px padding and 16px gaps feels polished — even though it now requires more viewport space.
+   - A page with 40px section padding feels like a Word document. The same page with 80px section padding feels like a designed experience.
+   - **Test:** If a layout feels "off" but you cannot pinpoint why, increase all spacing by one step on your scale (e.g., 16px to 24px, 24px to 32px). In most cases, this resolves the issue.
+
+## Details
+
+### Spacing Scale Reference
+
+| Context               | Tight (Dashboard) | Standard (App) | Generous (Marketing) |
+| --------------------- | ----------------- | -------------- | -------------------- |
+| Section padding       | 32-48px           | 48-80px        | 80-128px             |
+| Card internal padding | 12-16px           | 16-24px        | 24-32px              |
+| Between form fields   | 12-16px           | 16-24px        | 20-32px              |
+| Between list items    | 4-8px             | 8-12px         | 12-16px              |
+| Button padding (v/h)  | 6/12px            | 8/16px         | 12/24px              |
+| Icon-to-label gap     | 4-6px             | 8px            | 8-12px               |
+| Page margin (mobile)  | 12-16px           | 16-20px        | 20-24px              |
+| Page margin (desktop) | 24-40px           | 40-80px        | 80-120px             |
+
+### Whitespace Audit Procedure
+
+To evaluate an existing design's whitespace:
+
+1. **List every unique spacing value.** If there are more than 8-10 distinct values, the system lacks a scale.
+2. **Check that each value is a multiple of the base unit.** Values like 13px, 17px, or 23px indicate ad-hoc spacing.
+3. **Verify proximity grouping.** Related elements should have less space between them than unrelated elements. If a label is 16px from its input but also 16px from the next form group, the grouping signal is ambiguous.
+4. **Check for passive whitespace.** Look for large empty areas that serve no grouping or rhythm purpose. These usually appear at the bottom of sidebars, between a short page and its footer, or inside oversized containers.
+5. **Measure the luxury-utility ratio.** Compare total whitespace area to total content area. Marketing pages: 40-60% whitespace. Dashboards: 15-30% whitespace. If a dashboard is 50% whitespace, it is wasting screen real estate.
+
+### Anti-Patterns
+
+1. **Horror vacui (fear of empty space).** Filling every available pixel with content, decoration, borders, or background patterns. The result is overwhelming — the eye has no resting point and cannot establish hierarchy. Diagnosis: if removing an element would improve the design, horror vacui is present.
+
+2. **Inconsistent spacing.** Using 8px here, 13px there, 20px somewhere else — values chosen per-element rather than from a scale. This creates a subliminal sense of disorder that users feel but cannot articulate. Even non-designers perceive inconsistent spacing as "unprofessional." Fix: audit all spacing values and round each to the nearest scale value.
+
+3. **Equal spacing everywhere.** Uniform 16px gaps between all elements regardless of their relationship. This eliminates the grouping signal that whitespace provides — a label is the same distance from its input as it is from an unrelated heading. The fix is not more space, but differential space: tighter within groups, looser between groups.
+
+4. **Decorative fillers.** Using background patterns, gradient dividers, ornamental lines, or clip-art to fill space that "feels too empty." These are symptoms of horror vacui. The space was doing its job — the filler undermines it. Stripe uses only two dividers on its entire homepage: a subtle border-top on the footer and a color-shift between sections.
+
+### Real-World Examples
+
+**Apple Product Pages:**
+
+- Hero section: product image centered in ~600px of vertical whitespace
+- Feature sections: 100-120px padding top and bottom, single idea per section
+- Text blocks: max-width 680px centered, generous 40px+ margins on either side
+- The spatial treatment communicates: "this product deserves contemplation, not scanning"
+
+**Stripe Dashboard vs. Stripe Marketing:**
+
+- Dashboard: 16px card padding, 8px gaps between data rows, 24px section spacing. Dense, efficient, utilitarian.
+- Marketing: 32px card padding, 96px section padding, 48px between feature blocks. Generous, premium, persuasive.
+- Same brand, same spacing scale (8px base), radically different density — because the contexts demand different approaches.
+
+**Vercel Homepage:**
+
+- Section vertical padding: 120-160px — among the most generous in SaaS
+- Content max-width: ~1100px with auto margins, leaving significant horizontal whitespace on wide screens
+- Code blocks float in 40-60px of surrounding space, making them feel like curated examples rather than documentation
+- The extreme whitespace positions Vercel as a premium developer tool, not a commodity platform
+
+**Spotify Desktop App:**
+
+- Playlist view: 4px micro-spacing between track rows for scan density (expert users want to see many tracks)
+- Album header: 32px between album art and metadata — clear grouping without waste
+- Home page browse cards: 16px gap between cards, 48px between sections (genre rows)
+- Sidebar navigation: 4px between items within a group, 16px between groups (Your Library vs. Playlists)
+- Demonstrates that a single product can use 3-4 different density zones: dense in lists, moderate in navigation, generous in discovery
+
+### Responsive Whitespace Adaptation
+
+Whitespace must scale with viewport — but not linearly. A 96px section padding on desktop should not shrink proportionally to 24px on mobile. Instead:
+
+- **Desktop (1200px+):** Full spacing scale. Section padding 80-120px. Page margins 40-80px.
+- **Tablet (768-1199px):** Reduce macro whitespace by ~30%. Section padding 56-80px. Page margins 24-40px. Micro whitespace stays the same — button padding, icon gaps, and label spacing should not change.
+- **Mobile (320-767px):** Reduce macro whitespace by ~50%. Section padding 40-64px. Page margins 16-20px. Micro whitespace unchanged.
+- **Key principle:** Macro whitespace is compressible. Micro whitespace is not. Shrinking the padding inside a button from 12px to 6px makes it feel broken. Shrinking section padding from 96px to 48px feels like a natural adaptation.
+
+## Source
+
+- Josef Muller-Brockmann, "Grid Systems in Graphic Design" — spatial rhythm and proportion
+- "Refactoring UI" by Adam Wathan and Steve Schoger — practical spacing guidelines for web interfaces
+- Material Design spacing documentation (m3.material.io/foundations/layout/spacing)
+- Edward Tufte, "Envisioning Information" — data-ink ratio and meaningful use of space
+
+## Process
+
+1. **Define** a spacing scale based on a 4px or 8px base unit before placing any elements
+2. **Apply** spacing using the Gestalt proximity principle: tighter within groups, looser between groups
+3. **Audit** by listing all unique spacing values and verifying each is from the defined scale
+
+## Harness Integration
+
+This is a knowledge skill. When activated, its content is injected into the system prompt to guide spacing and layout decisions. It does not execute code or modify files. Use alongside `design-grid-systems` for structural layout, `design-content-density` for density calibration, and `design-visual-hierarchy` for attention management.
+
+## Success Criteria
+
+- All spacing values derive from a declared scale with a consistent base unit
+- Macro and micro whitespace are independently calibrated for the page context
+- Related elements have tighter spacing than unrelated elements (proximity grouping)
+- No passive whitespace — every significant space can be explained as a scale value
+- Density matches the page purpose: generous for marketing, efficient for dashboards

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

@@ -0,0 +1,37 @@
+name: design-whitespace
+version: "1.0.0"
+description: Space as design element — macro vs. micro, breathing room, density control, whitespace as luxury signal
+stability: static
+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-content-density
+  - design-visual-hierarchy
+stack_signals: []
+keywords:
+  - whitespace
+  - negative space
+  - spacing
+  - padding
+  - margin
+  - breathing room
+  - density
+  - macro space
+  - micro space
+metadata:
+  author: community
+state:
+  persistent: false
+  files: []
+depends_on: []

package/dist/agents/skills/claude-code/detect-doc-drift/skill.yaml

@@ -1,6 +1,7 @@
 name: detect-doc-drift
 version: "1.0.0"
 description: Detect documentation that has drifted from code
+stability: static
 cognitive_mode: diagnostic-investigator
 triggers:
   - manual
@@ -8,6 +9,8 @@ triggers:
 platforms:
   - claude-code
   - gemini-cli
+  - cursor
+  - codex
 tools:
   - Bash
   - Read