@cubis/foundry 0.3.71 → 0.3.72

package/workflows/powers/swift-pro/references/testing-and-packages.md

@@ -0,0 +1,192 @@
+# Testing and Packages
+
+## Swift Testing framework
+
+### Basic test structure
+
+```swift
+import Testing
+
+@Test("User creation sets default role")
+func userCreationDefault() {
+    let user = User(name: "Alice")
+    #expect(user.role == .viewer)
+}
+
+@Test("Deposit increases balance")
+func depositIncreasesBalance() async throws {
+    let account = BankAccount(balance: 100)
+    try await account.deposit(50)
+    let balance = await account.balance
+    #expect(balance == 150)
+}
+```
+
+- Use `@Test` attribute with descriptive display names.
+- Use `#expect` for assertions — clearer failure messages than XCTest.
+- Use `#require` for preconditions that should abort the test on failure.
+
+### Parameterized tests
+
+```swift
+@Test("Parse valid integers", arguments: [
+    ("42", 42),
+    ("-1", -1),
+    ("0", 0),
+])
+func parseValid(input: String, expected: Int) throws {
+    let result = try parse(input)
+    #expect(result == expected)
+}
+```
+
+- Use `arguments:` to run the same test logic across multiple inputs.
+- Each argument combination runs as a separate test case with individual pass/fail.
+
+### Test organization with suites
+
+```swift
+@Suite("User Repository")
+struct UserRepositoryTests {
+    let repo: MockUserRepository
+
+    init() {
+        repo = MockUserRepository()
+    }
+
+    @Test func findExistingUser() async throws {
+        repo.seed(User(id: 1, name: "Alice"))
+        let user = try await repo.find(id: 1)
+        #expect(user?.name == "Alice")
+    }
+
+    @Test func findMissingReturnsNil() async throws {
+        let user = try await repo.find(id: 999)
+        #expect(user == nil)
+    }
+}
+```
+
+- `@Suite` groups related tests with shared setup in `init()`.
+- Each test gets a fresh instance — no shared mutable state between tests.
+
+### Testing async and actor code
+
+```swift
+@Test func actorStateUpdates() async {
+    let cache = ImageCache()
+    await cache.store(image, forKey: "logo")
+    let retrieved = await cache.get("logo")
+    #expect(retrieved != nil)
+}
+
+// Test expected errors
+@Test func withdrawInsufficientFunds() async {
+    let account = BankAccount(balance: 50)
+    await #expect(throws: BankError.insufficientFunds) {
+        try await account.withdraw(100)
+    }
+}
+```
+
+### Confirmation for event-driven behavior
+
+```swift
+@Test func notificationFired() async {
+    await confirmation("User saved notification") { confirm in
+        let observer = NotificationCenter.default.addObserver(
+            forName: .userSaved, object: nil, queue: nil
+        ) { _ in
+            confirm()
+        }
+        await service.saveUser(user)
+        NotificationCenter.default.removeObserver(observer)
+    }
+}
+```
+
+## Dependency injection for tests
+
+### Protocol-based injection
+
+```swift
+protocol NetworkClient: Sendable {
+    func data(from url: URL) async throws -> (Data, URLResponse)
+}
+
+// Production
+struct URLSessionClient: NetworkClient {
+    func data(from url: URL) async throws -> (Data, URLResponse) {
+        try await URLSession.shared.data(from: url)
+    }
+}
+
+// Test
+struct MockNetworkClient: NetworkClient {
+    var responses: [URL: (Data, URLResponse)] = [:]
+
+    func data(from url: URL) async throws -> (Data, URLResponse) {
+        guard let response = responses[url] else {
+            throw URLError(.badURL)
+        }
+        return response
+    }
+}
+
+// Injection
+class UserService {
+    private let network: NetworkClient
+
+    init(network: NetworkClient = URLSessionClient()) {
+        self.network = network
+    }
+}
+```
+
+- Inject dependencies through initializer parameters with production defaults.
+- Keep mock types simple — only implement what the test needs.
+- Avoid mocking frameworks unless the mock implementation becomes complex.
+
+## Package.swift module organization
+
+### Multi-target package
+
+```swift
+// swift-tools-version: 6.0
+import PackageDescription
+
+let package = Package(
+    name: "MyApp",
+    platforms: [.iOS(.v17), .macOS(.v14)],
+    products: [
+        .library(name: "Domain", targets: ["Domain"]),
+        .library(name: "Networking", targets: ["Networking"]),
+    ],
+    dependencies: [
+        .package(url: "https://github.com/apple/swift-algorithms", from: "1.2.0"),
+    ],
+    targets: [
+        // Core domain — no external dependencies
+        .target(name: "Domain"),
+
+        // Networking depends on Domain
+        .target(name: "Networking", dependencies: ["Domain"]),
+
+        // Tests
+        .testTarget(name: "DomainTests", dependencies: ["Domain"]),
+        .testTarget(name: "NetworkingTests", dependencies: [
+            "Networking",
+            .product(name: "Algorithms", package: "swift-algorithms"),
+        ]),
+    ]
+)
+```
+
+### Package organization guidelines
+
+- Keep `Domain` (models, protocols, business logic) as a standalone target with zero external dependencies.
+- Put I/O, networking, and persistence in separate targets that depend on `Domain`.
+- Use `@testable import` only in test targets.
+- Pin dependency versions with `.upToNextMinor(from:)` for stability. Use `.upToNextMajor(from:)` only for well-trusted packages.
+- Keep `Package.resolved` in version control for applications. Omit it for library packages.
+- Use conditional compilation (`#if canImport(UIKit)`) for platform-specific code in multi-platform targets.

