Chore: Add project documentation and automation configuration

[imagineux]

Summary

Migrate to @ankh-studio/themes namespace and align with project standards.

Changes

• Migrate package namespace from @okja/chi-themes to @ankh-studio/themes
• Update dependency from @okja/chi-tokens to @ankh-studio/tokens
• Add project config files (.editorconfig, .nvmrc, .npmrc)
• Add LICENSE (MIT) and CONTRIBUTING.md
• Add GitHub templates (dependabot, PR template)
• Add ADR documentation with initial architecture decision
• Refactor base styles to use design tokens
• Update README with documentation links

[qodo-code-review]

PR Compliance Guide 🔍

Below is a summary of compliance checks for this PR:

Security Compliance
🟢	No security concerns identified No security vulnerabilities detected by AI analysis. Human verification advised for critical code.
Ticket Compliance
⚪	🎫 No ticket provided Create ticket/issue
Codebase Duplication Compliance
⚪	Codebase context is not defined Follow the guide to enable codebase context checks.
Custom Compliance
🟢	Generic: Comprehensive Audit Trails Objective: To create a detailed and reliable record of critical system actions for security analysis and compliance. Status: Passed Learn more about managing compliance generic rules or creating your own custom rules
	Generic: Meaningful Naming and Self-Documenting Code Objective: Ensure all identifiers clearly express their purpose and intent, making code self-documenting Status: Passed Learn more about managing compliance generic rules or creating your own custom rules
	Generic: Robust Error Handling and Edge Case Management Objective: Ensure comprehensive error handling that provides meaningful context and graceful degradation Status: Passed Learn more about managing compliance generic rules or creating your own custom rules
	Generic: Secure Error Handling Objective: To prevent the leakage of sensitive system information through error messages while providing sufficient detail for internal debugging. Status: Passed Learn more about managing compliance generic rules or creating your own custom rules
	Generic: Secure Logging Practices Objective: To ensure logs are useful for debugging and auditing without exposing sensitive information like PII, PHI, or cardholder data. Status: Passed Learn more about managing compliance generic rules or creating your own custom rules
	Generic: Security-First Input Validation and Data Handling Objective: Ensure all data inputs are validated, sanitized, and handled securely to prevent vulnerabilities Status: Passed Learn more about managing compliance generic rules or creating your own custom rules
Update

Compliance status legend

🟢 - Fully Compliant
🟡 - Partial Compliant
🔴 - Not Compliant
⚪ - Requires Further Human Verification
🏷️ - Compliance label

[qodo-code-review]

PR Code Suggestions ✨

Explore these optional code suggestions:

Category	Suggestion	Impact
High-level	The architectural vision is overly ambitious The suggestion advises against committing to the unproven "cognitive context" architectural concept introduced in the ADR. It recommends validating this idea with a proof-of-concept before making it a foundational part of the project. Examples: docs/adr/001-themes-architecture.md [31-164] ### 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. ... (clipped 124 lines) Solution Walkthrough: Before: // In docs/adr/001-themes-architecture.md # ADR-001: Themes as Composable and Consumable Design Layer Status: Accepted ## The Bigger Intentions 1. Cognitive context as a design dimension... We're calling these "design intentions" (Expressive, Focus, Intense). ## Consequences ### Negative - Granular intention control is unproven - Cognitive framing is unvalidated - We're committing to a direction before knowing the mechanics ## The Bet We're betting that cognitive context is a useful design dimension... These bets might be wrong. But they're worth making. After: // In docs/adr/001-themes-architecture.md # ADR-001: Exploring Cognitive Context in Theming Status: Proposed // Changed from Accepted ## Context We are exploring if "cognitive context" can be a useful design dimension. ## Decision We will build a proof-of-concept to validate the "design intentions" idea in an isolated experiment. The core theme architecture will remain focused on proven patterns for now. If the PoC is successful, a new ADR will propose its integration. ## Consequences - Reduces risk by not committing the core architecture to an unproven concept. - Allows for focused validation before wider adoption. Suggestion importance[1-10]: 8 __ Why: This is a high-impact suggestion that correctly identifies a significant strategic risk in the project's foundational architecture, which is introduced in the 001-themes-architecture.md ADR file.	Medium
Possible issue	Fix media query syntax In src/internal/base-styles.css, replace the non-standard media query (width <= 600px) with the standard (max-width: 600px) to ensure correct responsive styling. src/internal/base-styles.css [19-24] -@media screen and (width <= 600px) { +@media screen and (max-width: 600px) { body { font-size: var(--font-size-2); line-height: var(--line-height-2); } } Apply / Chat Suggestion importance[1-10]: 8 __ Why: This suggestion corrects a non-standard media query syntax (width <= 600px) to the standard max-width: 600px, which is critical for ensuring cross-browser compatibility and correct responsive behavior.	Medium
General	✅ Add CSS layer annotations Suggestion Impact: Updated the two token CSS @import rules to explicitly assign them to the tokens layer using layer(tokens). code diff: -@import '@ankh-studio/tokens/dist/tokens.css'; -@import '@ankh-studio/tokens/dist/colors/grayscale.css'; +@import '@ankh-studio/tokens/dist/tokens.css' layer(tokens); +@import '@ankh-studio/tokens/dist/colors/grayscale.css' layer(tokens); In src/default.css, explicitly assign the @import rules for tokens to the tokens layer by appending layer(tokens) to each import statement. src/default.css [13-14] -@import '@ankh-studio/tokens/dist/tokens.css'; -@import '@ankh-studio/tokens/dist/colors/grayscale.css'; +@import '@ankh-studio/tokens/dist/tokens.css' layer(tokens); +@import '@ankh-studio/tokens/dist/colors/grayscale.css' layer(tokens); [Suggestion processed] Suggestion importance[1-10]: 7 __ Why: The suggestion correctly points out that explicitly assigning imports to a CSS layer improves the robustness and predictability of the cascade, which is a good practice for maintainability.	Medium
	Auto-clean before build In package.json, add a prebuild script that executes npm run clean to automatically clear the dist directory before the build script runs. package.json [35-39] "scripts": { + "prebuild": "npm run clean", "build": "postcss 'src/*.css' --dir dist --base src", "clean": "rimraf dist", "lint": "stylelint 'src/**/*.css'" }, Apply / Chat Suggestion importance[1-10]: 6 __ Why: This suggestion improves the build process by using npm's prebuild lifecycle script to automate cleaning the output directory, which is a common and useful practice for ensuring a clean build.	Low
	Align ADR with current implementation Align the cascade layer declaration in the Architecture Decision Record (ADR) with the current CSS implementation by changing @layer reset, tokens, intention, palette, base; to @layer reset, tokens, base;. docs/adr/001-themes-architecture.md [109] -@layer reset, tokens, intention, palette, base; +@layer reset, tokens, base; Apply / Chat Suggestion importance[1-10]: 4 __ Why: The suggestion correctly identifies a discrepancy between the documentation and the implementation, and aligning them improves clarity for future contributors.	Low
Update

[imagineux]

Rationale for unaddressed recommendation

ADR status (overly ambitious):
Acknowledged in the ADR's "Negative" consequences section. Intentionally exploratory.

Media query syntax:
Range syntax is standard CSS (Media Queries Level 4), supported in all modern browsers.

Auto-clean prebuild:
Prefer explicit over implicit. Keeping build steps visible.

Align ADR layers with implementation:
ADR documents target architecture including future layers. Implementation will grow into it.

[Brandon-Anubis]

Rationale for unaddressed recommendation

ADR status (overly ambitious): Acknowledged in the ADR's "Negative" consequences section. Intentionally exploratory.

Media query syntax: Range syntax is standard CSS (Media Queries Level 4), supported in all modern browsers.

Auto-clean prebuild: Prefer explicit over implicit. Keeping build steps visible.

Align ADR layers with implementation: ADR documents target architecture including future layers. Implementation will grow into it.

@imagineux

This all makes sense to me, agree with your rationale, thank you for the focused rationale!

[Brandon-Anubis]

This looks good to me, good to merge, appreciate the easy to review PR and commit cadence, thank you for that @imagineux