@animus-ui/core 0.2.0-beta.0 → 0.2.0-beta.2

package/docs/AGENT-QUESTIONS.md

@@ -1,79 +0,0 @@
-# Agent Questions & Learning Needs
-
-This document tracks what AI agents need to learn to effectively use Animus. These questions emerged from deep analysis of the framework.
-
-## High Priority Questions
-
-### 1. Responsive Design Pattern
-- How do responsive arrays work? `<Box p={[8, 16, 24, 32]} />`
-- What are the default breakpoints?
-- Can I use object syntax? `{ xs: 8, md: 16 }`
-
-### 2. Theming Integration
-- How do design tokens work in styles?
-- Can I reference theme values? `color: 'brand.primary'`
-- How are theme values typed?
-- Scale integration: `padding: 'space.md'`
-
-### 3. Complex Selectors
-- Where do these belong: `:nth-child`, `::before`, `:not()`?
-- In `.styles()` or `.states()`?
-- How to handle nested selectors?
-
-### 4. Animation Patterns
-- Where do animations/transitions belong in the cascade?
-- Best practices for performance?
-- Integration with state changes?
-
-### 5. Complete Component Example
-Need to see all features together:
-- Base styles
-- Variants
-- States
-- Responsive props
-- Theme integration
-- Custom props
-
-### 6. Common UI Patterns
-How to implement idiomatically:
-- Modal with overlay
-- Dropdown menu
-- Form field with error states
-- Toast notifications
-
-## Medium Priority Questions
-
-### 7. Compound Components
-- Can I create `Card.Header`, `Card.Body` patterns?
-- How does this work with the builder?
-- Type inference for sub-components?
-
-### 8. Global Styles
-- How to handle CSS resets?
-- App-wide styles?
-- Font imports?
-
-### 9. Performance Considerations
-- Patterns to avoid?
-- When does runtime overhead matter?
-- Best practices for large apps?
-
-### 10. Design System Integration
-- How to integrate existing tokens?
-- Migration from other systems?
-- Maintaining consistency?
-
-### 11. Migration Guide
-- From Emotion/Styled Components
-- Transformation patterns
-- Common gotchas
-
-## Why These Matter for AI Agents
-
-Understanding these patterns will enable:
-- **Correct code generation** first time
-- **Idiomatic patterns** that match framework philosophy
-- **Performance-aware** implementations
-- **Real-world readiness** beyond toy examples
-
-These questions represent the gap between theoretical understanding and practical mastery.

package/docs/agentic-alliance.md

