@harness-engineering/cli 1.23.2 → 1.24.0

package/dist/agents/skills/codex/design-feedback-patterns/skill.yaml

@@ -0,0 +1,35 @@
+name: design-feedback-patterns
+version: "1.0.0"
+description: System response design — immediate vs delayed feedback, optimistic updates, progress indicators, confirmation patterns, undo vs confirm, toast/snackbar/banner
+cognitive_mode: advisory-guide
+type: knowledge
+tier: 3
+triggers:
+  - manual
+platforms:
+  - claude-code
+  - gemini-cli
+  - cursor
+  - codex
+tools: []
+paths: []
+related_skills:
+  - design-state-design
+  - design-micro-interactions
+  - design-affordances
+stack_signals: []
+keywords:
+  - feedback
+  - optimistic-updates
+  - progress-indicators
+  - confirmation
+  - undo
+  - toast
+  - snackbar
+  - banner
+metadata:
+  author: community
+state:
+  persistent: false
+  files: []
+depends_on: []

package/dist/agents/skills/codex/design-fluent-design/SKILL.md

@@ -0,0 +1,241 @@
+# Fluent Design System (Fluent 2)
+
+> Microsoft's cross-platform design system covering the five foundational elements (light, depth, motion, material, scale), Acrylic and Mica materials, reveal highlight interactions, connected animations, responsive container strategies, and the Fluent 2 token theming architecture.
+
+## When to Use
+
+- Building Windows apps (WinUI 3, WPF with Fluent theme) where Acrylic, Mica, and reveal highlight are platform expectations
+- Developing Microsoft 365 integrations (Teams tabs, Outlook add-ins, SharePoint web parts) that must match Fluent 2 visual language
+- Implementing a React-based UI using `@fluentui/react-components` (Fluent UI React v9) with Griffel CSS-in-JS and token theming
+- Creating responsive layouts for apps that span desktop (1920px), tablet (1024px), and compact (320px) using Fluent's breakpoint and container strategy
+- Migrating from Fluent 1 (Fabric) to Fluent 2 where the token system, component API, and material model have fundamentally changed
+
+## Instructions
+
+Fluent Design is organized around five foundational elements: **Light** (illumination that reveals interactive surfaces), **Depth** (layering that establishes hierarchy), **Motion** (animation that connects user actions to outcomes), **Material** (translucent surfaces that establish context), and **Scale** (adaptive layouts from 320px mobile to 3840px Surface Hub). Unlike Material Design's single-seed generative approach, Fluent uses a brand-token injection model: you provide a brand ramp (16 shades of your brand color), and the system maps those shades to 160+ semantic alias tokens.
+
+**Key architectural distinction:** Fluent 2 separates "global tokens" (platform-level primitives like `colorNeutralBackground1`), "alias tokens" (semantic mappings like `colorBrandBackground`), and "component tokens" (per-component overrides). The alias layer is where theming happens. Swapping the alias-to-global mapping changes the entire application's appearance.
+
+**Fluent is context-aware.** The same `Dialog` component renders with Acrylic material on Windows 11 (where the compositor supports real-time blur), falls back to a solid color with subtle noise texture on web (where backdrop-filter has performance implications), and uses Mica on Windows 11 desktop app backgrounds. Material selection is not a design choice -- it is a platform capability negotiation.
+
+## Details
+
+### The Five Foundational Elements
+
+**Light** in Fluent manifests as reveal highlight -- a lighting effect that follows the cursor and illuminates interactive surface boundaries. On hover, a radial gradient (diameter ~120px, falloff from 12% white at center to 0% at edge) follows the pointer, making borders and clickable regions glow. This effect answers the question "what can I interact with?" without requiring explicit affordances.
+
+**Reveal highlight implementation (CSS approximation):**
+
+```css
+.fluent-reveal {
+  position: relative;
+  overflow: hidden;
+}
+.fluent-reveal::before {
+  content: '';
+  position: absolute;
+  inset: 0;
+  background: radial-gradient(
+    circle 120px at var(--mouse-x) var(--mouse-y),
+    rgba(255, 255, 255, 0.12) 0%,
+    rgba(255, 255, 255, 0.04) 40%,
+    transparent 100%
+  );
+  pointer-events: none;
+}
+```
+
+The JavaScript component tracks `mousemove` events and updates `--mouse-x` / `--mouse-y` CSS custom properties. On Windows 11 with WinUI 3, this is handled natively by the compositor at 60fps with no JavaScript overhead.
+
+**Depth** uses three explicit layers: Base (z=0, app content), Raised (z=8, cards and commanding surfaces), and Overlay (z=32, dialogs, flyouts, teaching tips). Each layer has a corresponding shadow token:
+
+```
+shadow2:    0 1px 2px rgba(0,0,0,0.14), 0 0 2px rgba(0,0,0,0.12)     (Raised)
+shadow4:    0 2px 4px rgba(0,0,0,0.14), 0 0 2px rgba(0,0,0,0.12)     (Commanding)
+shadow8:    0 4px 8px rgba(0,0,0,0.14), 0 0 2px rgba(0,0,0,0.12)     (Cards)
+shadow16:   0 8px 16px rgba(0,0,0,0.14), 0 0 2px rgba(0,0,0,0.12)    (Flyouts)
+shadow28:   0 14px 28px rgba(0,0,0,0.24), 0 0 8px rgba(0,0,0,0.20)   (Dialogs)
+shadow64:   0 32px 64px rgba(0,0,0,0.24), 0 0 8px rgba(0,0,0,0.20)   (Full overlays)
+```
+
+Each shadow uses a dual-layer technique: a larger spread for the ambient term and a tighter spread for the key light.
+
+**Motion** uses four duration tiers and two easing families:
+
+```
+Duration:
+  ultraFast:   50ms     (checkbox check, toggle snap)
+  fast:        100ms    (button press feedback)
+  normal:      200ms    (panel slide, card expand)
+  slow:        300ms    (page transition, dialog enter)
+  slower:      500ms    (connected animation, full-screen morph)
+
+Easing:
+  accelerate:  cubic-bezier(0.9, 0.1, 1.0, 0.2)     (element exiting)
+  decelerate:  cubic-bezier(0.1, 0.9, 0.2, 1.0)     (element entering)
+  linear:      cubic-bezier(0, 0, 1, 1)               (progress bars, spinners)
+```
+
+**Scale** defines four responsive tiers with specific adaptation rules:
+
+```
+Small:    320px - 479px    Single column, stacked nav, bottom sheet
+Medium:   480px - 1023px   Flexible column, rail nav, side panel
+Large:    1024px - 1365px  Multi-column, sidebar nav, inline panel
+XLarge:   1366px+          Extended layout, expanded sidebar, canvas
+```
+
+### Acrylic and Mica Materials
+
+**Acrylic** is a translucent material that blurs the content directly behind it. It comes in two variants:
+
+- **Background Acrylic:** Blurs content from behind the application window (the desktop, other windows). Used for navigation panes and sidebars. Tint: 80% opacity of the surface color with a Gaussian blur at 30px radius and a noise texture at 2% opacity.
+- **In-app Acrylic:** Blurs content within the application (the content area beneath a flyout or command bar). Used for command bars, context menus, and flyouts. Tint: 70% opacity, blur: 20px, noise: 2%.
+
+**Acrylic recipe (CSS for web approximation):**
+
+```css
+.acrylic-background {
+  background-color: rgba(255, 255, 255, 0.8); /* tint layer */
+  backdrop-filter: blur(30px) saturate(125%); /* blur + saturation boost */
+}
+.acrylic-background::after {
+  content: '';
+  position: absolute;
+  inset: 0;
+  background: url('noise.png'); /* 2% noise texture */
+  opacity: 0.02;
+  pointer-events: none;
+}
+```
+
+**Mica** is a material unique to Windows 11 that samples the user's desktop wallpaper and creates a subtle, static tint for the app's title bar and background. Unlike Acrylic, Mica does not blur in real-time -- it samples once and applies a static color derived from the wallpaper. This makes it dramatically cheaper to render.
+
+**Mica properties:**
+
+```
+Base Mica:       Wallpaper sample at 80% luminance, no blur, very subtle tint
+Mica Alt:        Wallpaper sample at 70% luminance, slightly more opaque
+Fallback (web):  Solid colorNeutralBackground1 (#FFFFFF light / #292929 dark)
+```
+
+**Material selection decision procedure:**
+
+1. Is this a window/title bar background? -> **Mica**
+2. Is this a navigation pane behind content? -> **Background Acrylic**
+3. Is this a flyout/menu overlaying content? -> **In-app Acrylic**
+4. Is the platform unable to composite blur? -> **Solid fallback with noise texture**
+5. Has the user enabled "Transparency effects: Off"? -> **Solid fallback, no blur, no noise**
+
+### Connected Animations
+
+Connected animations create visual continuity between views by morphing a shared element from its position in the source view to its position in the destination view.
+
+**The three-phase model:**
+
+1. **Prepare** (0ms): Snapshot the source element's bounds, corner radius, and opacity.
+2. **Animate** (300ms, `decelerate` easing): Interpolate position, size, corner radius, and opacity from source to destination.
+3. **Complete** (0ms): Hand off rendering to the destination element.
+
+**Concrete example -- file explorer thumbnail (80x80, radius 4px, at position 120,340) morphing to full image preview (1200x800, radius 0px, at 0,0):** All properties -- position, size, corner radius -- interpolate over 300ms with `decelerate` easing. On web, implement using the FLIP technique (First-Last-Invert-Play): snapshot source bounds, position destination, calculate the inverse transform, then animate from inverted to natural position.
+
+### Responsive Containers and Layout
+
+Fluent 2 uses container-based responsive design rather than viewport-based. A `Card` adapts to its container width, not the window width. This means the same Card component works in a full-width layout, a split-view panel, and a Teams tab without media query overrides.
+
+**Container query breakpoints:** Use `container-type: inline-size` on parent elements. Compact (<300px): stack vertically, center actions. Standard (300-599px): row layout with trailing actions. Extended (600px+): grid with metadata column. This replaces viewport media queries entirely.
+
+**Fluent's 4px grid:** All spacing values are multiples of 4px: `XXS: 2px` (icon-to-text), `XS: 4px` (compact padding), `S: 8px` (standard gap), `M: 12px` (card padding), `L: 16px` (section gap), `XL: 20px` (panel margin), `XXL: 24px` (page margin).
+
+### Token Theming Architecture
+
+Fluent 2 tokens follow a three-tier hierarchy: **Global -> Alias -> Component**.
+
+**Brand ramp injection:** You supply 16 shades (shade10 through shade160) spanning L*=5 (darkest) to L*=98 (lightest). Example for a blue brand: shade10 `#020305`, shade40 `#1B2E54`, shade80 `#4F72B8` (primary), shade120 `#B1CCF2`, shade160 `#FAFCFF`.
+
+```
+
+The alias layer maps these brand shades to semantic roles:
+
+```
+
+colorBrandBackground: brand[80] (primary buttons)
+colorBrandBackgroundHover: brand[70] (primary hover)
+colorBrandBackgroundPressed: brand[40] (primary pressed)
+colorBrandForeground1: brand[80] (links, active text)
+colorBrandStroke1: brand[80] (focus rings)
+
+```
+
+**Neutral palette (auto-generated):** Fluent generates 28 neutral shades from the brand hue with reduced chroma:
+
+```
+
+colorNeutralBackground1: #FFFFFF (light) / #292929 (dark)
+colorNeutralBackground2: #FAFAFA / #1F1F1F
+colorNeutralBackground3: #F5F5F5 / #141414
+colorNeutralForeground1: #242424 / #FFFFFF
+colorNeutralForeground2: #424242 / #D6D6D6
+colorNeutralForeground3: #616161 / #ADADAD
+colorNeutralStroke1: #D1D1D1 / #404040
+colorNeutralStroke2: #E0E0E0 / #333333
+
+````
+
+**Theme application in Fluent UI React v9:**
+
+```jsx
+import { FluentProvider, webLightTheme, createLightTheme } from '@fluentui/react-components';
+
+const customTheme = createLightTheme(myBrand);
+
+function App() {
+  return (
+    <FluentProvider theme={customTheme}>
+      <MyApplication />
+    </FluentProvider>
+  );
+}
+````
+
+### Anti-Patterns
+
+**Using Acrylic material everywhere.** Acrylic triggers real-time compositor blur which is expensive. Applying Acrylic to scrollable content areas, list items, or the main canvas causes frame drops, especially on integrated GPUs. Acrylic is reserved for commanding surfaces (nav pane, command bar, flyout) -- surfaces that overlay content. Use Mica for window backgrounds and solid colors for content areas.
+
+**Ignoring the transparency effects system setting.** Windows allows users to disable transparency effects (Settings > Personalization > Colors > Transparency effects: Off). When disabled, Acrylic and Mica must fall back to solid colors. If your CSS relies on `backdrop-filter` without a solid fallback, users with transparency off see a fully transparent (invisible) surface. Always provide `background-color` as a base layer beneath `backdrop-filter`.
+
+**Applying reveal highlight to non-interactive elements.** Reveal highlight signals interactivity. Placing it on static text blocks, images, or decorative elements teaches users that the light effect is meaningless, destroying its value as an affordance signal. Only apply reveal to elements that respond to click or tap: buttons, list items, cards with actions, navigation items.
+
+**Using viewport media queries instead of container queries.** A Fluent Card in a Teams side panel at 400px width should render in its compact layout, but a viewport media query at 1920px window width would give it the extended layout. Container queries ensure components adapt to their actual available space, not the window size. This is especially critical in embedded contexts (Teams tabs, SharePoint web parts, Outlook add-ins) where the viewport is not the component's container.
+
+**Flat brand ramp with insufficient contrast spread.** A brand ramp where shade10 through shade160 spans only L*=20 to L*=70 (instead of L*=5 to L*=98) produces alias tokens that fail WCAG AA contrast. `colorBrandForeground1` (brand[80]) on `colorNeutralBackground1` (#FFFFFF) must achieve 4.5:1 contrast. If brand[80] is too light (L\*>55), all branded text becomes illegible. Test the brand ramp extremes against both light and dark neutral backgrounds before deployment.
+
+### Real-World Examples
+
+**Microsoft Teams** is the canonical Fluent 2 implementation. The sidebar uses Background Acrylic (30px blur of the desktop). The chat pane uses `colorNeutralBackground1` (solid). Hover over a message reveals a command bar with In-app Acrylic. The compose box sits at `shadow4` elevation. When switching between chats, message avatars use connected animations -- the avatar morphs from the chat list position to the message header position over 300ms with decelerate easing.
+
+**Windows 11 File Explorer** demonstrates Mica on the title bar and navigation pane header, with the file list on a solid `colorNeutralBackground1`. Folder thumbnails use connected animations when transitioning to the preview pane. Reveal highlight illuminates folder items on hover, with the light effect flowing across adjacent items as the cursor moves through the list.
+
+**Visual Studio Code (Fluent theme)** shows the token theming system at scale: 160+ alias tokens are remapped to match VS Code's syntax highlighting and panel structure. The brand ramp uses VS Code's signature blue (`#007ACC` at brand[80]), generating all interactive states from hover (`brand[70]`: `#0066B8`) to pressed (`brand[40]`: `#003F73`) automatically from the 16-shade ramp.
+
+**Microsoft Loop** uses container-responsive layouts throughout. A Loop component embedded in a Teams message at 280px width renders in compact mode (stacked, minimal chrome). The same component in a full Loop page at 900px renders in extended mode (multi-column, full toolbar). Container queries drive all layout shifts, making the components truly portable across Microsoft 365 hosts.
+
+## Source
+
+Microsoft Fluent 2 Design System (fluent2.microsoft.design, 2024). Fluent UI React v9 documentation (react.fluentui.dev). Windows App SDK design guidelines. MSDN documentation on Acrylic, Mica, and connected animations. WinUI 3 Gallery app source code.
+
+## Process
+
+1. Read the instructions and examples in this document.
+2. Apply the patterns to your implementation, adapting to your specific context.
+3. Verify your implementation against the details and edge cases listed above.
+
+## Harness Integration
+
+- **Type:** knowledge -- this skill is a reference document, not a procedural workflow.
+- **No tools or state** -- consumed as context by other skills and agents.
+
+## Success Criteria
+
+- The patterns described in this document are applied correctly in the implementation.
+- Edge cases and anti-patterns listed in this document are avoided.

package/dist/agents/skills/codex/design-fluent-design/skill.yaml

@@ -0,0 +1,35 @@
+name: design-fluent-design
+version: '1.0.0'
+description: Microsoft Fluent 2 design system covering light/depth/motion/material/scale, acrylic material, reveal highlight, connected animations, responsive containers, and token theming
+cognitive_mode: advisory-guide
+type: knowledge
+tier: 3
+triggers:
+  - manual
+platforms:
+  - claude-code
+  - gemini-cli
+  - cursor
+  - codex
+tools: []
+paths: []
+related_skills:
+  - design-elevation-shadow
+  - design-motion-principles
+  - design-token-architecture
+stack_signals: []
+keywords:
+  - fluent-design
+  - Microsoft
+  - acrylic
+  - reveal-highlight
+  - connected-animations
+  - responsive-containers
+  - Windows
+  - Teams
+metadata:
+  author: community
+state:
+  persistent: false
+  files: []
+depends_on: []

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

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

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

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