package/workflows/powers/tailwind-patterns/POWER.md

@@ -2,271 +2,102 @@
 ---
 inclusion: manual
 name: tailwind-patterns
-description: Tailwind CSS v4 principles. CSS-first configuration, container queries, modern patterns, design token architecture.
-allowed-tools: Read, Write, Edit, Glob, Grep
+description: "Use for Tailwind CSS v4 architecture, CSS-first theme setup, utility composition, container-query usage, design-token hygiene, and dark-mode strategy."
+license: MIT
+metadata:
+  author: cubis-foundry
+  version: "4.0"
+compatibility: Claude Code, Codex, GitHub Copilot
 ---
 
-# Tailwind CSS Patterns (v4 - 2025)
+# Tailwind Patterns
 
-> Modern utility-first CSS with CSS-native configuration.
+## Purpose
 
----
-
-## 1. Tailwind v4 Architecture
-
-### What Changed from v3
-
-| v3 (Legacy) | v4 (Current) |
-|-------------|--------------|
-| `tailwind.config.js` | CSS-based `@theme` directive |
-| PostCSS plugin | Oxide engine (10x faster) |
-| JIT mode | Native, always-on |
-| Plugin system | CSS-native features |
-| `@apply` directive | Still works, discouraged |
-
-### v4 Core Concepts
-
-| Concept | Description |
-|---------|-------------|
-| **CSS-first** | Configuration in CSS, not JavaScript |
-| **Oxide Engine** | Rust-based compiler, much faster |
-| **Native Nesting** | CSS nesting without PostCSS |
-| **CSS Variables** | All tokens exposed as `--*` vars |
-
----
-
-## 2. CSS-Based Configuration
-
-### Theme Definition
-
-```
-@theme {
-  /* Colors - use semantic names */
-  --color-primary: oklch(0.7 0.15 250);
-  --color-surface: oklch(0.98 0 0);
-  --color-surface-dark: oklch(0.15 0 0);
-  
-  /* Spacing scale */
-  --spacing-xs: 0.25rem;
-  --spacing-sm: 0.5rem;
-  --spacing-md: 1rem;
-  --spacing-lg: 2rem;
-  
-  /* Typography */
-  --font-sans: 'Inter', system-ui, sans-serif;
-  --font-mono: 'JetBrains Mono', monospace;
-}
-```
-
-### When to Extend vs Override
-
-| Action | Use When |
-|--------|----------|
-| **Extend** | Adding new values alongside defaults |
-| **Override** | Replacing default scale entirely |
-| **Semantic tokens** | Project-specific naming (primary, surface) |
-
----
-
-## 3. Container Queries (v4 Native)
-
-### Breakpoint vs Container
-
-| Type | Responds To |
-|------|-------------|
-| **Breakpoint** (`md:`) | Viewport width |
-| **Container** (`@container`) | Parent element width |
-
-### Container Query Usage
-
-| Pattern | Classes |
-|---------|---------|
-| Define container | `@container` on parent |
-| Container breakpoint | `@sm:`, `@md:`, `@lg:` on children |
-| Named containers | `@container/card` for specificity |
-
-### When to Use
-
-| Scenario | Use |
-|----------|-----|
-| Page-level layouts | Viewport breakpoints |
-| Component-level responsive | Container queries |
-| Reusable components | Container queries (context-independent) |
-
----
-
-## 4. Responsive Design
-
-### Breakpoint System
-
-| Prefix | Min Width | Target |
-|--------|-----------|--------|
-| (none) | 0px | Mobile-first base |
-| `sm:` | 640px | Large phone / small tablet |
-| `md:` | 768px | Tablet |
-| `lg:` | 1024px | Laptop |
-| `xl:` | 1280px | Desktop |
-| `2xl:` | 1536px | Large desktop |
-
-### Mobile-First Principle
-
-1. Write mobile styles first (no prefix)
-2. Add larger screen overrides with prefixes
-3. Example: `w-full md:w-1/2 lg:w-1/3`
-
----
-
-## 5. Dark Mode
-
-### Configuration Strategies
-
-| Method | Behavior | Use When |
-|--------|----------|----------|
-| `class` | `.dark` class toggles | Manual theme switcher |
-| `media` | Follows system preference | No user control |
-| `selector` | Custom selector (v4) | Complex theming |
-
-### Dark Mode Pattern
-
-| Element | Light | Dark |
-|---------|-------|------|
-| Background | `bg-white` | `dark:bg-zinc-900` |
-| Text | `text-zinc-900` | `dark:text-zinc-100` |
-| Borders | `border-zinc-200` | `dark:border-zinc-700` |
-
----
-
-## 6. Modern Layout Patterns
-
-### Flexbox Patterns
-
-| Pattern | Classes |
-|---------|---------|
-| Center (both axes) | `flex items-center justify-center` |
-| Vertical stack | `flex flex-col gap-4` |
-| Horizontal row | `flex gap-4` |
-| Space between | `flex justify-between items-center` |
-| Wrap grid | `flex flex-wrap gap-4` |
-
-### Grid Patterns
-
-| Pattern | Classes |
-|---------|---------|
-| Auto-fit responsive | `grid grid-cols-[repeat(auto-fit,minmax(250px,1fr))]` |
-| Asymmetric (Bento) | `grid grid-cols-3 grid-rows-2` with spans |
-| Sidebar layout | `grid grid-cols-[auto_1fr]` |
-
-> **Note:** Prefer asymmetric/Bento layouts over symmetric 3-column grids.
-
----
-
-## 7. Modern Color System
-
-### OKLCH vs RGB/HSL
-
-| Format | Advantage |
-|--------|-----------|
-| **OKLCH** | Perceptually uniform, better for design |
-| **HSL** | Intuitive hue/saturation |
-| **RGB** | Legacy compatibility |
+Use for Tailwind CSS v4 architecture, CSS-first theme setup, utility composition, container-query usage, design-token hygiene, and dark-mode strategy.
 
