@cubis/foundry 0.3.71 → 0.3.73

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

@@ -1,269 +1,100 @@
 ---
 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"

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

@@ -2,23 +2,168 @@
 ---
 inclusion: manual
 name: testing-patterns
-description: "Compatibility alias skill. Deprecated: use test-master."
+description: Design test strategies with unit, integration, and e2e testing. Apply TDD, mocking, fixtures, coverage analysis, and test architecture best practices.
+license: Apache-2.0
 metadata:
-  deprecated: true
-  replaced_by: test-master
-  removal_target: v0.6.0
+  author: cubis-foundry
+  version: "3.0"
+compatibility: Claude Code, Codex, GitHub Copilot, Gemini CLI
 ---
 
 # Testing Patterns
 
-## Compatibility Alias
+## Purpose
 
-This skill is deprecated and kept for backward compatibility.
+Guide test strategy, structure, and implementation across all testing levels. Covers unit, integration, and e2e testing patterns, TDD methodology, mocking strategies, and test architecture.
 
-Use `test-master` as the canonical skill.
+## When to Use
 
-## Migration
+- Writing tests for new features or bug fixes
+- Designing a test strategy for a new project or module
+- Debugging flaky or slow tests
+- Reviewing test quality and coverage gaps
+- Setting up test infrastructure (runners, fixtures, mocks)
+- Deciding what level of testing is appropriate
 
-1. Replace direct references to `testing-patterns` with `test-master`.
-2. Apply the full workflow from `test-master` for new work.
+## Instructions
+
+### Step 1 — Choose the Right Test Level
+
+| Level       | Tests                        | Speed    | Confidence                   | When to Use                                        |
+| ----------- | ---------------------------- | -------- | ---------------------------- | -------------------------------------------------- |
+| Unit        | Individual functions/classes | ms       | Logic correctness            | Pure logic, calculations, transformers             |
+| Integration | Module boundaries            | 100ms–1s | Components work together     | API routes, database queries, service interactions |
+| E2E         | Full user flows              | 5–30s    | System works as user expects | Critical paths (signup, checkout, deploy)          |
+
+**Testing Trophy** (preferred distribution):
+
+- Many integration tests (highest ROI)
+- Some unit tests (fast logic verification)
+- Few e2e tests (critical paths only)
+- Static analysis as the foundation (TypeScript, linting)
+
+### Step 2 — Write Effective Tests
+
+**Structure every test as Arrange → Act → Assert**:
+
+```typescript
+test("calculates total with tax", () => {
+  // Arrange
+  const items = [{ price: 100 }, { price: 200 }];
+  const taxRate = 0.1;
+
+  // Act
+  const total = calculateTotal(items, taxRate);
+
+  // Assert
+  expect(total).toBe(330);
+});
+```
+
+**Naming**: Use natural language that describes the behavior:
+
+- DO: `"returns empty array when no items match filter"`
+- DON'T: `"test filter"` or `"test1"`
+
+**One assertion per behavior** (not per test):
+
+- One test can have multiple `expect()` calls if they verify the same behavior
+- Split separate behaviors into separate tests
+
+### Step 3 — Mock Strategically
+
+**Mock at boundaries, not everywhere**:
+
+- Mock: external APIs, databases, file system, time, randomness
+- Don't mock: your own code, simple utilities, data transformations
+
+**Mock patterns**:
+
+```typescript
+// Dependency injection (preferred)
+function createUserService(db: Database) {
+  return { getUser: (id) => db.query("SELECT...", [id]) };
+}
+
+// Module mocking (when DI not available)
+vi.mock("./database", () => ({
+  query: vi.fn().mockResolvedValue([{ id: 1, name: "Alice" }]),
+}));
+```
+
+**Avoid**:
+
+- Mocking implementation details (private methods, internal state)
+- Over-mocking (if you mock everything, you're testing nothing)
+- Snapshot tests for behavior (only for serialized output like HTML)
+
+### Step 4 — Handle Test Data
+
+**Factories over fixtures**:
+
+```typescript
+function createUser(overrides = {}) {
+  return {
+    id: crypto.randomUUID(),
+    name: "Test User",
+    email: "test@example.com",
+    role: "user",
+    ...overrides,
+  };
+}
+
+// Usage
+const admin = createUser({ role: "admin" });
+```
+
+**Test isolation**:
+
+- Each test creates its own data (no shared mutable state)
+- Clean up after integration tests (database, files)
+- Use transactions for database tests (rollback after each test)
+
+### Step 5 — Fix Common Test Problems
+
+**Flaky tests**:
+
+- Remove timing dependencies (`setTimeout`, `sleep`)
+- Use deterministic data (no `Math.random()` without seeding)
+- Await all async operations properly
+- Isolate external dependencies (mock network, use test databases)
+
+**Slow tests**:
+
+- Run in parallel when tests are isolated
+- Use in-memory databases for integration tests
+- Minimize e2e tests — push logic down to unit/integration
+- Profile and fix the slowest 10% first
+
+**Brittle tests**:
+
+- Test behavior, not implementation
+- Use accessible queries in UI tests (role, label — not CSS selectors)
+- Avoid testing framework internals
+
+## Output Format
+
+```
+## Test Strategy
+[approach and reasoning for test level choices]
+
+## Tests
+[test code organized by describe blocks]
+
+## Coverage Notes
+[what's tested, what's intentionally not tested, and why]
+```
+
+## Examples
+
+**User**: "Write tests for this user registration function"
+
+**Response approach**: Unit tests for validation logic (email format, password strength). Integration test for the full registration flow (validate → hash password → insert DB → send email). Mock the email service and database. Test edge cases (duplicate email, weak password, missing fields).
+
+**User**: "Our test suite takes 20 minutes, help us speed it up"
+
+**Response approach**: Profile the slowest tests. Look for unnecessary e2e tests that could be integration. Check for missing parallelization. Identify shared state causing serial execution. Suggest in-memory database for integration tests.
 ````