Chore: Add project documentation and automation configuration

.editorconfig

@@ -0,0 +1,12 @@
+root = true
+
+[*]
+charset = utf-8
+end_of_line = lf
+indent_style = space
+indent_size = 2
+insert_final_newline = true
+trim_trailing_whitespace = true
+
+[*.md]
+trim_trailing_whitespace = false

.github/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,11 @@
+## Summary
+
+<!-- Brief description of what this PR does -->
+
+## Changes
+
+-
+
+## Notes
+
+<!-- Optional: anything reviewers should know, related issues, etc. -->

.github/dependabot.yml

@@ -0,0 +1,22 @@
+version: 2
+updates:
+  - package-ecosystem: npm
+    directory: /
+    schedule:
+      interval: weekly
+    commit-message:
+      prefix: "chore(deps):"
+    open-pull-requests-limit: 5
+    groups:
+      dev-dependencies:
+        dependency-type: development
+        update-types:
+          - minor
+          - patch
+
+  - package-ecosystem: github-actions
+    directory: /
+    schedule:
+      interval: weekly
+    commit-message:
+      prefix: "chore(ci):"

.github/workflows/lint.yml

@@ -18,4 +18,4 @@ jobs:
 
       - run: npm install
 
-      - run: npm run check
+      - run: npm run lint

.npmrc

@@ -0,0 +1 @@
+engine-strict=true

.nvmrc