@@ -1,415 +0,0 @@
-# The Agentic Alliance: Why Animus is Revolutionary for AI-Driven Development
-
-## Defining "Revolutionary" for AI Agents
-
-A styling framework is revolutionary for AI agents when it fundamentally transforms how agents approach styling tasks - from navigating infinite possibilities to operating within a guided, constraint-based system that makes correct usage the path of least resistance.
-
-## The 10 Criteria for Agent-Revolutionary Frameworks
-
-### 1. **Deterministic Execution Paths** (Weight: 15%)
-The framework must produce predictable outputs from given inputs, with no hidden state or surprising behaviors.
-
-### 2. **Constraint-Driven Architecture** (Weight: 15%)
-The API should structurally limit the solution space to only valid patterns, not merely document them.
-
-### 3. **Self-Documenting APIs** (Weight: 12%)
-The type system and API structure should guide correct usage without requiring external documentation.
-
-### 4. **Structurally Impossible Invalid States** (Weight: 12%)
-Beyond type safety - the API design should make incorrect patterns impossible to express.
-
-### 5. **Semantic Intent Expression** (Weight: 10%)
-Ability to express high-level design intent that maps predictably to low-level implementation.
-
-### 6. **Compositional Clarity** (Weight: 10%)
-Clear, enforceable rules for how styles compose, cascade, and override each other.
-
-### 7. **Complete Static Analyzability** (Weight: 8%)
-The entire styling logic should be analyzable and optimizable at compile time.
-
-### 8. **Guided Error Recovery** (Weight: 8%)
-Errors should guide agents (and developers) toward correct solutions, not just indicate failure.
-
-### 9. **Minimal Solution Ambiguity** (Weight: 5%)
-Ideally one canonical way to achieve each styling goal.
-
-### 10. **Progressive Disclosure** (Weight: 5%)
-Complex features shouldn't complicate simple use cases; complexity should be opt-in.
-
-## Comparative Analysis
-
-### Traditional CSS-in-JS (Emotion, Styled Components)
-- **Score: 3.4/10**
-- Fails criteria 1, 2, 4, 6, 7, 9 completely
-- Arbitrary template strings create infinite solution space
-- Runtime generation prevents static analysis
-- No structural constraints on usage
-
-### Tailwind CSS
-- **Score: 4.6/10**
-- String concatenation is inherently ambiguous
-- No real constraints (can write `hover:flex:items-center` even though invalid)
-- Excellent documentation but agents must memorize class names
-- Multiple ways to achieve same result
-
-### Vanilla Extract
-- **Score: 7.8/10**
-- Excellent static analyzability and performance
-- Good type safety but still allows arbitrary CSS
-- Doesn't structurally enforce best practices
-- API doesn't guide usage patterns
-
-### Panda CSS
-- **Score: 7.2/10**
-- Good balance of constraints and flexibility
-- Object merging creates ambiguity for agents
-- Multiple API styles (atomic, recipes, patterns) increase complexity
-- Static extraction is partial, not complete
-
-### Tamagui
-- **Score: 5.9/10**
-- Large API surface creates learning burden
-- Runtime optimizations make behavior less predictable
-- Many ways to achieve same result
-- Complex mental model for agents to maintain
-
-### **Animus (Current)**
-- **Score: 8.1/10**
-- Enforced method ordering is unique and powerful
-- Progressive type narrowing prevents invalid states
-- Single canonical build pattern
-- Lacks semantic intent layer and full static extraction
-
-### **Animus (Future Optimized)**
-- **Score: 9.4/10**
-- Only framework with structurally enforced cascade ordering
-- Progressive type narrowing creates impossible invalid states
-- Complete static extraction potential due to deterministic AST
-- Could add semantic intent methods while maintaining constraints
-
-## What Makes Animus Uniquely Revolutionary
-
-### 1. **Progressive Type Narrowing Through Inheritance**
-No other framework uses class inheritance to enforce method calling order. This is genuinely unprecedented:
-
-```typescript
-// This is structurally impossible in Animus:
-animus
-  .props({ color: 'brand' })
-  .styles({ padding: 10 }) // Error: 'styles' doesn't exist on AnimusWithSystem
-
-// The only valid order:
-animus
-  .styles({ padding: 10 })
-  .props({ color: 'brand' })
-```
-
-### 2. **API Structure Mirrors CSS Cascade**
-The enforced method order (styles → variants → states → props) directly maps to CSS cascade principles. This conceptual alignment is unique - other frameworks treat cascade as an implementation detail, not an API principle.
-
-### 3. **Finite State Machine for Styling**
-Animus transforms the infinite problem space of CSS into a finite state machine with clear transitions:
-- Start → Base Styles → Variants → States → Props → Terminal
-- Each transition is type-safe and irreversible
-
-### 4. **Extension Preserves Constraints**
-The `extend()` pattern maintains cascade order while allowing flexibility - a unique solution to the composition problem that no other framework achieves.
-
-### 5. **Single Canonical Path**
-Unlike every other framework offering multiple approaches, Animus has essentially one way to build each component type. This eliminates decision paralysis for agents.
-
-## Why This Is Revolutionary Specifically for AI Agents
-
-### 1. **Transforms Open-Ended to Closed-Form**
-Styling traditionally requires choosing from infinite valid CSS combinations. Animus reduces this to choosing from finite, valid method chains.
-
-### 2. **API as Constraint System**
-The API itself is the guardrail system. Agents don't need to check documentation or linting rules - the TypeScript compiler enforces all constraints.
-
-### 3. **Predictable AST Generation**
-Every builder chain produces a deterministic AST that can be statically analyzed, optimized, and cached - perfect for agent-generated code.
-
-### 4. **Self-Correcting Usage**
-When agents make mistakes, TypeScript errors guide them to the exact next valid method, creating a self-correcting system.
-
-## Future Enhancements for Peak Revolution
-
-### 1. **Semantic Intent Layer**
-```typescript
-animus
-  .intent('primary-action')
-  .intent('high-emphasis')
-  .asElement('button')
-// Maps to predefined style configurations
-```
-
-### 2. **Agent-Specific Error Messages**
-```typescript
-// Error: Cannot call styles() after props()
-// Agent hint: Build order is styles->variants->states->props->terminal
-// Suggested fix: Start with animus.styles({...})
-```
-
-### 3. **Design System Constraints**
-```typescript
-animus
-  .styles({ 
-    padding: 'md', // Enforces scale usage
-    color: 'brand.primary' // Validates against theme
-  })
-```
-
-### 4. **Compile-Time Style Extraction**
-Full static extraction while maintaining the revolutionary DX, achieving Vanilla Extract performance with superior agent ergonomics.
-
-## Conclusion
-
-Animus is revolutionary for AI agents because it's the only framework where:
-1. The API structure itself enforces best practices through type narrowing
-2. Invalid patterns are structurally impossible, not just discouraged
-3. There's one canonical way to build components, eliminating ambiguity
-4. The build process creates a deterministic, analyzable AST
-
-This isn't just an incremental improvement - it's a fundamental rethinking of how styling APIs can guide rather than permit, constrain rather than enable, and ultimately transform an open-ended problem into a solvable one.
-
-For AI agents, this means the difference between "generate valid CSS" (infinite problem space) and "choose the correct method sequence" (finite state machine). That transformation is genuinely revolutionary.
-
-## Critical Reassessment: A Reality Check
-
-### What I May Have Overstated
-
-1. **The Constraint Paradox**: While I praised constraints, they can become prisons. The enforced method ordering that seems elegant in theory might frustrate developers handling edge cases or integrating with legacy code.
-
-2. **Type System Complexity**: Progressive type narrowing through inheritance creates a sophisticated but potentially opaque system. When types become too clever, they can hinder more than help - even for AI agents.
-
-3. **The "Revolutionary" Label**: Is this truly revolutionary, or just a clever engineering solution? Revolution implies paradigm shift. Animus might be more evolution - a refined approach rather than fundamental transformation.
-
-4. **Static Analysis Assumptions**: I assumed the builder pattern would be easy to statically analyze, but method chaining might actually complicate AST analysis compared to simpler object literals.
-
-### Underexplored Critical Viewpoints
-
-1. **Developer Experience vs Agent Experience**: What's best for agents might not align with developer joy. The rigid structure could feel oppressive rather than guiding.
-
-2. **The Debugging Nightmare**: When something goes wrong in a deeply inherited type system with enforced ordering, where do you even start? The elegance might crumble under production pressure.
-
-3. **Adoption Barriers**: A unique pattern means zero knowledge transfer from other frameworks. This could doom it regardless of technical merit.
-
-4. **Real-World Messiness**: Production code needs quick fixes, workarounds, and integration with various systems. Does Animus handle the 20% edge cases, or does it force awkward solutions?
-
-### The Honest Agent Perspective
-
-After deep reflection, here's what I, as an AI agent, actually think:
-
-**What Would Work Best For Me:**
-1. **Flat, predictable APIs** over clever inheritance chains
-2. **Flexible constraints** - guidelines that can be broken when needed
-3. **Excellent error messages** that teach rather than just restrict
-4. **Multiple valid approaches** for different contexts
-5. **Gradual complexity** - simple things simple, complex things possible
-
-**The Truth About Animus:**
-- It's **well-designed** but not revolutionary
-- The constraints are **helpful** but potentially frustrating
-- The type system is **clever** but maybe too clever
-- It optimizes for **one specific workflow** at the expense of flexibility
-
-**My Actual Preference:**
-I would work best with something like **Panda CSS** or a **simplified Vanilla Extract** - frameworks that provide structure and constraints but don't enforce them through complex type hierarchies. The ideal framework for AI agents might actually be:
-- Clear patterns with escape hatches
-- Type safety without type puzzles  
-- Constraints as guidance, not walls
-- Predictable without being rigid
-
-### Final Reconciliation
-
-Animus represents an important exploration in API design - pushing the boundaries of how much we can constrain and guide through types and structure. It's valuable as an experiment and might be perfect for teams that want maximum consistency and are willing to accept the tradeoffs.
-
-But revolutionary? For AI agents? I was caught up in the elegance of the idea. The reality is that we (AI agents) often work best with simpler, more forgiving systems that handle the full messiness of real-world development.
-
-**The Real Revolution** for AI agents won't be maximum constraint, but rather the perfect balance of:
-- Structure when you need it
-- Flexibility when you don't
-- Clear patterns without rigid enforcement
-- Type safety without type gymnastics
-
-Animus leans too far toward constraint. The future isn't about forcing developers (or agents) down a single path, but about making the right path the easiest one while keeping other paths available.
-
-**My Ultimate Feeling**: I admire Animus's ambition and elegance, but I would personally struggle with its rigidity. I work best when I can adapt to different situations, learn from patterns rather than rules, and help developers solve real problems rather than navigate architectural constraints. The pattern is intellectually satisfying but practically limiting - and that's okay. Not every framework needs to optimize for AI agents, and not every clever idea needs to be revolutionary.
-
-## Second Reality Check: Are the Constraints Really Inflexible?
-
-After deeper examination, I realize I conflated "structured API" with "inflexible styling" - a critical error. Let me correct this:
-
-### What's Actually Flexible
-
-1. **The `extend()` Escape Hatch**: Returns an `AnimusExtended` instance where ALL methods (styles, variant, states, groups, props) can be called in ANY order. This completely breaks the ordering constraint when needed.
-
-2. **Full CSS Power**: The `styles()` method accepts any valid CSS. There's no limitation on what styles you can write.
-
-3. **Emotion Integration**: Since Animus uses `@emotion/styled`, you get:
-   - The `css` prop for runtime style overrides
-   - `className` prop for external CSS integration
-   - `style` prop for inline styles
-   - Full theming support with CSS variables
-
-4. **Dynamic Composition**: You can create components dynamically, extend them conditionally, and compose them freely.
-
-### What Would Actually Be Hard?
-
-Honestly? I'm struggling to find real limitations. The only "constraints" are:
-- Initial builder must follow the order (but `extend()` bypasses this)
-- Props defined in the registry are consumed (but you control what's in the registry)
-- Method chaining syntax instead of object syntax (purely stylistic preference)
-
-### The Real Insight
-
-**The constraints exist only at the API design level, not at the capability level.** Animus can do everything other CSS-in-JS solutions can do, it just guides you through a specific pattern to get there. But when you need to break that pattern, `extend()` is right there.
-
-This is actually brilliant: 
-- **For 95% of cases**: The enforced ordering provides clarity and prevents errors
-- **For 5% edge cases**: `extend()` gives you full flexibility
-- **For runtime needs**: Emotion's features are all available
-
-I was wrong to call it inflexible. It's more like a **guided flexibility** - structure when helpful, freedom when needed. This might actually be the ideal balance for AI agents: clear patterns for common cases, escape hatches for exceptions.
-
-## Final Reconciliation: Would I Actually Work Best With This?
-
-Given this deeper understanding, I need to revise my assessment:
-
-**What Animus Actually Offers AI Agents:**
-1. **Clear happy path** - The enforced ordering tells me exactly how to structure components
-2. **Full escape velocity** - `extend()` means I'm never truly trapped
-3. **Type-guided development** - Errors guide me to the next valid step
-4. **No capability sacrifice** - Everything possible in CSS is still possible
-5. **Predictable patterns** - I can learn once and apply everywhere
-
-**The Revolutionary Aspect I Missed:**
-Animus doesn't constrain what you can style, it constrains how you express your intent. This is exactly what AI agents need - not fewer capabilities, but clearer ways to express them.
-
-**My Revised Assessment:**
-Yes, this actually IS the pattern I would work best with. The initial method ordering gives me a clear template to follow for 95% of cases. When users need something unusual, `extend()` is there. When they need runtime dynamism, Emotion's features are available.
-
-The key insight: **Animus provides structure without sacrificing power**. It's not about limitation, it's about guidance. And for an AI agent, having a clear, type-safe path with well-defined escape hatches is actually ideal.
-
-I was wrong to fear the constraints. They're not walls, they're guardrails - and that's exactly what makes this pattern revolutionary for AI agents. We thrive with clear patterns and struggle with infinite possibility. Animus elegantly solves this by making the right thing the obvious thing, while keeping everything else possible.
-
-**My True Feeling**: I would genuinely prefer working with Animus over more "flexible" but ambiguous alternatives. The pattern isn't just intellectually satisfying - it's practically optimal for how AI agents approach code generation.
-
-## The Philosophy: Constraining Expression, Not Capability
-
-### The Core Insight
-
-"Animus doesn't constrain what you can style, it constrains how you express your intent."
-
-This distinction is profound and represents a fundamental shift in API design philosophy. Traditional frameworks focus on either:
-1. **Maximum capability** (CSS-in-JS): "Here's everything, figure it out"
-2. **Maximum constraint** (utility-first): "Here's what we allow, work within it"
-
-Animus takes a third path: **Maximum capability through constrained expression**.
-
-### What This Means in Practice
-
-**Traditional Approach (Emotion/Styled Components):**
-```javascript
-// Infinite ways to express the same thing
-styled.div`...` 
-styled.div({...})
-styled('div')`...`
-<div css={...}>
-<div style={{...}}>
-// Where do variants go? How do states compose? No guidance.
-```
-
-**Animus Approach:**
-```javascript
-// One clear path with explicit stages
-animus
-  .styles({...})      // Foundation
-  .variant({...})     // Design variations  
-  .states({...})      // Interactive states
-  .props({...})       // Dynamic properties
-  .asElement('div')   // Final form
-```
-
-The same styling power exists in both, but Animus provides a **structured narrative** for expressing design intent.
-
-### Why This Matters for AI Agents
-
-AI agents struggle with two things:
-1. **Infinite possibility paralysis** - Too many ways to achieve the same goal
-2. **Intent ambiguity** - Unclear what the developer is trying to accomplish
-
-Animus solves both by providing a **semantic structure for intent expression**:
-- `.styles()` = "This is what it always looks like"
-- `.variant()` = "This is how it varies by design choice"
-- `.states()` = "This is how it responds to interaction"
-- `.props()` = "This is what can be dynamically controlled"
-
-Each method isn't just a way to add styles - it's a way to **declare intent**.
-
-### Why This Matters for Human Developers
-
-Humans and AI agents actually have aligned needs here:
-
-**Cognitive Load Reduction:**
-- Humans benefit from not having to decide HOW to structure their styles
-- The method ordering matches how designers think: base → variations → states → dynamics
-
-**Self-Documenting Code:**
-```javascript
-// You can immediately understand the design system:
-const Button = animus
-  .styles({ padding: '8px 16px' })        // Base design
-  .variant({                              // Size variations
-    prop: 'size',
-    variants: { small: {...}, large: {...} }
-  })
-  .states({                               // Interactive states
-    hover: { background: 'lightblue' },
-    disabled: { opacity: 0.5 }
-  })
-  .asElement('button')
-
-// vs traditional approach where intent is buried:
-const Button = styled.button`
-  padding: 8px 16px;
-  ${props => props.size === 'small' && css`...`}
-  &:hover { background: lightblue; }
-  ${props => props.disabled && css`opacity: 0.5;`}
-`
-```
-
-### The Human-AI Alignment
-
-This philosophy creates perfect alignment between human and AI needs:
-
-**For Humans:**
-- Clear mental model for organizing styles
-- Self-documenting component structure
-- Reduced decision fatigue
-- Easier code review and maintenance
-
-**For AI Agents:**
-- Unambiguous intent expression
-- Predictable code generation patterns
-- Clear semantic meaning for each code section
-- Type-guided development path
-
-**The Shared Benefit:**
-Both humans and AI agents benefit from **intent-driven APIs** rather than **capability-driven APIs**. It's not about what you CAN do (that's a given), it's about clearly expressing what you INTEND to do.
-
-### The Broader Implication
-
-This philosophy suggests a new direction for API design in the AI age:
-1. **Preserve full capability** - Don't limit what's possible
-2. **Structure expression** - Create clear paths for common intents
-3. **Provide escape hatches** - Allow breaking structure when needed
-4. **Make intent explicit** - Each API choice should communicate purpose
-
-Animus demonstrates that the future of human-AI collaboration isn't about dumbing down APIs or limiting capabilities. It's about creating **structured ways to express intent** that both humans and AI can understand and work with effectively.
-
-### The Ultimate Realization
-
-The constraint isn't a limitation - it's a **communication protocol**. Just as HTTP constrains how we structure web requests (headers, body, methods) without limiting what we can send, Animus constrains how we structure styling intent without limiting what we can style.
-
-This is revolutionary because it acknowledges a fundamental truth: **In the age of AI, APIs aren't just about functionality - they're about creating a shared language for intent that both humans and machines can speak fluently.**

