@citron-systems/citron-ds 1.0.0 → 1.0.2

package/README.md

@@ -1,149 +1,218 @@
-# @citron-systems/citron-ds
-
-> Inkblot Studio design token system — Apple-inspired, accessible, AI-ready. The **Citron** design language: warmly minimal, quietly distinctive.
-
-[![npm version](https://img.shields.io/npm/v/@citron-systems/citron-ds.svg)](https://www.npmjs.com/package/@citron-systems/citron-ds)
-[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
-
----
-
-## Install
-
-```bash
-npm install @citron-systems/citron-ds
-```
-
-### CDN (no build step)
-
-```html
-<link rel="stylesheet" href="https://unpkg.com/@citron-systems/citron-ds/dist/css/inkblot-variables.css">
-```
-
----
-
-## Quick Start
-
-### CSS (recommended)
-
-```css
-@import '@citron-systems/citron-ds/css';
-
-.button {
-  background: var(--inkblot-semantic-color-interactive-primary);
-  color: var(--inkblot-semantic-color-text-inverse);
-  padding: var(--inkblot-spacing-3) var(--inkblot-spacing-6);
-  border-radius: var(--inkblot-radius-lg);
-  font-weight: var(--inkblot-typography-font-weight-medium);
-  min-height: var(--inkblot-size-touch-target-min);
-  transition: all var(--inkblot-duration-fast) var(--inkblot-easing-default);
-}
-```
-
-### SCSS
-
-```scss
-@use '@citron-systems/citron-ds/scss' as *;
-
-.card {
-  background: var(--inkblot-semantic-color-background-secondary);
-  border: 1px solid var(--inkblot-semantic-color-border-default);
-  border-radius: var(--inkblot-radius-xl);
-  padding: var(--inkblot-spacing-6);
-}
-```
-
-### JavaScript / ESM
-
-```javascript
-import {
-  InkblotColorAccentCitron500,
-  InkblotSpacing4,
-  InkblotRadiusLg,
-} from '@citron-systems/citron-ds';
-
-// Use in JS-driven styling (e.g. React inline, Canvas, etc.)
-const styles = {
-  backgroundColor: InkblotColorAccentCitron500,
-  padding: InkblotSpacing4,
-  borderRadius: InkblotRadiusLg,
-};
-```
-
-### JSON (for tooling, build scripts, AI)
-
-```javascript
-import tokens from '@citron-systems/citron-ds/tokens';
-// Flat resolved values: { "inkblot.color.accent.citron.500": "#c4a030", ... }
-```
-
----
-
-## Package Exports
-
-| Import path | Contents |
-|-------------|----------|
-| `@citron-systems/citron-ds` | ESM JS tokens (default) |
-| `@citron-systems/citron-ds/css` | CSS variables (`:root`) |
-| `@citron-systems/citron-ds/scss` | SCSS variables |
-| `@citron-systems/citron-ds/tokens` | Flat JSON (resolved values) |
-| `@citron-systems/citron-ds/ai-reference` | AI agent reference (token map, patterns, rules) |
-
----
-
-## Principles
-
-- **Radical Clarity** — One correct interpretation per rule. No ambiguity.
-- **Composable Independence** — Every component is self-contained and works in isolation.
-- **Universal Access** — WCAG AAA. 7:1 contrast. 44px touch targets. Full keyboard nav.
-- **AI-First** — Every token, component, and rule is machine-parseable JSON.
-- **Deliberate Restraint** — Minimum visual complexity. Every element earns its place.
-
----
-
-## Color Modes
-
-Light mode is default. Dark mode activates via:
-
-- `[data-theme="dark"]` on a parent element, or
-- `prefers-color-scheme: dark` (system preference)
-
----
-
-## For AI Agents
-
-**Primary reference** (include in context): `@citron-systems/citron-ds/ai-reference`
-
-- CSS variable map for all semantic tokens
-- Composite patterns (form, card, modal, table, list item)
-- Breakpoints, grid, easing (in CSS format)
-- Icon semantics, CSS snippets, component spacing
-- Validation and ARIA patterns
-
-**Rule**: Always use semantic tokens (`var(--inkblot-semantic-color-*)`), never primitives.
-
----
-
-## Standards
-
-- **Tokens**: [W3C Design Tokens Community Group](https://www.designtokens.org/)
-- **Build**: [Style Dictionary](https://styledictionary.com/) v4
-- **Accessibility**: WCAG 2.2 AAA
-- **Contrast**: 7:1 normal text, 4.5:1 large text, 3:1 UI components
-
----
-
-## Development
-
-```bash
-git clone https://github.com/GHDryanovski19/inkblot-studio-design-tokens.git
-cd inkblot-studio-design-tokens
-npm install
-npm run build
-npm run dev        # Live preview at localhost:5173
-```
-
----
-
-## License
-
-MIT © Inkblot Studio
+<div align="center">
+
+<img src="assets/brand/readme-hero.svg" width="100%" alt="Citron Design System — mascot and wordmark on citron-toned dark background" />
+
+<br />
+
+[![npm](https://img.shields.io/npm/v/@citron-systems/citron-ds?style=flat-square&logo=npm&logoColor=white&color=c4a030)](https://www.npmjs.com/package/@citron-systems/citron-ds)
+[![License: MIT](https://img.shields.io/badge/License-MIT-c4a030?style=flat-square)](https://opensource.org/licenses/MIT)
+[![GitHub](https://img.shields.io/badge/repo-Inkblot--Studio%2Fcitron--ds-1a1814?style=flat-square&logo=github&logoColor=f5f0e6)](https://github.com/Inkblot-Studio/citron-ds)
+
+**Citron** — Apple-inspired, accessible, AI-ready design tokens. Warmly minimal, quietly distinctive.
+
+[Repository](https://github.com/Inkblot-Studio/citron-ds) · [npm package](https://www.npmjs.com/package/@citron-systems/citron-ds)
+
+</div>
+
+---
+
+## Install
+
+```bash
+npm install @citron-systems/citron-ds
+```
+
+### CDN (no build step)
+
+```html
+<link rel="stylesheet" href="https://unpkg.com/@citron-systems/citron-ds/dist/css/inkblot-variables.css">
+```
+
+---
+
+## Quick Start
+
+### CSS (recommended)
+
+```css
+@import '@citron-systems/citron-ds/css';
+
+.button {
+  background: var(--inkblot-semantic-color-interactive-primary);
+  color: var(--inkblot-semantic-color-text-inverse);
+  padding: var(--inkblot-spacing-3) var(--inkblot-spacing-6);
+  border-radius: var(--inkblot-radius-lg);
+  font-weight: var(--inkblot-typography-font-weight-medium);
+  min-height: var(--inkblot-size-touch-target-min);
+  transition: all var(--inkblot-duration-fast) var(--inkblot-easing-default);
+}
+```
+
+### SCSS
+
+```scss
+@use '@citron-systems/citron-ds/scss' as *;
+
+.card {
+  background: var(--inkblot-semantic-color-background-secondary);
+  border: 1px solid var(--inkblot-semantic-color-border-default);
+  border-radius: var(--inkblot-radius-xl);
+  padding: var(--inkblot-spacing-6);
+}
+```
+
+### JavaScript / ESM
+
+```javascript
+import {
+  InkblotColorAccentCitron500,
+  InkblotSpacing4,
+  InkblotRadiusLg,
+} from '@citron-systems/citron-ds';
+
+// Use in JS-driven styling (e.g. React inline, Canvas, etc.)
+const styles = {
+  backgroundColor: InkblotColorAccentCitron500,
+  padding: InkblotSpacing4,
+  borderRadius: InkblotRadiusLg,
+};
+```
+
+### JSON (for tooling, build scripts, AI)
+
+```javascript
+import tokens from '@citron-systems/citron-ds/tokens';
+// Flat resolved values: { "inkblot.color.accent.citron.500": "#c4a030", ... }
+```
+
+---
+
+## Package exports
+
+| Import path | Contents |
+|-------------|----------|
+| `@citron-systems/citron-ds` | ESM JS tokens (default) |
+| `@citron-systems/citron-ds/css` | CSS variables (`:root`) |
+| `@citron-systems/citron-ds/scss` | SCSS variables |
+| `@citron-systems/citron-ds/tokens` | Flat JSON (resolved values) |
+| `@citron-systems/citron-ds/ai-reference` | AI agent reference (token map, patterns, rules) |
+| `@citron-systems/citron-ds/brand/citron-mascot.svg` | Citron mascot (full color; optional `--citron-mascot-fill`) |
+| `@citron-systems/citron-ds/brand/citron-mascot-mono.svg` | Mascot lockup (`currentColor`) |
+| `@citron-systems/citron-ds/bundle` | Bundle entry (`dist/bundle/README.md`) |
+| `@citron-systems/citron-ds/bundle/*` | Resolved tokens, CSS/SCSS bundles, system JSON, etc. |
+| `@citron-systems/citron-ds/preview/mascot.html` | Static mascot preview page |
+
+---
+
+## Brand assets
+
+Source SVGs live in `assets/brand/`; `npm run build` copies them into `dist/brand/` for publishing. Import from the package as in the table above, or copy from `dist/brand/` in a checkout.
+
+| File | Use |
+|------|-----|
+| `citron-mascot.svg` | Full-color mark (`#c4a030` citron **500**) |
+| `citron-mascot-mono.svg` | Single-color / `currentColor` lockups |
+| `readme-hero.svg` | README banner (warm dark + citron accent **900→950**) |
+
+**GitHub (maintainers):** Set the repository **Social preview** (Settings → General) to a **1280×640** image exported from `readme-hero.svg` (or a wider crop). Use `citron-mascot-mono.svg` for the repo or org avatar so the mark stays clear at small sizes.
+
+---
+
+## CLI
+
+The **citron-mascot** binary prints the ASCII Citron mascot (with a short color animation in supported terminals).
+
+From a project that already depends on this package:
+
+```bash
+npx citron-mascot
+```
+
+One-off without adding a dependency:
+
+```bash
+npx --package=@citron-systems/citron-ds citron-mascot
+```
+
+---
+
+## Principles
+
+- **Radical Clarity** — One correct interpretation per rule. No ambiguity.
+- **Composable Independence** — Every component is self-contained and works in isolation.
+- **Universal Access** — WCAG AAA. 7:1 contrast. 44px touch targets. Full keyboard nav.
+- **AI-First** — Every token, component, and rule is machine-parseable JSON.
+- **Deliberate Restraint** — Minimum visual complexity. Every element earns its place.
+
+---
+
+## Color modes
+
+Light mode is default. Dark mode activates via:
+
+- `[data-theme="dark"]` on a parent element, or
+- `prefers-color-scheme: dark` (system preference)
+
+---
+
+## For AI agents
+
+**Primary reference** (include in context): `@citron-systems/citron-ds/ai-reference`
+
+- CSS variable map for all semantic tokens
+- Composite patterns (form, card, modal, table, list item)
+- Breakpoints, grid, easing (in CSS format)
+- Icon semantics, CSS snippets, component spacing
+- Validation and ARIA patterns
+
+**Rule**: Always use semantic tokens (`var(--inkblot-semantic-color-*)`), never primitives.
+
+---
+
+## Standards
+
+- **Tokens**: [W3C Design Tokens Community Group](https://www.designtokens.org/)
+- **Build**: [Style Dictionary](https://styledictionary.com/) v4
+- **Accessibility**: WCAG 2.2 AAA
+- **Contrast**: 7:1 normal text, 4.5:1 large text, 3:1 UI components
+
+---
+
+## Development
+
+```bash
+git clone https://github.com/Inkblot-Studio/citron-ds.git
+cd citron-ds
+npm install
+npm run build
+npm run dev        # Live preview at localhost:5173
+```
+
+- **`npm run build`** — Style Dictionary outputs plus copy steps for brand assets, mascot preview, and desktop bundle (`dist/`).
+- **`prepublishOnly`** runs `npm run build` before `npm publish`.
+
+### Publish note (maintainers)
+
+If you publish with **npm provenance** from GitHub Actions, `package.json` **`repository.url`** must point at the **same** GitHub repository as the workflow (otherwise the registry returns `422` provenance validation errors). Run `npm pkg fix` if npm warns about normalized fields during publish.
+
+---
+
+## Deploy preview to Vercel
+
+1. Push to GitHub and [import the repo](https://vercel.com/new) in Vercel.
+2. Vercel will auto-detect the build from `vercel.json`.
+3. Deploy — the preview site will be live.
+
+Or deploy from the CLI:
+
+```bash
+npm install -g vercel
+npm run build:deploy
+vercel --prod
+```
+
+---
+
+## License
+
+MIT © Inkblot Studio

package/cli/citron-mascot.mjs

@@ -0,0 +1,117 @@
+#!/usr/bin/env node
+import { readFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const pkgPath = join(__dirname, '..', 'package.json');
+const version = JSON.parse(readFileSync(pkgPath, 'utf8')).version ?? '0.0.0';
+
+const CITRON = '\x1b[38;2;196;160;48m';
+const DIM = '\x1b[2m';
+const RESET = '\x1b[0m';
+
+/**
+ * Compact ASCII: small pause eyes + stepped block smile (diagonal “wings”, solid base only).
+ * No extra rows that cross the mouth — avoids a busy / intersecting look. All lines = CANVAS_W.
+ */
+export const MASCOT_CANVAS_W = 28;
+
+export const SMILE_FRAMES = [
+  [
+    '',
+    '',
+    '',
+    '            ██  ██           ',
+    '            ██  ██           ',
+    '      ██              ██      ',
+    '        ██          ██        ',
+    '          ██████████         ',
+    '',
+    '           Citron           ',
+    '',
+  ],
+  [
+    '',
+    '',
+    '',
+    '           ██  ██           ',
+    '           ██  ██           ',
+    '',
+    '    ██                ██    ',
+    '      ██            ██      ',
+    '       ██████████           ',
+    '',
+    '           Citron           ',
+    '',
+  ],
+];
+
+const ASCII = SMILE_FRAMES[0];
+
+function usage() {
+  return `citron-mascot — Citron mascot in the terminal (${version})
+
+Usage:
+  citron-mascot [options]
+  npm run mascot   (in this repo)
+  npx --package @citron-systems/citron-ds citron-mascot
+
+Options:
+  --animate    Alternate smile frames a few times (TTY: clears screen between frames)
+  --no-color   Plain text (also respects NO_COLOR=1)
+  --help, -h   Show this message
+
+Browser preview (no terminal): open dist/preview/mascot.html, or after npm install:
+  node_modules/@citron-systems/citron-ds/dist/preview/mascot.html
+`;
+}
+
+function printMascot(lines, noColor) {
+  for (const line of lines) {
+    if (line === '' || noColor) {
+      process.stdout.write(line + '\n');
+      continue;
+    }
+    if (line.includes('Citron')) {
+      process.stdout.write(DIM + line + RESET + '\n');
+      continue;
+    }
+    process.stdout.write(CITRON + line + RESET + '\n');
+  }
+}
+
+async function main() {
+  const argv = process.argv.slice(2);
+  if (argv.includes('--help') || argv.includes('-h')) {
+    process.stdout.write(usage());
+    process.exit(0);
+  }
+
+  const noColor =
+    argv.includes('--no-color') ||
+    process.env.NO_COLOR === '1' ||
+    process.env.NO_COLOR === 'true' ||
+    !process.stdout.isTTY;
+
+  if (argv.includes('--animate')) {
+    const cycles = SMILE_FRAMES.length * 5;
+    for (let i = 0; i < cycles; i++) {
+      if (process.stdout.isTTY && !noColor) {
+        process.stdout.write('\x1b[2J\x1b[H');
+      }
+      printMascot(SMILE_FRAMES[i % SMILE_FRAMES.length], noColor);
+      if (i < cycles - 1) {
+        await new Promise((r) => setTimeout(r, 380));
+      }
+    }
+    return;
+  }
+
+  printMascot(ASCII, noColor);
+}
+
+main().catch((err) => {
+  process.stderr.write(String(err) + '\n');
+  process.exit(1);
+});