@girardmedia/bootspring 3.3.2 → 3.4.0

package/assets/skills/responsive-design.md

@@ -0,0 +1,199 @@
+---
+name: responsive-design
+description: Responsive design patterns with mobile-first CSS, container queries, fluid typography, and breakpoint strategy.
+---
+
+# Responsive Design
+
+## When to Use
+Apply to every web interface. Over 60% of web traffic is mobile. Responsive design ensures your UI works on phones (320px), tablets (768px), laptops (1024px), and ultrawide monitors (2560px) without separate codebases. Start mobile-first and progressively enhance.
+
+## How It Works
+
+### Mobile-First Approach
+
+Write base styles for the smallest screen, then add complexity with `min-width` media queries:
+
+```css
+/* Base -- mobile (320px+) */
+.card-grid {
+  display: grid;
+  grid-template-columns: 1fr;
+  gap: 1rem;
+  padding: 1rem;
+}
+
+/* Tablet (640px+) */
+@media (min-width: 640px) {
+  .card-grid {
+    grid-template-columns: repeat(2, 1fr);
+    gap: 1.5rem;
+  }
+}
+
+/* Desktop (1024px+) */
+@media (min-width: 1024px) {
+  .card-grid {
+    grid-template-columns: repeat(3, 1fr);
+    gap: 2rem;
+    max-width: 1200px;
+    margin: 0 auto;
+  }
+}
+```
+
+Never use `max-width` queries as your primary strategy. You end up overriding desktop styles for mobile, which is more code and more bugs.
+
+### Container Queries
+
+Media queries respond to the viewport. Container queries respond to the parent container -- critical for reusable components:
+
+```css
+/* Define the container */
+.sidebar {
+  container-type: inline-size;
+  container-name: sidebar;
+}
+
+/* Component adapts to its container, not the viewport */
+@container sidebar (min-width: 300px) {
+  .user-card {
+    display: flex;
+    flex-direction: row;
+    gap: 1rem;
+  }
+}
+
+@container sidebar (max-width: 299px) {
+  .user-card {
+    display: flex;
+    flex-direction: column;
+    text-align: center;
+  }
+}
+```
+
+Use container queries when a component lives in multiple layout contexts (sidebar, main content, modal).
+
+### Fluid Typography
+
+Scale text smoothly between breakpoints with `clamp()`:
+
+```css
+:root {
+  --text-xs: clamp(0.75rem, 0.7rem + 0.25vw, 0.875rem);
+  --text-sm: clamp(0.875rem, 0.8rem + 0.35vw, 1rem);
+  --text-base: clamp(1rem, 0.9rem + 0.5vw, 1.125rem);
+  --text-lg: clamp(1.125rem, 1rem + 0.65vw, 1.375rem);
+  --text-xl: clamp(1.375rem, 1.1rem + 1.2vw, 2rem);
+  --text-2xl: clamp(1.75rem, 1.3rem + 2vw, 3rem);
+}
+
+h1 { font-size: var(--text-2xl); }
+h2 { font-size: var(--text-xl); }
+p  { font-size: var(--text-base); }
+```
+
+The formula `clamp(min, preferred, max)` prevents text from being too small on phones or too large on 4K monitors.
+
+### Breakpoint Strategy
+
+Use content-driven breakpoints, not device-specific ones:
+
+```css
+/* Tailwind defaults -- a solid starting point */
+/* sm: 640px   -- small tablets, large phones landscape */
+/* md: 768px   -- tablets portrait */
+/* lg: 1024px  -- tablets landscape, small laptops */
+/* xl: 1280px  -- standard laptops */
+/* 2xl: 1536px -- large monitors */
+
+/* Custom breakpoint only when content demands it */
+@media (min-width: 480px) {
+  .pricing-card { flex-direction: row; }
+}
+```
+
+Rules: use 3-5 breakpoints maximum. Name them by size (sm/md/lg), not by device.
+
+### Touch Targets
+
+Mobile users tap with fingers. Minimum touch target: 44x44px (WCAG), recommended 48x48px:
+
+```css
+.nav-link {
+  min-height: 44px;
+  padding: 12px 16px;
+  display: flex;
+  align-items: center;
+}
+
+.button-group {
+  display: flex;
+  gap: 8px; /* minimum 8px between adjacent targets */
+}
+
+.icon-button {
+  width: 48px;
+  height: 48px;
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  border-radius: 50%;
+}
+```
+
+### Responsive Layout Patterns
+
+```css
+/* Sidebar layout -- collapses on mobile */
+.app-layout {
+  display: grid;
+  grid-template-columns: 1fr;
+}
+@media (min-width: 1024px) {
+  .app-layout { grid-template-columns: 280px 1fr; }
+}
+
+/* Responsive table -- stacks on mobile */
+@media (max-width: 639px) {
+  table, thead, tbody, th, td, tr { display: block; }
+  thead { position: absolute; width: 1px; height: 1px; overflow: hidden; }
+  td::before {
+    content: attr(data-label);
+    font-weight: 600;
+    display: block;
+  }
+}
+```
+
+Responsive images with art direction:
+
+```html
+<picture>
+  <source media="(min-width: 1024px)" srcset="/hero-wide.webp" />
+  <source media="(min-width: 640px)" srcset="/hero-medium.webp" />
+  <img src="/hero-mobile.webp" alt="Hero" loading="lazy" />
+</picture>
+```
+
+## Examples
+
+| Problem | Solution | Benefit |
+|---------|----------|---------|
+| Cards overflow on 320px | Mobile-first grid, 1fr base | Content always fits |
+| Component in sidebar and modal | Container queries | Adapts to container |
+| Heading huge on mobile | `clamp()` fluid typography | Smooth scaling |
+| Users mis-tap small buttons | 48px minimum touch targets | Fewer mis-taps |
+| Data table unreadable on mobile | Stack cells with `data-label` | Readable at any width |
+| Desktop images on mobile | `<picture>` with sources | 3x faster mobile load |
+
+## Checklist
+- [ ] Base styles target mobile (320px), enhanced with `min-width` queries
+- [ ] Layout uses CSS Grid or Flexbox, not floats
+- [ ] 3-5 breakpoints maximum, driven by content
+- [ ] Typography uses `clamp()` for fluid scaling
+- [ ] Reusable components use container queries
+- [ ] Touch targets at least 44x44px with 8px minimum spacing
+- [ ] Images use responsive sources (`<picture>`, `srcset`)
+- [ ] Tested at 320px, 768px, 1024px, and 1440px widths