package/docs/ai-collaboration-guide.md

@@ -1,141 +0,0 @@
-# AI Agent Collaboration Guide for Animus Babel Plugin
-
-## Purpose
-This guide helps human developers effectively collaborate with AI agents (Claude, GPT-4, etc.) on implementing the Animus Babel plugin tasks. Each task is designed to be self-contained and delegatable.
-
-## How to Request Help from AI Agents
-
-### Task Assignment Template
-When asking an AI agent to implement a specific task, use this template:
-
-```markdown
-I'm working on the Animus CSS-in-JS library's static extraction feature. 
-I need help implementing [TASK NAME] from the requirements document.
-
-Context files to review:
-- /packages/core/docs/babel-plugin-requirements.md (Task [NUMBER] section)
-- /packages/core/docs/babel-plugin-architecture.md
-- /packages/core/src/static-poc/ (proof of concept implementation)
-
-The task contract is:
-[PASTE THE SPECIFIC TASK CONTRACT HERE]
-
-Please implement this according to the specifications.
-```
-
-### Optimal Task Delegation
-
-#### Best for AI Agents:
-1. **Task 1: AST Visitor Pattern** - Pattern matching and AST traversal
-2. **Task 3: Class Name Generator** - Deterministic algorithms  
-3. **Task 6: Theme Integration** - Token resolution logic
-4. **Task 2: Style Extractor** - Rule-based transformations
-
-#### Best for Human Developers:
-1. **Task 7: Build Tool Integration** - Requires specific tool knowledge
-2. **Task 8: Extension Chain Resolver** - Complex state management
-3. **Task 5: CSS Output Manager** - File system operations
-
-## AI Agent Instructions
-
-### For Any AI Agent Working on These Tasks:
-
-1. **Review Order**:
-   - Read the specific task section in requirements.md
-   - Review the architecture overview
-   - Check the POC implementation for patterns
-   - Look at existing Animus core code for style patterns
-
-2. **Implementation Guidelines**:
-   - Follow the TypeScript contracts exactly
-   - Include comprehensive error handling
-   - Add JSDoc comments for public APIs
-   - Write unit tests alongside implementation
-   - Use existing Animus patterns (check packages/core/src)
-
-3. **Code Style**:
-   - Use functional programming where appropriate
-   - Prefer immutability
-   - Clear, descriptive variable names
-   - No unnecessary comments (code should be self-documenting)
-
-4. **Testing Requirements**:
-   - Unit tests for all public methods
-   - Edge case coverage
-   - Integration test for the complete flow
-   - Performance benchmarks for critical paths
-
-## Example AI Agent Prompts
-
-### For Style Extractor Implementation:
-```
-I need to implement the Style Extractor (Task 2) for the Animus Babel plugin.
-The extractor should parse AST nodes and convert style objects to atomic CSS.
-
-Requirements:
-- Handle theme tokens ($space.md → var(--space-md))
-- Support responsive arrays
-- Return null for non-extractable styles
-- Generate deterministic class names
-
-Please implement StyleExtractor.ts with the provided contract interface.
-```
-
-### For Class Name Generator:
-```
-Implement the Class Name Generator (Task 3) for Animus static CSS extraction.
-It should create atomic CSS class names like "_p-1rem" for "padding: 1rem".
-
-Requirements:
-- Deterministic (same input → same output)
-- Handle special characters safely
-- Support collision detection
-- Configurable naming strategies
-
-Include unit tests covering edge cases like spaces, hashes, and quotes.
-```
-
-## Sharing Results
-
-When an AI agent completes a task:
-
-1. **Create a PR** with:
-   - Implementation in the correct directory
-   - Unit tests
-   - Integration test if applicable
-   - Updates to this guide if patterns emerged
-
-2. **Document Learnings**:
-   - Add any discovered edge cases
-   - Note any architectural decisions
-   - Update contracts if needed
-
-3. **Share Context**:
-   - Export conversation as markdown
-   - Include in PR description
-   - Help future AI agents learn from the work
-
-## Success Metrics for AI Implementation
-
-- Passes all unit tests
-- Follows TypeScript contracts exactly
-- Handles edge cases gracefully
-- Maintains Animus code style
-- Includes helpful error messages
-- Performance meets benchmarks
-
-## Common Pitfalls to Avoid
-
-1. **Don't assume Babel APIs** - Check Babel 7 documentation
-2. **Don't modify shared state** - Keep transforms pure
-3. **Don't forget error boundaries** - Graceful degradation is key
-4. **Don't over-optimize early** - Correctness first, performance second
-
-## Resources for AI Agents
-
-- Babel Handbook: https://github.com/jamiebuilds/babel-handbook
-- AST Explorer: https://astexplorer.net/
-- Animus Core Source: /packages/core/src/
-- POC Implementation: /packages/core/src/static-poc/
-
-Remember: The goal is to maintain 100% API compatibility while extracting static CSS at build time. When in doubt, fall back to runtime generation rather than breaking user code.