@dynokostya/just-works 1.0.0

package/.claude/skills/swift-coding/SKILL.md

@@ -0,0 +1,401 @@
+---
+name: swift-coding
+description: Apply when writing or editing Swift (.swift) files. Behavioral corrections for error handling, concurrency, memory management, type safety, protocol-oriented design, security defaults, and common antipatterns. Project conventions always override these defaults.
+---
+
+# Swift Coding
+
+Match the project's existing conventions. When uncertain, read 2-3 existing files to infer the local style. Check `Package.swift` or `.xcodeproj`/`.xcworkspace` for Swift version, platform targets, and dependencies. These defaults apply only when the project has no established convention.
+
+## Never rules
+
+These are unconditional. They prevent bugs and vulnerabilities regardless of project style.
+
+- **Never force unwrap (`!`) outside tests and controlled contexts** — crashes at runtime with no recovery path. Use `guard let`, `if let`, `??`, or optional chaining. Force unwrap is acceptable in tests, `@IBOutlet`, and when failure is provably a programmer error with an explaining comment.
+- **Never `try!` outside tests** — crashes on any error. Use `do`-`catch`, `try?`, or propagate with `throws`. A network timeout, a missing file, a malformed response — any of these kill your process silently with no chance to recover or report.
+- **Never bare `catch { }` without handling** — silently swallows errors. Catch specific error types, or log and rethrow. A decode failure looks the same as a permission error, and you'll never know which one is happening in production.
+- **Never `[weak self]` without checking for nil** — accessing self after capture without `guard let self` leads to silent no-ops or partial execution. Half-completed operations are worse than failures because they corrupt state without raising errors.
+- **Never mutable global or static state** — shared mutable state causes data races. Use actors, `@MainActor`, or dependency injection. The Swift 6 concurrency model will flag these as compile errors, so fix them now.
+- **Never blocking calls on MainActor** — no `Thread.sleep()`, synchronous network calls, or heavy computation on the main thread. Use `Task`, `async`/`await`, or dispatch to a background context. Blocking main freezes the UI and triggers watchdog kills on iOS.
+- **Never `+` string concatenation in loops** — use string interpolation or array `joined(separator:)`. Swift strings are value types; repeated concatenation copies the entire buffer each time — O(n^2) at scale.
+- **Never `Random.default` for security** — not cryptographically secure. Use `SecRandomCopyBytes` or `CryptoKit` for tokens, keys, session IDs. An attacker who observes outputs can predict future ones.
+- **Never `print()` in production code** — use `os.Logger` or `OSLog`. `print` is not filterable, not structured, and persists in release builds. It cannot be searched in Console.app and adds noise to device logs.
+- **Never `class` when `struct` suffices** — default to value types. Use `class` only when you need reference semantics, inheritance, or identity. Structs are stack-allocated, thread-safe by default, and avoid retain/release overhead.
+- **Never retain cycles in closures** — escaping closures capturing `self` in classes must use `[weak self]` or `[unowned self]`. Retain cycles cause silent memory leaks that accumulate over app lifetime, eventually triggering OOM kills.
+- **Never `Any` or `AnyObject` when a protocol or generic suffices** — type erasure disables compile-time checking. Use generics, `some`, or `any` with specific protocols. A runtime cast failure is always worse than a compile error.
+
+## Error handling
+
+Use `throws` and `do`-`catch` at system boundaries. Propagate errors with `throws` through internal layers and handle them at the outermost boundary where you can take meaningful action.
+
+```swift
+enum NetworkError: Error {
+    case invalidURL(String)
+    case requestFailed(statusCode: Int)
+    case decodingFailed(underlying: Error)
+}
+
+func fetchUser(id: Int) async throws -> User {
+    guard let url = URL(string: "https://api.example.com/users/\(id)") else {
+        throw NetworkError.invalidURL("/users/\(id)")
+    }
+    let (data, response) = try await URLSession.shared.data(from: url)
+    guard let http = response as? HTTPURLResponse, (200...299).contains(http.statusCode) else {
+        throw NetworkError.requestFailed(statusCode: (response as? HTTPURLResponse)?.statusCode ?? 0)
+    }
+    do {
+        return try JSONDecoder().decode(User.self, from: data)
+    } catch {
+        throw NetworkError.decodingFailed(underlying: error)
+    }
+}
+```
+
+Use `guard` for early exits. It keeps the happy path unindented and makes preconditions explicit:
+
+```swift
+func process(order: Order?) throws -> Receipt {
+    guard let order else { throw AppError.missingOrder }
+    guard order.items.isEmpty == false else { throw AppError.emptyOrder }
+    guard order.total > 0 else { throw AppError.invalidTotal(order.total) }
+    return Receipt(order: order, timestamp: .now)
+}
+```
+
+When to use `Result` vs `throws`: prefer `throws` for most code. Use `Result` when you need to store an outcome for later processing, pass it across non-throwing boundaries, or work with callback-based APIs that cannot be made async.
+
+Swift 6 typed throws allow callers to handle specific error types without type erasure:
+
+```swift
+func validate(input: String) throws(ValidationError) -> Validated {
+    guard input.count >= 3 else { throw .tooShort(minimum: 3) }
+    return Validated(value: input)
+}
+```
+
+## Resource cleanup
+
+Use `defer` for cleanup — file handles, locks, temporary state restoration. `defer` executes when the scope exits regardless of how (return, throw, break):
+
+```swift
+func writeData(_ data: Data, to path: String) throws {
+    let handle = try FileHandle(forWritingTo: URL(filePath: path))
+    defer { try? handle.close() }
+    handle.write(data)
+}
+```
+
+With structured concurrency, child tasks are automatically cancelled when their parent scope exits. Prefer structured concurrency (`async let`, `TaskGroup`) over unstructured `Task { }` to get automatic cleanup for free.
+
+## Async patterns
+
+Use `async`/`await` for all asynchronous work. Prefer structured concurrency over unstructured tasks.
+
+`TaskGroup` for concurrent work with dynamic fan-out:
+
+```swift
+func fetchAllUsers(ids: [Int]) async throws -> [User] {
+    try await withThrowingTaskGroup(of: User.self) { group in
+        for id in ids {
+            group.addTask { try await fetchUser(id: id) }
+        }
+        var users: [User] = []
+        for try await user in group {
+            users.append(user)
+        }
+        return users
+    }
+}
+```
+
+Actors for shared mutable state — they serialize access automatically:
+
+```swift
+actor ImageCache {
+    private var cache: [URL: Data] = [:]
+
+    func image(for url: URL) -> Data? { cache[url] }
+
+    func store(_ data: Data, for url: URL) { cache[url] = data }
+}
+```
+
+Use `@MainActor` for UI work. Apply it to the type when all members need main-thread access, or to individual methods when only some do:
+
+```swift
+@MainActor
+final class ViewModel: Observable {
+    var items: [Item] = []
+
+    func refresh() async throws {
+        let fetched = try await service.fetchItems()
+        items = fetched
+    }
+}
+```
+
+`Sendable` conformance is required for values crossing actor boundaries. Structs and enums with all-Sendable stored properties conform automatically. For classes, mark as `final class: Sendable` with only immutable (`let`) properties or use `@unchecked Sendable` with internal synchronization.
+
+Check cancellation in long-running work:
+
+```swift
+for item in largeCollection {
+    try Task.checkCancellation()
+    await process(item)
+}
+```
+
+When to use structured vs unstructured concurrency: use `async let` and `TaskGroup` (structured) for work scoped to a function. Use `Task { }` (unstructured) only for fire-and-forget work or bridging from synchronous contexts. Structured concurrency handles cancellation and error propagation automatically.
+
+## Type system
+
+`some` (opaque types) returns a specific concrete type hidden from the caller — use it when you want to hide implementation details while preserving type identity. `any` (existentials) is a type-erased box — use it when you need heterogeneous collections or dynamic dispatch:
+
+```swift
+// Opaque: caller gets one concrete type, compiler optimizes
+func makeSequence() -> some Sequence<Int> {
+    [1, 2, 3].lazy.filter { $0 > 1 }
+}
+
+// Existential: heterogeneous collection of different types
+func allValidators() -> [any Validator] {
+    [EmailValidator(), LengthValidator(min: 3)]
+}
+```
+
+Protocols with associated types:
+
+```swift
+protocol Repository {
+    associatedtype Entity: Identifiable
+    func find(by id: Entity.ID) async throws -> Entity?
+    func save(_ entity: Entity) async throws
+}
+
+struct UserRepository: Repository {
+    typealias Entity = User
+    func find(by id: User.ID) async throws -> User? { /* ... */ }
+    func save(_ entity: User) async throws { /* ... */ }
+}
+```
+
+Generic functions with constraints:
+
+```swift
+func merge<T: Decodable & Sendable>(_ items: [T], with others: [T]) -> [T]
+    where T: Equatable
+{
+    var result = items
+    for item in others where !result.contains(item) {
+        result.append(item)
+    }
+    return result
+}
+```
+
+## Value vs reference types
+
+Default to structs. Use classes when you need reference semantics (shared mutable state), inheritance, or Objective-C interop. Use enum as a namespace (caseless enum) for grouping constants and static functions:
+
+```swift
+enum API {
+    static let baseURL = URL(string: "https://api.example.com")!
+    static let timeout: TimeInterval = 30
+}
+```
+
+Collections use copy-on-write — passing an array to a function does not copy until mutation. This means value semantics are cheap in practice for standard library types.
+
+## Data modeling
+
+| Use Case | Choice | Reason |
+|----------|--------|--------|
+| API response/request | `Codable` struct | Serialization, immutable |
+| Configuration | struct with defaults | Value semantics |
+| Domain entity with identity | class or actor | Reference semantics, shared state |
+| Simple value objects | struct | Stack-allocated, value equality |
+| Fixed set of states | enum with associated values | Exhaustive switch, type-safe |
+| UI state (SwiftUI) | `@Observable` class | Observation framework |
+
+Codable at system boundaries:
+
+```swift
+struct UserResponse: Codable, Sendable {
+    let id: Int
+    let email: String
+    let name: String
+    let createdAt: Date
+
+    enum CodingKeys: String, CodingKey {
+        case id, email, name
+        case createdAt = "created_at"
+    }
+}
+```
+
+Enums with associated values for domain states:
+
+```swift
+enum PaymentResult {
+    case success(transactionId: String, amount: Decimal)
+    case declined(reason: String)
+    case requiresVerification(url: URL)
+}
+
+func handle(_ result: PaymentResult) {
+    switch result {
+    case .success(let id, let amount):
+        log.info("Payment \(id) completed: \(amount)")
+    case .declined(let reason):
+        showError("Payment declined: \(reason)")
+    case .requiresVerification(let url):
+        openVerification(url)
+    }
+}
+```
+
+## Memory management
+
+ARC manages memory automatically, but you must handle reference cycles. Strong references (the default) keep objects alive. Use `weak` for optional back-references and delegates. Use `unowned` only when the referenced object is guaranteed to outlive the reference.
+
+Delegate pattern with `weak`:
+
+```swift
+protocol DownloadDelegate: AnyObject {
+    func downloadDidFinish(_ data: Data)
+}
+
+class Downloader {
+    weak var delegate: DownloadDelegate?
+
+    func start() async {
+        let data = try? await fetchData()
+        delegate?.downloadDidFinish(data ?? Data())
+    }
+}
+```
+
+Closure capture lists — always unwrap `weak self` before doing work:
+
+```swift
+service.onComplete = { [weak self] result in
+    guard let self else { return }
+    self.items = result.items
+    self.tableView.reloadData()
+}
+```
+
+Use value captures to snapshot a value at closure creation time:
+
+```swift
+let currentCount = items.count
+Task { [currentCount] in
+    await reportAnalytics(itemCount: currentCount)
+}
+```
+
+## Pattern matching
+
+`switch` must be exhaustive — the compiler enforces this for enums. Use `@unknown default` when switching on enums from external modules to catch future cases:
+
+```swift
+switch status {
+case .pending:
+    showSpinner()
+case .completed(let result):
+    display(result)
+case .failed(let error) where error is NetworkError:
+    retryButton.isHidden = false
+case .failed:
+    showGenericError()
+@unknown default:
+    showGenericError()
+}
+```
+
+`if case let` and `guard case let` for single-pattern extraction:
+
+```swift
+if case .success(let user) = result {
+    greet(user)
+}
+
+guard case .authenticated(let token) = session else {
+    throw AuthError.notAuthenticated
+}
+```
+
+Tuple patterns for combining conditions:
+
+```swift
+switch (isLoggedIn, hasPermission) {
+case (true, true):  proceed()
+case (true, false): requestPermission()
+case (false, _):    showLogin()
+}
+```
+
+## Naming conventions
+
+Follow the [Swift API Design Guidelines](https://www.swift.org/documentation/api-design-guidelines/). Types and protocols use UpperCamelCase. Properties, methods, variables, and arguments use lowerCamelCase.
+
+Booleans read as assertions: `isEmpty`, `hasPermission`, `canFly`, `shouldRefresh`. Mutating/nonmutating pairs: `sort()`/`sorted()`, `append()`/`appending()`, `formUnion()`/`union()`.
+
+Argument labels form prepositional phrases with the method name: `move(to: position)`, `remove(at: index)`, `fade(from: color, to: color)`. Omit the label when the argument is the direct object of the verb: `print(value)`, `contains(element)`.
+
+Protocols that describe what something is use nouns: `Collection`, `Sequence`, `Error`. Protocols that describe a capability use `-able`/`-ible`: `Codable`, `Sendable`, `Identifiable`.
+
+## Testing
+
+Use Swift Testing (`@Test`, `#expect`, `#require`, `@Suite`) for new tests. Use XCTest for UI tests and when the project is already standardized on it.
+
+```swift
+@Suite("UserService")
+struct UserServiceTests {
+    let service = UserService(repository: MockRepository())
+
+    @Test("Returns user when found")
+    func userFound() async throws {
+        let user = try await service.getUser(id: 42)
+        #expect(user.name == "Alice")
+    }
+
+    @Test("Throws not found for missing user")
+    func userNotFound() async {
+        await #expect(throws: AppError.notFound) {
+            try await service.getUser(id: 999)
+        }
+    }
+
+    @Test("Validates email formats", arguments: [
+        ("alice@example.com", true),
+        ("not-an-email", false),
+        ("", false),
+    ])
+    func emailValidation(email: String, isValid: Bool) {
+        #expect(EmailValidator.isValid(email) == isValid)
+    }
+}
+```
+
+Swift Testing provides parameterized tests via `arguments`, tags for organizing, and traits for configuring behavior. `#expect` replaces `XCTAssertEqual` with a single macro that captures the expression. `#require` unwraps optionals or throws on failure, replacing `XCTUnwrap`.
+
+When to mock: external APIs with rate limits or costs, network-dependent behavior, error paths. When to use real instances: pure logic, value types, in-memory implementations. Test behavior, not implementation — test what a function returns or what state it changes, not how it works internally.
+
+## Concurrency migration (Swift 6)
+
+Enable strict concurrency checking incrementally. Start with warnings (`-strict-concurrency=targeted`), then move to `complete`, then enable the Swift 6 language mode.
+
+Fix bottom-up: start with leaf modules that have no dependencies, make their types `Sendable`, then work up the dependency graph. Mark callbacks and closures as `@Sendable` when they cross isolation boundaries.
+
+Use `nonisolated` to opt methods out of an actor's isolation when they only access immutable or `Sendable` state:
+
+```swift
+actor SessionManager {
+    let configuration: AppConfiguration  // immutable
+
+    nonisolated var appName: String {
+        configuration.name
+    }
+}
+```

package/.claude/skills/tailwind-css-coding/SKILL.md

@@ -0,0 +1,268 @@
+---
+name: tailwind-css-coding
+description: Apply when writing or editing Tailwind CSS classes in any template or component file. Behavioral corrections for dynamic styling, class composition, responsive design, dark mode, interaction states, accessibility, and common antipatterns. Project conventions always override these defaults.
+---
+
+# Tailwind CSS Coding
+
+Match the project's existing conventions. When uncertain, read 2-3 existing components to infer the local style. Check `package.json` for the `tailwindcss` version. v4 signals: `@tailwindcss/postcss` or `@tailwindcss/vite` in deps, `@import "tailwindcss"` in CSS, `@theme {}` blocks. v3 signals: `tailwind.config.js` with `module.exports`, `@tailwind base;` directives, `autoprefixer` as separate dep. These defaults apply only when the project has no established convention.
+
+## Never rules
+
+These are unconditional. They prevent broken builds, invisible bugs, and inaccessible UI regardless of project style.
+
+- **Never construct class names dynamically** -- Tailwind's compiler scans source files as plain text with regex. It never executes code. Template literals, string concatenation, and interpolation produce classes the compiler cannot find. Use lookup maps of complete static strings.
+
+```tsx
+// Wrong: compiler cannot extract "bg-red-500" from this
+const cls = `bg-${color}-500`;
+
+// Correct: every class is a complete static string
+const bgMap = {
+  red: "bg-red-500",
+  blue: "bg-blue-500",
+} as const;
+const cls = bgMap[color];
+```
+
+- **Never use template literal concatenation for class composition** -- CSS source order determines which class wins when two utilities target the same property, not HTML attribute order. `p-4 p-6` is unpredictable. Use `cn()` (clsx + tailwind-merge) to merge classes safely.
+
+```tsx
+// Wrong: conflicting padding, last-in-source wins (not last-in-string)
+className={`p-4 ${isLarge ? "p-6" : ""}`}
+
+// Correct: tailwind-merge resolves conflicts deterministically
+import { cn } from "@/lib/utils";
+className={cn("p-4", isLarge && "p-6")}
+```
+
+- **Never use arbitrary values when a design token exists** -- `p-[16px]` is `p-4`. `bg-[#3b82f6]` is `bg-blue-500`. `w-[100%]` is `w-full`. `text-[14px]` is `text-sm`. Arbitrary values bypass the design system and create inconsistency.
+
+- **Never omit interaction states on interactive elements** -- every button and link needs `hover:`, `focus-visible:`, and `disabled:` states. Add `transition-colors` for smooth feedback. In v4: add `cursor-pointer` explicitly -- Preflight no longer sets it on buttons.
+
+```tsx
+// Wrong: no interaction feedback
+<button className="bg-blue-500 text-white px-4 py-2 rounded">Save</button>
+
+// Correct: full interaction states (v4: include cursor-pointer)
+<button className="bg-blue-500 text-white px-4 py-2 rounded hover:bg-blue-600 focus-visible:outline-2 focus-visible:outline-offset-2 focus-visible:outline-blue-500 disabled:opacity-50 disabled:cursor-not-allowed transition-colors cursor-pointer">
+  Save
+</button>
+```
+
+- **Never use `@apply` for patterns extractable to components** -- extract a React/Vue/Svelte component instead. `@apply` is only for third-party library overrides, CMS/Markdown HTML, and non-component template languages.
+
+- **Never forget dark mode counterparts** -- every `bg-`, `text-`, and `border-` color needs a `dark:` variant, or use CSS variable theming to handle both modes in one declaration.
+
+- **Never use `sm:` thinking it means "small screens"** -- `sm:` means 640px AND ABOVE. Unprefixed utilities apply to all screens (mobile-first). Write base styles for mobile, then layer breakpoints upward.
+
+```html
+<!-- Wrong mental model: "sm means small phones" -->
+<div class="hidden sm:block">Only on small screens</div>
+
+<!-- Correct: sm:block means "show at 640px and above" -->
+<div class="block sm:hidden">Mobile only</div>
+<div class="hidden sm:block">Desktop only</div>
+```
+
+- **Never hallucinate class names** -- common fakes: `flex-center` (use `flex items-center justify-center`), `text-bold` (use `font-bold`), `bg-grey-500` (American spelling: `bg-gray-500`), `d-flex` (Bootstrap, not Tailwind).
+
+- **Never output conflicting utilities** -- `p-4 p-6` is unpredictable. One value per CSS property. Don't redundantly set defaults (`flex flex-row`, `flex flex-nowrap`).
+
+- **Never forget accessibility** -- use `sr-only` for icon-only button labels, `focus:not-sr-only` for skip links. Every interactive element needs visible focus indication via `focus-visible:`.
+
+## Dynamic styling
+
+For conditional classes, use `cn()` (clsx + tailwind-merge). For truly dynamic values that cannot be enumerated (user-set colors, computed positions), use inline `style` props -- these bypass the compiler entirely and always work.
+
+```tsx
+// Conditional classes: cn()
+<div className={cn("rounded p-4", isActive && "ring-2 ring-blue-500")} />
+
+// Truly dynamic: inline style
+<div className="rounded p-4" style={{ backgroundColor: user.brandColor }} />
+```
+
+For variant-driven styling, use a lookup map with complete static strings:
+
+```tsx
+const sizeClasses = {
+  sm: "px-2 py-1 text-sm",
+  md: "px-4 py-2 text-base",
+  lg: "px-6 py-3 text-lg",
+} as const;
+
+function Button({ size = "md", className, ...props }: ButtonProps) {
+  return <button className={cn(sizeClasses[size], className)} {...props} />;
+}
+```
+
+For components with 2+ variant dimensions, consider `cva` from class-variance-authority.
+
+When the compiler must see classes that only appear in dynamic data (CMS content, database values), safelist them. In v4: `@source inline("bg-red-500 bg-blue-500")`. In v3: `safelist` array in `tailwind.config.js`.
+
+## Class composition
+
+The `cn()` helper combines `clsx` (conditional joining) with `tailwind-merge` (conflict resolution). Standard setup:
+
+```ts
+import { clsx, type ClassValue } from "clsx";
+import { twMerge } from "tailwind-merge";
+
+export function cn(...inputs: ClassValue[]) {
+  return twMerge(clsx(inputs));
+}
+```
+
+Use `cn()` whenever merging external `className` props with internal defaults -- raw concatenation silently breaks when both sides set the same property.
+
+```tsx
+// Wrong: parent's p-6 may or may not override internal p-4
+function Card({ className }: { className?: string }) {
+  return <div className={`rounded bg-white p-4 ${className}`} />;
+}
+
+// Correct: tailwind-merge ensures parent overrides win
+function Card({ className }: { className?: string }) {
+  return <div className={cn("rounded bg-white p-4", className)} />;
+}
+```
+
+## Responsive design
+
+Mobile-first: write base styles for the smallest screen, then add breakpoints upward. Always order breakpoints `sm:` -> `md:` -> `lg:` -> `xl:` -> `2xl:`. Never skip to `lg:` without considering the gap.
+
+```html
+<!-- Single column on mobile, two on tablet, three on desktop -->
+<div class="grid grid-cols-1 sm:grid-cols-2 lg:grid-cols-3 gap-4">
+```
+
+In v4: container queries are built-in (no plugin). Use `@container` for component-scoped responsive design:
+
+```tsx
+// Parent declares a container
+<div className="@container">
+  {/* Child responds to container width, not viewport */}
+  <div className="flex flex-col @md:flex-row @lg:grid @lg:grid-cols-3 gap-4">
+    {children}
+  </div>
+</div>
+```
+
+## Dark mode
+
+Cover every visible color. A component with `bg-white text-gray-900` needs `dark:bg-gray-900 dark:text-white`. Missing a single `dark:` variant causes unreadable text or invisible elements.
+
+Better approach -- CSS variable theming. Define colors once, switch palettes:
+
+```css
+/* v4: @theme block */
+@theme {
+  --color-surface: #ffffff;
+  --color-on-surface: #111827;
+}
+
+@custom-variant dark (&:where(.dark, .dark *));
+
+.dark {
+  --color-surface: #111827;
+  --color-on-surface: #f9fafb;
+}
+```
+
+Then use `bg-surface text-on-surface` everywhere -- no `dark:` variants needed per component.
+
+## Interaction states
+
+Minimum states for buttons: `hover:`, `focus-visible:`, `disabled:`, `transition-colors`. Minimum for inputs: `focus:`, `disabled:`, `placeholder:`. Minimum for links: `hover:`, `focus-visible:`.
+
+```tsx
+// Complete button pattern
+<button className={cn(
+  "px-4 py-2 rounded font-medium transition-colors",
+  "bg-blue-600 text-white",
+  "hover:bg-blue-700",
+  "focus-visible:outline-2 focus-visible:outline-offset-2 focus-visible:outline-blue-600",
+  "disabled:opacity-50 disabled:cursor-not-allowed",
+  "cursor-pointer" // v4: Preflight no longer sets cursor:pointer on buttons
+)}>
+```
+
+Complete input pattern:
+
+```tsx
+<input className={cn(
+  "w-full rounded border px-3 py-2 transition-colors",
+  "border-gray-300 bg-white text-gray-900",
+  "dark:border-gray-600 dark:bg-gray-800 dark:text-white",
+  "placeholder:text-gray-400 dark:placeholder:text-gray-500",
+  "focus:border-blue-500 focus:outline-none focus:ring-1 focus:ring-blue-500",
+  "disabled:cursor-not-allowed disabled:bg-gray-100 disabled:opacity-50",
+)} />
+```
+
+In v4: `hover:` only fires on hover-capable devices (`@media (hover: hover)`). Touch-only devices skip hover styles entirely -- don't rely on hover for critical information.
+
+## Accessibility
+
+Icon-only buttons need screen reader text:
+
+```tsx
+<button className="p-2 rounded hover:bg-gray-100">
+  <SearchIcon className="h-5 w-5" aria-hidden="true" />
+  <span className="sr-only">Search</span>
+</button>
+```
+
+Skip links use `sr-only` that becomes visible on focus:
+
+```tsx
+<a href="#main" className="sr-only focus:not-sr-only focus:absolute focus:top-4 focus:left-4 focus:z-50 focus:px-4 focus:py-2 focus:bg-white focus:text-black focus:rounded">
+  Skip to main content
+</a>
+```
+
+Every focusable element needs a visible focus indicator. `focus-visible:` is preferred over `focus:` -- it only shows for keyboard navigation, not mouse clicks.
+
+Ensure sufficient color contrast on interactive states. A `hover:bg-blue-700` on `bg-blue-600` is barely visible -- test both light and dark modes.
+
+## v4 configuration
+
+In v4, configuration lives in CSS, not JavaScript. Entry point is `@import "tailwindcss"`. Autoprefixer is built-in (don't add it separately).
+
+```css
+@import "tailwindcss";
+
+@theme {
+  --font-display: "Inter", sans-serif;
+  --color-brand: #4f46e5;
+  --breakpoint-3xl: 1920px;
+}
+
+@utility card {
+  background: var(--color-surface);
+  border-radius: var(--radius-lg);
+  padding: var(--spacing-6);
+}
+```
+
+Key v4 renames (old names still work via compat but generate warnings):
+
+```
+v3                    v4
+shadow            ->  shadow-sm       ring              ->  ring-3
+shadow-sm         ->  shadow-xs       outline-none      ->  outline-hidden
+rounded           ->  rounded-sm      bg-gradient-to-r  ->  bg-linear-to-r
+rounded-sm        ->  rounded-xs      blur              ->  blur-sm
+```
+
+Other v4 changes inline:
+
+```tsx
+// v3: bg-opacity-50       -> v4: bg-black/50 (opacity modifier)
+// v3: bg-[--brand-color]  -> v4: bg-(--brand-color) (CSS variable syntax)
+// v3: !bg-red-500         -> v4: bg-red-500! (important modifier at end)
+// v3: first:*:pt-0        -> v4: *:first:pt-0 (variant stacking left-to-right)
+```
+
+Borders default to `currentColor` in v4, not `gray-200`. Add explicit border colors if the v3 default was relied upon. Custom utilities via `@utility name {}` not `@layer components {}`. Safelist via `@source inline("...")` not `safelist` array.