package/assets/skills/ruby-rails-patterns.md

@@ -0,0 +1,178 @@
+---
+name: ruby-rails-patterns
+description: Apply idiomatic Ruby on Rails patterns for models, controllers, background jobs, and Hotwire/Turbo real-time UIs.
+---
+
+# Ruby on Rails Patterns
+
+## When to Use
+
+Apply these patterns when building or reviewing Rails applications. They cover
+ActiveRecord modeling, concern extraction, service objects for complex business
+logic, background jobs, and Hotwire/Turbo Streams for server-rendered real-time
+UIs. Use this skill when standing up new features, refactoring fat controllers
+or models, or adding real-time behavior without a JavaScript framework.
+
+## How It Works
+
+### 1. ActiveRecord — Keep Models Thin
+
+Push queries into scopes. Push multi-step mutations into service objects.
+
+```ruby
+class Order < ApplicationRecord
+  belongs_to :user
+  has_many :line_items, dependent: :destroy
+
+  scope :recent,    -> { where("created_at > ?", 30.days.ago) }
+  scope :fulfilled, -> { where(status: :fulfilled) }
+  scope :expensive, ->(min) { where("total_cents >= ?", min) }
+
+  validates :total_cents, numericality: { greater_than: 0 }
+
+  # Callbacks are fine for simple lifecycle hooks — not business logic
+  after_create_commit :broadcast_to_dashboard
+end
+```
+
+### 2. Concerns — Shared Behavior Modules
+
+Extract cross-cutting behavior into concerns. Keep each concern under 50 lines.
+
+```ruby
+# app/models/concerns/sluggable.rb
+module Sluggable
+  extend ActiveSupport::Concern
+
+  included do
+    before_validation :generate_slug, on: :create
+    validates :slug, presence: true, uniqueness: true
+  end
+
+  private
+
+  def generate_slug
+    self.slug = name&.parameterize
+  end
+end
+```
+
+### 3. Service Objects — Encapsulate Business Logic
+
+One public method (`call`), explicit inputs, return a result object.
+
+```ruby
+class Orders::Checkout
+  def initialize(user:, cart:, payment_method:)
+    @user = user
+    @cart = cart
+    @payment_method = payment_method
+  end
+
+  def call
+    ActiveRecord::Base.transaction do
+      order = Order.create!(user: @user, total_cents: @cart.total_cents)
+      @cart.items.each { |item| order.line_items.create!(item.attributes) }
+      charge = PaymentGateway.charge(@payment_method, order.total_cents)
+      order.update!(payment_id: charge.id, status: :paid)
+      Result.new(success: true, order: order)
+    end
+  rescue PaymentGateway::Error => e
+    Result.new(success: false, error: e.message)
+  end
+
+  Result = Struct.new(:success, :order, :error, keyword_init: true)
+end
+```
+
+### 4. Background Jobs — Sidekiq/ActiveJob
+
+Isolate slow work: emails, API calls, reports. Keep jobs idempotent.
+
+```ruby
+class SyncInventoryJob < ApplicationJob
+  queue_as :default
+  retry_on Net::OpenTimeout, wait: :polynomially_longer, attempts: 5
+
+  def perform(product_id)
+    product = Product.find(product_id)
+    stock = WarehouseApi.fetch_stock(product.sku)
+    product.update!(quantity: stock.available)
+  end
+end
+```
+
+### 5. Hotwire — Turbo Frames and Streams
+
+Replace SPA complexity with server-rendered partials streamed over WebSocket.
+
+```erb
+<!-- app/views/orders/index.html.erb -->
+<%= turbo_stream_from "orders" %>
+
+<div id="orders">
+  <%= turbo_frame_tag "orders_list" do %>
+    <%= render @orders %>
+  <% end %>
+</div>
+```
+
+```ruby
+# Broadcast from model or job
+class Order < ApplicationRecord
+  after_create_commit -> {
+    broadcast_prepend_to "orders",
+      partial: "orders/order",
+      locals: { order: self }
+  }
+end
+```
+
+### 6. Turbo Stream Actions
+
+Use `turbo_stream` responses for form submissions without full page reloads.
+
+```ruby
+# app/controllers/comments_controller.rb
+def create
+  @comment = @post.comments.build(comment_params)
+  if @comment.save
+    respond_to do |format|
+      format.turbo_stream
+      format.html { redirect_to @post }
+    end
+  else
+    render :new, status: :unprocessable_entity
+  end
+end
+```
+
+```erb
+<!-- app/views/comments/create.turbo_stream.erb -->
+<%= turbo_stream.append "comments", @comment %>
+<%= turbo_stream.replace "comment_form", partial: "comments/form", locals: { comment: Comment.new } %>
+```
+
+## Examples
+
+| Pattern | When | Benefit |
+|---------|------|---------|
+| Scopes | Repeated query logic | Composable, testable queries |
+| Concerns | Shared model behavior | DRY without deep inheritance |
+| Service objects | Multi-step transactions | Testable, single-responsibility |
+| Background jobs | Slow external calls | Non-blocking, retry-safe |
+| Turbo Frames | Inline editing, modals | No JS framework needed |
+| Turbo Streams | Live updates | Real-time without polling |
+
+## Checklist
+
+- [ ] Models have no business logic beyond validations, scopes, and associations
+- [ ] Multi-model mutations live in service objects with explicit inputs
+- [ ] Concerns are under 50 lines and represent a single behavior
+- [ ] Background jobs are idempotent — safe to retry
+- [ ] Jobs use `retry_on` with backoff for transient failures
+- [ ] Turbo Frames wrap independently-loadable page sections
+- [ ] Turbo Streams broadcast from `after_commit` (not `after_save`) to avoid race conditions
+- [ ] N+1 queries are caught with `strict_loading` or Bullet gem
+- [ ] Database indexes exist for all foreign keys and columns used in scopes
+- [ ] Controllers stay under 10 lines per action — delegate to services

