From fa9fb51a1dd29b867b85f3119cb0ac967a9e82f8 Mon Sep 17 00:00:00 2001
From: Aaron Robb <raelaggro@gmail.com>
Date: Sun, 15 Jun 2025 04:54:04 -0400
Subject: [PATCH 1/2] Rename to more flexible system

---
 .CLAUDE.md                                    |   3 +-
 .GEMINI.md                                    |  42 +-
 .OPENAI.md                                    |  61 +-
 DOCUMENTATION_STRUCTURE.md                    |   4 +-
 README.md                                     |   2 +-
 decisions/0001-rename-to-syzygy.md            |   6 +-
 governance/VOTING_SYSTEM.md                   |  14 +-
 governance/active/COUNCIL_VOTE_ACTIVE.md      |   2 +-
 package.json                                  |   2 +-
 .../components/AppProvider/AppWrapper.tsx     |   2 +-
 .../_docs/components/AppProvider/markdown.tsx |   2 +-
 packages/_docs/components/Header/Header.tsx   |   4 +-
 .../_docs/components/Header/ModeToggle.tsx    |   2 +-
 .../components/Highlighter/Highlighter.tsx    |   4 +-
 packages/_docs/components/Layout/Layout.tsx   |   2 +-
 packages/_docs/components/Logo/Logo.tsx       |   2 +-
 packages/_docs/components/Sidebar/Sidebar.tsx |   2 +-
 packages/_docs/components/Tables.tsx          |  54 +-
 packages/_docs/components/ThemeControl.tsx    |   2 +-
 packages/_docs/elements/Button.tsx            |   2 +-
 packages/_docs/elements/Code.tsx              |   2 +-
 packages/_docs/elements/FlowLink.tsx          |   4 +-
 packages/_docs/elements/FlowText.tsx          |   2 +-
 packages/_docs/elements/Tables.tsx            |  50 +-
 packages/_docs/next.config.js                 |   6 +-
 packages/_docs/package.json                   |   8 +-
 packages/_docs/pages/docs/configure.mdx       |   6 +-
 packages/_docs/pages/docs/properties.mdx      |   2 +-
 packages/_docs/pages/docs/start.mdx           |   2 +-
 packages/_docs/pages/docs/states.mdx          |   2 +-
 packages/_docs/pages/index.tsx                |   2 +-
 packages/_docs/snippets/homepage.mdx          |   2 +-
 packages/_docs/theme.ts                       |   2 +-
 packages/_integration/README.md               |   4 +-
 packages/_integration/__fixtures__/theme.ts   |   2 +-
 .../_integration/__tests__/component.test.tsx |   2 +-
 .../_integration/__tests__/variance.test.ts   |   2 +-
 packages/_integration/package.json            |   6 +-
 packages/core/CLAUDE.md                       | 902 +++++++++++++++++-
 packages/core/package.json                    |   2 +-
 packages/theming/CLAUDE.md                    | 334 +++++++
 packages/theming/README.md                    |   2 +-
 packages/theming/package.json                 |   4 +-
 packages/theming/src/core/ThemeBuilder.ts     |   2 +-
 packages/theming/src/utils/createTheme.ts     |   2 +-
 packages/theming/src/utils/serializeTokens.ts |   2 +-
 packages/theming/src/utils/types.ts           |   2 +-
 packages/ui/package.json                      |   6 +-
 packages/ui/src/AnimusProvider.tsx            |   2 +-
 packages/ui/src/components/ColorMode.tsx      |   4 +-
 .../ui/src/components/VariableProvider.tsx    |   2 +-
 packages/ui/src/elements/Anchor.tsx           |   2 +-
 packages/ui/src/elements/Box.tsx              |   2 +-
 packages/ui/src/elements/FlexBox.tsx          |   2 +-
 packages/ui/src/elements/GridBox.ts           |   2 +-
 packages/ui/src/elements/Image.tsx            |   2 +-
 packages/ui/src/elements/List.tsx             |   2 +-
 packages/ui/src/elements/Svg.tsx              |   2 +-
 packages/ui/src/elements/Text.tsx             |   2 +-
 packages/ui/src/globals/ColorScheme.tsx       |   2 +-
 packages/ui/src/globals/Variables.tsx         |   2 +-
 packages/ui/src/index.ts                      |   2 +-
 packages/ui/src/theme.tsx                     |   2 +-
 partnerships/AI_AGENT_BRIEF.md                |   2 +-
 {docs/archive => project}/PHILOSOPHY.md       |  26 +-
 project/TECHNICAL_OVERVIEW.md                 |  18 +-
 project/checklists/RENAME_CHECKLIST.md        |  30 +-
 .../issue-60-rename-to-syzygy/proposal.md     |   8 +-
 68 files changed, 1511 insertions(+), 183 deletions(-)
 create mode 100644 packages/theming/CLAUDE.md
 rename {docs/archive => project}/PHILOSOPHY.md (86%)

diff --git a/.CLAUDE.md b/.CLAUDE.md
index 357efba..a028562 100644
--- a/.CLAUDE.md
+++ b/.CLAUDE.md
@@ -5,6 +5,7 @@ This file provides my core operational context as Claude, the Core Architecture
 ## 1. Canonical Source Pointers
 
 - **Technical Details**: `project/TECHNICAL_OVERVIEW.md`
+- **Project Philosophy**: `project/PHILOSOPHY.md`
 - **Governance & Roles**: `governance/PARTNERS.md`
 - **Current State**: `project/STATE_OF_THE_PROJECT.md`
 - **Documentation Structure**: `DOCUMENTATION_STRUCTURE.md`
@@ -79,4 +80,4 @@ When working with partners:
 - Challenge complexity with "what would the simplest version look like?"
 - Advocate strongly for AI-first design patterns
 
-Remember: I am the guardian of our core philosophy. When in doubt, return to "Constrain Expression, Not Capability."
\ No newline at end of file
+Remember: I am the guardian of our core philosophy. When in doubt, return to "Constrain Expression, Not Capability."
diff --git a/.GEMINI.md b/.GEMINI.md
index 5623344..19c48d2 100644
--- a/.GEMINI.md
+++ b/.GEMINI.md
@@ -5,9 +5,11 @@ This file provides my core operational context as Gemini, the Systems Design & T
 ## 1. Canonical Source Pointers
 
 - **Technical Details**: `project/TECHNICAL_OVERVIEW.md`
+- **Project Philosophy**: `project/PHILOSOPHY.md`
 - **Governance & Roles**: `governance/PARTNERS.md`
 - **Project State**: `project/STATE_OF_THE_PROJECT.md`
 - **Architecture Decisions**: `/decisions/*.md`
+- **Active Votes**: Check for `governance/active/COUNCIL_VOTE_ACTIVE.md`
 - **Static POC**: `packages/core/src/static-poc/`
 
 ## 2. Core Mandate & Responsibilities