@@ -0,0 +1 @@
+lts/*

CONTRIBUTING.md

@@ -0,0 +1,49 @@
+# Contributing
+
+Thanks for your interest in contributing to @ankh-studio/themes.
+
+## Setup
+
+```bash
+git clone https://github.com/ankh-studio/themes.git
+cd themes
+nvm use
+npm install
+```
+
+## Development
+
+```bash
+npm run lint    # Check CSS style
+npm run build   # Compile themes to dist/
+```
+
+## Making Changes
+
+1. Create a branch from `main`
+2. Make your changes in `src/`
+3. Run `npm run lint` and `npm run build`
+4. Submit a pull request
+
+## Code Style
+
+- CSS custom properties only (no preprocessors)
+- Follow existing naming conventions
+- Use tokens from `@ankh-studio/tokens`
+- Run `npm run lint` before committing
+
+## Theme Structure
+
+Each theme file should:
+
+1. Import CSS reset
+2. Import tokens (base + color palette)
+3. Define base styles in `@layer base`
+
+## Design Decisions
+
+Significant changes should be discussed first. For new themes or architectural changes, consider proposing an [ADR](./docs/adr/).
+
+## Questions
+
+Open an issue for discussion before starting large changes.

LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Ankh Studio LLC
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

README.md

@@ -1,25 +1,25 @@
-# @okja/chi-themes
+# @ankh-studio/themes
 
-Pre-composed CSS themes built on Chi Design System tokens. Import one file and get reset, tokens, and base styles.
+Pre-composed CSS themes built on Ankh Studio design tokens. Import one file and get reset, tokens, and base styles.
 
-Built on [@okja/chi-tokens](https://github.com/Okja-Engineering/chi-tokens) - the foundational design tokens for the Chi Design System.
+Built on [@ankh-studio/tokens](https://github.com/ankh-studio/tokens) - the foundational design tokens for the Ankh Studio design system.
 
 ## Installation
 
 ```bash
-npm install @okja/chi-themes
+npm install @ankh-studio/themes
 ```
 
 ## Quick Start
 
 ```css
-@import '@okja/chi-themes/default.css';
+@import '@ankh-studio/themes/default.css';
 ```
 
 Or in HTML:
 
 ```html
-<link rel="stylesheet" href="node_modules/@okja/chi-themes/dist/default.css">
+<link rel="stylesheet" href="node_modules/@ankh-studio/themes/dist/default.css">
 ```
 
 ## Available Themes
@@ -62,7 +62,7 @@ All themes include design tokens:
 - **Shadows** - `--shadow-0` through `--shadow-5`
 - **Motion** - Durations and easings
 
-See [@okja/chi-tokens](https://github.com/Okja-Engineering/chi-tokens) for the complete token reference.
+See [@ankh-studio/tokens](https://github.com/ankh-studio/tokens) for the complete token reference.
 
 ## Dark Mode
 
@@ -104,11 +104,16 @@ Each theme uses CSS Cascade Layers:
 ```
 
 - **reset** - Normalize browser defaults
-- **tokens** - Design tokens from @okja/chi-tokens
+- **tokens** - Design tokens from @ankh-studio/tokens
 - **base** - Typography, links, focus states
 
 Your styles layer on top, giving you full cascade control.
 
+## Documentation
+
+- [Architecture Decision Records](./docs/adr/) - Design decisions and proposals
+- [Contributing](./CONTRIBUTING.md) - How to contribute
+
 ## Changelog
 
 ### 0.1.0

docs/adr/000-template.md

@@ -0,0 +1,20 @@
+# ADR-000: Title
+
+**Status:** Proposed | Accepted | Implemented | Superseded
+**Date:** YYYY-MM-DD
+
+## Context
+
+What problem are we solving?
+
+## Decision
+
+What are we proposing?
+
+## Consequences
+
+What are the trade-offs?
+
+## Open Questions
+
+- [ ] Unresolved items

docs/adr/001-themes-architecture.md

@@ -0,0 +1,164 @@
+# ADR-001: Themes as Composable and Consumable Design Layer
+
+**Status:** Accepted
+**Date:** 2026-01-30
+
+## Context
+
+We're building a design system following well-established patterns — Material Design, Radix, Tailwind, and others have proven that tokens, themes, and layered architecture work. We're building on that foundation.
+
+But we have bigger intentions.
+
+### The Proven Foundation
+
+**What we know works:**
+- Design tokens as single source of truth
+- CSS custom properties for runtime theming
+- Cascade layers for predictable specificity
+- `light-dark()` and `prefers-color-scheme` for dark mode
+- `prefers-reduced-motion` for accessibility
+- Semantic color roles (primary, surface, error)
+- Separation of structure (spacing, radius) from color
+
+We're aligning with Material Design 3's multi-dimensional customization:
+- Color (dynamic palettes, tonal ranges)
+- Typography (type scales)
+- Shape (corner radii)
+- Motion (springs, easing, duration)
+- Spacing/Density
+- Elevation
+
+### The Bigger Intentions
+
+**What we're reaching for:**
+
+1. **Cognitive context as a design dimension** — Not just "what color" but "what cognitive state." We're calling these "design intentions" (Expressive, Focus, Intense). The same interface might need different intentions in different contexts.
+
+2. **Themes as more than color swatches** — Color calibrated for cognitive context. Purple-expressive isn't just purple + generous spacing. The colors themselves shift — higher chroma for engagement, muted baseline for expert vigilance.
+
+3. **Granular intention control** — Not just "the whole app is Focus" but the ability for individual modules or sections to dial in their own intention. A dashboard where one panel is Intense while another is Focus.
+
+We're exploring ways to support this. It's ongoing.
+
+## Decision
+
+### The Layered System
+
+```
+┌─────────────────────────────────┐
+│     @ankh-studio/themes         │  ← color palettes, modes, intention calibration
+├─────────────────────────────────┤
+│     @ankh-studio/tokens         │  ← structure, intentions, primitives
+└─────────────────────────────────┘
+```
+
+**`@ankh-studio/tokens`** provides:
+- Base design tokens (spacing, typography, radius, shadow, motion)
+- Design intention system (Expressive, Focus, Intense)
+- Structural customization dimensions
+
+**`@ankh-studio/themes`** provides:
+- Color palettes with chromatic identity
+- Mode-aware variants (light/dark, reduced motion)
+- Intention-specific color calibration
+- Directly consumable theme bundles
+
+### Directly Consumable
+
+Themes work today as single imports:
+
+```css
+@import '@ankh-studio/themes/purple.css';
+/* You get: reset + tokens + palette + base styles */
+```
+
+This is the primary use case. Import a theme, build your application.
+
+### Granular Intention Control
+
+The goal is for individual modules or sections of a codebase to dial in their intention — not just a global setting. How we support this is being explored.
+
+Possibilities we're considering:
+- Data attributes on containers
+- Scoped CSS custom property overrides
+- Separate intention stylesheets that can be applied per-region
+
+We don't have the answer yet.
+
+### Separation of Concerns
+
+**Tokens own structure:**
+- Spacing, typography, radius, shadows, motion
+- Design intentions (how these shift per cognitive context)
+
+**Themes own color:**
+- Palettes (chromatic identity)
+- Light/dark mode
+- Reduced motion mode
+- Intention-specific color calibration
+
+| Intention | Chroma | Contrast | Accent Usage |
+|-----------|--------|----------|--------------|
+| Expressive | Higher, vibrant | Softer | Liberal |
+| Focus | Moderate | Balanced | Purposeful |
+| Intense | Low baseline | Sharp, high-contrast alerts | Reserved for signals |
+
+### Cascade Layer Structure
+
+```css
+@layer reset, tokens, intention, palette, base;
+```
+
+## What We're Exploring
+
+**Granular intention mechanics:**
+- How do sections/modules opt into different intentions?
+- CSS-only or does it require JavaScript coordination?
+- How do nested intentions interact?
+
+**Color calibration:**
+- How granular should intention-specific color shifts be?
+- Per-role adjustments or systematic chroma/lightness transforms?
+
+**Mode switching:**
+- Manual user control vs system preference vs hybrid
+- Per-section mode overrides
+
+These are active questions. The answers will come from building and using the system.
+
+## Consequences
+
+### Positive
+
+- Following proven patterns reduces risk
+- Directly consumable themes work now
+- Granular intention control opens possibilities we're still discovering
+- Clear separation between tokens (structure) and themes (color)
+
+### Negative
+
+- Granular intention control is unproven
+- Cognitive framing is unvalidated
+- We're committing to a direction before knowing the mechanics
+
+### Neutral
+
+- Current themes work as Focus-intention defaults
+- We can iterate as we learn
+
+## Implementation Path
+
+1. **Phase 1** (Current): Simple palette themes — directly consumable
+2. **Phase 2**: Implement intention tokens in `@ankh-studio/tokens`
+3. **Phase 3**: Create intention-calibrated color variants per palette
+4. **Phase 4**: Explore and validate granular intention control patterns
+5. **Phase 5**: Tooling for custom palette generation
+
+## The Bet
+
+We're betting that:
+- Cognitive context is a useful design dimension
+- Color calibration per intention creates meaningfully different experiences
+- Granular intention control (per-module, not all-or-nothing) is valuable
+
+These bets might be wrong. But they're worth making.

docs/adr/README.md

@@ -0,0 +1,22 @@
+# Architecture Decision Records
+
+This directory contains Architecture Decision Records (ADRs) for @ankh-studio/themes.
+
+## Status
+
+| Status | Meaning |
+|--------|---------|
+| **Proposed** | Under consideration |
+| **Accepted** | Decision made |
+| **Implemented** | In codebase |
+| **Superseded** | Replaced by another ADR |
+
+## Index
+
+| ADR | Title | Status |
+|-----|-------|--------|
+| [001](./001-themes-architecture.md) | Themes as Composable and Consumable Design Layer | Accepted |
+
+## Creating an ADR
+
+Copy `000-template.md` and number sequentially.