package/assets/skills/rust-patterns.md

@@ -0,0 +1,211 @@
+---
+name: rust-patterns
+description: Rust patterns for ownership, lifetimes, traits, error handling with thiserror/anyhow, async, and serde.
+---
+
+# Rust Patterns
+
+## When to Use
+
+Apply these patterns when writing Rust code. Use this skill for managing ownership
+and lifetimes correctly, designing trait-based abstractions, handling errors with
+thiserror (libraries) and anyhow (applications), writing async code with tokio, and
+serializing data with serde.
+
+## How It Works
+
+### Ownership and Borrowing
+
+Pass by reference (`&T`) when you only need to read. Pass by `&mut T` when you
+need to modify. Take ownership (`T`) when the function needs to store or consume
+the value. Use `Clone` explicitly rather than fighting the borrow checker.
+
+```rust
+// Borrow for read-only access
+fn word_count(text: &str) -> usize {
+    text.split_whitespace().count()
+}
+
+// Take ownership when storing
+struct Cache {
+    entries: HashMap<String, Vec<u8>>,
+}
+
+impl Cache {
+    fn insert(&mut self, key: String, value: Vec<u8>) {
+        self.entries.insert(key, value);
+    }
+}
+```
+
+### Lifetimes
+
+Only annotate lifetimes when the compiler cannot infer them. The most common case
+is a struct that borrows data.
+
+```rust
+struct Parser<'a> {
+    input: &'a str,
+    pos: usize,
+}
+
+impl<'a> Parser<'a> {
+    fn new(input: &'a str) -> Self {
+        Self { input, pos: 0 }
+    }
+
+    fn remaining(&self) -> &'a str {
+        &self.input[self.pos..]
+    }
+}
+```
+
+### Traits and Trait Objects
+
+Use traits for polymorphism. Prefer generics (`impl Trait`) for static dispatch.
+Use `dyn Trait` for dynamic dispatch when you need heterogeneous collections.
+
+```rust
+trait Renderer {
+    fn render(&self, data: &Document) -> String;
+}
+
+// Static dispatch (monomorphized, zero-cost)
+fn render_to_file(renderer: &impl Renderer, doc: &Document, path: &Path) -> io::Result<()> {
+    let output = renderer.render(doc);
+    fs::write(path, output)
+}
+
+// Dynamic dispatch (when you need a collection of different types)
+fn render_all(renderers: &[Box<dyn Renderer>], doc: &Document) -> Vec<String> {
+    renderers.iter().map(|r| r.render(doc)).collect()
+}
+```
+
+### Error Handling: thiserror for Libraries
+
+Use `thiserror` in library crates to define structured error types. Each variant
+wraps an underlying error or carries context.
+
+```rust
+use thiserror::Error;
+
+#[derive(Error, Debug)]
+pub enum StorageError {
+    #[error("file not found: {path}")]
+    NotFound { path: String },
+
+    #[error("permission denied: {path}")]
+    PermissionDenied { path: String },
+
+    #[error("IO error")]
+    Io(#[from] std::io::Error),
+
+    #[error("deserialization failed")]
+    Parse(#[from] serde_json::Error),
+}
+```
+
+### Error Handling: anyhow for Applications
+
+Use `anyhow` in binaries and CLI tools. Attach context with `.context()`.
+
+```rust
+use anyhow::{Context, Result};
+
+fn load_config(path: &Path) -> Result<Config> {
+    let content = fs::read_to_string(path)
+        .with_context(|| format!("failed to read config from {}", path.display()))?;
+
+    let config: Config = toml::from_str(&content)
+        .context("failed to parse config TOML")?;
+
+    Ok(config)
+}
+```
+
+### Async with Tokio
+
+Use `tokio::spawn` for concurrent tasks. Use `tokio::select!` for racing futures.
+Always use timeouts on network operations.
+
+```rust
+use tokio::time::{timeout, Duration};
+
+async fn fetch_with_timeout(url: &str) -> Result<String> {
+    let result = timeout(Duration::from_secs(10), reqwest::get(url))
+        .await
+        .context("request timed out")?
+        .context("request failed")?
+        .text()
+        .await
+        .context("failed to read body")?;
+    Ok(result)
+}
+
+async fn fetch_all(urls: Vec<String>) -> Vec<Result<String>> {
+    let handles: Vec<_> = urls.into_iter()
+        .map(|url| tokio::spawn(async move { fetch_with_timeout(&url).await }))
+        .collect();
+
+    let mut results = Vec::new();
+    for handle in handles {
+        results.push(handle.await.unwrap_or_else(|e| Err(e.into())));
+    }
+    results
+}
+```
+
+### Serde
+
+Derive `Serialize`/`Deserialize`. Use `#[serde(rename_all = "camelCase")]` for
+JSON APIs. Use `#[serde(default)]` for optional fields with defaults.
+
+```rust
+use serde::{Deserialize, Serialize};
+
+#[derive(Debug, Serialize, Deserialize)]
+#[serde(rename_all = "camelCase")]
+struct ApiResponse {
+    request_id: String,
+    #[serde(default)]
+    items: Vec<Item>,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    next_cursor: Option<String>,
+}
+```
+
+## Examples
+
+**Pattern: Builder for complex structs**
+```rust
+struct Request {
+    url: String,
+    timeout: Duration,
+    headers: HashMap<String, String>,
+}
+
+struct RequestBuilder { inner: Request }
+
+impl RequestBuilder {
+    fn new(url: impl Into<String>) -> Self {
+        Self { inner: Request { url: url.into(), timeout: Duration::from_secs(30), headers: HashMap::new() } }
+    }
+    fn timeout(mut self, d: Duration) -> Self { self.inner.timeout = d; self }
+    fn header(mut self, k: impl Into<String>, v: impl Into<String>) -> Self { self.inner.headers.insert(k.into(), v.into()); self }
+    fn build(self) -> Request { self.inner }
+}
+```
+
+## Checklist
+
+- [ ] Borrow (`&T`) by default; take ownership only when storing or consuming
+- [ ] Lifetime annotations only where the compiler requires them
+- [ ] `thiserror` for library error types, `anyhow` for application error handling
+- [ ] Every `?` operator has context attached via `.context()` or descriptive error variant
+- [ ] Traits are small (1-3 methods), defined at the consumer
+- [ ] `impl Trait` for static dispatch, `dyn Trait` only for heterogeneous collections
+- [ ] Async code uses `tokio::timeout` on all network operations
+- [ ] Serde types use `rename_all`, `default`, and `skip_serializing_if`
+- [ ] `clippy` passes with zero warnings (`cargo clippy -- -D warnings`)
+- [ ] Tests use `#[test]` or `#[tokio::test]`, assertions use `assert_eq!`/`assert!`