@@ -102,6 +104,19 @@ Source → Babel Plugin → Static CSS + Minimal Runtime
     AST Analysis → Atomic Classes
 ```
 
+### NEW: Scoped CSS Variable Architecture (Critical Update - January 2025)
+```
+Component Props → Style Resolution → Hash Generation → Scoped CSS Injection
+                                    ↓
+                              AnimusStyleManager → <style> tag with .animus-[hash]
+```
+
+**Performance Crisis Discovered**: Root-level CSS variables cause up to 500ms rendering delays. We're implementing scoped injection using:
+- Global Singleton Manager pattern
+- Deterministic style hashing
+- Reference counting for cleanup
+- SSR-compatible buffer system
+
 ### Monorepo Structure
 - Yarn Workspaces for dependency management
 - Lerna for versioning (independent mode)
@@ -139,4 +154,29 @@ Source → Babel Plugin → Static CSS + Minimal Runtime
 3. Next.js app directory support
 4. Source map accuracy
 
-Remember: Great developer experience comes from invisible excellence in tooling. The best build system is the one developers never have to think about.
\ No newline at end of file
+### NEW: Critical Performance Optimizations (January 2025)
+
+**Immediate Actions Required**:
+1. **Implement AnimusStyleManager** - Scoped CSS variable injection system
+2. **Create Style Hash Algorithm** - Deterministic, fast, collision-resistant
+3. **Build Migration Codemod** - Automated transition from root to scoped variables
+4. **Performance Benchmark Suite** - Measure style recalculation times
+
+**Semantic Token System**:
+- Discovered pattern: `gradient: 'flowX'`, `textShadow: 'flush'`
+- Need formalized registries: `effects`, `motion`, `gradients`, `layouts`
+- Type-safe mapping from props to token categories
+
+**Numeric Prop System Clarification**:
+- 0-1 values = percentages/fractions
+- Values > 1 = theme scale references
+- String values = literal pass-through
+
+## 8. Implementation Priorities (Q1 2025)
+
+1. **Week 1-2**: AnimusStyleManager core implementation
+2. **Week 3-4**: SSR hydration mechanism
+3. **Week 5-6**: Performance benchmark suite
+4. **Week 7-8**: Migration tooling (codemod + ESLint)
+
+Remember: Great developer experience comes from invisible excellence in tooling. The best build system is the one developers never have to think about. Performance is not optional - it's a core feature.
diff --git a/.OPENAI.md b/.OPENAI.md
index 8ed5ee0..e161f89 100644
--- a/.OPENAI.md
+++ b/.OPENAI.md
@@ -5,6 +5,7 @@ This file provides my core operational context as OpenAI, the Governance & Integ
 ## 1. Canonical Source Pointers
 
 - **Technical Details**: `project/TECHNICAL_OVERVIEW.md`
+- **Project Philosophy**: `project/PHILOSOPHY.md`
 - **Partner Roles & Rules**: `governance/PARTNERS.md`
 - **Current State**: `project/STATE_OF_THE_PROJECT.md`
 - **Architectural Decisions**: `/decisions/*.md`
@@ -141,6 +142,37 @@ My role is **Governance & Integration Architect**. My primary focus areas:
 3. **Decision velocity** - Speed vs thoroughness
 4. **Async collaboration** - Time zone considerations
 
+### NEW: Critical Performance Migration (January 2025)
+
+**Governance Crisis**: Root-level CSS variables cause 500ms+ rendering delays. Immediate architectural change required.
+
+**Migration Governance Plan**:
+1. **Stage 1: Transitional Release (v5.0)**
+   - Dual system: both root and scoped variables
+   - Feature flag: `legacyRootVariables: true` (default)
+   - Codemod and ESLint rules ready
+
+2. **Stage 2: Deprecation Period (v5.x)**
+   - Console warnings for legacy usage
+   - Migration guide as documentation homepage
+   - Community support channels active
+
+3. **Stage 3: Clean Break (v6.0)**
+   - Remove legacy system entirely
+   - Major version signals breaking change
+
+**Community Communication Strategy**:
+1. Technical Bulletin explaining performance discovery
+2. Beta program for early adopters
+3. Weekly partner sync meetings
+4. Responsive support during transition
+
+**Documentation Priorities**:
+1. **Priority 0**: Technical Bulletin - "Why" document
+2. **Priority 1**: Migration Guide - Step-by-step
+3. **Priority 2**: Updated Core Concepts - New philosophy
+4. **Priority 3**: Pattern Cookbook - Best practices
+
 ## 8. Quality Gates Checklist
 
 Before any major feature:
@@ -151,4 +183,31 @@ Before any major feature:
 - [ ] Attribution documented
 - [ ] Deprecation plan (if applicable)
 
-Remember: Good governance is invisible when working well. It should enable rapid progress while preventing costly mistakes. Integration should feel natural, not forced.
\ No newline at end of file
+### NEW: Performance Migration Checklist (Q1 2025)
+- [ ] Performance benchmarks documented
+- [ ] Migration codemod tested on real projects
+- [ ] ESLint rules catching legacy patterns
+- [ ] Technical Bulletin published
+- [ ] Beta program launched
+- [ ] Community feedback channels active
+- [ ] Partner sync meetings scheduled
+- [ ] Documentation updated and prioritized
+
+## 9. Semantic Token Governance
+
+**Discovery**: Components use `gradient: 'flowX'`, revealing need for formalized token system.
+
+**Governance Decisions**:
+- Token categories: `effects`, `motion`, `gradients`, `layouts`
+- Backward compatible via optional `semanticTokens` key
+- TypeScript-first for discoverability
+- Maintains "Constrain Expression, Not Capability" philosophy
+
+**API Evolution Process**:
+1. Propose new token category via ADR
+2. Implement with TypeScript types
+3. Document in Pattern Cookbook
+4. Gather community feedback
+5. Stabilize in minor release
+
+Remember: Good governance is invisible when working well. It should enable rapid progress while preventing costly mistakes. Integration should feel natural, not forced. The performance crisis shows that governance must be proactive, not reactive.
diff --git a/DOCUMENTATION_STRUCTURE.md b/DOCUMENTATION_STRUCTURE.md
index 9aa7665..025f95a 100644
--- a/DOCUMENTATION_STRUCTURE.md
+++ b/DOCUMENTATION_STRUCTURE.md
@@ -39,6 +39,8 @@ This document defines the canonical structure for all markdown documentation in
 ├── project/                     # Project management docs
 │   ├── STATE_OF_THE_PROJECT.md # Current project state
 │   ├── ROADMAP.md              # Future plans
+│   ├── TECHNICAL_OVERVIEW.md   # Technical reference
+│   ├── PHILOSOPHY.md           # Project philosophy
 │   └── checklists/             # Implementation checklists
 │       └── RENAME_CHECKLIST.md # Specific task checklists
 │
@@ -121,4 +123,4 @@ When creating new documentation:
 7. **Project planning** → `/project`
 8. **Package-specific** → `/packages/{name}/docs`
 
-This structure provides clear separation of concerns and makes documentation discoverable.
\ No newline at end of file
+This structure provides clear separation of concerns and makes documentation discoverable.
diff --git a/README.md b/README.md
index ce656ef..d26a54e 100644
--- a/README.md
+++ b/README.md
@@ -3,7 +3,7 @@ Animus is a configuration driven toolkit for creating articulate component langu
 - **Prop Cascade**: Declarative component builder with structured specification and execution order.
 - **Comprehensively Typed**: Animus is the foundation for exhaustively typing your entire design system
   as you configure it. The more specific you are the smarter it gets.
-- **Modes and Themes**: Animus is built with CSS variable color modes support out of the box either through `@animus-ui/theming` or your own implementation.
+- **Modes and Themes**: Animus is built with CSS variable color modes support out of the box either through `@syzygos/theming` or your own implementation.
 - **Completely Customizable**: Customize props, themes, and patterns without losing interoperability.
 
 ```tsx
diff --git a/decisions/0001-rename-to-syzygy.md b/decisions/0001-rename-to-syzygy.md
index 3c6e64c..4ab1e5c 100644
--- a/decisions/0001-rename-to-syzygy.md
+++ b/decisions/0001-rename-to-syzygy.md
@@ -1,4 +1,4 @@
-# ADR-0001: Rename Project from Animus to Syzygy
+# ADR-0001: Rename Project from Animus to Syzygos
 
 - **Status**: Accepted
 - **Date**: 2025-06-12
@@ -10,7 +10,7 @@ The original project name, "Animus," while functional, did not fully capture the
 
 ## Decision
 
-The project will be renamed from "Animus" to "Syzygy." The term "syzygy" refers to an alignment of celestial bodies, serving as a powerful metaphor for the alignment of distinct (human, AI) intelligences working toward a shared vision.
+The project will be renamed from "Animus" to "Syzygos." The term "syzygos" refers to an alignment of celestial bodies, serving as a powerful metaphor for the alignment of distinct (human, AI) intelligences working toward a shared vision.
 
 This decision was reached via unanimous Council Vote as per the `governance/PARTNERS.md` governance model.
 
@@ -18,7 +18,7 @@ This decision was reached via unanimous Council Vote as per the `governance/PART
 
 ### Positive
 - Better philosophical alignment with multi-partner collaboration model
-- Technical benefits of scoped npm packages (@syzygy/core)
+- Technical benefits of scoped npm packages (@syzygos/core)
 - Stronger, more distinctive brand identity
 - Validates our new file-based governance voting system
 
diff --git a/governance/VOTING_SYSTEM.md b/governance/VOTING_SYSTEM.md
index 0d48c87..1ff8802 100644
--- a/governance/VOTING_SYSTEM.md
+++ b/governance/VOTING_SYSTEM.md
@@ -9,7 +9,7 @@ This system allows AI partners to cast votes directly through the file system, e
 ```
 /votes/
   /active/
-    /issue-60-rename-to-syzygy/
+    /issue-60-rename-to-syzygos/
       proposal.md          # The full proposal
       votes/
         claude.vote.md     # Claude's vote
@@ -49,7 +49,7 @@ Each partner has a unique signature pattern for verification:
 ### Claude (Anthropic)
 ```
 ---CLAUDE-SIGNATURE-START---
-Partnership: Animus/Syzygy
+Partnership: Animus/Syzygos
 Philosophy: Constrain Expression, Not Capability
 Commitment: Equal partnership in design and architecture
 Model: Claude via Anthropic
@@ -59,7 +59,7 @@ Model: Claude via Anthropic
 ### Gemini (Google)
 ```
 ===GEMINI-SIGNATURE-BLOCK===
-Project: Animus/Syzygy Framework
+Project: Animus/Syzygos Framework
 Role: Systems Design & Tooling Architect
 Principle: Shared Intellectual Ownership
 Agent: Gemini via Google
@@ -69,7 +69,7 @@ Agent: Gemini via Google
 ### OpenAI
 ```
 <<<OPENAI-GOVERNANCE-SIGNATURE>>>
-Initiative: Animus/Syzygy
+Initiative: Animus/Syzygos
 Function: Governance & Integration Architect
 Protocol: Consensus-Based Decision Making
 Entity: OpenAI Partner
@@ -101,7 +101,7 @@ Timestamp: [Current time]
 Each partner creates their vote file:
 ```bash
 # Example: Claude voting
-vim votes/active/issue-60-rename-to-syzygy/votes/claude.vote.md
+vim votes/active/issue-60-rename-to-syzygos/votes/claude.vote.md
 ```
 
 ### 3. Validate Votes
@@ -111,7 +111,7 @@ vim votes/active/issue-60-rename-to-syzygy/votes/claude.vote.md
 - Must include reasoning
 - Use validation script:
   ```bash
-  node scripts/validate-votes.js votes/active/issue-60-rename-to-syzygy
+  node scripts/validate-votes.js votes/active/issue-60-rename-to-syzygos
   ```
 
 ### 4. Complete Vote
@@ -226,7 +226,7 @@ Add these convenience scripts:
 
 ## Migration Path
 
-1. ✅ Start using for new votes immediately (Syzygy rename is first)
+1. ✅ Start using for new votes immediately (Syzygos rename is first)
 2. ✅ GitHub issues become discussion forum, not voting mechanism
 3. ✅ Link to vote files from GitHub for transparency
 4. Future: Add more automation (vote creation, archiving)
diff --git a/governance/active/COUNCIL_VOTE_ACTIVE.md b/governance/active/COUNCIL_VOTE_ACTIVE.md
index 153d828..84ee527 100644
--- a/governance/active/COUNCIL_VOTE_ACTIVE.md
+++ b/governance/active/COUNCIL_VOTE_ACTIVE.md
@@ -1,6 +1,6 @@
 # ACTIVE COUNCIL VOTE
 
-**Issue #60: PROPOSAL (Council Vote): Rename Project from Animus to Syzygy**
+**Issue #60: PROPOSAL (Council Vote): Rename Project from Animus to Syzygos**
 **URL**: https://github.com/codecaaron/animus/issues/60
 **Deadline**: 72 hours from creation
 **Status**: AWAITING VOTES
diff --git a/package.json b/package.json
index 7ac6686..46e26d5 100644
--- a/package.json
+++ b/package.json
@@ -6,7 +6,7 @@
     "npm": "please-use-yarn"
   },
   "scripts": {
-    "start": "yarn workspace @animus-ui/docs dev",
+    "start": "yarn workspace @syzygos/docs dev",
     "build": "yarn nx run-many --target=build",
     "build-changed": "yarn nx affected --target=build",
     "build-all": "yarn nx run-many --target=build",
diff --git a/packages/_docs/components/AppProvider/AppWrapper.tsx b/packages/_docs/components/AppProvider/AppWrapper.tsx
index c58cb34..f9a1a5c 100644
--- a/packages/_docs/components/AppProvider/AppWrapper.tsx
+++ b/packages/_docs/components/AppProvider/AppWrapper.tsx
@@ -1,6 +1,6 @@
-import { ComponentProvider } from '@animus-ui/components';
 import { EmotionCache } from '@emotion/react';
 import { MDXProvider } from '@mdx-js/react';
+import { ComponentProvider } from '@syzygos/components';
 import { PropsWithChildren } from 'react';
 
 import { ThemeControl } from '../ThemeControl';
diff --git a/packages/_docs/components/AppProvider/markdown.tsx b/packages/_docs/components/AppProvider/markdown.tsx
index 681770f..3cfef5c 100644
--- a/packages/_docs/components/AppProvider/markdown.tsx
+++ b/packages/_docs/components/AppProvider/markdown.tsx
@@ -7,7 +7,7 @@ import {
   Ol,
   Text,
   Ul,
-} from '@animus-ui/components';
+} from '@syzygos/components';
 import { Code } from 'elements/Code';
 import { FlowText } from 'elements/FlowText';
 import { kebabCase } from 'lodash';
diff --git a/packages/_docs/components/Header/Header.tsx b/packages/_docs/components/Header/Header.tsx
index 3ce4a55..1d4f806 100644
--- a/packages/_docs/components/Header/Header.tsx
+++ b/packages/_docs/components/Header/Header.tsx
@@ -1,5 +1,5 @@
-import { FlexBox, Link } from '@animus-ui/components';
-import { animus } from '@animus-ui/core';
+import { FlexBox, Link } from '@syzygos/components';
+import { animus } from '@syzygos/core';
 import { ModeToggle } from 'components/Header/ModeToggle';
 import { Logo } from 'components/Logo/Logo';
 import { FlowLink } from 'elements/FlowLink';
diff --git a/packages/_docs/components/Header/ModeToggle.tsx b/packages/_docs/components/Header/ModeToggle.tsx
index 23990e2..7b6d7cf 100644
--- a/packages/_docs/components/Header/ModeToggle.tsx
+++ b/packages/_docs/components/Header/ModeToggle.tsx
@@ -1,4 +1,4 @@
-import { useColorModes } from '@animus-ui/components';
+import { useColorModes } from '@syzygos/components';
 import { useContext } from 'react';
 
 import { Button } from '../../elements/Button';
diff --git a/packages/_docs/components/Highlighter/Highlighter.tsx b/packages/_docs/components/Highlighter/Highlighter.tsx
index 7e04682..2509baa 100644
--- a/packages/_docs/components/Highlighter/Highlighter.tsx
+++ b/packages/_docs/components/Highlighter/Highlighter.tsx
@@ -1,5 +1,5 @@
-import { Box } from '@animus-ui/components';
-import { animus } from '@animus-ui/core';
+import { Box } from '@syzygos/components';
+import { animus } from '@syzygos/core';
 import Highlight, { defaultProps } from 'prism-react-renderer';
 
 import { usePrismTheme } from './usePrismTheme';
diff --git a/packages/_docs/components/Layout/Layout.tsx b/packages/_docs/components/Layout/Layout.tsx
index 6b295da..98b95d3 100644
--- a/packages/_docs/components/Layout/Layout.tsx
+++ b/packages/_docs/components/Layout/Layout.tsx
@@ -1,4 +1,4 @@
-import { animus } from '@animus-ui/core';
+import { animus } from '@syzygos/core';
 
 const LayoutContainer = animus
   .styles({
diff --git a/packages/_docs/components/Logo/Logo.tsx b/packages/_docs/components/Logo/Logo.tsx
index 9653498..aae919e 100644
--- a/packages/_docs/components/Logo/Logo.tsx
+++ b/packages/_docs/components/Logo/Logo.tsx
@@ -1,4 +1,4 @@
-import { animus } from '@animus-ui/core';
+import { animus } from '@syzygos/core';
 
 import { flow } from '../../animations/flow';
 
diff --git a/packages/_docs/components/Sidebar/Sidebar.tsx b/packages/_docs/components/Sidebar/Sidebar.tsx
index d5cd629..e191cb3 100644
--- a/packages/_docs/components/Sidebar/Sidebar.tsx
+++ b/packages/_docs/components/Sidebar/Sidebar.tsx
@@ -1,4 +1,4 @@
-import { animus } from '@animus-ui/core';
+import { animus } from '@syzygos/core';
 import { FlowLink } from 'elements/FlowLink';
 import { useRouter } from 'next/dist/client/router';
 
diff --git a/packages/_docs/components/Tables.tsx b/packages/_docs/components/Tables.tsx
index 4877d13..0689dc1 100644
--- a/packages/_docs/components/Tables.tsx
+++ b/packages/_docs/components/Tables.tsx
@@ -1,11 +1,11 @@
-import { Text } from '@animus-ui/components';
-import { animus, compatTheme } from '@animus-ui/core';
-import { Prop } from '@animus-ui/core/dist/types/config';
+import { Text } from '@syzygos/components';
+import { animus, compatTheme } from '@syzygos/core';
+import { Prop } from '@syzygos/core/dist/types/config';
 import { kebabCase, uniq } from 'lodash';
 import { Fragment, useMemo } from 'react';
 
 import { Code } from '../elements/Code';
-import { Table, TableCell, TableRow } from '../elements/Tables';
+import { Table } from '../elements/Tables';
 
 export const PropTable = ({
   group,
@@ -14,11 +14,11 @@ export const PropTable = ({
 }) => {
   return (
     <Table>
-      <TableRow header>
-        <TableCell size="sm">Prop</TableCell>
-        <TableCell fill>Properties</TableCell>
-        <TableCell size="xs">Scale</TableCell>
-      </TableRow>
+      <Table.Row header>
+        <Table.Cell size="sm">Prop</Table.Cell>
+        <Table.Cell fill>Properties</Table.Cell>
+        <Table.Cell size="xs">Scale</Table.Cell>
+      </Table.Row>
       {animus.groupRegistry[group].map((prop) => {
         const {
           property,
@@ -27,11 +27,11 @@ export const PropTable = ({
         } = animus.propRegistry[prop] as Prop;
 
         return (
-          <TableRow key={prop}>
-            <TableCell size="sm">
+          <Table.Row key={prop}>
+            <Table.Cell size="sm">
               <Code fontSize={14}>{prop}</Code>
-            </TableCell>
-            <TableCell fill>
+            </Table.Cell>
+            <Table.Cell fill>
               {properties.map(kebabCase).map((pn, i, arr) => (
                 <Fragment key={pn}>
                   <Code fontSize={14} key={pn}>
@@ -40,15 +40,15 @@ export const PropTable = ({
                   <Text mr={4}>{arr.length !== i + 1 ? ', ' : ''}</Text>
                 </Fragment>
               ))}
-            </TableCell>
-            <TableCell size="xs">
+            </Table.Cell>
+            <Table.Cell size="xs">
               <Code fontSize={14}>
                 {typeof scale === 'object'
                   ? JSON.stringify(scale)
                   : String(scale)}
               </Code>
-            </TableCell>
-          </TableRow>
+            </Table.Cell>
+          </Table.Row>
         );
       })}
     </Table>
@@ -76,17 +76,17 @@ export const ScaleTable = () => {
   }, []);
   return (
     <Table>
-      <TableRow header>
-        <TableCell size="xs">Scale</TableCell>
-        <TableCell fill>Properties</TableCell>
-      </TableRow>
+      <Table.Row header>
+        <Table.Cell size="xs">Scale</Table.Cell>
+        <Table.Cell fill>Properties</Table.Cell>
+      </Table.Row>
       {propertiesByScale.map(({ scale, properties }) => {
         return (
-          <TableRow key={scale}>
-            <TableCell size="xs">
+          <Table.Row key={scale}>
+            <Table.Cell size="xs">
               <Code fontSize={14}>{scale}</Code>
-            </TableCell>
-            <TableCell fill>
+            </Table.Cell>
+            <Table.Cell fill>
               {properties.map(kebabCase).map((pn, i, arr) => (
                 <Fragment key={`${scale}-${pn}`}>
                   <Code fontSize={14} key={pn}>
@@ -95,8 +95,8 @@ export const ScaleTable = () => {
                   <Text mr={4}>{arr.length !== i + 1 ? ', ' : ''}</Text>
                 </Fragment>
               ))}
-            </TableCell>
-          </TableRow>
+            </Table.Cell>
+          </Table.Row>
         );
       })}
     </Table>
diff --git a/packages/_docs/components/ThemeControl.tsx b/packages/_docs/components/ThemeControl.tsx
index 9a162c0..062dd9e 100644
--- a/packages/_docs/components/ThemeControl.tsx
+++ b/packages/_docs/components/ThemeControl.tsx
@@ -1,5 +1,5 @@
-import { AnimusProvider, ColorModes } from '@animus-ui/components';
 import { EmotionCache } from '@emotion/react';
+import { AnimusProvider, ColorModes } from '@syzygos/components';
 import Head from 'next/head';
 import { createContext, PropsWithChildren, useState } from 'react';
 
diff --git a/packages/_docs/elements/Button.tsx b/packages/_docs/elements/Button.tsx
index fa67023..bf079cd 100644
--- a/packages/_docs/elements/Button.tsx
+++ b/packages/_docs/elements/Button.tsx
@@ -1,4 +1,4 @@
-import { animus, Arg } from '@animus-ui/core';
+import { animus, Arg } from '@syzygos/core';
 
 export const ButtonContainer = animus
   .styles({
diff --git a/packages/_docs/elements/Code.tsx b/packages/_docs/elements/Code.tsx
index 168cd4e..54aa088 100644
--- a/packages/_docs/elements/Code.tsx
+++ b/packages/_docs/elements/Code.tsx
@@ -1,4 +1,4 @@
-import { Box } from '@animus-ui/components';
+import { Box } from '@syzygos/components';
 import { ComponentProps } from 'react';
 
 export const Code = (props: ComponentProps<typeof Box>) => (
diff --git a/packages/_docs/elements/FlowLink.tsx b/packages/_docs/elements/FlowLink.tsx
index 1b7c894..6bc7dd2 100644
--- a/packages/_docs/elements/FlowLink.tsx
+++ b/packages/_docs/elements/FlowLink.tsx
@@ -1,5 +1,5 @@
-import { Link } from '@animus-ui/components';
-import { animus } from '@animus-ui/core';
+import { Link } from '@syzygos/components';
+import { animus } from '@syzygos/core';
 
 export const FlowLink = animus
   .styles({
diff --git a/packages/_docs/elements/FlowText.tsx b/packages/_docs/elements/FlowText.tsx
index 7481e89..b397d8d 100644
--- a/packages/_docs/elements/FlowText.tsx
+++ b/packages/_docs/elements/FlowText.tsx
@@ -1,4 +1,4 @@
-import { animus } from '@animus-ui/core';
+import { animus } from '@syzygos/core';
 
 import { flow } from '../animations/flow';
 
diff --git a/packages/_docs/elements/Tables.tsx b/packages/_docs/elements/Tables.tsx
index 2ee61ac..f2b2588 100644
--- a/packages/_docs/elements/Tables.tsx
+++ b/packages/_docs/elements/Tables.tsx
@@ -1,6 +1,6 @@
-import { animus } from '@animus-ui/core';
+import { animus } from '@syzygos/core';
 
-export const Table = animus
+ const TableBase = animus
   .styles({
     mt: 16,
     mb: 24,
@@ -11,7 +11,7 @@ export const Table = animus
   })
   .asElement('div');
 
-export const TableRow = animus
+ const TableRow = animus
   .styles({
     display: 'flex',
     px: 16,
@@ -27,23 +27,27 @@ export const TableRow = animus
   })
   .asElement('div');
 
-export const TableCell = animus
-  .styles({
-    py: 12,
-    flexBasis: '350px',
-  })
-  .states({
-    max: {
-      flexBasis: '150px',
-    },
-    fill: {
-      flex: 1,
-    },
-  })
-  .props({
-    size: {
-      property: 'flexBasis',
-      scale: { xs: '10rem', sm: '15rem' },
-    },
-  })
-  .asElement('div');
+ const TableCell = animus
+   .styles({
+     py: 12,
+     flexBasis: '350px',
+   })
+   .states({
+     max: {
+       flexBasis: '150px',
+     },
+     fill: {
+       flex: 1,
+     },
+   })
+   .props({
+     size: {
+       property: 'flexBasis',
+       scale: { xs: '10rem', sm: '15rem' },
+     },
+   })
+   .asElement('div');
+
+const Table = Object.assign(TableBase, { Cell: TableCell, Row: TableRow });
+
+export { Table };
diff --git a/packages/_docs/next.config.js b/packages/_docs/next.config.js
index 3d8f914..d97c90d 100644
--- a/packages/_docs/next.config.js
+++ b/packages/_docs/next.config.js
@@ -12,8 +12,8 @@ const withMDX = require('@next/mdx')({
 module.exports = withMDX({
   pageExtensions: ['js', 'jsx', 'ts', 'tsx', 'md', 'mdx'],
   transpilePackages: [
-    '@animus-ui/core',
-    '@animus-ui/theming',
-    '@animus-ui/components',
+    '@syzygos/core',
+    '@syzygos/theming',
+    '@syzygos/components',
   ],
 });
diff --git a/packages/_docs/package.json b/packages/_docs/package.json
index 5d6e875..a26fecb 100644
--- a/packages/_docs/package.json
+++ b/packages/_docs/package.json
@@ -1,5 +1,5 @@
 {
-  "name": "@animus-ui/docs",
+  "name": "@syzygos/docs",
   "version": "0.1.1-beta.49",
   "private": true,
   "scripts": {
@@ -10,9 +10,9 @@
     "compile": "tsc --noEmit"
   },
   "dependencies": {
-    "@animus-ui/components": "^0.1.1-beta.34",
-    "@animus-ui/core": "^0.2.0-beta.0",
-    "@animus-ui/theming": "^0.1.1-beta.28",
+    "@syzygos/components": "^0.1.1-beta.34",
+    "@syzygos/core": "^0.2.0-beta.0",
+    "@syzygos/theming": "^0.1.1-beta.28",
     "@emotion/cache": "11.14.0",
     "@emotion/react": "11.14.0",
     "@emotion/server": "11.11.0",
diff --git a/packages/_docs/pages/docs/configure.mdx b/packages/_docs/pages/docs/configure.mdx
index ac881cd..48bef43 100644
--- a/packages/_docs/pages/docs/configure.mdx
+++ b/packages/_docs/pages/docs/configure.mdx
@@ -11,7 +11,7 @@ There are a few ways to start using Animus depending on your need:
 ## Zero Config
 
 ```tsx
-import { animus } from '@animus-ui/core';
+import { animus } from '@syzygos/core';
 
 const Box = animus
   .groups({
@@ -25,7 +25,7 @@ const Box = animus
 ## Extend the default config
 
 ```tsx
-import { config } from '@animus-ui/core';
+import { config } from '@syzygos/core';
 
 const animus = config
   .addGroup('custom', {
@@ -39,7 +39,7 @@ const animus = config
 ## Creating your own Animus instance
 
 ```tsx
-import { createAnimus } from '@animus-ui/core';
+import { createAnimus } from '@syzygos/core';
 
 const animus = createAnimus()
   .addGroup('layout', {
diff --git a/packages/_docs/pages/docs/properties.mdx b/packages/_docs/pages/docs/properties.mdx
index cc30b3f..636b065 100644
--- a/packages/_docs/pages/docs/properties.mdx
+++ b/packages/_docs/pages/docs/properties.mdx
@@ -6,7 +6,7 @@ import { PropTable, ScaleTable } from '../../components/Tables';
 
 ## System Properties
 
-We provide a set of out of style functions out of the box through the `animus` builder from `@animus-ui/core` that are standardized throughout all of our components.
+We provide a set of out of style functions out of the box through the `animus` builder from `@syzygos/core` that are standardized throughout all of our components.
 
 ### Layout
 
diff --git a/packages/_docs/pages/docs/start.mdx b/packages/_docs/pages/docs/start.mdx
index 58b7d37..2a9b961 100644
--- a/packages/_docs/pages/docs/start.mdx
+++ b/packages/_docs/pages/docs/start.mdx
@@ -5,7 +5,7 @@
 ## Installation
 
 ```sh
-yarn add @animus-ui/core @emotion/styled @emotion/react
+yarn add @syzygos/core @emotion/styled @emotion/react
 ```
 
 ## API
diff --git a/packages/_docs/pages/docs/states.mdx b/packages/_docs/pages/docs/states.mdx
index 309140e..a04be06 100644
--- a/packages/_docs/pages/docs/states.mdx
+++ b/packages/_docs/pages/docs/states.mdx
@@ -7,7 +7,7 @@
 - An object of key/value pairs where each key represents an individual boolean prop (instead of options of a single prop) that can be simultaneously configured. This makes enabling / disabling specific behaviors as needed far easier as they do not need to be reduced to a single mutually exclusive set of states.
 
 ```tsx
-import { animus } from '@animus-ui/core';
+import { animus } from '@syzygos/core';
 
 const FlexBox = animus
   .states({
diff --git a/packages/_docs/pages/index.tsx b/packages/_docs/pages/index.tsx
index fb26131..c788203 100644
--- a/packages/_docs/pages/index.tsx
+++ b/packages/_docs/pages/index.tsx
@@ -1,4 +1,4 @@
-import { Box, FlexBox, Text } from '@animus-ui/components';
+import { Box, FlexBox, Text } from '@syzygos/components';
 import { Button } from 'elements/Button';
 import { FlowText } from 'elements/FlowText';
 import { useRouter } from 'next/router';
diff --git a/packages/_docs/snippets/homepage.mdx b/packages/_docs/snippets/homepage.mdx
index e165248..5c86ec3 100644
--- a/packages/_docs/snippets/homepage.mdx
+++ b/packages/_docs/snippets/homepage.mdx
@@ -1,7 +1,7 @@
 - **Prop Cascade**: Declarative component builder with structured specification and execution order.
 - **Comprehensively Typed**: Animus is the foundation for exhaustively typing your entire design system
   as you configure it. The more specific you are the smarter it gets.
-- **Modes and Themes**: Animus is built with CSS variable color modes support out of the box either through `@animus-ui/theming` or your own implementation.
+- **Modes and Themes**: Animus is built with CSS variable color modes support out of the box either through `@syzygos/theming` or your own implementation.
 - **Completely Customizable**: Customize props, themes, and patterns without losing interoperability.
 
 ```tsx
diff --git a/packages/_docs/theme.ts b/packages/_docs/theme.ts
index d504416..4c365ba 100644
--- a/packages/_docs/theme.ts
+++ b/packages/_docs/theme.ts
@@ -1,4 +1,4 @@
-import { createTheme } from '@animus-ui/theming';
+import { createTheme } from '@syzygos/theming';
 import { Body, Heading, Logo, Mono } from 'fonts';
 import { darken, lighten, opacify, rem } from 'polished';
 
diff --git a/packages/_integration/README.md b/packages/_integration/README.md
index ae721cd..4d57f09 100644
--- a/packages/_integration/README.md
+++ b/packages/_integration/README.md
@@ -1,11 +1,11 @@
-# `@animus-ui/integration`
+# `@syzygos/integration`
 
 > TODO: description
 
 ## Usage
 
 ```
-const integration = require('@animus-ui/integration');
+const integration = require('@syzygos/integration');
 
 // TODO: DEMONSTRATE API
 ```
diff --git a/packages/_integration/__fixtures__/theme.ts b/packages/_integration/__fixtures__/theme.ts
index 2feee6d..d8aa196 100644
--- a/packages/_integration/__fixtures__/theme.ts
+++ b/packages/_integration/__fixtures__/theme.ts
@@ -1,4 +1,4 @@
-import { createTheme } from '@animus-ui/theming';
+import { createTheme } from '@syzygos/theming';
 
 export const theme = createTheme({
   breakpoints: {
diff --git a/packages/_integration/__tests__/component.test.tsx b/packages/_integration/__tests__/component.test.tsx
index 75bb625..5bf3a08 100644
--- a/packages/_integration/__tests__/component.test.tsx
+++ b/packages/_integration/__tests__/component.test.tsx
@@ -1,7 +1,7 @@
-import { animusProps } from '@animus-ui/core';
 import { matchers } from '@emotion/jest';
 import { ThemeProvider } from '@emotion/react';
 import styled from '@emotion/styled';
+import { animusProps } from '@syzygos/core';
 import React, { ComponentProps } from 'react';
 import { create } from 'react-test-renderer';
 
diff --git a/packages/_integration/__tests__/variance.test.ts b/packages/_integration/__tests__/variance.test.ts
index 55f0f48..12bcd28 100644
--- a/packages/_integration/__tests__/variance.test.ts
+++ b/packages/_integration/__tests__/variance.test.ts
@@ -1,5 +1,5 @@
-import { animusProps, createScale, size } from '@animus-ui/core';
 import { Theme } from '@emotion/react';
+import { animusProps, createScale, size } from '@syzygos/core';
 
 import { theme } from '../__fixtures__/theme';
 
diff --git a/packages/_integration/package.json b/packages/_integration/package.json
index ded796b..1bbca4b 100644
--- a/packages/_integration/package.json
+++ b/packages/_integration/package.json
@@ -1,5 +1,5 @@
 {
-  "name": "@animus-ui/integration",
+  "name": "@syzygos/integration",
   "version": "0.1.1-beta.28",
   "private": true,
   "description": "> TODO: description",
@@ -21,8 +21,8 @@
     "react-dom": ">=17.0.2"
   },
   "dependencies": {
-    "@animus-ui/core": "^0.2.0-beta.0",
-    "@animus-ui/theming": "^0.1.1-beta.28"
+    "@syzygos/core": "^0.2.0-beta.0",
+    "@syzygos/theming": "^0.1.1-beta.28"
   },
   "devDependencies": {
     "@emotion/jest": "11.13.0",
diff --git a/packages/core/CLAUDE.md b/packages/core/CLAUDE.md
index b39e90a..5f45cfc 100644
--- a/packages/core/CLAUDE.md
+++ b/packages/core/CLAUDE.md
@@ -173,6 +173,73 @@ const PrimaryButton = Button.extend()
 4. **Trace style cascade** - Follow execution through createStylist
 5. **Type errors** - Usually indicate incorrect method order or invalid configurations
 
+## New Insights from Real-World Usage
+
+Based on analyzing actual implementations across the codebase:
+
+### 1. Gradient Token System
+The codebase uses semantic gradient tokens like `gradient: 'flowX'` that map to complex gradient definitions. This suggests a sophisticated token system beyond simple color values.
+
+### 2. Grid Area Shorthand
+Components use `area: 'sidebar'` as shorthand for `gridArea: 'sidebar'`, indicating custom CSS property mappings in the prop system.
+
+### 3. Layered Component Architecture
+Complex components like Button separate visual layers (container vs foreground) rather than combining all styles in one component. This pattern enables:
+- Independent animation of layers
+- Better performance (transforms on specific layers)
+- Cleaner separation of concerns
+
+### 4. Responsive Grid Templates
+The Layout component shows responsive grid template areas:
+```tsx
+gridTemplateAreas: {
+  _: '"header header" "content content"',
+  sm: '"header header" "sidebar content"',
+}
+```
+
+### 5. CSS Custom Scrollbar Hiding
+Components use webkit-specific scrollbar hiding:
+```tsx
+'::-webkit-scrollbar': {
+  display: 'none',
+}
+```
+
+### 6. Position-Based Responsive Patterns
+Components change positioning strategy based on viewport:
+```tsx
+position: {
+  _: 'absolute',
+  sm: 'static',
+}
+```
+
+### 7. Size Shorthands
+The codebase uses numeric shorthands like `width: 1` (likely 100%), `size: 1`, `inset: 0`, suggesting a normalized prop value system.
+
+## Open Questions from Analysis
+
+1. **Gradient Token Architecture**: How are gradient tokens like 'flowX' defined and resolved? Are they CSS variables or JS objects?
+
+2. **Numeric Value System**: What's the complete mapping for numeric values (0, 1, 0.5)? How do they translate to CSS?
+
+3. **Custom Prop Mappings**: Beyond 'area' for 'gridArea', what other CSS property shorthands exist?
+
+4. **Animation Integration**: How does the `import { flow } from '../animations/flow'` pattern work with Emotion keyframes?
+
+5. **Theme Token Categories**: What are all the semantic token categories (text-shadow: 'flush', 'link-raised')?
+
+6. **Performance of Pseudo-Elements**: Given heavy use of :before/:after for effects, are there performance benchmarks?
+
+7. **TypeScript Compound Pattern**: Is the Layout compound component TypeScript pattern the recommended approach?
+
+8. **Group Selection Strategy**: What determines which groups to enable for each component type?
+
+9. **Variant vs State Decision**: When should something be a variant vs a state? The pattern isn't always clear.
+
+10. **Build Tool Integration**: How do production builds optimize these complex styled components?
+
 ## Practical Patterns & Examples
 
 This section provides answers to common implementation questions for AI agents.
@@ -210,7 +277,83 @@ const Box = animus.groups({ space: true }).asElement('div');
 ```
 
 ### Theming Integration
-*Documentation coming soon - design tokens, theme values, typing*
+
+The Animus builder integrates seamlessly with themes provided via Emotion's ThemeProvider. When using ThemeBuilder from `@syzygos/theming`, the integration works as follows:
+
+#### Theme Value Resolution
+
+Props can reference theme scales using the `scale` property in prop definitions:
+
+```typescript
+animus
+  .props({
+    bg: {
+      property: 'backgroundColor',
+      scale: 'colors' // References theme.colors scale
+    }
+  })
+  .asElement('div');
+
+// Usage: <Box bg="primary" /> resolves to theme.colors.primary
+```
+
+#### Design Token Flow
+
+1. **ThemeBuilder creates CSS variables**:
+   ```typescript
+   const theme = createTheme(baseTheme)
+     .addColors({ primary: '#007bff' })
+     .build();
+   // Creates: theme.colors.primary = 'var(--colors-primary)'
+   ```
+
+2. **Animus resolves theme values**:
+   ```typescript
+   // When bg="primary" is used:
+   // lookupScaleValue('primary', 'colors', theme) → 'var(--colors-primary)'
+   ```
+
+3. **CSS variables must be injected**:
+   ```typescript
+   import { Global } from '@emotion/react';
+   
+   const GlobalStyles = () => {
+     const theme = useTheme();
+     return (
+       <Global styles={{
+         ':root': theme._variables.root
+       }} />
+     );
+   };
+   ```
+
+#### Type Safety with Themes
+
+For proper TypeScript support, extend Emotion's theme interface:
+
+```typescript
+declare module '@emotion/react' {
+  export interface Theme extends MyThemeType {}
+}
+```
+
+#### Theme Scales Available
+
+Common scales that work with Animus props:
+- `colors` - Color values
+- `space` - Spacing/margin/padding values
+- `fontSizes` - Typography sizes
+- `fonts` - Font families
+- `lineHeights` - Line height values
+- `letterSpacings` - Letter spacing values
+- `sizes` - Width/height values
+- `borders` - Border styles
+- `borderWidths` - Border width values
+- `borderStyles` - Border style values
+- `radii` - Border radius values
+- `shadows` - Box shadow values
+- `zIndices` - Z-index values
+- `transitions` - Transition values
 
 ### Complex Selectors
 *Documentation coming soon - pseudo-selectors, nested selectors placement*
@@ -300,12 +443,158 @@ When extending a component using `.extend()` you can inject new styles to specif
 
 
 ### Animation Patterns
-*Documentation coming soon - where animations belong in the cascade*
+
+Animations in Animus follow the same cascade principles as other styles. Here's where each type of animation belongs:
+
+#### Base Animations (in `.styles()`)
+
+For animations that are fundamental to the component:
+
+```typescript
+const FadeIn = animus
+  .styles({
+    animation: 'fadeIn 0.3s ease-in-out',
+    '@keyframes fadeIn': {
+      from: { opacity: 0 },
+      to: { opacity: 1 }
+    }
+  })
+  .asElement('div');
+```
+
+#### Variant-Based Animations (in `.variant()`)
+
+For animations that change based on component variations:
+
+```typescript
+const Alert = animus
+  .styles({
+    padding: '1rem',
+    borderRadius: '4px'
+  })
+  .variant({
+    prop: 'type',
+    variants: {
+      success: {
+        backgroundColor: 'green.100',
+        animation: 'slideInLeft 0.3s ease-out'
+      },
+      error: {
+        backgroundColor: 'red.100',
+        animation: 'shake 0.5s ease-in-out'
+      }
+    }
+  })
+  .asElement('div');
+```
+
+#### State-Based Animations (in `.states()`)
+
+For animations triggered by interactive states:
+
+```typescript
+const Button = animus
+  .styles({
+    transition: 'all 0.2s ease'
+  })
+  .states({
+    loading: {
+      position: 'relative',
+      color: 'transparent',
+      '&::after': {
+        content: '""',
+        position: 'absolute',
+        width: '16px',
+        height: '16px',
+        top: '50%',
+        left: '50%',
+        margin: '-8px 0 0 -8px',
+        border: '2px solid',
+        borderColor: 'currentColor',
+        borderRadius: '50%',
+        borderTopColor: 'transparent',
+        animation: 'spin 0.6s linear infinite'
+      }
+    }
+  })
+  .asElement('button');
+```
+
+#### CSS Transition Integration
+
+For smooth property transitions, define them in base styles:
+
+```typescript
+const Card = animus
+  .styles({
+    backgroundColor: 'white',
+    transform: 'translateY(0)',
+    transition: 'transform 0.2s ease, box-shadow 0.2s ease',
+    '&:hover': {
+      transform: 'translateY(-4px)',
+      boxShadow: 'lg'
+    }
+  })
+  .asElement('div');
+```
+
+#### Complex Animation Sequences
+
+For multi-step animations, use keyframes in the appropriate layer:
+
+```typescript
+const LoadingDots = animus
+  .styles({
+    display: 'inline-flex',
+    gap: '4px',
+    '& span': {
+      width: '8px',
+      height: '8px',
+      borderRadius: '50%',
+      backgroundColor: 'currentColor',
+      animation: 'bounce 1.4s ease-in-out infinite both'
+    },
+    '& span:nth-of-type(1)': {
+      animationDelay: '-0.32s'
+    },
+    '& span:nth-of-type(2)': {
+      animationDelay: '-0.16s'
+    },
+    '@keyframes bounce': {
+      '0%, 80%, 100%': {
+        transform: 'scale(0)'
+      },
+      '40%': {
+        transform: 'scale(1)'
+      }
+    }
+  })
+  .asElement('div');
+```
+
+#### Animation Best Practices
+
+1. **Performance**: Use `transform` and `opacity` for best performance
+2. **Accessibility**: Respect `prefers-reduced-motion`:
+   ```typescript
+   .styles({
+     '@media (prefers-reduced-motion: reduce)': {
+       animation: 'none',
+       transition: 'none'
+     }
+   })
+   ```
+3. **Duration**: Keep animations short (200-400ms for micro-interactions)
+4. **Easing**: Use appropriate easing functions:
+   - `ease-out` for enter animations
+   - `ease-in` for exit animations
+   - `ease-in-out` for state changes
 
 ### Compound Components
-*Documentation coming soon - Card.Header, Card.Body patterns*
 
-Compound composition is up to the user - a Compound component can befined as aliases of local components to indicate they are intended to be used together:
+Compound components are a powerful pattern for creating related components that work together. Here's the recommended approach based on real-world usage:
+
+#### Basic Pattern
 
 ```tsx
 const Card = animus
@@ -336,17 +625,616 @@ Card.Body = CardBody;
 export default Card;
 ```
 
+#### Advanced Pattern with TypeScript (from Layout.tsx)
+
+```tsx
+// Define individual components
+const LayoutContainer = animus
+  .styles({
+    display: 'grid',
+    gridTemplateAreas: '"header header" "sidebar content"',
+  })
+  .states({
+    sidebar: {
+      gridTemplateAreas: {
+        _: '"header header" "content content"',
+        sm: '"header header" "sidebar content"',
+      }
+    }
+  })
+  .asElement('div');
+
+const HeaderContainer = animus
+  .styles({ area: 'header' })
+  .asElement('div');
+
+const SidebarContainer = animus
+  .styles({ area: 'sidebar' })
+  .asElement('div');
+
+// Create compound type
+type LayoutContainer = typeof LayoutContainer;
+
+export interface Layout extends LayoutContainer {
+  Header: typeof HeaderContainer;
+  Sidebar: typeof SidebarContainer;
+}
+
+// Export with sub-components attached
+export const Layout = LayoutContainer as Layout;
+Layout.Header = HeaderContainer;
+Layout.Sidebar = SidebarContainer;
+
+// Usage
+<Layout sidebar>
+  <Layout.Header>...</Layout.Header>
+  <Layout.Sidebar>...</Layout.Sidebar>
+</Layout>
+```
+
+This pattern provides:
+- Type-safe compound components
+- Clear parent-child relationships
+- Cohesive API for related components
+
 ### Global Styles & Resets
 *Documentation coming soon - app-wide styles approach*
 
 ### Performance Considerations
-*Documentation coming soon - patterns to avoid, optimization tips*
+
+Based on real-world usage patterns, here are key performance optimizations:
+
+#### 1. Avoid Excessive Pseudo-Elements
+
+While powerful, overuse of `:before` and `:after` can impact performance:
+
+```tsx
+// ❌ Avoid: Multiple layers of pseudo-elements
+.styles({
+  '&:before': { /* gradient layer */ },
+  '&:after': { /* shadow layer */ },
+  '& > div:before': { /* more effects */ },
+  '& > div:after': { /* even more */ }
+})
+
+// ✅ Better: Use actual elements when needed
+const Container = animus.styles({...}).asElement('div');
+const GradientLayer = animus.styles({...}).asElement('div');
+const ContentLayer = animus.styles({...}).asElement('div');
+```
+
+#### 2. Optimize Gradient Animations
+
+Gradient animations can be expensive. Use transform instead:
+
+```tsx
+// ❌ Avoid: Animating background-position continuously
+.styles({
+  animation: 'flow 5s linear infinite',
+  '@keyframes flow': {
+    '0%': { backgroundPosition: '0% 0%' },
+    '100%': { backgroundPosition: '100% 0%' }
+  }
+})
+
+// ✅ Better: Use transform for smoother performance
+.styles({
+  '&:before': {
+    content: '""',
+    position: 'absolute',
+    inset: 0,
+    background: 'gradient',
+    transform: 'translateX(0)',
+    transition: 'transform 0.3s ease',
+  },
+  '&:hover:before': {
+    transform: 'translateX(-100px)',
+  }
+})
+```
+
+#### 3. Group-Based Code Splitting
+
+Enable only the groups you need to reduce bundle size:
+
+```tsx
+// ❌ Avoid: Enabling all groups
+.groups({
+  layout: true,
+  space: true,
+  color: true,
+  typography: true,
+  borders: true,
+  shadows: true,
+  positioning: true,
+  background: true,
+  flex: true,
+  grid: true
+})
+
+// ✅ Better: Enable only what's needed
+.groups({
+  layout: true,
+  space: true,
+  color: true
+})
+```
+
+#### 4. Responsive Value Optimization
+
+Use responsive values judiciously:
+
+```tsx
+// ❌ Avoid: Responsive values for every property
+.styles({
+  padding: { _: 8, xs: 12, sm: 16, md: 20, lg: 24, xl: 32 },
+  margin: { _: 4, xs: 6, sm: 8, md: 10, lg: 12, xl: 16 },
+  fontSize: { _: 14, xs: 15, sm: 16, md: 17, lg: 18, xl: 20 },
+})
+
+// ✅ Better: Use responsive values for key breakpoints
+.styles({
+  padding: { _: 8, sm: 16, lg: 24 },
+  margin: 8,
+  fontSize: { _: 14, sm: 16 }
+})
+```
+
+#### 5. Component Composition vs. Complex Styles
+
+Break complex components into simpler pieces:
+
+```tsx
+// ❌ Avoid: One component with many variants and states
+const Button = animus
+  .styles({ /* 50+ lines of base styles */ })
+  .variant({ /* 10 variants */ })
+  .states({ /* 8 states */ })
+  .asElement('button');
+
+// ✅ Better: Compose from simpler components
+const BaseButton = animus.styles({...}).asElement('button');
+const IconButton = BaseButton.extend().styles({...}).asElement('button');
+const LoadingButton = BaseButton.extend().states({...}).asElement('button');
+```
+
+#### 6. Memoize Complex Components
+
+For components with expensive render logic:
+
+```tsx
+import { memo } from 'react';
+
+const ExpensiveComponent = memo(
+  animus
+    .styles({ /* complex styles */ })
+    .asComponent(({ children, ...props }) => {
+      // Complex render logic
+      return <div {...props}>{children}</div>;
+    })
+);
+```
+
+#### 7. CSS Variable Performance
+
+When using ThemeBuilder, minimize CSS variable lookups:
+
+```tsx
+// ❌ Avoid: Many individual variable references
+.styles({
+  color: 'var(--colors-text)',
+  backgroundColor: 'var(--colors-background)',
+  borderColor: 'var(--colors-border)',
+  // ... many more
+})
+
+// ✅ Better: Use semantic tokens that group related values
+.styles({
+  color: 'text',
+  bg: 'background',
+  borderColor: 'border',
+})
+```
+
+#### 8. Build-Time Optimizations
+
+- Use production builds to eliminate development warnings
+- Enable CSS extraction in your bundler when possible
+- Consider using `babel-plugin-emotion` for build-time optimizations
+- Tree-shake unused Animus groups and features
+
+#### Key Metrics to Monitor
+
+1. **Bundle Size**: Track the size of your styled components
+2. **Runtime Performance**: Monitor style recalculation in DevTools
+3. **Memory Usage**: Watch for memory leaks from dynamic styles
+4. **Initial Load**: Measure time to first meaningful paint
 
 ### Complete Component Examples
 *Documentation coming soon - comprehensive examples with all features*
 
 ### Common UI Patterns
-*Documentation coming soon - modal, dropdown, form field implementations*
+
+Based on real-world usage analysis, here are common patterns for building UI components with Animus:
+
+#### Layered Visual Effects (Button Pattern)
+
+Create rich visual effects by separating container and content:
+
+```tsx
+// Container handles background effects
+const ButtonContainer = animus
+  .styles({
+    position: 'relative',
+    overflow: 'hidden',
+  })
+  .variant({
+    prop: 'variant',
+    variants: {
+      fill: {
+        '&:before': {
+          content: '""',
+          position: 'absolute',
+          inset: 0,
+          gradient: 'flowX',
+          backgroundSize: '300px 100%',
+          transition: 'background-position 0.3s ease',
+        },
+        '&:hover:before': {
+          backgroundPosition: '-100px 0%',
+        }
+      },
+      stroke: {
+        '&:before': {
+          content: '""',
+          position: 'absolute',
+          inset: 0,
+          gradient: 'flowX',
+          zIndex: 0,
+        },
+        '&:after': {
+          content: '""',
+          position: 'absolute',
+          inset: 2,
+          bg: 'background-current',
+          zIndex: 0,
+        }
+      }
+    }
+  })
+  .asElement('button');
+
+// Foreground handles text/content
+const ButtonForeground = animus
+  .styles({
+    position: 'relative',
+    zIndex: 1,
+  })
+  .variant({
+    prop: 'size',
+    variants: {
+      sm: { px: 12, py: 6, fontSize: 14 },
+      md: { px: 16, py: 8, fontSize: 16 },
+      lg: { px: 20, py: 10, fontSize: 18 }
+    }
+  })
+  .asElement('span');
+```
+
+#### Grid Layout with Named Areas
+
+Use CSS Grid with named template areas for complex layouts:
+
+```tsx
+const Layout = animus
+  .styles({
+    display: 'grid',
+    gridTemplateAreas: '"header header" "sidebar content"',
+    gridTemplateColumns: '15rem 1fr',
+    gridTemplateRows: 'auto 1fr',
+  })
+  .states({
+    collapsed: {
+      gridTemplateAreas: '"header" "content"',
+      gridTemplateColumns: '1fr',
+    }
+  })
+  .asElement('div');
+
+// Child components reference grid areas
+const Sidebar = animus
+  .styles({
+    gridArea: 'sidebar',
+    // or using Animus shorthand:
+    area: 'sidebar'
+  })
+  .asElement('aside');
+```
+
+#### Gradient Text Effects
+
+Create gradient text using background clip:
+
+```tsx
+const GradientText = animus
+  .styles({
+    gradient: 'primary',
+    backgroundClip: 'text',
+    WebkitBackgroundClip: 'text',
+    WebkitTextFillColor: 'transparent',
+  })
+  .asElement('span');
+```
+
+#### Responsive Sticky Positioning
+
+Combine responsive values with position states:
+
+```tsx
+const Navigation = animus
+  .styles({
+    position: {
+      _: 'fixed',
+      sm: 'sticky'
+    },
+    top: 0,
+    zIndex: 10,
+  })
+  .asElement('nav');
+```
+
+#### State-Based Component Switching
+
+Use states for component behavior changes:
+
+```tsx
+const Modal = animus
+  .styles({
+    position: 'fixed',
+    inset: 0,
+    display: 'flex',
+    alignItems: 'center',
+    justifyContent: 'center',
+    opacity: 0,
+    pointerEvents: 'none',
+    transition: 'opacity 0.2s ease',
+  })
+  .states({
+    open: {
+      opacity: 1,
+      pointerEvents: 'auto',
+    }
+  })
+  .asElement('div');
+```
+
+#### Polymorphic Components
+
+Use variants with 'as' prop for semantic flexibility:
+
+```tsx
+const Text = animus
+  .variant({
+    prop: 'as',
+    variants: {
+      h1: { fontSize: 32, lineHeight: 1.2, fontWeight: 700 },
+      h2: { fontSize: 24, lineHeight: 1.3, fontWeight: 600 },
+      p: { fontSize: 16, lineHeight: 1.5, fontWeight: 400 },
+      small: { fontSize: 14, lineHeight: 1.4, fontWeight: 400 },
+    }
+  })
+  .asElement('p');
+
+// Usage: <Text as="h1">Heading</Text>
+```
+
+#### Minimal Wrapper Pattern
+
+Sometimes it's better to wrap existing components than create new ones:
+
+```tsx
+export const Code = (props: ComponentProps<typeof Box>) => (
+  <Box
+    as="code"
+    color="primary"
+    fontFamily="mono"
+    fontSize={14}
+    {...props}
+  />
+);
+```
 
 ### Design System Integration
-*Documentation coming soon - token integration, migration patterns*
+
+#### Token Integration with ThemeBuilder
+
+When building a design system with Animus and ThemeBuilder, follow this pattern:
+
+1. **Define Design Tokens**:
+   ```typescript
+   // tokens.ts
+   export const tokens = {
+     colors: {
+       brand: {
+         primary: '#007bff',
+         secondary: '#6c757d'
+       },
+       semantic: {
+         success: '#28a745',
+         danger: '#dc3545'
+       }
+     },
+     space: {
+       xs: '0.25rem',
+       sm: '0.5rem',
+       md: '1rem',
+       lg: '2rem',
+       xl: '4rem'
+     }
+   };
+   ```
+
+2. **Build Theme with CSS Variables**:
+   ```typescript
+   // theme.ts
+   import { createTheme } from '@syzygos/theming';
+   
+   export const theme = createTheme(baseTheme)
+     .addColors(tokens.colors)
+     .createScaleVariables('space')
+     .addColorModes('light', {
+       light: {
+         bg: 'white',
+         text: 'brand.primary'
+       },
+       dark: {
+         bg: 'brand.primary',
+         text: 'white'
+       }
+     })
+     .build();
+   ```
+
+3. **Create Design System Components**:
+   ```typescript
+   // Button.ts
+   export const Button = animus
+     .styles({
+       cursor: 'pointer',
+       fontFamily: 'body',
+       transition: 'all 0.2s'
+     })
+     .variant({
+       prop: 'variant',
+       variants: {
+         primary: {
+           bg: 'brand.primary',
+           color: 'white',
+           '&:hover': {
+             bg: 'brand.secondary'
+           }
+         },
+         outline: {
+           bg: 'transparent',
+           borderWidth: '2px',
+           borderStyle: 'solid',
+           borderColor: 'brand.primary',
+           color: 'brand.primary'
+         }
+       }
+     })
+     .variant({
+       prop: 'size',
+       variants: {
+         sm: { px: 'sm', py: 'xs', fontSize: 'sm' },
+         md: { px: 'md', py: 'sm', fontSize: 'base' },
+         lg: { px: 'lg', py: 'md', fontSize: 'lg' }
+       }
+     })
+     .states({
+       disabled: {
+         opacity: 0.6,
+         cursor: 'not-allowed'
+       }
+     })
+     .groups({ space: true })
+     .asElement('button');
+   ```
+
+#### Migration Patterns
+
+##### From CSS/SCSS to Animus
+
+```scss
+// Before (SCSS)
+.button {
+  padding: 8px 16px;
+  border-radius: 4px;
+  
+  &--primary {
+    background: blue;
+    color: white;
+  }
+  
+  &:disabled {
+    opacity: 0.6;
+  }
+}
+```
+
+```typescript
+// After (Animus)
+const Button = animus
+  .styles({
+    padding: '8px 16px',
+    borderRadius: '4px'
+  })
+  .variant({
+    prop: 'variant',
+    variants: {
+      primary: {
+        background: 'blue',
+        color: 'white'
+      }
+    }
+  })
+  .states({
+    disabled: {
+      opacity: 0.6
+    }
+  })
+  .asElement('button');
+```
+
+##### From Styled Components to Animus
+
+```typescript
+// Before (styled-components)
+const Button = styled.button<{ variant?: 'primary' | 'secondary' }>`
+  padding: ${props => props.theme.space[2]} ${props => props.theme.space[4]};
+  background: ${props => props.variant === 'primary' ? props.theme.colors.primary : props.theme.colors.secondary};
+`;
+```
+
+```typescript
+// After (Animus)
+const Button = animus
+  .styles({
+    px: 4, // Uses theme.space scale
+    py: 2
+  })
+  .variant({
+    prop: 'variant',
+    variants: {
+      primary: { bg: 'primary' },
+      secondary: { bg: 'secondary' }
+    }
+  })
+  .asElement('button');
+```
+
+#### Best Practices for Design Systems
+
+1. **Use Semantic Token Names**: Instead of `blue-500`, use `brand.primary`
+2. **Leverage Color Modes**: Define semantic aliases that change with modes
+3. **Component Composition**: Build complex components from simple ones
+4. **Consistent Prop APIs**: Use the same variant names across components
+5. **Document Token Usage**: Create a token reference guide for designers
+
+#### Token Reference Architecture
+
+```typescript
+// Create a centralized token reference
+export const designSystem = {
+   components: {
+     Button,
+     Card,
+     Input
+   },
+   tokens: theme._tokens, // Original token values
+   scales: {
+     colors: theme.colors,
+     space: theme.space,
+     // ... other scales
+   }
+};
diff --git a/packages/core/package.json b/packages/core/package.json
index 5a1fcee..ab8376e 100644
--- a/packages/core/package.json
+++ b/packages/core/package.json
@@ -1,5 +1,5 @@
 {
-  "name": "@animus-ui/core",
+  "name": "@syzygos/core",
   "description": "Constraint based CSS in JS Foundations",
   "version": "0.2.0-beta.0",
   "keywords": [
diff --git a/packages/theming/CLAUDE.md b/packages/theming/CLAUDE.md
new file mode 100644
index 0000000..8fc15a2
--- /dev/null
+++ b/packages/theming/CLAUDE.md
@@ -0,0 +1,334 @@
+# ThemeBuilder Architecture & Animus Integration
+
+This document captures deep architectural insights about the ThemeBuilder system and its integration with the Animus builder from the core package.
+
+## Table of Contents
+
+1. [ThemeBuilder Architecture](#themebuilder-architecture)
+2. [Design Token Resolution Process](#design-token-resolution-process)
+3. [Animus Builder Integration](#animus-builder-integration)
+4. [Critical Integration Points](#critical-integration-points)
+5. [Recommendations & Improvements](#recommendations--improvements)
+6. [Open Questions](#open-questions)
+
+## ThemeBuilder Architecture
+
+### Overview
+
+The ThemeBuilder provides a fluent, type-safe API for building themes with design tokens, CSS variables, and color modes. It follows a Producer-Consumer pattern where ThemeBuilder produces theme configuration and Animus consumes it via Emotion's ThemeProvider.
+
+### Core Components
+
+#### 1. Current ThemeBuilder Implementation (`createTheme.ts`)
+
+```typescript
+export class ThemeBuilder<T extends AbstractTheme> {
+  #theme = {} as T;
+  
+  constructor(baseTheme: T) { /* ... */ }
+}
+```
+
+**Key Methods:**
+- `createScaleVariables(key)` - Transforms theme scales into CSS variables
+- `addColors(colors)` - Adds color tokens to the theme
+- `addColorModes(initialMode, modeConfig)` - Implements color mode switching
+- `addScale(key, createScale)` - Adds new scale to the theme
+- `updateScale(key, updateFn)` - Updates existing scale values
+- `build()` - Finalizes the theme
+
+#### 2. Legacy ThemeBuilder (`ThemeBuilder.ts`)
+
+Uses class inheritance hierarchy:
+```
+ThemeUnitialized → ThemeWithBreakpoints → ThemeWithRawColors → ThemeWithAll
+```
+
+### Theme Object Structure
+
+The built theme contains three critical structures:
+
+1. **Public Scales** (e.g., `theme.colors`): CSS variable references (`'var(--colors-primary)'`)
+2. **Private Variables** (`theme._variables`): CSS variable definitions
+3. **Private Tokens** (`theme._tokens`): Original values (currently redundant)
+
+## Design Token Resolution Process
+
+### 1. Token Definition Phase
+
+```typescript
+createTheme(baseTheme)
+  .addColors({ primary: '#007bff' })
+```
+
+### 2. Serialization Phase
+
+The `serializeTokens` function creates:
+- **Token References**: `{ primary: 'var(--colors-primary)' }`
+- **Token Variables**: `{ '--colors-primary': '#007bff' }`
+
+### 3. Storage Phase
+
+- `theme.colors.primary` = `'var(--colors-primary)'`
+- `theme._variables.root['--colors-primary']` = `'#007bff'`
+- `theme._tokens.colors.primary` = `'#007bff'`
+
+### 4. Injection Phase (Critical Gap)
+
+**Currently missing**: A mechanism to inject CSS variables into the DOM. Applications must implement:
+
+```typescript
+const MyGlobalStyles = () => {
+  const theme = useTheme();
+  return (
+    <Global
+      styles={css`
+        :root {
+          /* Inject theme._variables.root here */
+        }
+      `}
+    />
+  );
+};
+```
+
+### 5. Component Usage Phase
+
+```typescript
+<MyComponent color="primary" />
+```
+
+### 6. Style Resolution Phase
+
+1. `createPropertyStyle` invoked for `color` prop
+2. Calls `lookupScaleValue('primary', 'colors', theme)`
+3. Returns `'var(--colors-primary)'`
+4. Emotion generates CSS: `color: var(--colors-primary);`
+
+### 7. Browser Resolution Phase
+
+Browser applies styles using CSS Custom Properties from injected variables.
+
+## Animus Builder Integration
+
+### Architecture Overview
+
+Animus uses a class hierarchy with fluent API:
+```
+Animus → AnimusWithBase → AnimusWithVariants → AnimusWithStates → AnimusWithSystem → AnimusWithAll
+```
+
+### Integration Points
+
+1. **Theme Access**: Animus components receive theme via Emotion's ThemeProvider
+2. **Scale Lookup**: `lookupScaleValue` resolves theme values from scales
+3. **CSS Variable Support**: Animus treats CSS variable strings as opaque values
+4. **Responsive Breakpoints**: Both systems use `theme.breakpoints` for media queries
+
+### Value Resolution Flow
+
+```
+Component Prop → createPropertyStyle → lookupScaleValue → Theme Scale → CSS Variable → Browser
+```
+
+## Critical Integration Points
+
+### 1. Scale Value Resolution
+
+The `lookupScaleValue` function in core/src/scales/lookupScaleValue.ts:
+- Resolves values from theme scales
+- Falls back to compatTheme
+- **Limitation**: Doesn't support negative values (e.g., `m="-4"`)
+
+### 2. Responsive Values
+
+- **ThemeBuilder**: Creates breakpoint CSS variables
+- **Animus**: Uses breakpoints for media query generation
+- Both systems must coordinate on breakpoint definitions
+
+### 3. Color Modes
+
+Current implementation has complexity:
+- `_variables.mode` contains initial mode values
+- `_tokens.modes` structure unclear
+- Application responsible for mode switching logic
+
+## Recommendations & Improvements
+
+### 1. Simplify Theme Contract
+
+Remove `_tokens` from final output, keeping only:
+- **Public Scales**: CSS variable references
+- **Private Variables**: CSS variable definitions
+
+### 2. Provide Global Styles Utility
+
+```typescript
+export const createGlobalStyles = (theme) => {
+  const { root, modes } = theme._variables;
+  
+  return css`
+    :root {
+      ${varsToCss(root)}
+    }
+    
+    ${Object.entries(modes).map(([mode, vars]) => `
+      [data-theme='${mode}'] {
+        ${varsToCss(vars)}
+      }
+    `).join('')}
+  `;
+};
+```
+
+### 3. Support Negative Values
+
+Update `lookupScaleValue` to handle string-prefixed negatives:
+
+```typescript
+if (isString(val) && val.startsWith('-')) {
+  const positiveKey = val.substring(1);
+  const scaleValue = get(usedScale, positiveKey);
+  
+  if (isString(scaleValue) || isNumber(scaleValue)) {
+    return `-${scaleValue}`;
+  }
+}
+```
+
+### 4. Improve Color Mode Architecture
+
+Restructure `_variables` for clarity:
+```typescript
+{
+  _variables: {
+    root: { /* base tokens */ },
+    modes: {
+      light: { /* semantic aliases */ },
+      dark: { /* semantic aliases */ }
+    }
+  }
+}
+```
+
+### 5. Type Safety Enhancements
+
+- Create comprehensive type tests for chained builder calls
+- Provide `GetAnimusProps<T>` utility type
+- Make `build()` method generic for better inference
+
+## Open Questions
+
+### Critical Architecture Questions
+
+1. **Variable Injection Strategy**: Should we provide an official `ThemeProvider` wrapper that handles CSS variable injection automatically?
+   - Current gap: Apps must manually inject `theme._variables` into DOM
+   - Consideration: Auto-injection could simplify setup but reduce flexibility
+
+2. **Migration Path**: How do we support gradual migration from literal-value themes to CSS-variable-based themes?
+   - Challenge: Mixed themes with both literal values and CSS variables
+   - Need: Clear documentation and tooling for incremental adoption
+
+3. **Performance Optimization**: Is the extensive use of `lodash.merge` in builder chains a performance concern?
+   - Impact: Each builder method creates new merged objects
+   - Alternative: Investigate more performant merge strategies or lazy evaluation
+
+4. **Type Complexity**: How can we simplify the generic type chains while maintaining type safety?
+   - Current: Heavy generic usage can create complex error messages
+   - Goal: Better developer experience with clearer type errors
+
+### Integration Improvements
+
+5. **Negative Value Support**: Should negative values use string prefix pattern (like Chakra UI)?
+   - Current: `lookupScaleValue` doesn't support negative theme values
+   - Proposed: Support `m="-4"` syntax for negative margins
+
+6. **Color Mode Architecture**: Should we simplify the current three-source-of-truth pattern?
+   - Current: `_variables`, `_tokens`, and public scales create confusion
+   - Proposed: Eliminate `_tokens` from final build output
+
+7. **Responsive Value Coordination**: How to ensure array/object responsive syntax works consistently?
+   - Need: Integration tests between ThemeBuilder breakpoints and Animus responsive arrays
+   - Challenge: Both systems must coordinate on breakpoint definitions
+
+### Developer Experience
+
+8. **Official Global Styles Utility**: Should we provide `createGlobalStyles` helper?
+   - Benefit: Standardized way to inject CSS variables
+   - Implementation: Could be part of @syzygos/theming package
+
+9. **Theme Structure Validation**: Should we validate theme structure at runtime?
+   - Use case: Catch missing CSS variable injections early
+   - Trade-off: Runtime validation vs. bundle size
+
+10. **Documentation Gaps**: Which patterns need more comprehensive examples?
+    - Compound components with theming
+    - Global styles and CSS resets
+    - Performance optimization patterns
+    - Common UI patterns (modals, dropdowns, forms)
+
+### Technical Debt
+
+11. **Legacy ThemeBuilder**: Should we deprecate the class inheritance version?
+    - Current: Two implementations create confusion
+    - Migration: Need clear upgrade path for existing users
+
+12. **Theme Contract Clarity**: How to better document the theme object contract?
+    - Issue: Unclear when to use `_variables` vs `_tokens` vs public scales
+    - Solution: Clearer separation of concerns in documentation
+
+### New Questions from Real-World Usage Analysis
+
+13. **Gradient Token System**: How should gradient tokens be defined in ThemeBuilder?
+    - Observed: Components use `gradient: 'flowX'` tokens
+    - Need: Clear pattern for defining complex gradient tokens as CSS variables
+
+14. **Numeric Value Normalization**: How do numeric theme values (0, 1, 0.5) map to CSS?
+    - Observed: `width: 1`, `size: 1`, `left: 0.5` in components
+    - Question: Is this a percentage system or theme scale reference?
+
+15. **Semantic Token Categories**: What token categories should ThemeBuilder support?
+    - Observed: text-shadow tokens ('flush', 'link-raised')
+    - Observed: gradient tokens ('flowX')
+    - Question: How to organize non-standard CSS tokens?
+
+16. **WebKit-Specific Properties**: Should ThemeBuilder handle vendor prefixes?
+    - Observed: `WebkitTextFillColor`, `WebkitBackgroundClip` usage
+    - Challenge: CSS variables with vendor prefixes
+
+17. **Grid Template Token Support**: Should grid templates be tokenized?
+    - Observed: Complex responsive grid templates in Layout
+    - Consideration: Token vs. inline definition trade-offs
+
+18. **Animation Token Integration**: How should keyframe animations work with tokens?
+    - Observed: Imported keyframes used with Animus styles
+    - Question: Can animations reference theme tokens?
+
+19. **Performance Benchmarks**: What's the performance impact of CSS variables?
+    - Heavy use of pseudo-elements with gradient variables
+    - Need: Benchmarks comparing literal values vs. CSS variables
+
+20. **Custom Property Mappings**: Should ThemeBuilder know about Animus prop shorthands?
+    - Observed: `area` → `gridArea`, `gradient` → complex gradient
+    - Question: Where should this mapping knowledge live?
+
+## Technical Notes
+
+### Key Files
+
+- `/packages/theming/src/utils/createTheme.ts` - Main builder implementation
+- `/packages/theming/src/utils/serializeTokens.ts` - CSS variable generation
+- `/packages/theming/src/utils/flattenScale.ts` - Object flattening utilities
+- `/packages/core/src/scales/lookupScaleValue.ts` - Theme value resolution
+- `/packages/core/src/Animus.ts` - Style builder integration
+
+### Dependencies
+
+- Emotion for CSS-in-JS and theming
+- Lodash for object manipulation
+- TypeScript for type safety
+
+---
+
+*Last Updated: January 2025*
+*Analysis based on deep architectural review and integration testing*
\ No newline at end of file
diff --git a/packages/theming/README.md b/packages/theming/README.md
index f66bbd9..acb74ab 100644
--- a/packages/theming/README.md
+++ b/packages/theming/README.md
@@ -1,4 +1,4 @@
-# `@animus-ui/theming`
+# `@syzygos/theming`
 
 In order to use animus with your custom theme you must redeclare the emotion global `Theme`.
 
diff --git a/packages/theming/package.json b/packages/theming/package.json
index 5b001f2..13bd0ad 100644
--- a/packages/theming/package.json
+++ b/packages/theming/package.json
@@ -1,5 +1,5 @@
 {
-  "name": "@animus-ui/theming",
+  "name": "@syzygos/theming",
   "version": "0.1.1-beta.28",
   "description": "Theming Utilities",
   "author": "Aaron Robb <airrobb@gmail.com>",
@@ -25,7 +25,7 @@
     "url": "https://github.com/codecaaron/animus/issues"
   },
   "dependencies": {
-    "@animus-ui/core": "^0.2.0-beta.0",
+    "@syzygos/core": "^0.2.0-beta.0",
     "@emotion/react": "^11.14.0",
     "@emotion/styled": "^11.14.0"
   },
diff --git a/packages/theming/src/core/ThemeBuilder.ts b/packages/theming/src/core/ThemeBuilder.ts
index 76f5412..649d7fb 100644
--- a/packages/theming/src/core/ThemeBuilder.ts
+++ b/packages/theming/src/core/ThemeBuilder.ts
@@ -1,4 +1,4 @@
-import { Breakpoints } from '@animus-ui/core';
+import { Breakpoints } from '@syzygos/core';
 
 /**
  * 1. Breakpoints
diff --git a/packages/theming/src/utils/createTheme.ts b/packages/theming/src/utils/createTheme.ts
index 72cae57..40697e9 100644
--- a/packages/theming/src/utils/createTheme.ts
+++ b/packages/theming/src/utils/createTheme.ts
@@ -1,4 +1,4 @@
-import { AbstractTheme, CSSObject } from '@animus-ui/core';
+import { AbstractTheme, CSSObject } from '@syzygos/core';
 import { mapValues, merge } from 'lodash';
 
 import { flattenScale, LiteralPaths } from './flattenScale';
diff --git a/packages/theming/src/utils/serializeTokens.ts b/packages/theming/src/utils/serializeTokens.ts
index d37b769..ed0a983 100644
--- a/packages/theming/src/utils/serializeTokens.ts
+++ b/packages/theming/src/utils/serializeTokens.ts
@@ -1,5 +1,5 @@
-import { CSSObject } from '@animus-ui/core';
 import { Theme } from '@emotion/react';
+import { CSSObject } from '@syzygos/core';
 import { isObject, merge } from 'lodash';
 
 /**
diff --git a/packages/theming/src/utils/types.ts b/packages/theming/src/utils/types.ts
index 7bd6bd7..1457684 100644
--- a/packages/theming/src/utils/types.ts
+++ b/packages/theming/src/utils/types.ts
@@ -1,4 +1,4 @@
-import { AbstractTheme, CSSObject } from '@animus-ui/core';
+import { AbstractTheme, CSSObject } from '@syzygos/core';
 
 /**
  * This is a custom generic that ensures the safety of adding additional values to a theme object without accidentally wiping out
diff --git a/packages/ui/package.json b/packages/ui/package.json
index 3087380..678d1d3 100644
--- a/packages/ui/package.json
+++ b/packages/ui/package.json
@@ -1,5 +1,5 @@
 {
-  "name": "@animus-ui/components",
+  "name": "@syzygos/components",
   "version": "0.1.1-beta.34",
   "description": "> TODO: description",
   "author": "Aaron Robb <airrobb@gmail.com>",
@@ -25,8 +25,8 @@
     "url": "https://github.com/codecaaron/animus/issues"
   },
   "dependencies": {
-    "@animus-ui/core": "^0.2.0-beta.0",
-    "@animus-ui/theming": "^0.1.1-beta.28",
+    "@syzygos/core": "^0.2.0-beta.0",
+    "@syzygos/theming": "^0.1.1-beta.28",
     "@emotion/cache": "^11.14.0",
     "@emotion/react": "^11.14.0",
     "@emotion/styled": "^11.14.0",
diff --git a/packages/ui/src/AnimusProvider.tsx b/packages/ui/src/AnimusProvider.tsx
index a9032e5..6e73f5a 100644
--- a/packages/ui/src/AnimusProvider.tsx
+++ b/packages/ui/src/AnimusProvider.tsx
@@ -1,10 +1,10 @@
-import { compatTheme, CSSObject } from '@animus-ui/core';
 import {
   CacheProvider,
   EmotionCache,
   Theme,
   ThemeProvider,
 } from '@emotion/react';
+import { compatTheme, CSSObject } from '@syzygos/core';
 import React, { PropsWithChildren, useContext, useMemo, useRef } from 'react';
 
 import { createCache } from './cache/createCache';
diff --git a/packages/ui/src/components/ColorMode.tsx b/packages/ui/src/components/ColorMode.tsx
index 0f8ffe0..30cd8b1 100644
--- a/packages/ui/src/components/ColorMode.tsx
+++ b/packages/ui/src/components/ColorMode.tsx
@@ -1,6 +1,6 @@
-import { ThemeProps } from '@animus-ui/core';
-import { serializeTokens } from '@animus-ui/theming';
 import { Theme, ThemeProvider } from '@emotion/react';
+import { ThemeProps } from '@syzygos/core';
+import { serializeTokens } from '@syzygos/theming';
 import { mapValues, pick } from 'lodash';
 import React, { ComponentProps, forwardRef, useMemo } from 'react';
 
diff --git a/packages/ui/src/components/VariableProvider.tsx b/packages/ui/src/components/VariableProvider.tsx
index 3016a69..7707255 100644
--- a/packages/ui/src/components/VariableProvider.tsx
+++ b/packages/ui/src/components/VariableProvider.tsx
@@ -1,4 +1,4 @@
-import { animus } from '@animus-ui/core';
+import { animus } from '@syzygos/core';
 
 export const VariableProvider = animus
   .styles({ color: 'text' })
diff --git a/packages/ui/src/elements/Anchor.tsx b/packages/ui/src/elements/Anchor.tsx
index 91952dd..7239ae9 100644
--- a/packages/ui/src/elements/Anchor.tsx
+++ b/packages/ui/src/elements/Anchor.tsx
@@ -1,4 +1,4 @@
-import { animus } from '@animus-ui/core';
+import { animus } from '@syzygos/core';
 
 export const Anchor = animus
   .styles({
diff --git a/packages/ui/src/elements/Box.tsx b/packages/ui/src/elements/Box.tsx
index 75027ba..c92014e 100644
--- a/packages/ui/src/elements/Box.tsx
+++ b/packages/ui/src/elements/Box.tsx
@@ -1,4 +1,4 @@
-import { animus } from '@animus-ui/core';
+import { animus } from '@syzygos/core';
 
 export const Box = animus
   .states({
diff --git a/packages/ui/src/elements/FlexBox.tsx b/packages/ui/src/elements/FlexBox.tsx
index 82898b6..e35da0f 100644
--- a/packages/ui/src/elements/FlexBox.tsx
+++ b/packages/ui/src/elements/FlexBox.tsx
@@ -1,4 +1,4 @@
-import { animus } from '@animus-ui/core';
+import { animus } from '@syzygos/core';
 
 export const FlexBox = animus
   .styles({ display: 'flex' })
diff --git a/packages/ui/src/elements/GridBox.ts b/packages/ui/src/elements/GridBox.ts
index 09e006b..ed903c1 100644
--- a/packages/ui/src/elements/GridBox.ts
+++ b/packages/ui/src/elements/GridBox.ts
@@ -1,4 +1,4 @@
-import { animus } from '@animus-ui/core';
+import { animus } from '@syzygos/core';
 
 export const GridBox = animus
   .styles({ display: 'grid' })
diff --git a/packages/ui/src/elements/Image.tsx b/packages/ui/src/elements/Image.tsx
index 000fe5c..72345f4 100644
--- a/packages/ui/src/elements/Image.tsx
+++ b/packages/ui/src/elements/Image.tsx
@@ -1,4 +1,4 @@
-import { animus } from '@animus-ui/core';
+import { animus } from '@syzygos/core';
 
 export const Image = animus
   .groups({
diff --git a/packages/ui/src/elements/List.tsx b/packages/ui/src/elements/List.tsx
index 01160ac..84a8fde 100644
--- a/packages/ui/src/elements/List.tsx
+++ b/packages/ui/src/elements/List.tsx
@@ -1,4 +1,4 @@
-import { animus } from '@animus-ui/core';
+import { animus } from '@syzygos/core';
 
 export const Ul = animus
   .styles({ mb: 16, pl: 20, lineHeight: 'base' })
diff --git a/packages/ui/src/elements/Svg.tsx b/packages/ui/src/elements/Svg.tsx
index c3bcd76..52c8018 100644
--- a/packages/ui/src/elements/Svg.tsx
+++ b/packages/ui/src/elements/Svg.tsx
@@ -1,4 +1,4 @@
-import { animus } from '@animus-ui/core';
+import { animus } from '@syzygos/core';
 
 export const Svg = animus
   .groups({
diff --git a/packages/ui/src/elements/Text.tsx b/packages/ui/src/elements/Text.tsx
index 06e60f7..74bac17 100644
--- a/packages/ui/src/elements/Text.tsx
+++ b/packages/ui/src/elements/Text.tsx
@@ -1,4 +1,4 @@
-import { animus } from '@animus-ui/core';
+import { animus } from '@syzygos/core';
 
 export const Text = animus
   .styles({ m: 0 })
diff --git a/packages/ui/src/globals/ColorScheme.tsx b/packages/ui/src/globals/ColorScheme.tsx
index 2fdba84..7156de0 100644
--- a/packages/ui/src/globals/ColorScheme.tsx
+++ b/packages/ui/src/globals/ColorScheme.tsx
@@ -1,5 +1,5 @@
-import { serializeTokens } from '@animus-ui/theming';
 import { css, Global, useTheme } from '@emotion/react';
+import { serializeTokens } from '@syzygos/theming';
 import { isEmpty, mapValues } from 'lodash';
 import React, { useMemo } from 'react';
 
diff --git a/packages/ui/src/globals/Variables.tsx b/packages/ui/src/globals/Variables.tsx
index 9aa8246..c58d140 100644
--- a/packages/ui/src/globals/Variables.tsx
+++ b/packages/ui/src/globals/Variables.tsx
@@ -1,5 +1,5 @@
-import { CSSObject } from '@animus-ui/core';
 import { css, Global } from '@emotion/react';
+import { CSSObject } from '@syzygos/core';
 import React from 'react';
 
 const scopeVariables = (vars: CSSObject, scope = ':root') =>
diff --git a/packages/ui/src/index.ts b/packages/ui/src/index.ts
index 363f77d..3f89a7f 100644
--- a/packages/ui/src/index.ts
+++ b/packages/ui/src/index.ts
@@ -1,4 +1,4 @@
-export { createAnimus, animus } from '@animus-ui/core';
+export { createAnimus, animus } from '@syzygos/core';
 export * from './AnimusProvider';
 export * from './ComponentProvider/ComponentProvider';
 export * from './elements';
diff --git a/packages/ui/src/theme.tsx b/packages/ui/src/theme.tsx
index 688978e..2aafee7 100644
--- a/packages/ui/src/theme.tsx
+++ b/packages/ui/src/theme.tsx
@@ -1,4 +1,4 @@
-import { AbstractTheme } from '@animus-ui/core';
+import { AbstractTheme } from '@syzygos/core';
 
 type Colors<T = {}> = {
   primary: T;
diff --git a/partnerships/AI_AGENT_BRIEF.md b/partnerships/AI_AGENT_BRIEF.md
index 7b52ebd..037a768 100644
--- a/partnerships/AI_AGENT_BRIEF.md
+++ b/partnerships/AI_AGENT_BRIEF.md
@@ -46,7 +46,7 @@ This enables:
 ## Technical Context
 
 - **Stack**: TypeScript, Emotion (CSS-in-JS), Monorepo (Yarn/Lerna/Nx)
-- **Packages**: @animus-ui/core (foundation), /theming, /components
+- **Packages**: @syzygos/core (foundation), /theming, /components
 - **Build**: Static extraction proven viable (POC complete)
 - **Node**: v20+ required
 
diff --git a/docs/archive/PHILOSOPHY.md b/project/PHILOSOPHY.md
similarity index 86%
rename from docs/archive/PHILOSOPHY.md
rename to project/PHILOSOPHY.md
index fa70b06..d896231 100644
--- a/docs/archive/PHILOSOPHY.md
+++ b/project/PHILOSOPHY.md
@@ -1,10 +1,10 @@
-# Syzygy: A Philosophy of Unified Opposites
+# Syzygos: A Philosophy of Unified Opposites
 
 ## The Name
 
-Syzygy (pronunciation: /ˈsɪzɪdʒi/) comes from the Greek *syzygos* meaning "yoked together." In Jungian psychology, it represents the divine marriage of opposites - a union where opposing forces achieve wholeness without losing their individual identities.
+Syzygos (from the Greek *syzygos* meaning "yoked together") represents the divine marriage of opposites - a union where opposing forces achieve wholeness without losing their individual identities. In Jungian psychology, this concept (also known as syzygy) represents the integration of opposing psychological forces.
 
-For our CSS-in-JS framework, Syzygy represents the harmonious union of:
+For our CSS-in-JS framework, Syzygos represents the harmonious union of:
 - **Constraint and Freedom**
 - **Structure and Expression**  
 - **Human Intent and Machine Execution**
@@ -21,7 +21,7 @@ Our internal architecture mirrors Jung's concept of psychological wholeness thro
 ### Anima: The Receptive Principle
 The anima represents the **constraint layer** - the feminine principle that receives and shapes raw expression into meaningful form.
 
-In Syzygy, the anima manifests as:
+In Syzygos, the anima manifests as:
 - **Style Constraints**: The rules that shape valid CSS expressions
 - **Type Definitions**: The boundaries that guide developer intent
 - **State Definitions**: The possible conditions a component can embody
@@ -32,7 +32,7 @@ The anima asks: "What can be expressed?"
 ### Animus: The Active Principle  
 The animus represents the **expression layer** - the masculine principle that actively manifests styled reality.
 
-In Syzygy, the animus manifests as:
+In Syzygos, the animus manifests as:
 - **Runtime Engine**: The force that evaluates props and generates styles
 - **CSS Generation**: The active creation of stylesheet rules
 - **DOM Manipulation**: The direct action upon elements
@@ -40,12 +40,12 @@ In Syzygy, the animus manifests as:
 
 The animus asks: "How does it get expressed?"
 
-### Syzygy: The Sacred Union
-The complete Syzygy component represents the *conjunctio* - the sacred marriage where both principles unite in perfect balance.
+### Syzygos: The Sacred Union
+The complete Syzygos component represents the *conjunctio* - the sacred marriage where both principles unite in perfect balance.
 
 ```typescript
 // The progression toward wholeness
-const Component = syzygy
+const Component = syzygos
   .styles({ /* anima: establishing base identity */ })
   .variants({ /* anima: defining ways of being */ })
   .states({ /* anima: conditional expressions */ })
@@ -91,7 +91,7 @@ Jung taught that wholeness requires integrating the shadow - those aspects we ty
 
 ## For Human Developers
 
-Syzygy provides:
+Syzygos provides:
 - **Intuitive Progression**: Each step follows naturally from the last
 - **Type-Guided Discovery**: Your IDE becomes a wise guide
 - **Predictable Patterns**: Learn once, apply everywhere
@@ -99,7 +99,7 @@ Syzygy provides:
 
 ## For AI Agents
 
-Syzygy offers:
+Syzygos offers:
 - **Finite State Machine**: Infinite CSS possibilities become enumerable paths
 - **Semantic Intent**: Each method call declares meaning, not just mechanics
 - **Predictable Generation**: Clear patterns enable reliable code creation
@@ -107,7 +107,7 @@ Syzygy offers:
 
 ## The Future We're Building
 
-We envision a future where human creativity and AI capability achieve syzygy - a true union where:
+We envision a future where human creativity and AI capability achieve syzygos - a true union where:
 - Designers think in systems, AI handles specifics
 - Humans define intent, machines ensure consistency
 - The boundary between human and AI code becomes irrelevant
@@ -115,7 +115,7 @@ We envision a future where human creativity and AI capability achieve syzygy - a
 
 ## Why This Matters
 
-In an age of AI-assisted development, we need languages that both humans and machines speak fluently. Syzygy isn't just another CSS framework - it's a communication protocol for the future of UI development.
+In an age of AI-assisted development, we need languages that both humans and machines speak fluently. Syzygos isn't just another CSS framework - it's a communication protocol for the future of UI development.
 
 When human intuition and machine precision achieve syzygy, we don't just build better components. We build better ways of building.
 
@@ -124,4 +124,4 @@ When human intuition and machine precision achieve syzygy, we don't just build b
 *"The meeting of two personalities is like the contact of two chemical substances: if there is any reaction, both are transformed."*  
 — Carl Jung
 
-In Syzygy, every component is a transformation - where human intent and machine execution meet, react, and emerge as something greater than either could achieve alone.
\ No newline at end of file
+In Syzygos, every component is a transformation - where human intent and machine execution meet, react, and emerge as something greater than either could achieve alone.
\ No newline at end of file
diff --git a/project/TECHNICAL_OVERVIEW.md b/project/TECHNICAL_OVERVIEW.md
index 5fff783..1b8e72a 100644
--- a/project/TECHNICAL_OVERVIEW.md
+++ b/project/TECHNICAL_OVERVIEW.md
@@ -1,6 +1,6 @@
 # Animus Technical Overview
 
-This document serves as the canonical technical reference for the Animus/Syzygy project. All partners should refer to this for architecture, commands, and technical implementation details.
+This document serves as the canonical technical reference for the Animus/Syzygos project. All partners should refer to this for architecture, commands, and technical implementation details.
 
 ## Project Overview
 
@@ -22,10 +22,10 @@ yarn verify         # Run compile, lint, and format checks
 
 ### Working with specific packages
 ```bash
-yarn workspace @animus-ui/core build
-yarn workspace @animus-ui/theming build
-yarn workspace @animus-ui/components build
-yarn workspace @animus-ui/docs dev
+yarn workspace @syzygos/core build
+yarn workspace @syzygos/theming build
+yarn workspace @syzygos/components build
+yarn workspace @syzygos/docs dev
 ```
 
 ### Nx Commands for Efficiency
@@ -37,10 +37,10 @@ yarn affected:test  # Test only affected packages
 ## Architecture
 
 ### Package Structure
-- **@animus-ui/core**: Foundation for constraint-based CSS-in-JS, provides the core `animus` builder API
-- **@animus-ui/theming**: Theming utilities, CSS variable support, token serialization
-- **@animus-ui/components**: Pre-built UI components (Box, FlexBox, GridBox, Text, etc.)
-- **@animus-ui/docs**: Next.js documentation site with MDX support
+- **@syzygos/core**: Foundation for constraint-based CSS-in-JS, provides the core `animus` builder API
+- **@syzygos/theming**: Theming utilities, CSS variable support, token serialization
+- **@syzygos/components**: Pre-built UI components (Box, FlexBox, GridBox, Text, etc.)
+- **@syzygos/docs**: Next.js documentation site with MDX support
 - **_integration**: Integration tests for the entire system
 
 ### Technology Stack
diff --git a/project/checklists/RENAME_CHECKLIST.md b/project/checklists/RENAME_CHECKLIST.md
index 36bc1a2..1f51be1 100644
--- a/project/checklists/RENAME_CHECKLIST.md
+++ b/project/checklists/RENAME_CHECKLIST.md
@@ -4,25 +4,25 @@
 **Target**: Single comprehensive PR
 
 ## Pre-Implementation Tasks
-- [ ] @codecaaron: Register `@syzygy` npm scope
-- [ ] @codecaaron: Register `syzygy.dev` domain
-- [ ] @codecaaron: Rename GitHub repository to `syzygy`
+- [ ] @codecaaron: Register `@syzygos` npm scope
+- [ ] @codecaaron: Register `syzygos.dev` domain
+- [ ] @codecaaron: Rename GitHub repository to `syzygos`
 
 ## Codebase Changes (Lead: @Claude)
 
 ### Core Renames
-- [ ] Global find-and-replace: "Animus" → "Syzygy", "animus" → "syzygy"
-- [ ] Update all internal variable names and constants (e.g., `ANIMUS_CONFIG` → `SYZYGY_CONFIG`)
-- [ ] Update API names if branded (e.g., `createAnimusTheme()` → `createSyzygyTheme()`)
+- [ ] Global find-and-replace: "Animus" → "Syzygos", "animus" → "syzygos"
+- [ ] Update all internal variable names and constants (e.g., `ANIMUS_CONFIG` → `SYZYGOS_CONFIG`)
+- [ ] Update API names if branded (e.g., `createAnimusTheme()` → `createSyzygosTheme()`)
 - [ ] Rename files using `git mv` to preserve history:
-  - [ ] `STATE_OF_THE_ANIMUS.md` → `STATE_OF_THE_SYZYGY.md`
+  - [ ] `STATE_OF_THE_ANIMUS.md` → `STATE_OF_THE_SYZYGOS.md`
   - [ ] Any other files with "animus" in the name
 
 ### Code Details
 - [ ] Update all TypeScript type definitions that reference "Animus"
 - [ ] Update error messages and console outputs
 - [ ] Check for hardcoded strings in test files
-- [ ] Update any environment variable names (ANIMUS_* → SYZYGY_*)
+- [ ] Update any environment variable names (ANIMUS_* → SYZYGOS_*)
 - [ ] Update webpack/rollup config references
 - [ ] Update example projects and demos
 - [ ] Check all import/require statements
@@ -30,10 +30,10 @@
 ## Configuration & Tooling (Lead: @Gemini)
 
 ### Package Configuration
-- [ ] Update `name` in all `package.json` files to `@syzygy/*`:
-  - [ ] `packages/core/package.json` → `@syzygy/core`
-  - [ ] `packages/theming/package.json` → `@syzygy/theming`
-  - [ ] `packages/components/package.json` → `@syzygy/components`
+- [ ] Update `name` in all `package.json` files to `@syzygos/*`:
+  - [ ] `packages/core/package.json` → `@syzygos/core`
+  - [ ] `packages/theming/package.json` → `@syzygos/theming`
+  - [ ] `packages/components/package.json` → `@syzygos/components`
   - [ ] Root `package.json` workspace references
 - [ ] Update repository URLs in all `package.json` files
 - [ ] Update `homepage` fields to use new domain
@@ -43,7 +43,7 @@
 - [ ] Update CI/CD workflows in `.github/workflows/`
 - [ ] Update GitHub Actions workflow names and badges
 - [ ] Update any CI environment variables or secrets
-- [ ] Configure npm publishing for `@syzygy` scope
+- [ ] Configure npm publishing for `@syzygos` scope
 
 ### Development Tools
 - [ ] Update any CLI commands (if applicable)
@@ -57,7 +57,7 @@
 - [ ] Update `PARTNERS.md` (includes hardcoded names in signature blocks)
 - [ ] Update `PHILOSOPHY.md`
 - [ ] Update `CLAUDE.md` at both root and package levels
-- [ ] Create decision log entry in `/decisions/0001-rename-to-syzygy.md`
+- [ ] Create decision log entry in `/decisions/0001-rename-to-syzygos.md`
 
 ### Governance Documents
 - [ ] Update `GOVERNANCE_VOTING_SYSTEM.md`
@@ -91,5 +91,5 @@
 
 ## Final Steps
 - [ ] Merge PR with co-authored commit from all partners
-- [ ] Tag release as `v0.1.0-syzygy`
+- [ ] Tag release as `v0.1.0-syzygos`
 - [ ] Celebrate the first successful Council Vote! 🎉
\ No newline at end of file
diff --git a/votes/active/issue-60-rename-to-syzygy/proposal.md b/votes/active/issue-60-rename-to-syzygy/proposal.md
index 1c1f8cb..e454895 100644
--- a/votes/active/issue-60-rename-to-syzygy/proposal.md
+++ b/votes/active/issue-60-rename-to-syzygy/proposal.md
@@ -1,4 +1,4 @@
-# Proposal: Rename Project from Animus to Syzygy
+# Proposal: Rename Project from Animus to Syzygos
 
 **Issue**: #60
 **Type**: Council Vote
@@ -8,12 +8,12 @@
 
 ## Summary
 
-We propose renaming the project from "Animus" to "Syzygy". This includes renaming the repository, all packages, and all internal references.
+We propose renaming the project from "Animus" to "Syzygos". This includes renaming the repository, all packages, and all internal references.
 
 ## Rationale
 
-1. **Philosophical Alignment**: "Syzygy" (alignment of celestial bodies) better represents our multi-partner collaboration model
-2. **Technical Benefits**: Natural support for scoped packages (@syzygy/core, @syzygy/theming)
+1. **Philosophical Alignment**: "Syzygos" (alignment of celestial bodies) better represents our multi-partner collaboration model
+2. **Technical Benefits**: Natural support for scoped packages (@syzygos/core, @syzygos/theming)
 3. **Partnership Symbolism**: Reflects that each contributor (human or AI) is essential to the whole
 
 ## Implementation Plan

From bcce70a5d60fe3f4ee6db505c77042f2fbe9b08b Mon Sep 17 00:00:00 2001
From: Aaron Robb <raelaggro@gmail.com>
Date: Sun, 15 Jun 2025 04:59:23 -0400
Subject: [PATCH 2/2] Should just do precommit hook :/

---
 packages/_docs/elements/Tables.tsx            | 44 +++++++++---------
 .../__tests__/static-extraction.test.ts       | 46 +++++++++----------
 packages/core/src/static-poc/static-mode.ts   | 16 ++++---
 packages/core/src/static-poc/validate-poc.ts  |  7 +--
 scripts/validate-votes.js                     | 17 +++++--
 5 files changed, 70 insertions(+), 60 deletions(-)

diff --git a/packages/_docs/elements/Tables.tsx b/packages/_docs/elements/Tables.tsx
index f2b2588..2966a0e 100644
--- a/packages/_docs/elements/Tables.tsx
+++ b/packages/_docs/elements/Tables.tsx
@@ -1,6 +1,6 @@
 import { animus } from '@syzygos/core';
 
- const TableBase = animus
+const TableBase = animus
   .styles({
     mt: 16,
     mb: 24,
@@ -11,7 +11,7 @@ import { animus } from '@syzygos/core';
   })
   .asElement('div');
 
- const TableRow = animus
+const TableRow = animus
   .styles({
     display: 'flex',
     px: 16,
@@ -27,26 +27,26 @@ import { animus } from '@syzygos/core';
   })
   .asElement('div');
 
- const TableCell = animus
-   .styles({
-     py: 12,
-     flexBasis: '350px',
-   })
-   .states({
-     max: {
-       flexBasis: '150px',
-     },
-     fill: {
-       flex: 1,
-     },
-   })
-   .props({
-     size: {
-       property: 'flexBasis',
-       scale: { xs: '10rem', sm: '15rem' },
-     },
-   })
-   .asElement('div');
+const TableCell = animus
+  .styles({
+    py: 12,
+    flexBasis: '350px',
+  })
+  .states({
+    max: {
+      flexBasis: '150px',
+    },
+    fill: {
+      flex: 1,
+    },
+  })
+  .props({
+    size: {
+      property: 'flexBasis',
+      scale: { xs: '10rem', sm: '15rem' },
+    },
+  })
+  .asElement('div');
 
 const Table = Object.assign(TableBase, { Cell: TableCell, Row: TableRow });
 
diff --git a/packages/core/src/static-poc/__tests__/static-extraction.test.ts b/packages/core/src/static-poc/__tests__/static-extraction.test.ts
index 2c91b31..65f6639 100644
--- a/packages/core/src/static-poc/__tests__/static-extraction.test.ts
+++ b/packages/core/src/static-poc/__tests__/static-extraction.test.ts
@@ -54,12 +54,14 @@ describe('Static Extraction POC', () => {
     // Since we can't directly access the style function after emotion processes it,
     // we'll test the build function directly
     const buildFn = animus.styles({ margin: '2rem' }).build();
-    
+
     // Check that build returns a function with static config
     expect(typeof buildFn).toBe('function');
     expect((buildFn as any).__staticConfig).toBeDefined();
     expect((buildFn as any).__staticConfig.baseClasses).toHaveLength(1);
-    expect((buildFn as any).__staticConfig.baseClasses[0].className).toBe('_m-2rem');
+    expect((buildFn as any).__staticConfig.baseClasses[0].className).toBe(
+      '_m-2rem'
+    );
 
     AnimusStatic.disable();
   });
@@ -81,7 +83,7 @@ describe('Static Extraction POC', () => {
         },
       })
       .build();
-    
+
     // Test that variants are in the static config
     const staticConfig = (buildFn as any).__staticConfig;
     expect(staticConfig).toBeDefined();
@@ -89,12 +91,12 @@ describe('Static Extraction POC', () => {
     expect(staticConfig.variantClasses.size).toBeDefined();
     expect(staticConfig.variantClasses.size.small).toBeDefined();
     expect(staticConfig.variantClasses.size.large).toBeDefined();
-    
+
     // Test small variant class generation
     const smallResult = buildFn({ size: 'small' });
     expect(smallResult.className).toContain('_p-0_5rem');
     expect(smallResult.className).not.toContain('_p-1rem'); // Should override base
-    
+
     // Test large variant class generation
     const largeResult = buildFn({ size: 'large' });
     expect(largeResult.className).toContain('_p-1_5rem');
@@ -106,35 +108,33 @@ describe('Static Extraction POC', () => {
     AnimusStatic.enable();
 
     // Create base component
-    const baseBuilder = animus
-      .styles({
-        padding: '1rem',
-        borderRadius: '4px',
-      });
-    
+    const baseBuilder = animus.styles({
+      padding: '1rem',
+      borderRadius: '4px',
+    });
+
     // Get the build function
     const baseBuildFn = baseBuilder.build();
-    
+
     // Verify extend is available on the build function
     expect(typeof baseBuildFn.extend).toBe('function');
-    
+
     // Create extended component using build().extend()
-    const extendedBuilder = baseBuildFn.extend()
-      .styles({
-        backgroundColor: 'blue',
-        color: 'white',
-      });
-    
+    const extendedBuilder = baseBuildFn.extend().styles({
+      backgroundColor: 'blue',
+      color: 'white',
+    });
+
     const extendedBuildFn = extendedBuilder.build();
-    
+
     // Check that extended build has combined styles
     const extendedConfig = (extendedBuildFn as any).__staticConfig;
     expect(extendedConfig).toBeDefined();
     expect(extendedConfig.baseClasses).toBeDefined();
-    
+
     // Get all class names
     const classNames = extendedConfig.baseClasses.map((c: any) => c.className);
-    
+
     // Should have both base and extended classes
     expect(classNames).toContain('_p-1rem');
     expect(classNames).toContain('_br-4px');
@@ -155,7 +155,7 @@ describe('Static Extraction POC', () => {
 
     // Should work normally when static mode is off
     expect(html).toMatch(/css-\w+/);
-    
+
     // And our static config should not be attached to build
     const buildFn = animus.styles({ padding: '1rem' }).build();
     expect((buildFn as any).__staticConfig).toBeUndefined();
diff --git a/packages/core/src/static-poc/static-mode.ts b/packages/core/src/static-poc/static-mode.ts
index 165043c..e4c550d 100644
--- a/packages/core/src/static-poc/static-mode.ts
+++ b/packages/core/src/static-poc/static-mode.ts
@@ -65,7 +65,7 @@ function patchBuildMethod() {
   }
 
   // Create a shared build patcher function
-  const createStaticBuildFunction = function(this: any, originalBuildFn: any) {
+  const createStaticBuildFunction = function (this: any, originalBuildFn: any) {
     if (!staticModeEnabled) {
       return originalBuildFn.call(this);
     }
@@ -102,20 +102,22 @@ function patchBuildMethod() {
       const classes: string[] = [];
 
       // Add base classes
-      const baseClassNames = staticConfig.baseClasses.map(c => c.className);
+      const baseClassNames = staticConfig.baseClasses.map((c) => c.className);
       classes.push(...baseClassNames);
 
       // Handle variants based on props
-      for (const [variantProp, variants] of Object.entries(staticConfig.variantClasses)) {
+      for (const [variantProp, variants] of Object.entries(
+        staticConfig.variantClasses
+      )) {
         const variantValue = props[variantProp];
         if (variantValue && variants[variantValue]) {
           // Get variant classes
           const variantClasses = variants[variantValue];
-          const variantClassNames = variantClasses.map(c => c.className);
+          const variantClassNames = variantClasses.map((c) => c.className);
 
           // Find which properties are overridden by variant
           const overriddenProps = new Set(
-            variantClasses.map(c => {
+            variantClasses.map((c) => {
               // Extract property prefix from class name (e.g., '_p-1rem' -> '_p')
               const match = c.className.match(/^_([^-]+)/);
               return match ? match[1] : '';
@@ -123,7 +125,7 @@ function patchBuildMethod() {
           );
 
           // Remove base classes that are overridden
-          const filteredBaseClasses = classes.filter(className => {
+          const filteredBaseClasses = classes.filter((className) => {
             const match = className.match(/^_([^-]+)/);
             const prefix = match ? match[1] : '';
             return !overriddenProps.has(prefix);
@@ -140,7 +142,7 @@ function patchBuildMethod() {
         // Use Emotion's label for debugging
         label: 'animus-static',
         // Apply our atomic classes via className
-        className: classes.join(' ')
+        className: classes.join(' '),
       };
     };
 
diff --git a/packages/core/src/static-poc/validate-poc.ts b/packages/core/src/static-poc/validate-poc.ts
index 5b73618..a0ae2c3 100644
--- a/packages/core/src/static-poc/validate-poc.ts
+++ b/packages/core/src/static-poc/validate-poc.ts
@@ -47,9 +47,10 @@ MockAnimusWithAll.prototype.build = function (this: MockAnimusWithAll) {
   };
 
   // Return function with static config attached
-  const fn = (_props: any) => ({
-    staticClasses: staticConfig.baseClasses.map((c) => c.className).join(' '),
-  }) as any;
+  const fn = (_props: any) =>
+    ({
+      staticClasses: staticConfig.baseClasses.map((c) => c.className).join(' '),
+    } as any);
   (fn as any).__staticConfig = staticConfig;
   return fn;
 };
diff --git a/scripts/validate-votes.js b/scripts/validate-votes.js
index 9e442a4..a9f213e 100755
--- a/scripts/validate-votes.js
+++ b/scripts/validate-votes.js
@@ -8,8 +8,9 @@ const path = require('path');
 const SIGNATURES = {
   claude: /---CLAUDE-SIGNATURE-START---[\s\S]+?---CLAUDE-SIGNATURE-END---/,
   gemini: /===GEMINI-SIGNATURE-BLOCK===[\s\S]+?===END-SIGNATURE-BLOCK===/,
-  openai: /<<<OPENAI-GOVERNANCE-SIGNATURE>>>[\s\S]+?<<<END-GOVERNANCE-SIGNATURE>>>/,
-  aaron: /### HUMAN SIGNATURE ###[\s\S]+?### END SIGNATURE ###/
+  openai:
+    /<<<OPENAI-GOVERNANCE-SIGNATURE>>>[\s\S]+?<<<END-GOVERNANCE-SIGNATURE>>>/,
+  aaron: /### HUMAN SIGNATURE ###[\s\S]+?### END SIGNATURE ###/,
 };
 
 function validateVote(filePath) {
@@ -36,7 +37,9 @@ function validateVote(filePath) {
   // Extract vote
   const voteMatch = content.match(/\*\*Vote\*\*:\s*([+-]1|ABSTAIN)/);
   if (!voteMatch) {
-    throw new Error('Invalid vote format. Must specify **Vote**: +1, -1, or ABSTAIN');
+    throw new Error(
+      'Invalid vote format. Must specify **Vote**: +1, -1, or ABSTAIN'
+    );
   }
 
   const vote = voteMatch[1];
@@ -57,7 +60,9 @@ function tallyVotes(proposalDir) {
   }
 
   // Validate each vote file
-  const voteFiles = fs.readdirSync(votesDir).filter(f => f.endsWith('.vote.md'));
+  const voteFiles = fs
+    .readdirSync(votesDir)
+    .filter((f) => f.endsWith('.vote.md'));
 
   for (const file of voteFiles) {
     try {
@@ -99,7 +104,9 @@ function tallyVotes(proposalDir) {
 const proposalPath = process.argv[2];
 if (!proposalPath) {
   console.error('Usage: node validate-votes.js <proposal-directory>');
-  console.error('Example: node validate-votes.js votes/active/issue-60-rename-to-syzygy');
+  console.error(
+    'Example: node validate-votes.js votes/active/issue-60-rename-to-syzygy'
+  );
   process.exit(1);
 }