-### Color Token Architecture
+## When to Use
 
-| Layer | Example | Purpose |
-|-------|---------|---------|
-| **Primitive** | `--blue-500` | Raw color values |
-| **Semantic** | `--color-primary` | Purpose-based naming |
-| **Component** | `--button-bg` | Component-specific |
+- Building or refactoring Tailwind-based UI systems.
+- Choosing theme token structure and CSS-first configuration.
+- Applying container queries, responsive composition, and utility extraction.
+- Reviewing class composition for maintainability and scale.
+- Setting up dark mode, color-scheme toggling, or multi-theme systems.
+- Optimizing Tailwind output for production bundle size.
 
----
+## Instructions
 
-## 8. Typography System
+1. Confirm whether the codebase is truly Tailwind-first and which v4 features are active.
+2. Establish semantic tokens (color, spacing, type, radius) before piling on utilities.
+3. Define dark-mode and color-scheme strategy at the theme level, not per-component.
+4. Use responsive and container-query rules deliberately at the component boundary.
+5. Extract repeated patterns only when reuse and readability clearly improve.
+6. Verify the result stays readable, consistent, and easy to extend.
 
-### Font Stack Pattern
+### Baseline standards
 
-| Type | Recommended |
-|------|-------------|
-| Sans | `'Inter', 'SF Pro', system-ui, sans-serif` |
-| Mono | `'JetBrains Mono', 'Fira Code', monospace` |
-| Display | `'Outfit', 'Poppins', sans-serif` |
+- Prefer CSS-first theme and token definition in v4-era setups.
+- Keep utility composition semantic at the component boundary.
+- Use container queries for component context, not everything.
+- Treat arbitrary values as exceptions, not the system.
+- Keep spacing, typography, and color scales coherent.
+- Define dark mode via `@custom-variant` or built-in `dark:` — never inline JavaScript toggling of raw classes.
+- Use CSS custom properties for tokens that need runtime switching.
 
-### Type Scale
+### Implementation guidance
 
