@harness-engineering/cli 1.23.2 → 1.24.1

package/dist/agents/skills/cursor/design-imagery-photography/SKILL.md

@@ -0,0 +1,172 @@
+# Imagery and Photography
+
+> Image in design — art direction, aspect ratios, focal point composition, image treatments (duotone, overlay, blur), placeholder strategy, and the role of image as hero vs. supporting element
+
+## When to Use
+
+- Defining image art direction for a product, marketing site, or editorial platform
+- Choosing aspect ratios for responsive image containers across breakpoints
+- Selecting or commissioning photography that aligns with brand tone
+- Applying image treatments (duotone, gradient overlays, blur) for visual consistency
+- Designing placeholder and loading states for image-heavy interfaces
+- Deciding when an image should dominate the layout (hero) vs. support text content
+- Building an image style guide for a design system
+- Evaluating whether product photography communicates the intended emotional tone
+
+## Instructions
+
+1. **Define art direction before sourcing images.** Art direction is the set of constraints that makes 100 different photographs feel like they belong to the same product. Without it, every image is an independent aesthetic decision. Define these attributes explicitly:
+   - **Subject matter:** What is in the frame? People, products, landscapes, abstract textures?
+   - **Color temperature:** Warm (golden hour, tungsten) or cool (overcast, blue hour, fluorescent)?
+   - **Contrast level:** High contrast (dramatic shadows, punchy blacks) or low contrast (soft, flat, editorial)?
+   - **Depth of field:** Shallow (blurred background, subject isolation) or deep (everything in focus, environmental)?
+   - **Composition style:** Centered, rule-of-thirds, asymmetric, negative space dominant?
+   - **Human presence:** Faces visible, silhouettes, hands only, no people?
+
+   Airbnb's art direction specifies: warm color temperature, natural lighting, shallow-to-medium depth of field, human presence with faces visible, environments that feel lived-in (not staged). Every listing photo that matches these constraints reinforces the brand; every photo that violates them feels off-brand.
+
+2. **Choose aspect ratios systematically, not per-image.** Aspect ratios are layout constraints, not creative decisions. Define a small set of ratios for your product and use them consistently:
+
+   | Ratio | Decimal | Use Case                                                    |
+   | ----- | ------- | ----------------------------------------------------------- |
+   | 1:1   | 1.0     | Avatars, thumbnails, Instagram-style grids, product squares |
+   | 4:3   | 1.33    | Traditional photography, cards, content thumbnails          |
+   | 3:2   | 1.5     | 35mm photography standard, editorial, landscape cards       |
+   | 16:9  | 1.78    | Video, hero banners, widescreen presentations               |
+   | 21:9  | 2.33    | Ultrawide hero banners, cinematic crops                     |
+   | 2:3   | 0.67    | Portrait cards, mobile-first hero images, book covers       |
+   | 9:16  | 0.56    | Stories format, mobile full-screen, vertical video          |
+
+   Decision procedure: pick 2-3 ratios for your product. Use the same ratio for all instances of a component type. A card grid should never mix 4:3 and 16:9 cards — the inconsistency disrupts the layout rhythm. Stripe uses 16:9 for product screenshots and 1:1 for team/avatar photos — two ratios, consistently applied.
+
+3. **Compose images around a single focal point.** Every image needs one dominant subject that the eye locks onto first. Measure focal point effectiveness with the "squint test" — squint until the image blurs and see what remains prominent. If nothing stands out, the image lacks a focal point.
+   - **Rule of thirds:** Place the focal point at one of the four intersection points of a 3x3 grid overlay. This creates dynamic tension and prevents the static feel of dead-center composition.
+   - **Negative space direction:** The focal point should have breathing room in the direction it faces or moves. A person looking right needs more space on the right side of the frame.
+   - **Text overlay consideration:** If text will be placed over the image, the focal point must not compete with the text zone. Apple's product hero images place the device in the lower 60% of the frame, leaving the upper 40% as a clean gradient zone for headline text.
+
+4. **Apply image treatments for brand cohesion, not decoration.** Treatments are systematic filters that normalize disparate source imagery into a unified visual language:
+   - **Duotone** — Maps the image's luminance range to two colors (shadow color and highlight color). Spotify uses duotone aggressively: editorial playlist covers map artist photos to brand-adjacent color pairs (e.g., deep purple shadows + electric green highlights). Duotone provides: strong brand reinforcement, visual unity across diverse source images, and automatic color palette compliance. Implementation: `mix-blend-mode: multiply` on a gradient overlay, or CSS `filter: grayscale(100%)` combined with a colored overlay.
+   - **Color overlay** — A semi-transparent color layer over the image. Simpler than duotone, maintains some photographic realism. Use 40-70% opacity for text-over-image readability. Stripe applies blue-tinted overlays (`rgba(6, 27, 49, 0.6)`) on product screenshots to integrate them with the page's navy color scheme.
+   - **Blur** — Background blur (`backdrop-filter: blur(20px)`) creates depth and hierarchy. Apple's iOS uses blur extensively for layered surfaces. Use blur to de-emphasize background images when foreground content needs focus. Avoid blur values below 8px — they look like rendering errors rather than intentional effects.
+   - **Grain/noise** — Adds a subtle film-grain texture. Humanizes digital imagery, adds tactile quality. Use at 3-8% opacity for subtlety. Above 10%, grain dominates and degrades image quality.
+
+5. **Design image placeholders as first-class UI states.** Users see placeholders during loading, on error, and when no image exists. Each state needs deliberate design:
+   - **Loading placeholder:** Use a solid color matching the image's dominant color (extract via server-side color analysis), a low-resolution blurred preview (LQIP — 20x20px inline base64 scaled up with CSS blur), or a skeleton shimmer animation. Facebook pioneered the shimmer placeholder — a gradient animation that signals "content is coming" without committing to a shape.
+   - **Error placeholder:** A branded fallback — not a broken image icon. Use a solid brand color with a subtle icon (camera with X, or brand logo at low opacity). Never show the browser's default broken-image icon.
+   - **Empty state placeholder:** When no image has been uploaded, show an actionable prompt (dashed border with "Add photo" text and camera icon) rather than a blank space.
+
+   Concrete implementation: use `<img>` with `loading="lazy"`, `decoding="async"`, a `background-color` matching the image's average color, and an `onerror` handler that swaps to the branded fallback. The CSS `aspect-ratio` property on the container prevents layout shift during loading.
+
+6. **Distinguish hero images from supporting images in layout weight.** Hero images dominate the viewport and establish emotional tone. Supporting images illustrate specific content without commanding attention.
+
+   | Attribute         | Hero Image                         | Supporting Image                           |
+   | ----------------- | ---------------------------------- | ------------------------------------------ |
+   | Viewport coverage | 60-100% of viewport width          | 25-50% of column width                     |
+   | Aspect ratio      | Wide (16:9, 21:9) or full-bleed    | Standard (4:3, 3:2, 1:1)                   |
+   | Text overlay      | Common — headline + CTA over image | Rare — text adjacent, not overlaid         |
+   | Image quality     | Maximum resolution, art-directed   | Adequate resolution, may be user-generated |
+   | Count per page    | 1 (at most 2 in long-scroll pages) | Multiple                                   |
+   | Loading priority  | `fetchpriority="high"`, eager load | `loading="lazy"`, low priority             |
+
+   Apple's product pages use exactly one hero image per section — the iPhone floating on a black background, full-bleed, no competing elements. Below it, supporting images show specific features at 50% viewport width with adjacent text blocks.
+
+## Details
+
+### Responsive Image Art Direction
+
+Different viewport sizes may need different crops, not just scaled versions of the same image. The `<picture>` element with `<source>` tags enables art direction:
+
+```html
+<picture>
+  <source media="(min-width: 1024px)" srcset="hero-wide.jpg" />
+  <source media="(min-width: 640px)" srcset="hero-medium.jpg" />
+  <img src="hero-mobile.jpg" alt="Product showcase" />
+</picture>
+```
+
+The wide crop might show the full product in context (16:9). The medium crop centers on the product (4:3). The mobile crop is a tight vertical crop of just the product face (2:3). This is not responsive scaling — it is three different compositions optimized for three viewport contexts. Airbnb uses art direction for listing hero images: desktop shows the full room (16:9), mobile shows a tighter crop focused on the most compelling detail (4:3).
+
+### Image Performance as Design Constraint
+
+Image file size directly impacts perceived design quality because slow-loading images degrade the experience. Design constraints:
+
+- **Hero images:** Target 200KB maximum for LCP (Largest Contentful Paint). Use WebP or AVIF format. AVIF achieves ~50% smaller files than JPEG at equivalent quality.
+- **Thumbnails:** Target 15-30KB each. Generate server-side at exact display dimensions — never send a 2000px image for a 200px thumbnail.
+- **LQIP previews:** 200-500 bytes inline base64. A 20x20px JPEG at quality 20 is ~300 bytes and, when scaled with CSS blur, creates an effective placeholder.
+- **Cumulative Layout Shift:** Always declare `width` and `height` attributes on `<img>` tags, or use `aspect-ratio` CSS on containers. A hero image that causes 0.15 CLS (shifting the headline down by 400px on load) feels broken regardless of its artistic quality.
+
+### Anti-Patterns
+
+1. **Aspect Ratio Chaos.** A card grid where each card uses whatever aspect ratio the source image happens to be — some 4:3, some 16:9, some 1:1 — creating a ragged, uneven layout. Fix: enforce a single aspect ratio per component type using CSS `aspect-ratio` and `object-fit: cover`. Crop the image to fit the container, never stretch or letterbox.
+
+2. **Unanchored Text Overlays.** Placing white text over a photograph without a scrim, gradient, or sufficient contrast zone. The text is legible over the dark tree but disappears over the bright sky. Fix: always apply a gradient scrim (`background: linear-gradient(to top, rgba(0,0,0,0.7) 0%, transparent 60%)`) from the text edge toward the image. Apple uses a bottom-to-top black gradient on every text-over-image hero, ensuring minimum 4.5:1 contrast ratio regardless of image content.
+
+3. **Decorative Images Without Alt Text Strategy.** Marking all images as `alt=""` (decorative) or giving all images verbose literal descriptions. Neither is correct universally. Fix: hero images that convey emotional tone should have brief, contextual alt text ("Team collaborating in a sunlit office"). Decorative texture or pattern backgrounds should have `alt=""`. Product images should have descriptive alt text that adds information not available in adjacent text.
+
+4. **Stock Photo Uncanny Valley.** Using obviously staged stock photography — perfectly diverse groups of smiling people in a pristine office — that reads as inauthentic. Users have developed strong pattern recognition for stock photography and subconsciously distrust it. Fix: commission custom photography with real employees/users, use candid rather than posed shots, or use abstract/illustrated imagery that does not pretend to be photographic.
+
+5. **Loading State Neglect.** No placeholder during image load, resulting in layout shift and a flash of empty space. On slow connections, the page is broken for 2-5 seconds. Fix: implement LQIP (Low Quality Image Placeholder) with inline base64 blur-up, use CSS `aspect-ratio` to reserve space, and add skeleton shimmer animation for content-heavy grids.
+
+### Real-World Examples
+
+**Apple — Photography as Product.** Apple's product photography is the product page. The iPhone is the hero — shot on black or white backgrounds with controlled studio lighting, no environmental context, zero distractions. The device fills 60-80% of the viewport. Text is minimal and placed above or below, never competing with the product. Color accuracy is critical — the "Midnight" iPhone must look identical across apple.com, the Apple Store app, and physical retail displays. Apple achieves this with ICC color profiles embedded in every image and strict display calibration standards. Key lesson: when the product is the visual, image quality IS brand quality.
+
+**Spotify — Duotone as Brand System.** Spotify's editorial playlists (RapCaviar, Today's Top Hits, Discover Weekly) apply duotone treatments to artist photography, mapping the image to two-color palettes that shift seasonally. The treatment transforms diverse source photography — candid concert shots, studio portraits, street photography — into a unified visual system. Each playlist has a signature color pair (RapCaviar: black + gold; Discover Weekly: greens). The duotone treatment is so strongly associated with Spotify that users recognize it outside the app. Key lesson: a strong image treatment can become a brand asset more recognizable than a logo.
+
+**Airbnb — Warm Photography as Brand Promise.** Every listing photo on Airbnb is evaluated against art direction guidelines: warm color temperature, natural light, human-scale perspective (shot from eye level, not drone height), and environmental context (the room in use, not sterile and empty). Airbnb's photo quality directly correlates with booking rates — listings with professionally shot photos following these guidelines see 40% more bookings. The platform provides host photography guides that encode these art direction principles for non-professional photographers. Key lesson: art direction is not just for marketing — it is a product quality metric.
+
+**Vercel — Monochrome Imagery as Developer Identity.** Vercel uses almost exclusively monochrome or desaturated imagery. Product screenshots are rendered in dark-mode with the Vercel color palette. Marketing photography, when used, is desaturated and cool-toned. The restraint signals developer seriousness — "we do not dress up our product with colorful imagery because the product speaks for itself." Key lesson: the absence of vibrant photography is itself an art direction decision.
+
+### Image Accessibility Beyond Alt Text
+
+Accessible imagery extends beyond alt text to include:
+
+- **Color independence:** Images that encode information through color alone (a chart screenshot, a map with color-coded regions) must have supplementary text or non-color encodings. A product screenshot showing a red error banner should include alt text that describes the error state, not just "product screenshot."
+- **Motion and autoplay:** Hero images implemented as video loops or animated GIFs must respect `prefers-reduced-motion`. Provide a static fallback: `<picture><source media="(prefers-reduced-motion: no-preference)" srcset="hero-animated.webm" type="video/webm" /><img src="hero-static.jpg" alt="..." /></picture>`.
+- **Text in images:** Avoid baking text into images. Text rendered as part of a photograph or illustration cannot be resized, translated, or read by screen readers. If text must appear over an image, use HTML text with CSS positioning — never Photoshop the text into the image file.
+- **Flashing content:** Images or videos with flashing content (strobe effects, rapid color changes) can trigger seizures. WCAG 2.3.1 requires no more than 3 flashes per second. This applies to animated hero images, parallax scroll effects, and autoplay video backgrounds.
+
+### Image Governance at Scale
+
+Products with user-generated or editorial imagery need governance to maintain art direction:
+
+- **Automated quality gates:** Use server-side image analysis to enforce minimum resolution (reject uploads below 1200px on the long edge), aspect ratio compliance (auto-crop to the component's target ratio), and file size limits (reject uncompressed TIFFs).
+- **Color analysis for consistency:** Extract the dominant color palette from uploaded images and flag those that deviate significantly from the brand's color temperature. Airbnb uses color analysis to surface listing photos that look artificially blue-shifted (common in real estate photography) for manual review.
+- **Focal point metadata:** Allow editors to mark the focal point of each image (a click-to-set tool in the CMS). Use this metadata for responsive cropping — the crop algorithm keeps the focal point visible at every breakpoint. WordPress and Cloudinary both support focal-point-aware cropping.
+- **Expiration and freshness:** Photography that shows dated technology (old phones, outdated UI), expired seasonal content (Christmas imagery in March), or former employees should be flagged for review. Set metadata expiration dates on time-sensitive imagery.
+
+### Image Format Decision Matrix
+
+| Format | Best For                           | Compression                              | Browser Support | Transparency           |
+| ------ | ---------------------------------- | ---------------------------------------- | --------------- | ---------------------- |
+| WebP   | General purpose, photos + graphics | Lossy + lossless, ~30% smaller than JPEG | 97%+ global     | Yes (lossy + lossless) |
+| AVIF   | High-quality photos, hero images   | Lossy, ~50% smaller than JPEG            | 92%+ global     | Yes                    |
+| JPEG   | Fallback for legacy browsers       | Lossy only                               | 100%            | No                     |
+| PNG    | Screenshots with text, UI elements | Lossless only, large files               | 100%            | Yes                    |
+| SVG    | Icons, logos, illustrations        | Vector, infinite scale                   | 100%            | Yes                    |
+
+Decision procedure: serve AVIF with WebP fallback and JPEG as last resort using `<picture>` with multiple `<source>` elements. Use PNG only for screenshots containing text that must remain pixel-sharp. Use SVG for everything that is not photographic.
+
+## Source
+
+- Apple Human Interface Guidelines — Images and Icons (2024)
+- Airbnb Design — Photography Style Guide
+- Spotify Design — Visual Identity Guidelines
+- Web.dev — Image Performance Best Practices (2024)
+- WCAG 2.2 — Non-text Content (1.1.1), Images of Text (1.4.5), Three Flashes (2.3.1)
+
+## 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/cursor/design-imagery-photography/skill.yaml

@@ -0,0 +1,36 @@
+name: design-imagery-photography
+version: "1.0.0"
+description: Image in design — art direction, aspect ratios, focal point, image treatments (duotone, overlay, blur), placeholder strategy, image as hero vs supporting
+stability: static
+cognitive_mode: advisory-guide
+type: knowledge
+tier: 3
+triggers:
+  - manual
+platforms:
+  - claude-code
+  - gemini-cli
+  - cursor
+  - codex
+tools: []
+paths: []
+related_skills:
+  - design-brand-consistency
+  - design-visual-hierarchy
+stack_signals: []
+keywords:
+  - imagery
+  - photography
+  - art-direction
+  - aspect-ratio
+  - focal-point
+  - duotone
+  - overlay
+  - placeholder
+  - hero-image
+metadata:
+  author: community
+state:
+  persistent: false
+  files: []
+depends_on: []

package/dist/agents/skills/cursor/design-information-architecture/SKILL.md

@@ -0,0 +1,155 @@
+# Information Architecture
+
+> Structuring information — card sorting, tree testing, mental models, labeling systems, organization schemes, findability
+
+## When to Use
+
+- Designing the navigation structure of a new application, website, or documentation site
+- Reorganizing an existing product whose navigation has grown organically and become inconsistent or confusing
+- Planning a content-heavy experience (knowledge base, documentation, settings page, admin panel) where users must find specific items among hundreds
+- Conducting user research to understand how your audience groups, labels, and prioritizes information
+- Designing search and filtering systems where findability depends on correct categorization
+- Merging or migrating content from multiple sources into a unified structure
+- Auditing a product where users report difficulty finding features — "I didn't know that existed" is an IA failure
+- Building a design system where component organization, naming, and discoverability affect adoption
+
+## Instructions
+
+1. **Start with user mental models, not organizational charts.** The number one IA mistake is structuring information to match the company's internal departments rather than the user's mental model. Users do not think in terms of "Platform Engineering" vs "Infrastructure Services" — they think "I need to deploy my app." Card sorting reveals how real users group and label information. Run an open card sort (users create their own categories) with 15-20 participants before committing to any navigation structure. Spotify's music organization follows listener mental models (mood, activity, genre) rather than music industry categories (label, distributor, format).
+
+2. **Use the four organization schemes and choose deliberately.** Every information structure uses one or more of these schemes:
+
+   | Scheme        | Principle                | Best For                             | Example                                         |
+   | ------------- | ------------------------ | ------------------------------------ | ----------------------------------------------- |
+   | Alphabetical  | A-Z ordering             | Reference lookups, known-item search | Contact list, API reference, country selector   |
+   | Chronological | Time-based ordering      | Activity feeds, logs, history        | Email inbox, commit history, notification feed  |
+   | Topical       | Subject-based grouping   | Learning, exploration, browsing      | Documentation sections, product categories      |
+   | Task-based    | Action-oriented grouping | Goal-driven workflows, tool UIs      | "Create," "Manage," "Analyze" navigation groups |
+
+   Most products need a hybrid. GitHub uses topical for repository tabs (Code, Issues, Pull Requests) but chronological within each tab (newest issues first). Material Design's documentation uses topical at the top level (Foundations, Styles, Components) and alphabetical within each section. The mistake is defaulting to topical when task-based would serve users better — users come to tools to accomplish tasks, not to browse topics.
+
+3. **Apply the principle of progressive disclosure to information depth.** Not all information is equally important, and showing everything at once overwhelms. Structure information in layers: Level 1 (always visible) is the 3-7 most important categories. Level 2 (one click away) is the subcategories within each category. Level 3 (two clicks away) is the individual items. Amazon's category navigation demonstrates this: "Electronics" (L1) expands to "Computers & Accessories" (L2), which leads to "Laptops" (L3). Each level shows only what is relevant at that depth. If your top-level navigation has more than 7 items, your IA needs another layer of hierarchy.
+
+4. **Label for recognition, not recall.** Navigation labels must be instantly understood without context or explanation. "Settings" is universally recognized. "Configuration Management" requires the user to parse jargon. "Dashboard" is clear. "Operational Overview" is not. Test labels with a 5-second comprehension test: show the label to a user for 5 seconds, then ask what they would expect to find behind it. If more than 20% of users guess wrong, the label fails. Material Design's settings organization uses plain labels — "Display," "Sound," "Notifications" — not "Visual Configuration," "Audio Management," "Alert Preferences."
+
+5. **Design for three findability strategies simultaneously.** Users find information in three ways, and your IA must support all three:
+   - **Known-item search:** The user knows exactly what they want. Support: search bar with autocomplete, direct URL patterns, keyboard shortcuts. GitHub's command palette (Cmd+K) serves this — type "settings" and jump directly to repository settings.
+   - **Exploratory browsing:** The user knows roughly what they need but not where it is. Support: clear category labels, breadcrumbs, progressive disclosure, "related items" links.
+   - **Re-finding:** The user found something before and needs it again. Support: recent items, bookmarks/favorites, persistent URLs, browser history compatibility.
+
+   If your product only supports one findability strategy, two-thirds of user navigation attempts will fail.
+
+6. **Validate structure with tree testing before building.** Tree testing (also called reverse card sorting) evaluates findability without visual design bias. Present users with the navigation tree as a text hierarchy and ask them to find specific items: "Where would you find the setting to change your notification preferences?" If fewer than 70% of users navigate to the correct location, the structure needs revision. Tree testing is cheaper and faster than usability testing on a built prototype and catches structural problems that no amount of visual polish can fix.
+
+7. **Use consistent depth and parallel structure.** If "Settings" has three subcategories and "Account" has twelve, the IA is unbalanced. Aim for consistent breadth at each level (3-7 items) and consistent depth (2-3 levels). Parallel structure means sibling items should be the same type: if one top-level item is a category ("Products") and another is an action ("Create Report"), the IA is mixing metaphors. Apple's System Settings in macOS Ventura reorganized from a flat grid of 30+ panes into a hierarchical sidebar with consistent grouping — each group contains 3-6 related settings panes.
+
+8. **Design the labeling system as a controlled vocabulary.** Consistent labeling means the same concept always uses the same word across the entire product. If the navigation says "Projects," the empty state should say "No projects yet" not "No workspaces found." If the settings say "Notifications," the onboarding should say "Set up your notifications" not "Configure your alerts." Create a terminology guide that maps each concept to exactly one label and enforce it in code review. Slack is disciplined about this: a "channel" is always a "channel" — never a "room," "group," or "chat."
+
+## Details
+
+### Card Sorting Methods
+
+**Open card sort:** Participants are given 30-60 content items on cards and asked to group them into categories they create and name themselves. This reveals how users naturally organize the information. Run with 15-20 participants. Analyze by looking for agreement: if 80% of participants put "billing" and "invoices" in the same group, they belong together. If "integrations" splits 50/50 between "settings" and "tools," you have an IA ambiguity that needs resolution.
+
+**Closed card sort:** Participants are given the same content items but must sort them into pre-defined categories. This tests whether your proposed category labels make sense to users. Run after an open sort has suggested candidate categories. If users consistently misplace items in a category, the category label is misleading or the item belongs elsewhere.
+
+**Hybrid card sort:** Participants sort into pre-defined categories but can create new ones if nothing fits. This is the most efficient single-round approach — it tests your structure while still surfacing surprises. Use when time allows only one sort round.
+
+**Remote tools:** OptimalSort, Maze, and UserZoom support remote card sorting at scale. Remote sorts typically need 30-50 participants for statistical reliability because engagement varies. In-person sorts with 15 participants often yield cleaner data because participants are more attentive.
+
+### Mental Model Alignment
+
+A mental model is the user's internal representation of how a system works. When the IA matches the mental model, navigation feels intuitive. When it does not, every interaction requires conscious effort.
+
+**Identifying mental models:** Interview users before designing the IA. Ask "How would you describe the main parts of [product type]?" and "If you needed to [task], where would you start?" The language and groupings users use reveal their mental model. If most users describe email as "inbox, sent, drafts, trash" — that is the mental model. Structuring it as "received communications, dispatched items, pending compositions, deleted materials" maps to the same data with none of the intuitive recognition.
+
+**Model mismatch signals:** High search usage for items that exist in the navigation, support tickets asking "Where is X?", analytics showing users visit 3-4 wrong pages before finding the right one, and A/B tests where "reorganized navigation" consistently outperforms "current navigation" all signal mental model mismatch.
+
+**Evolving models:** User mental models change as they gain expertise. A novice's model of a code editor is "write code, run code, see errors." An expert's model includes "debug, profile, refactor, version control, test." Support both with progressive disclosure — show the novice model by default and reveal expert features as the user demonstrates readiness (or provide an explicit "advanced" toggle).
+
+### Labeling Systems
+
+Labels are the most visible artifact of information architecture. A labeling system is a controlled vocabulary — a defined set of terms that are used consistently across the product.
+
+**Label testing.** For each proposed label, ask 10 users: "What would you expect to find under [label]?" If the responses cluster around the correct content, the label works. If responses scatter or cluster around the wrong content, the label is misleading. "Activity" commonly fails this test — users expect anything from "my recent actions" to "what others are doing" to "exercise tracking."
+
+**Label conventions by content type:**
+
+| Content Type | Label Convention               | Example                      |
+| ------------ | ------------------------------ | ---------------------------- |
+| Sections     | Nouns (plural)                 | Projects, Settings, Reports  |
+| Actions      | Verbs (imperative)             | Create, Import, Share        |
+| Statuses     | Adjectives or past participles | Active, Archived, Pending    |
+| Filters      | Noun + qualifier               | My Projects, Recent, Starred |
+
+Mixing conventions creates cognitive friction. If most navigation items are nouns ("Projects," "Teams," "Settings") but one is a verb ("Analyze"), the verb item feels out of place and users may not recognize it as a navigation destination.
+
+### Organization at Scale
+
+Products with hundreds of items (documentation sites, admin panels, e-commerce catalogs) require faceted organization — multiple independent classification axes that users can combine:
+
+**Faceted classification.** Each item is tagged along multiple dimensions: type, audience, date, status, topic. Users can filter along any axis or combination. A documentation site might offer facets for: product area (API, SDK, Dashboard), content type (tutorial, reference, guide), skill level (beginner, intermediate, advanced), and platform (iOS, Android, Web). Users compose their own view by selecting facets, rather than navigating a single rigid hierarchy.
+
+**Polyhierarchy.** Some items legitimately belong in multiple categories. "Two-factor authentication" belongs in both "Security" and "Account settings." Rather than forcing it into one location, use cross-references: list it in both places, or list it in the primary location with a link from the secondary one. Avoid duplicating the content itself — that creates a maintenance burden where one copy gets updated and the other does not.
+
+**Search as first-class navigation.** At scale, browsing breaks down. When a product has 200+ settings, no hierarchical navigation will serve all users. Search with intelligent autocomplete becomes the primary navigation tool. Algolia's documentation search demonstrates this — the search understands synonyms ("auth" matches "authentication"), handles typos, and weights results by relevance. Every product with more than 50 findable items needs robust search.
+
+### Anti-Patterns
+
+1. **The Org-Chart Navigation.** Structuring navigation to match internal company departments: "Marketing Tools," "Engineering Resources," "Sales Dashboard." Users do not know or care about your org chart. They want to accomplish tasks. A user who wants to "see monthly revenue" should not need to know whether that report lives in "Sales," "Finance," or "Analytics." Structure by user task and mental model, not by team ownership.
+
+2. **The Junk Drawer.** A navigation category that collects unrelated items that did not fit elsewhere: "More," "Other," "Miscellaneous," or the classic "Tools." When a category becomes a junk drawer, it means the IA has gaps — there are concepts in the product that have no natural home. The fix is not a catch-all category; it is restructuring the IA to accommodate the orphaned items or questioning whether they belong in the product at all.
+
+3. **The Deep Hierarchy.** Requiring 4+ clicks to reach commonly used items. Every level of depth reduces findability and increases abandonment. If users must navigate Home > Settings > Account > Security > Two-Factor Authentication to enable 2FA, the IA is too deep. Flatten by promoting frequently accessed items, using shortcuts, and limiting hierarchy to 2-3 levels. Amazon limits primary navigation to 3 levels despite having millions of products — anything deeper is reached through search or filtering.
+
+4. **Synonym Pollution.** Using different words for the same concept across the product. The navigation says "Workspace," the settings say "Organization," the API says "Tenant," and the documentation says "Account." The user encounters four words and does not know if they refer to the same thing or four different things. This is the most common labeling failure and the easiest to prevent: create a terminology map, enforce it in code review, and search the codebase for violations quarterly.
+
+5. **The False Floor.** An IA that appears complete but hides significant functionality behind non-obvious paths. A settings page that shows 10 options but has 40 more behind an "Advanced" link that looks like body text. A navigation sidebar that requires scrolling to reveal critical items below the fold. Users form a mental model of the product's scope based on what they can see — hidden features might as well not exist.
+
+### Real-World Examples
+
+**Material Design's Settings Organization.** Material Design prescribes a specific IA for Android settings: top-level groups (Network & Internet, Connected Devices, Apps, Notifications, Battery, Storage, Sound, Display, Accessibility, Security, Privacy, Location, System). Each group contains 3-7 items. The grouping is user-mental-model-driven: "Network & Internet" covers Wi-Fi, mobile data, and hotspot — things a user associates with "being connected." The labels are plain language, the depth is consistently 2 levels, and the most common settings (Wi-Fi, Bluetooth, Display brightness) are reachable in 2 taps.
+
+**Apple's System Settings Reorganization.** In macOS Ventura, Apple reorganized System Preferences (a flat grid of 30+ icon panes) into System Settings (a hierarchical sidebar). The flat grid failed at scale — with 30+ panes, users could not scan them quickly. The new sidebar groups related settings and allows search. This reorganization demonstrates that flat structures work at small scale (under 10 items) but require hierarchy when they grow. Apple's execution validates the "3-7 items per level" rule — each sidebar group contains 3-6 items.
+
+**GitHub's Repository Navigation.** A GitHub repository uses tab-based navigation with 6-8 tabs: Code, Issues, Pull Requests, Actions, Projects, Wiki, Security, Settings. This IA is task-based — each tab represents a distinct workflow. The tab count stays within the 7-item limit. Sub-navigation within tabs uses secondary patterns (sidebar filters for Issues, breadcrumbs for Code file navigation). The IA scales from a personal project with 10 issues to a massive open-source project with 10,000 issues by keeping the top-level structure constant and scaling the within-tab filtering and search.
+
+**Stripe's Documentation IA.** Stripe's documentation uses a three-axis structure: product area (Payments, Billing, Connect, etc.), content type (guides, API reference, sample code), and progression level (quick start, integration guide, advanced topics). The left sidebar provides topical browsing, the search bar provides known-item finding, and breadcrumbs provide orientation. Each API endpoint page follows an identical structure: description, parameters table, request example, response example, error codes. The consistent structure means that once a developer learns to read one page, they can read any page — the IA itself teaches the navigation pattern.
+
+**Airbnb's Search Facets.** Airbnb's search results page demonstrates faceted IA at scale. Users can filter by: location (map-based), dates (calendar), guests (counter), price range (slider), property type (checkboxes), amenities (checkboxes), accessibility features, and host language. Each facet is independent — selecting "pool" does not change available "price" options, it just reduces the result count. The faceted approach lets each user construct their own navigation path through thousands of listings without requiring a single rigid hierarchy.
+
+### Measuring IA Effectiveness
+
+IA quality is measurable. Track these metrics to validate your structure:
+
+**Tree test success rate.** The percentage of users who navigate to the correct item on the first try in a tree test. Target: 70% or higher for primary tasks, 50% or higher for secondary tasks. Below these thresholds, the structure needs revision.
+
+**Navigation path length.** The average number of clicks to reach target content from the homepage. Compare against the theoretical minimum (the depth of the item in the hierarchy). A ratio above 1.5x suggests users are taking wrong turns. Google Analytics behavior flow and click-path analysis tools like FullStory or Hotjar measure this in production.
+
+**Search-to-navigate ratio.** The percentage of users who use search versus browse navigation to find items. A high search ratio (above 40%) for items that exist in the navigation suggests the navigation labels are not working — users cannot find items by browsing, so they search instead. A low search ratio for deep items suggests the IA is working well for browsing.
+
+**Time to find.** The average time users take to locate a specific item. Measure in usability tests with task-based scenarios. Compare against a baseline (experienced user on the same task). If novice users take more than 3x longer than experienced users, the IA relies too heavily on learned behavior rather than intuitive structure.
+
+## Source
+
+- Rosenfeld, L., Morville, P., Arango, J. — _Information Architecture_ (4th ed., 2015), the foundational IA text
+- Wodtke, C. — _Information Architecture: Blueprints for the Web_ (2009), practical IA methods
+- Spencer, D. — _Card Sorting: Designing Usable Categories_ (2009), card sorting methodology
+- Nielsen Norman Group — "Tree Testing" methodology articles, https://www.nngroup.com/articles/tree-testing/
+- Material Design — Navigation patterns, https://m3.material.io/foundations/navigation
+
+## 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/cursor/design-information-architecture/skill.yaml

@@ -0,0 +1,38 @@
+name: design-information-architecture
+version: "1.0.0"
+description: Structuring information — card sorting, tree testing, mental models, labeling systems, organization schemes, findability
+stability: static
+cognitive_mode: advisory-guide
+type: knowledge
+tier: 3
+triggers:
+  - manual
+platforms:
+  - claude-code
+  - gemini-cli
+  - cursor
+  - codex
+tools: []
+paths: []
+related_skills:
+  - design-navigation-ux
+  - design-content-density
+  - design-visual-hierarchy
+  - ux-content-hierarchy
+  - ux-navigation-labels
+stack_signals: []
+keywords:
+  - information-architecture
+  - IA
+  - card-sorting
+  - tree-testing
+  - mental-models
+  - labeling
+  - findability
+  - organization
+metadata:
+  author: community
+state:
+  persistent: false
+  files: []
+depends_on: []

package/dist/agents/skills/cursor/design-loading-patterns/SKILL.md

@@ -0,0 +1,175 @@
+# Loading Patterns
+
+> Perceived performance — skeleton screens, progressive loading, optimistic rendering, shimmer effects, content-first loading, perceived vs actual speed
+
+## When to Use
+
+- Designing loading states for any view that fetches data from a server or API
+- Choosing between skeleton screens, spinners, progress bars, and shimmer effects
+- Optimizing perceived performance when actual performance cannot be improved
+- Implementing lazy loading, infinite scroll, or paginated content loading
+- Building offline-first or cache-first architectures that show stale data while refreshing
+- Designing content-heavy pages (feeds, dashboards, search results) where load time varies
+- Auditing an application for loading state gaps — views that show blank white screens during data fetch
+- Implementing optimistic rendering for user-initiated mutations (create, update, delete)
+
+## Instructions
+
+1. **Match the loading pattern to the content predictability.** The core decision tree:
+   - **Layout is known, content is unknown:** Use skeleton screens. You know the page has a profile header, three stat cards, and a data table — render those shapes as gray placeholders that will be replaced by real content. Facebook, LinkedIn, YouTube, and Slack all use skeleton screens for their primary feeds.
+   - **Layout is unknown, content is unknown:** Use a spinner or indeterminate progress bar. Search results where the count and format vary, or dynamic dashboards where widget configuration varies per user. A spinner says "something is coming, but I do not know what shape it will take."
+   - **Duration is known:** Use a determinate progress bar. File uploads, build processes, multi-step operations. Show percentage complete and estimated time remaining. Vercel's build progress bar shows both.
+   - **Duration is unknown but operation is user-initiated:** Use an indeterminate progress bar with descriptive status text. "Analyzing dependencies..." then "Running tests..." then "Deploying..." — the text updates communicate progress even though percentage is unknown.
+
+2. **Build skeleton screens that match the actual content layout exactly.** A skeleton screen must be a pixel-accurate placeholder of the final rendered content. If the real page has a 48px circular avatar, a 200px-wide heading, and three lines of 14px body text, the skeleton must have a 48px circle, a 200px rectangle at heading height, and three rectangles at body text height with appropriate line spacing. Mismatched skeletons (wrong sizes, wrong positions, wrong count) create a jarring "swap" moment when real content loads — defeating the purpose. Facebook's skeleton screens match their post layout precisely: avatar circle, name bar, timestamp bar, content block, engagement bar.
+
+3. **Animate skeleton screens with a left-to-right shimmer.** Static gray rectangles feel dead. An animated shimmer (a gradient that sweeps left-to-right across the skeleton elements) communicates "loading in progress" and makes the wait feel shorter. Implementation: use a CSS gradient animation on a `::before` pseudo-element:
+
+   ```css
+   .skeleton {
+     background: #e0e0e0;
+     position: relative;
+     overflow: hidden;
+   }
+   .skeleton::before {
+     content: '';
+     position: absolute;
+     inset: 0;
+     background: linear-gradient(90deg, transparent, rgba(255, 255, 255, 0.4), transparent);
+     animation: shimmer 1.5s infinite;
+   }
+   @keyframes shimmer {
+     0% {
+       transform: translateX(-100%);
+     }
+     100% {
+       transform: translateX(100%);
+     }
+   }
+   ```
+
+   The shimmer duration should be 1.5-2.0 seconds per cycle. Faster feels frantic; slower feels stalled. LinkedIn uses 1.8 seconds. YouTube uses approximately 1.5 seconds. The gradient should be subtle — 30-40% white opacity, not a harsh white band.
+
+4. **Apply the 100ms/1s/10s threshold rules for loading indicator appearance.** These are Jakob Nielsen's perceptual thresholds, validated repeatedly:
+   - **Under 100ms:** Show nothing — the content will appear to load instantly. Adding a loading indicator for sub-100ms loads creates flicker (the skeleton flashes for one frame then disappears).
+   - **100ms-1s:** Show a skeleton screen or subtle loading indicator. No spinner needed — the wait is short enough that a spinner feels heavy-handed.
+   - **1-5s:** Show a skeleton screen with shimmer animation, or a spinner with a status message. The user has noticed the delay and needs reassurance that the system is working.
+   - **5-10s:** Show a skeleton screen or spinner with progress information: step name, percentage if determinable, estimated time remaining. Consider streaming partial content.
+   - **Over 10s:** Show all of the above, plus offer a cancel option and consider sending a notification when complete. The user will likely switch context.
+
+   To prevent flicker for fast loads, delay the skeleton/spinner appearance by 200ms. If the content loads within 200ms, no loading indicator ever appears. If it takes longer than 200ms, the skeleton fades in. This eliminates the flash-of-skeleton for fast connections while still showing a loading state for slow ones.
+
+5. **Implement progressive loading to prioritize above-the-fold content.** Load and render content in priority order: (1) navigation and page structure (cached, renders immediately), (2) above-the-fold content (first API call, critical data), (3) below-the-fold content (deferred, lazy-loaded on scroll), (4) non-essential enhancements (analytics, recommendation widgets, social proof badges). Each priority tier can render independently — the page builds up rather than appearing all at once. Vercel's dashboard loads the navigation shell from cache, then the deployment list (above the fold), then the activity feed (below the fold), then the usage graph (far below the fold).
+
+6. **Use optimistic rendering for user-initiated mutations.** When a user creates, updates, or deletes something, render the expected outcome immediately without waiting for server confirmation. The three-step pattern:
+   - **Render optimistically:** Show the new item / updated state / removal immediately in the UI.
+   - **Sync in background:** Send the mutation to the server.
+   - **Reconcile on response:** On success, replace the optimistic placeholder with the server-confirmed data (updating timestamps, IDs, etc.). On failure, rollback the optimistic change and show an error with retry.
+
+   GitHub's star/unstar is optimistic rendering: the star fills and the count changes on click, before the server responds. Slack's message send is optimistic rendering: the message appears in the channel immediately. Linear's status change is optimistic rendering: the issue moves to the new column immediately.
+
+7. **Design content-first loading that shows real data before chrome.** Invert the traditional loading order: instead of loading the full page shell then filling in data, load the most important data first and build the shell around it. For a blog post, load the article text first (renders in under 500ms as server-rendered HTML), then load the header/footer navigation, sidebar, comments, and related posts progressively. The user gets to the content — the reason they are on the page — as fast as possible. Medium uses this pattern: the article text renders almost immediately, then author info, clap count, and responses load progressively.
+
+8. **Implement stale-while-revalidate for cached data.** Show the cached version immediately (stale data), then fetch fresh data in the background, then swap the stale data with fresh data when it arrives. The swap must be non-disruptive — if the data has not changed (common case), do nothing. If the data has changed, update individual elements rather than replacing the entire view (which would cause a layout shift). The HTTP `Cache-Control: stale-while-revalidate` header supports this pattern at the network level. SWR (by Vercel) and React Query implement it at the application level: `const { data } = useSWR('/api/dashboard', fetcher)` returns cached data immediately and refreshes in the background.
+
+## Details
+
+### Skeleton Screen Design Specifications
+
+Skeleton elements should follow these visual rules:
+
+- **Color:** Use a neutral gray at 10-15% of the text-to-background contrast ratio. On white backgrounds (#FFFFFF), use #E0E0E0 to #EEEEEE. On dark backgrounds (#121212), use #2C2C2C to #333333. The skeleton should be visible but not attention-grabbing.
+- **Shape:** Match the shape of the content they represent. Text blocks are rounded rectangles (border-radius: 4px) at the exact line height and approximate width of the expected text. Avatars are circles at the exact avatar dimensions. Images are rectangles at the exact aspect ratio. Do not use generic rectangles for all content — the shapes should communicate what type of content is loading.
+- **Width variation:** Text skeleton lines should vary in width to simulate natural text length: first line 100%, second line 95%, third line 60% (simulating a paragraph that does not fill the last line). Uniform-width lines look artificial.
+- **Spacing:** Match the exact spacing of the real content. If the real layout has 16px between the avatar and the name, the skeleton has 16px between the circle and the rectangle. Spacing mismatches cause layout shift when real content replaces the skeleton.
+- **Count:** Match the expected count of items. If the API typically returns 10 items, show 10 skeleton rows. If the count is unknown, show enough to fill the viewport (usually 5-8 items) — showing 3 skeleton items when 20 load creates a jarring expansion.
+
+### Perceived Performance vs Actual Performance
+
+Research from Stanford University (Seow, 2008) and IBM (Card, Robertson, and Mackinlay, 1991) established that perceived speed and actual speed diverge based on UX patterns:
+
+**Patterns that make waits feel shorter:**
+
+- **Progress indicators** reduce perceived wait time by 15-20% versus no indicator. Any indication of progress — even indeterminate — reassures the user that the system is working.
+- **Skeleton screens** reduce perceived wait time by 20-30% versus blank screens or spinners. The user's brain starts processing the layout structure before content arrives, making the transition to full content feel faster.
+- **Animation during waits** reduces perceived time by 10-15%. The shimmer effect on skeletons, a loading animation, or even background movement gives the brain something to process during the wait.
+- **Early content delivery** (showing any real content before everything is loaded) has the largest impact: 30-50% reduction in perceived wait time. A page that shows the title and first paragraph in 200ms, then loads images over the next 2 seconds, feels dramatically faster than a page that shows everything at 2.2 seconds.
+- **Providing status updates** during long waits reduces perceived time by 20-25%. "Installing dependencies... Building assets... Running tests..." gives the user a narrative of progress.
+
+**Patterns that make waits feel longer:**
+
+- **Blank screens** feel 50-100% longer than actual time. A white screen with no indication of activity causes the user to wonder if the page is broken.
+- **Spinners for long waits** (>5 seconds) increase anxiety because the spinner provides no progress information — the user cannot tell if the wait is 5% or 95% complete.
+- **Repeated loading states** when navigating between already-visited pages. If the user saw this page 30 seconds ago, showing a full loading state again feels like regression. Use stale-while-revalidate to show the cached version instantly.
+- **Layout shifts** during loading (content jumping as new elements load) extend perceived load time because the user must re-orient after each shift. The Cumulative Layout Shift (CLS) Core Web Vital directly measures this.
+
+### Lazy Loading Implementation
+
+Lazy loading defers the loading of below-the-fold content until the user scrolls near it. Implementation details:
+
+**Intersection Observer pattern:** Use `IntersectionObserver` to detect when a placeholder element enters the viewport, then trigger the content load. Set `rootMargin: '200px'` to start loading 200px before the element becomes visible — this gives the network request a head start so content appears loaded by the time the user scrolls to it.
+
+**Image lazy loading:** Use the native `loading="lazy"` attribute on `<img>` tags for images below the fold. This is supported in all modern browsers and requires zero JavaScript. For above-the-fold images (hero images, logos), do NOT use lazy loading — they should load immediately. The `<img>` `fetchpriority="high"` attribute signals to the browser that above-the-fold images are critical.
+
+**Infinite scroll vs pagination:** Infinite scroll works for content browsing (social feeds, search results, image galleries) where the user's intent is exploration. Pagination works for task-oriented interfaces (email inbox, transaction history, admin tables) where the user needs to find specific items and track their position. Infinite scroll must preserve scroll position on back navigation — if the user clicks an item (navigating away) and hits back, they must return to their exact scroll position, not the top of the page. This requires storing scroll position and loaded items in memory or session state.
+
+### Loading States for Different Content Types
+
+**Text content:** Skeleton lines that match the expected text layout. Use 3-4 lines for a paragraph placeholder, 1 line for a heading, 1 short line for metadata (date, author). Render real text as soon as the API response arrives — text has near-zero render cost.
+
+**Images:** Show a placeholder at the exact aspect ratio of the expected image (prevents layout shift). Options: solid color matching the dominant color of the image (if known from a low-resolution preview or palette extraction), blurred low-resolution preview (LQIP — Low Quality Image Placeholder, used by Medium and Facebook), or a generic gray placeholder. The placeholder should have the exact dimensions so that layout does not shift when the full image loads.
+
+**Data tables:** Show skeleton rows with column-width-matched rectangles. Show the actual column headers immediately (they are static and known ahead of time). Animate the shimmer across rows. Render data rows as they arrive from the API — partial table rendering is better than waiting for all data.
+
+**Charts and visualizations:** Show the chart axes and labels immediately (static, known). Show the chart area as a skeleton placeholder. On data arrival, animate the chart elements in (bars grow from zero, lines draw from left to right). This progressive reveal makes the chart feel responsive even if the data took 2 seconds to load.
+
+**Maps:** Show a static map tile (low-resolution, from cache) immediately. Overlay interactive elements (pins, routes) as they load. Google Maps uses this: the base map renders from cached tiles almost instantly, then points of interest, traffic layers, and route overlays appear progressively.
+
+### Anti-Patterns
+
+1. **The Fake Progress Bar.** A progress bar that fills linearly from 0-90% in 3 seconds, then stalls at 90% for an unknown duration until the operation completes. Users learn that the bar is lying and stop trusting it. Fix: either use a genuine determinate progress bar (where percentage reflects actual completion) or use an indeterminate indicator (spinner, pulsing bar) that does not claim to know the completion percentage. If you use a determinate bar, it must be tied to real milestones — 10% after dependency resolution, 40% after build, 70% after tests, 100% on deploy.
+
+2. **Spinner Everything.** Using a centered spinner for every loading state — page loads, component loads, data refreshes, image loads. Spinners convey no information about what is loading or what the page will look like. They require the user to wait for the "reveal" of the page layout, increasing perceived load time. Fix: use skeleton screens for any view where the layout is predictable. Reserve spinners for truly unpredictable content (search results, dynamic dashboards) or for inline indicators within already-rendered pages (a spinner inside a button during form submission).
+
+3. **Layout Shift Avalanche.** Content loads progressively but each new element causes existing content to shift position: the header pushes down when the banner loads, the article jumps when an image loads, the sidebar pushes the content when ads load. Each shift disrupts reading and forces the user to re-find their place. Fix: reserve exact space for every element before it loads. Use `aspect-ratio` on image containers, fixed heights on ad slots, and `min-height` on dynamic sections. Target CLS (Cumulative Layout Shift) under 0.1 as defined by Core Web Vitals.
+
+4. **Full-Page Reload for Partial Data.** Re-rendering the entire page (navigation, header, sidebar, footer, and content) when only the content area needs to update. The user sees a full loading state for a route change when 80% of the page is identical between routes. Fix: use client-side routing that preserves the persistent shell and only reloads the content area. Show a loading indicator only in the content area. Next.js, Remix, and SvelteKit all support this with their layout/route architecture.
+
+5. **Stale-Without-Revalidate.** Showing cached data but never refreshing it. The user sees data from their last visit — potentially hours or days old — with no indication that it might be stale, and no background refresh. Fix: always revalidate cached data. Show the cached version immediately (good) but fetch fresh data in the background and update when it arrives. Display a "Last updated: X minutes ago" indicator when the data age exceeds a threshold (e.g., 5 minutes for dashboards, 1 hour for settings).
+
+### Real-World Examples
+
+**Facebook/Meta News Feed Skeleton.** Facebook pioneered the skeleton screen pattern in 2014 and it remains the most studied implementation. Their skeleton matches the post layout exactly: a 40px circle (avatar), two stacked rectangles at 40% and 30% width (name and timestamp), a large rectangle at full width (content block), and a row of small rectangles (reaction/comment/share buttons). The shimmer animates left-to-right at 1.5s per cycle. On content arrival, the skeleton morphs into the real post — the circle becomes the avatar, the rectangles become text — with no layout shift because the dimensions are identical. Facebook reported a 10% decrease in perceived load time after deploying skeleton screens.
+
+**Vercel Build and Deploy Progress.** Vercel's deployment provides multi-stage progressive feedback: (1) "Queued" — gray indicator, immediate acknowledgment of the deployment trigger. (2) "Building" — animated yellow dot, streaming build log visible in real-time (the user can watch `npm install` and `next build` output line by line). (3) "Deploying" — animated blue dot, "Deploying to edge network." (4) "Ready" — green checkmark, preview URL, deployment time. Each stage transition updates a timeline visualization showing elapsed time per stage. If a build fails, the error is shown inline in the build log with the exact failing command highlighted in red.
+
+**Slack Channel Loading.** When opening a Slack channel, the loading sequence is: (1) Channel header (name, topic, member count) renders from cache immediately. (2) Message history appears from local cache (potentially stale). (3) A "loading new messages" indicator appears between cached messages and the message input. (4) New messages stream in from the server and append below the cached messages. (5) The "loading" indicator disappears. The user can read cached messages and even start typing a reply while new messages load — no blocking loading state. If the user is offline, the entire channel renders from cache with a yellow "You're not connected" banner.
+
+**YouTube Video Page Loading.** YouTube uses a sophisticated multi-tier loading strategy: (1) Video player loads first (highest priority) — a black rectangle with a spinner at the exact video aspect ratio. (2) Video title and channel info load from a fast endpoint (skeleton → real content in under 200ms). (3) Video description and metadata expand on click (deferred). (4) Related videos sidebar loads asynchronously (skeleton column of 20 video cards). (5) Comments section loads only when scrolled into view (full lazy loading). The result: the user can start watching the video within 1-2 seconds while the rest of the page builds itself progressively over the next 3-5 seconds.
+
+**Linear Dashboard Loading.** Linear loads its issue list with a content-first strategy: (1) The sidebar navigation renders from cache (persistent shell). (2) Issue list renders from local state (offline-first architecture — issues are synced to IndexedDB). (3) A background sync checks for updates from the server. (4) If new issues exist, they fade into the list without disrupting scroll position. (5) If an issue was modified elsewhere, the update appears inline with a subtle highlight that fades after 2 seconds. The user never sees a loading spinner for the primary issue list — it is always available from local state.
+
+## Source
+
+- Nielsen, J. — "Response Times: The 3 Important Limits" (1993), perceptual timing thresholds
+- Seow, S. — _Designing and Engineering Time_ (2008), perceived vs actual performance
+- Facebook Engineering — "Building Skeleton Screens" (2014), original implementation research
+- Google — Core Web Vitals, https://web.dev/vitals/ (LCP, FID, CLS metrics)
+- Vercel — SWR (stale-while-revalidate) library, https://swr.vercel.app/
+- Card, S., Robertson, G., and Mackinlay, J. — "The Information Visualizer" (1991), animation and perceived time
+
+## 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.