@harness-engineering/cli 1.23.2 → 1.24.0

package/dist/agents/skills/gemini-cli/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/gemini-cli/design-information-architecture/skill.yaml

@@ -0,0 +1,35 @@
+name: design-information-architecture
+version: "1.0.0"
+description: Structuring information — card sorting, tree testing, mental models, labeling systems, organization schemes, findability
+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
+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/gemini-cli/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.

package/dist/agents/skills/gemini-cli/design-loading-patterns/skill.yaml

@@ -0,0 +1,33 @@
+name: design-loading-patterns
+version: "1.0.0"
+description: Perceived performance — skeleton screens, progressive loading, optimistic rendering, shimmer effects, content-first loading, perceived vs actual speed
+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-motion-principles
+  - design-empty-error-states
+stack_signals: []
+keywords:
+  - loading
+  - skeleton-screen
+  - progressive-loading
+  - optimistic-rendering
+  - shimmer
+  - perceived-performance
+metadata:
+  author: community
+state:
+  persistent: false
+  files: []
+depends_on: []

package/dist/agents/skills/gemini-cli/design-material-design-3/SKILL.md

@@ -0,0 +1,184 @@
+# Material Design 3 (Material You)
+
+> Google's adaptive design language covering dynamic color extraction from wallpaper, HCT-based tonal palettes, elevation through tonal surface color rather than drop shadows, shape theming with corner families, and choreographed motion with shared-axis transitions.
+
+## When to Use
+
+- Building Android apps targeting API 31+ where dynamic color is available via `DynamicColors.applyToActivitiesIfAvailable()`
+- Implementing a component library using Material 3 tokens (`md.sys.color.*`, `md.sys.shape.*`, `md.sys.motion.*`)
+- Migrating from Material Design 2 to M3 where elevation model, color roles, and shape system have fundamentally changed
+- Creating a cross-platform design system that includes Android as a primary target and must honor M3 conventions
+- Theming an app where the seed color must propagate through 5 tonal palettes and 29 color roles without manual per-role assignment
+
+## Instructions
+
+Material Design 3 is a generative design system. Instead of prescribing fixed palettes, it derives an entire theme from a single seed color using the HCT (Hue, Chroma, Tone) color space. Every surface, text, and icon color is a deterministic function of that seed. This means understanding M3 requires understanding HCT math, the tonal palette generation algorithm, the 29 color role mappings, the tonal elevation model, shape corner families, and motion easing choreography.
+
+**The generative pipeline:** Seed color (e.g., `#6750A4`) -> HCT decomposition (H:282, C:34, T:40) -> 5 tonal palettes (Primary, Secondary, Tertiary, Neutral, Neutral Variant) -> 13 tones per palette (0, 10, 20, 30, 40, 50, 60, 70, 80, 90, 95, 99, 100) -> 29 color roles mapped to specific palette+tone combinations -> component token resolution.
+
+**Key departure from M2:** Elevation no longer uses shadow intensity. M3 uses tonal surface color -- a surface at elevation 3 is tinted with the primary color at a specific opacity, not darkened with a shadow. Shadows exist only for components that physically overlap (FAB, dialogs, bottom sheets).
+
+## Details
+
+### Dynamic Color and HCT Color Space
+
+HCT (Hue, Chroma, Tone) is Google's perceptually uniform color space that combines CAM16 hue and chroma with L\* (CIELAB lightness) as the tone axis. Unlike HSL, HCT guarantees that tone 40 in any hue produces the same perceived brightness.
+
+**Seed to palette algorithm:**
+
+1. Extract the seed color's HCT values. For `#6750A4`: H=282, C=34, T=40.
+2. Generate the Primary tonal palette: hold H=282, set C to max achievable at each tone, generate 13 tones (0-100).
+3. Generate Secondary: shift H by 0, reduce C by ~33%. For seed C=34, secondary C~22.
+4. Generate Tertiary: rotate H by +60 degrees (282+60=342), maintain similar C. This creates an analogous accent.
+5. Generate Neutral: hold H=282, reduce C to ~4. Near-gray with a hint of the seed hue.
+6. Generate Neutral Variant: hold H=282, reduce C to ~8. Slightly more chromatic neutral.
+
+**Concrete palette output for seed `#6750A4`:**
+
+```
+Primary     T40: #6750A4  T80: #D0BCFF  T90: #EADDFF
+Secondary   T40: #625B71  T80: #CCC2DC  T90: #E8DEF8
+Tertiary    T40: #7D5260  T80: #EFB8C8  T90: #FFD8E4
+Neutral     T40: #605D62  T80: #C9C5CA  T90: #E6E1E5
+NeutralVar  T40: #605D66  T80: #CAC4D0  T90: #E7E0EC
+```
+
+**Color role mapping (light theme):** The 29 roles map palette+tone combinations to semantic purposes:
+
+```
+md.sys.color.primary:              Primary T40     (#6750A4)
+md.sys.color.on-primary:           Primary T100    (#FFFFFF)
+md.sys.color.primary-container:    Primary T90     (#EADDFF)
+md.sys.color.on-primary-container: Primary T10     (#21005D)
+md.sys.color.surface:              Neutral T99     (#FFFBFE)
+md.sys.color.on-surface:           Neutral T10     (#1C1B1F)
+md.sys.color.surface-variant:      NeutralVar T90  (#E7E0EC)
+md.sys.color.outline:              NeutralVar T50  (#79747E)
+```
+
+**Dark theme inversion:** Swap tone positions. Where light uses T40 for primary, dark uses T80. Where light uses T90 for container, dark uses T30. The hue and chroma remain identical -- only tone shifts.
+
+```
+Light: primary = Primary T40, primary-container = Primary T90
+Dark:  primary = Primary T80, primary-container = Primary T30
+```
+
+### Tonal Elevation Model
+
+M3 replaces shadow-based elevation with surface tint. A surface at a higher elevation receives more primary color overlay, creating a subtle tonal shift that implies depth without casting shadows.
+
+**Elevation levels and tint opacities:**
+
+```
+Level 0:  0dp   -> 0% primary tint    (base surface)
+Level 1:  1dp   -> 5% primary tint    (cards, navigation rail)
+Level 2:  3dp   -> 8% primary tint    (top app bar, scrolled)
+Level 3:  6dp   -> 11% primary tint   (FAB, search bar)
+Level 4:  8dp   -> 12% primary tint   (navigation drawer)
+Level 5:  12dp  -> 14% primary tint   (dialogs, bottom sheets)
+```
+
+**Implementation in CSS:** Compose the surface color with a primary overlay:
+
+```css
+/* Level 2 surface in light theme */
+.surface-level-2 {
+  background-color: color-mix(in srgb, var(--md-sys-color-primary) 8%, var(--md-sys-color-surface));
+}
+```
+
+**When shadows still apply:** Physical overlap components -- FAB hovering over content, dialog overlaying the page, bottom sheet sliding up -- still cast shadows. The shadow uses `md.sys.elevation.shadow` tokens. But a Card at elevation 1 gets tint only, no shadow.
+
+**Dark mode elevation:** The tint effect is more visible because the base surface is dark (Neutral T6, ~`#1C1B1F`). A 5% primary tint on near-black is perceptually stronger than 5% on near-white. M3 accounts for this -- the tint percentages are the same, but the visual distinction is naturally stronger in dark mode.
+
+### Shape Theme System
+
+M3 defines shape using corner families (rounded, cut) and size scales. Every component maps to a shape token that resolves to a specific corner radius.
+
+**Shape scale:**
+
+```
+md.sys.shape.corner.none:        0dp     (full-screen sheets)
+md.sys.shape.corner.extra-small: 4dp     (text fields, snackbars)
+md.sys.shape.corner.small:       8dp     (chips, menus)
+md.sys.shape.corner.medium:      12dp    (cards, dialogs)
+md.sys.shape.corner.large:       16dp    (FAB, navigation drawer)
+md.sys.shape.corner.extra-large: 28dp    (bottom sheets expanded)
+md.sys.shape.corner.full:        50%     (badges, pills, circular FAB)
+```
+
+**Shape families:** Round (default) uses `border-radius`. Cut uses `clip-path` with angled corners. A card with `shape.corner.medium` in the cut family becomes a chamfered rectangle at 12dp.
+
+**Morphing shapes:** FAB transitions from `corner.large` (16dp rounded) at rest to `corner.full` (circular) when scrolling collapses it to a mini-FAB. This morph is animated over 300ms with the `emphasized` easing curve.
+
+### Motion Choreography
+
+M3 motion uses shared-axis transitions, container transforms, and three easing curve families.
+
+**Easing curves (cubic-bezier values):**
+
+```
+md.sys.motion.easing.emphasized:           cubic-bezier(0.2, 0.0, 0, 1.0)
+md.sys.motion.easing.emphasized-decelerate: cubic-bezier(0.05, 0.7, 0.1, 1.0)
+md.sys.motion.easing.emphasized-accelerate: cubic-bezier(0.3, 0.0, 0.8, 0.15)
+md.sys.motion.easing.standard:             cubic-bezier(0.2, 0.0, 0, 1.0)
+md.sys.motion.easing.standard-decelerate:  cubic-bezier(0.0, 0.0, 0, 1.0)
+md.sys.motion.easing.standard-accelerate:  cubic-bezier(0.3, 0.0, 1.0, 1.0)
+```
+
+**Duration tokens:**
+
+```
+md.sys.motion.duration.short1:   50ms    (ripple fade-in)
+md.sys.motion.duration.short2:   100ms   (icon state change)
+md.sys.motion.duration.medium1:  250ms   (card expand)
+md.sys.motion.duration.medium2:  300ms   (FAB morph)
+md.sys.motion.duration.long1:    450ms   (page transition)
+md.sys.motion.duration.long2:    500ms   (full-screen expand)
+```
+
+**Shared-axis transitions:** Forward navigation slides content along the Z-axis (incoming element scales from 80% to 100%, outgoing fades). Lateral navigation uses X-axis (tabs slide left/right). Vertical feeds use Y-axis.
+
+**Container transform:** A card expanding to a detail page morphs its bounding rectangle. The card's corner radius animates from `corner.medium` (12dp) to `corner.none` (0dp). Internal content cross-fades during the morph. Duration: `long1` (450ms) with `emphasized` easing.
+
+### Anti-Patterns
+
+**Using drop shadows for all elevation levels.** M3 reserves shadows for physically overlapping components. Applying `box-shadow` to cards, app bars, and navigation rails replicates M2 behavior and defeats the tonal elevation model. A Card at elevation 1 should show a 5% primary tint on its background -- not a `0 1px 3px rgba(0,0,0,0.12)` shadow.
+
+**Hardcoding color hex values instead of using the 29 color roles.** If your button uses `background: #6750A4` instead of `background: var(--md-sys-color-primary)`, dynamic color cannot propagate. When the user's wallpaper changes the seed, your button stays purple while the rest of the app adapts. Every color reference must resolve through the `md.sys.color.*` role system.
+
+**Ignoring the secondary and tertiary palettes.** Teams that only use Primary for all accents produce monotone interfaces. M3 generates Secondary (reduced chroma, same hue) for less prominent elements like chips and toggles, and Tertiary (rotated hue) for complementary accents like FABs or progress indicators. Using only Primary collapses the visual hierarchy.
+
+**Applying the emphasized easing curve to all animations.** `emphasized` (0.2, 0.0, 0, 1.0) is designed for transitions where content enters the viewport -- container transforms, page transitions. Micro-interactions like ripple effects and icon toggles should use `standard` easing. Applying emphasized easing to a ripple makes it feel sluggish because the initial slow phase is perceptible at short durations (50-100ms).
+
+**Static shape tokens that ignore responsive morphing.** A FAB that stays at `corner.large` (16dp) when scrolling, instead of morphing to `corner.full` (circular mini-FAB), breaks the M3 motion contract. Shape is not static -- components have rest, pressed, and transitional shape states that animate along the shape scale.
+
+### Real-World Examples
+
+**Google Photos** uses dynamic color to tint its surface backgrounds from the user's wallpaper. On a phone with a sunset wallpaper (seed ~`#D4613C`), the Primary palette shifts to warm orange-browns, the app bar gets a Level 2 tonal tint (8% primary on surface), and chips use Secondary container colors. The entire 29-role mapping regenerates in ~16ms on Pixel 7.
+
+**Google Clock** demonstrates tonal elevation in its alarm list. Each alarm card sits at elevation 1 (5% primary tint). When expanded, the card animates to elevation 3 (11% primary tint) using a container transform over 250ms with emphasized easing. No shadow is added -- the tint shift alone conveys the depth change.
+
+**YouTube Music** uses the Tertiary palette for its mini-player progress bar, creating a complementary accent against the Primary-tinted navigation bar. The Tertiary hue is rotated +60 degrees from the dynamic seed, ensuring visual contrast without manual color selection.
+
+**Google Keep** applies shape theming where notes use `corner.medium` (12dp rounded), labels use `corner.full` (pill shape), and the compose FAB uses `corner.large` (16dp) that morphs to `corner.extra-large` (28dp) when expanded into a full compose sheet.
+
+## Source
+
+Google Material Design 3 specification (material.io/design, 2024). Material Color Utilities library documentation (github.com/material-foundation/material-color-utilities). Android Developers "Dynamic Color" guide. Material Theme Builder tool documentation.
+
+## 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.