-| Class | Size | Use |
-|-------|------|-----|
-| `text-xs` | 0.75rem | Labels, captions |
-| `text-sm` | 0.875rem | Secondary text |
-| `text-base` | 1rem | Body text |
-| `text-lg` | 1.125rem | Lead text |
-| `text-xl`+ | 1.25rem+ | Headings |
+- Use `@theme` blocks to define design tokens as CSS custom properties.
+- Prefer `@layer` directives to control specificity ordering.
+- Use `@variant` for semantic state grouping (e.g., `@variant hover, focus-visible`).
+- Keep component-level `@apply` usage to shared design-system primitives, not arbitrary shortcuts.
+- Use `@container` at the component wrapper level with named containers for clarity.
+- Compose responsive with container queries: responsive for page layout, container queries for component-internal layout.
 
----
+### Dark mode and theming
 
-## 9. Animation & Transitions
+- Define color tokens as HSL or OKLCH custom properties for easy theme switching.
+- Use `@custom-variant dark` with a class or media-query strategy — pick one per project and enforce it.
+- Keep contrast ratios WCAG AA minimum (4.5:1 text, 3:1 large text / UI).
+- Test both themes with real content, not just color swatches.
 
-### Built-in Animations
+### Performance and production
 
-| Class | Effect |
-|-------|--------|
-| `animate-spin` | Continuous rotation |
-| `animate-ping` | Attention pulse |
-| `animate-pulse` | Subtle opacity pulse |
-| `animate-bounce` | Bouncing effect |
+- Purge unused styles by keeping utility usage in template files Tailwind can scan.
+- Avoid dynamic class construction (`bg-${color}-500`) — Tailwind cannot detect these at build time.
+- Keep `@apply` chains short — long chains defeat tree-shaking.
+- Use `content` configuration to limit scan scope in monorepos.
+- Prefer targeted `@import` over importing the entire Tailwind base when only utilities are needed.
 
-### Transition Patterns
+### Constraints
 
-| Pattern | Classes |
-|---------|---------|
-| All properties | `transition-all duration-200` |
-| Specific | `transition-colors duration-150` |
-| With easing | `ease-out` or `ease-in-out` |
-| Hover effect | `hover:scale-105 transition-transform` |
+- Avoid dumping arbitrary values into every class list.
+- Avoid mixing old config habits into a CSS-first setup without reason.
+- Avoid repeating long class strings when a component or token should exist.
+- Avoid styling choices that fight the design system instead of clarifying it.
+- Avoid dynamic class name construction that breaks purge scanning.
+- Avoid overriding Tailwind with inline styles or `!important` instead of fixing token conflicts.
+- Avoid using `@apply` with responsive or state variants — compose those in the template.
 
----
+## Output Format
 
-## 10. Component Extraction
+Provide implementation guidance, code examples, and configuration as appropriate to the task.
 
-### When to Extract
+## References
 
-| Signal | Action |
-|--------|--------|
-| Same class combo 3+ times | Extract component |
-| Complex state variants | Extract component |
-| Design system element | Extract + document |
+Load on demand. Do not preload all reference files.
 
-### Extraction Methods
+| File                                            | Load when                                                                                                                 |
+| ----------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------- |
+| `references/token-and-composition-checklist.md` | You need deeper Tailwind guidance for v4 token setup, utility composition, container queries, and class extraction rules. |
+| `references/dark-mode-and-theming-guide.md`     | The task involves dark mode setup, multi-theme systems, color-scheme toggling, or OKLCH token architecture.               |
+| `references/performance-and-purge-checklist.md` | The task involves production build optimization, bundle size reduction, or monorepo content configuration.                |
 
-| Method | Use When |
-|--------|----------|
-| **React/Vue component** | Dynamic, JS needed |
-| **@apply in CSS** | Static, no JS needed |
-| **Design tokens** | Reusable values |
+## Scripts
 
----
+No helper scripts are required for this skill right now. Keep execution in `SKILL.md` and `references/` unless repeated automation becomes necessary.
 
-## 11. Anti-Patterns
-
-| Don't | Do |
-|-------|-----|
-| Arbitrary values everywhere | Use design system scale |
-| `!important` | Fix specificity properly |
-| Inline `style=` | Use utilities |
-| Duplicate long class lists | Extract component |
-| Mix v3 config with v4 | Migrate fully to CSS-first |
-| Use `@apply` heavily | Prefer components |
-
----
-
-## 12. Performance Principles
-
-| Principle | Implementation |
-|-----------|----------------|
-| **Purge unused** | Automatic in v4 |
-| **Avoid dynamism** | No template string classes |
-| **Use Oxide** | Default in v4, 10x faster |
-| **Cache builds** | CI/CD caching |
-
----
+## Examples
 
-> **Remember:** Tailwind v4 is CSS-first. Embrace CSS variables, container queries, and native features. The config file is now optional.
+- "Help me with tailwind patterns best practices in this project"
+- "Review my tailwind patterns implementation for issues"
 ````