@wtasnorg/candi 0.0.22

package/LICENSE

@@ -0,0 +1,7 @@
+Copyright © 2025 wtasg
+
+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.

package/README.md

@@ -0,0 +1,292 @@
+# Candi Design System
+
+A multi-platform design system based on Nordic/Scandinavian design principles: Hygge (warmth) and Lagom (balance).
+
+Candi provides a single source of truth for colors using the OKLCH color space, synchronized across Web, Flutter, VS Code, Vim, KDE, GNOME, and Obsidian.
+
+**[View Documentation Website](https://wtasg.github.io/candi/)** - Interactive color explorer, component playground, and comprehensive guides.
+
+---
+
+## Multi-Platform Support
+
+| Platform | Support | Integration |
+| :--- | :--- | :--- |
+| **Web** | Full | Tailwind CSS Plugin & CSS Variables |
+| **Flutter** | Full | Type-safe `CandiColors` with OKLCH metadata |
+| **VS Code** | Full | Light & Dark themes with unified syntax highlighting |
+| **Vim** | Full | Standalone `.vim` colorschemes (GUI & Terminal) |
+| **KDE Plasma** | Full | Color schemes for KDE 4, 5 & 6 |
+| **GNOME** | Full | GTK3 & GTK4 themes for X11 and Wayland |
+| **Obsidian** | Full | Light & Dark themes with 60+ CSS variables |
+
+---
+
+## Architecture
+
+### Single Source of Truth
+
+All colors are defined in `src/data/colors.js`. This file is the canonical source for the entire design system.
+
+```text
+src/data/colors.js (Source of Truth)
+        │
+        ▼
+scripts/sync-colors.js (Generator)
+        │
+        ├── src/css/base.css (CSS Variables)
+        ├── src/v4/theme.css (Tailwind v4 @theme)
+        └── dist/colors.json (Data export)
+
+Platform Builds (all consume colors.js directly):
+├── build-flutter.js → flutter/lib/candi_colors.dart
+├── build-vscode.js  → vscode/themes/*.json
+├── build-vim.js     → vim/colors/*.vim
+├── build-kde.js     → kde/v4,v5/*.colors
+├── build-gnome.js   → gnome/gtk-*/*.css
+└── build-obsidian.js → obsidian/theme.css
+```
+
+### OKLCH Color Space
+
+Candi uses OKLCH as its primary color space instead of Hex codes:
+
+- **Perceptual Uniformity**: Consistent contrast and brightness across the palette
+- **Synchronized Themes**: Updates to `src/data/colors.js` propagate to all platforms via `npm run build:all`
+- **Shared Logic**: Centralized conversion in `scripts/color-conv.js` ensures color accuracy
+- **Automated Accessibility**: Integrated WCAG 2.1 contrast ratio validation
+
+**[Learn more about OKLCH color conversion](docs/color-conversion.md)**
+
+---
+
+## Project Structure
+
+```text
+candi/
+├── src/                    # Source files for npm package
+│   ├── css/                # CSS files (base, components, utilities)
+│   ├── data/               # Source of truth (colors.js)
+│   ├── v4/                 # Tailwind v4 theme
+│   ├── index.js            # Main entry point
+│   ├── plugin.js           # Tailwind v3 plugin
+│   └── theme.js            # Tailwind v3 theme extension
+├── scripts/                # Build and test scripts
+│   ├── build.js            # Main npm package build
+│   ├── build-*.js          # Platform-specific builds
+│   ├── test-*.js           # Platform-specific tests
+│   ├── sync-colors.js      # Color synchronization
+│   └── color-conv.js       # OKLCH/RGB conversion utilities
+├── dist/                   # Built output (git-ignored)
+├── docs/                   # Documentation guides
+├── website/                # Documentation site (Vite + React)
+├── flutter/                # Flutter package
+├── vscode/                 # VS Code extension
+├── vim/                    # Vim colorschemes
+├── kde/                    # KDE Plasma color schemes
+├── gnome/                  # GTK3/GTK4 themes
+└── obsidian/               # Obsidian theme
+```
+
+---
+
+## Commands
+
+### Build
+
+| Command | Description |
+| :--- | :--- |
+| `npm run build` | Build npm package (CSS, JS, TypeScript declarations) |
+| `npm run build:all` | Build all platforms (Web, Flutter, VS Code, Vim, KDE, GNOME, Obsidian) |
+| `npm run build:flutter` | Build Flutter package only |
+| `npm run build:vscode` | Build VS Code extension only |
+| `npm run build:vim` | Build Vim colorschemes only |
+| `npm run build:kde` | Build KDE color schemes only |
+| `npm run build:gnome` | Build GNOME/GTK themes only |
+| `npm run build:obsidian` | Build Obsidian theme only |
+
+### Test
+
+| Command | Description |
+| :--- | :--- |
+| `npm test` | Run all tests |
+| `npm run test:color` | Test color definitions |
+| `npm run test:colors` | Test color conversions |
+| `npm run test:flutter` | Test Flutter package |
+| `npm run test:vscode` | Test VS Code extension |
+| `npm run test:vim` | Test Vim colorschemes |
+| `npm run test:kde` | Test KDE color schemes |
+| `npm run test:gnome` | Test GNOME themes |
+| `npm run test:obsidian` | Test Obsidian theme |
+
+### Package & Publish
+
+| Command | Description |
+| :--- | :--- |
+| `npm run artifact` | Package all platforms into zip archives |
+| `npm run vscode:package` | Generate `.vsix` VS Code extension |
+| `./scripts/package-bump.sh <version>` | Bump version across all packages |
+
+---
+
+## Installation & Usage
+
+### Using Prebuilt Releases
+
+Download ready-to-use artifacts from GitHub releases (recommended for most users).
+
+**[Using Prebuilt Releases Guide](docs/using-release-artifacts.md)**
+
+### GitHub Packages Authentication (Required)
+
+> [!IMPORTANT]
+> This package is published to **GitHub Packages**, not npmjs.com. You must authenticate with GitHub before installing.
+
+To install the package, you need to authenticate with GitHub:
+
+1. **Create a Personal Access Token (PAT)**:
+   - Go to GitHub Settings → [Developer settings → Personal access tokens → Tokens (classic)](https://github.com/settings/tokens)
+   - Click "Generate new token (classic)"
+   - Give it a descriptive name (e.g., "npm packages")
+   - Select the `read:packages` scope
+   - Click "Generate token" and copy the token
+
+2. **Configure npm authentication**:
+
+```bash
+npm login --scope=@wtasg --auth-type=legacy --registry=https://npm.pkg.github.com
+```
+
+- Username: Your GitHub username
+- Password: The PAT you just created
+- Email: Your GitHub email
+
+Or create/update your `~/.npmrc` file:
+
+```text
+//npm.pkg.github.com/:_authToken=YOUR_GITHUB_PAT
+@wtasg:registry=https://npm.pkg.github.com
+```
+
+### Web (Tailwind CSS)
+
+```bash
+npm install @wtasnorg/candi
+```
+
+**Tailwind v4** (Recommended):
+
+```css
+/* In your CSS */
+@import "tailwindcss";
+@import "@wtasnorg/candi/v4";
+```
+
+**Tailwind v3**:
+
+```js
+// tailwind.config.js
+const { theme, plugin } = require('@wtasnorg/candi');
+module.exports = {
+  theme: { extend: theme },
+  plugins: [plugin],
+};
+```
+
+**[Full Web Setup Guide](docs/use-with-tailwindcss.md)** | **[Use Without Tailwind](docs/use-without-tailwindcss.md)**
+
+### Platform Guides
+
+| Platform | Guide |
+| :--- | :--- |
+| Flutter | [Flutter Integration Guide](docs/flutter-integration.md) |
+| VS Code | [VS Code Theme Guide](docs/vscode-theme.md) |
+| Vim | [Vim Theme Guide](docs/vim-theme.md) |
+| KDE Plasma | [KDE Theme Guide](docs/kde-theme.md) |
+| GNOME | [GNOME Theme Guide](docs/gnome-theme.md) |
+| Obsidian | [Obsidian Theme Guide](docs/obsidian-theme.md) |
+
+---
+
+## Color Tokens
+
+| Token | Light | Dark | Usage |
+| :--- | :--- | :--- | :--- |
+| `bg` | Warm white | Warm dark | Page background |
+| `surface` | Soft cream | Card surface | Cards, sections |
+| `elevated` | Pure white | Elevated dark | Modals, popups |
+| `text` | Warm charcoal | Off-white | Primary text |
+| `text-subtle` | Medium gray | Light gray | Secondary text |
+| `text-muted` | Light gray | Muted gray | Tertiary text |
+| `accent` | Steel blue | Lighter steel | Primary actions |
+| `secondary` | Terracotta | Lighter terracotta | Secondary actions |
+| `success` | Forest green | Lighter green | Success states |
+| `warning` | Amber | Lighter amber | Warning states |
+| `error` | Coral red | Lighter coral | Error states |
+
+**[Customize Colors](docs/customizing-colors.md)**
+
+---
+
+## Design & Accessibility
+
+Candi is built with accessibility as a core requirement:
+
+- **WCAG Standards**: Color extraction pipeline automatically validates contrast ratios
+- **Primary Text**: Aimed at **4.5:1** contrast (WCAG AA) for standard text
+- **UI Elements**: Accents and status indicators tuned for **3.0:1** contrast (WCAG Graphical Objects)
+
+---
+
+## Development
+
+### Prerequisites
+
+- Node.js 24+
+- npm
+- Flutter SDK (for Flutter package development)
+
+### Setup
+
+```bash
+# Clone the repository
+git clone https://github.com/wtasg/candi.git
+cd candi
+
+# Install dependencies
+npm install
+
+# Build all platforms
+npm run build:all
+```
+
+### Working on the Documentation Website
+
+The docs website lives in `website/` and uses the built theme from `dist/`:
+
+```bash
+cd website
+npm install
+npm run dev     # Starts dev server at http://localhost:3000
+```
+
+The `predev` and `prebuild` scripts automatically rebuild the parent package, so changes to `src/data/colors.js` are reflected immediately.
+
+### Making Color Changes
+
+1. Edit `src/data/colors.js` (the single source of truth)
+2. Run `npm run build:all` to regenerate all platform themes
+3. Run `npm test` to validate color accuracy and contrast ratios
+
+---
+
+## Related Documentation
+
+- [Knowledge Base](Knowledge.md) - Lessons learned and development gotchas
+- [Color Conversion](docs/color-conversion.md) - OKLCH to RGB conversion pipeline
+
+---
+
+## License
+
+MIT

package/dist/base.css

@@ -0,0 +1,164 @@
+/*
+ * Scandinavian Theme - Base CSS
+ *
+ * AUTO-GENERATED FILE - DO NOT EDIT MANUALLY
+ * This file is generated by: npm run build (scripts/sync-colors.js)
+ * Source of truth: src/data/colors.js
+ * Manual changes will be overwritten on next build.
+ *
+ * OKLCH color tokens for light and dark modes.
+ * Import this file to get CSS custom properties without Tailwind.
+ */
+
+:root {
+  /* @tokens-start-light */
+    --candi-bg: oklch(98% 0.008 85);
+    --candi-surface: oklch(95.5% 0.012 85);
+    --candi-elevated: oklch(100% 0 0);
+    --candi-text: oklch(28% 0.015 250);
+    --candi-text-subtle: oklch(50% 0.01 250);
+    --candi-text-muted: oklch(62% 0.008 250);
+    --candi-border: oklch(90% 0.008 85);
+    --candi-border-strong: oklch(82% 0.01 85);
+    --candi-divider: oklch(88% 0.006 85);
+    --candi-accent: oklch(52% 0.06 230);
+    --candi-accent-subtle: oklch(85% 0.03 230);
+    --candi-on-accent: oklch(100% 0 0);
+    --candi-secondary: oklch(58% 0.12 55);
+    --candi-secondary-subtle: oklch(88% 0.04 55);
+    --candi-on-secondary: oklch(100% 0 0);
+    --candi-success: oklch(52% 0.08 145);
+    --candi-on-success: oklch(100% 0 0);
+    --candi-warning: oklch(68% 0.13 70);
+    --candi-on-warning: oklch(20% 0.02 70);
+    --candi-error: oklch(58% 0.12 25);
+    --candi-on-error: oklch(100% 0 0);
+    --candi-info: oklch(55% 0.1 240);
+    --candi-on-info: oklch(100% 0 0);
+    --candi-link: oklch(50% 0.08 230);
+    --candi-disabled: oklch(75% 0.005 250);
+    --candi-overlay: oklch(0% 0 0 / 0.5);
+    --candi-scrim: oklch(0% 0 0 / 0.32);
+    --candi-inverse-surface: oklch(25% 0.015 250);
+    --candi-inverse-text: oklch(92% 0.01 85);
+    --candi-shadow: 0 2px 8px rgba(45, 50, 57, 0.06);
+    --candi-shadow-md: 0 4px 20px rgba(45, 50, 57, 0.1);
+    --candi-shadow-lg: 0 8px 40px rgba(45, 50, 57, 0.15);
+    --candi-shadow-color: oklch(25% 0.01 250 / 0.15);
+    --candi-focus-ring: oklch(52% 0.06 230 / 0.4);
+    --candi-syntax-keyword: oklch(60% 0.15 0);
+    --candi-syntax-type: oklch(65% 0.12 280);
+    --candi-syntax-var: oklch(65% 0.1 200);
+    --candi-syntax-const: oklch(70% 0.14 50);
+    --candi-syntax-func: oklch(55% 0.12 240);
+    --candi-syntax-string: oklch(60% 0.12 140);
+    --candi-hover: oklch(0% 0 0 / 0.05);
+    --candi-active: oklch(0% 0 0 / 0.1);
+    --candi-terminal-black: oklch(25% 0.01 250);
+    --candi-terminal-red: oklch(58% 0.12 25);
+    --candi-terminal-green: oklch(52% 0.08 145);
+    --candi-terminal-yellow: oklch(68% 0.13 70);
+    --candi-terminal-blue: oklch(52% 0.06 230);
+    --candi-terminal-magenta: oklch(60% 0.15 0);
+    --candi-terminal-cyan: oklch(65% 0.1 200);
+    --candi-terminal-white: oklch(92% 0.01 85);
+
+    /* Terminal Palette */
+    --candi-terminal-black: oklch(25% 0.01 250);
+    --candi-terminal-red: var(--candi-error);
+    --candi-terminal-green: var(--candi-success);
+    --candi-terminal-yellow: var(--candi-warning);
+    --candi-terminal-blue: var(--candi-accent);
+    --candi-terminal-magenta: var(--candi-syntax-keyword);
+    --candi-terminal-cyan: var(--candi-syntax-var);
+    --candi-terminal-white: var(--candi-text);
+    /* @tokens-end-light */
+}
+
+.dark {
+  /* @tokens-start-dark */
+    --candi-bg: oklch(18% 0.015 250);
+    --candi-surface: oklch(22% 0.012 250);
+    --candi-elevated: oklch(25% 0.015 250);
+    --candi-text: oklch(92% 0.01 85);
+    --candi-text-subtle: oklch(72% 0.008 85);
+    --candi-text-muted: oklch(58% 0.006 85);
+    --candi-border: oklch(30% 0.01 250);
+    --candi-border-strong: oklch(40% 0.012 250);
+    --candi-divider: oklch(28% 0.008 250);
+    --candi-accent: oklch(62% 0.08 230);
+    --candi-accent-subtle: oklch(35% 0.04 230);
+    --candi-on-accent: oklch(15% 0.01 230);
+    --candi-secondary: oklch(65% 0.12 55);
+    --candi-secondary-subtle: oklch(30% 0.05 55);
+    --candi-on-secondary: oklch(15% 0.02 55);
+    --candi-success: oklch(60% 0.1 145);
+    --candi-on-success: oklch(15% 0.02 145);
+    --candi-warning: oklch(72% 0.13 70);
+    --candi-on-warning: oklch(15% 0.02 70);
+    --candi-error: oklch(65% 0.12 25);
+    --candi-on-error: oklch(15% 0.02 25);
+    --candi-info: oklch(65% 0.1 240);
+    --candi-on-info: oklch(15% 0.02 240);
+    --candi-link: oklch(60% 0.08 230);
+    --candi-disabled: oklch(45% 0.005 250);
+    --candi-overlay: oklch(0% 0 0 / 0.7);
+    --candi-scrim: oklch(0% 0 0 / 0.6);
+    --candi-inverse-surface: oklch(92% 0.008 85);
+    --candi-inverse-text: oklch(25% 0.015 250);
+    --candi-shadow: 0 2px 8px rgba(0, 0, 0, 0.25);
+    --candi-shadow-md: 0 4px 20px rgba(0, 0, 0, 0.35);
+    --candi-shadow-lg: 0 8px 40px rgba(0, 0, 0, 0.45);
+    --candi-shadow-color: oklch(0% 0 0 / 0.4);
+    --candi-focus-ring: oklch(62% 0.08 230 / 0.5);
+    --candi-syntax-keyword: oklch(70% 0.15 0);
+    --candi-syntax-type: oklch(75% 0.12 280);
+    --candi-syntax-var: oklch(75% 0.1 200);
+    --candi-syntax-const: oklch(80% 0.14 50);
+    --candi-syntax-func: oklch(65% 0.12 240);
+    --candi-syntax-string: oklch(70% 0.12 140);
+    --candi-hover: oklch(100% 0 0 / 0.1);
+    --candi-active: oklch(100% 0 0 / 0.2);
+    --candi-terminal-black: oklch(15% 0.01 250);
+    --candi-terminal-red: oklch(65% 0.12 25);
+    --candi-terminal-green: oklch(60% 0.1 145);
+    --candi-terminal-yellow: oklch(72% 0.13 70);
+    --candi-terminal-blue: oklch(62% 0.08 230);
+    --candi-terminal-magenta: oklch(70% 0.15 0);
+    --candi-terminal-cyan: oklch(75% 0.1 200);
+    --candi-terminal-white: oklch(92% 0.01 85);
+
+    /* Terminal Palette */
+    --candi-terminal-black: oklch(15% 0.01 250);
+    --candi-terminal-red: var(--candi-error);
+    --candi-terminal-green: var(--candi-success);
+    --candi-terminal-yellow: var(--candi-warning);
+    --candi-terminal-blue: var(--candi-accent);
+    --candi-terminal-magenta: var(--candi-syntax-keyword);
+    --candi-terminal-cyan: var(--candi-syntax-var);
+    --candi-terminal-white: var(--candi-text);
+    /* @tokens-end-dark */
+}
+
+/* Base styles */
+html {
+  font-family: Helvetica, sans-serif;
+  line-height: 1.7;
+  letter-spacing: 0.01em;
+}
+
+body {
+  background-color: var(--candi-bg);
+  color: var(--candi-text);
+  transition: background-color 0.3s ease, color 0.3s ease;
+}
+
+::selection {
+  background-color: var(--candi-accent-subtle);
+  color: var(--candi-text);
+}
+
+:focus-visible {
+  outline: 2px solid var(--candi-accent);
+  outline-offset: 2px;
+}