fractalstyler2 0.0.1 → 0.1.0

package/README.md

@@ -3,62 +3,35 @@
 A fractal-composition styling system for SvelteKit. **Every style unit is a SASS
 mixin ("a fractal"), and components and layouts are recipes of smaller fractals.**
 
-This is a standalone package with no relationship to any earlier styler. The
-product is framework-agnostic SASS surfaced through a SvelteKit library; the JS
-runtime is just a tiny mode helper.
+Use it either as a **shadcn-style scaffolder** (copying editable SASS into your project's `src/lib/styles`) or as a **direct package dependency**.
 
-## The idea
+---
 
-A fractal is a mixin: a tiny reusable styling decision that composes other
-fractals. They form four self-similar tiers — each tier is "a recipe of the one
-below":
-
-| Tier | What | Examples |
-| --- | --- | --- |
-| **Config** | scales-as-data + resolvers | `space()`, `radius()`, `align()`, `$breakpoints` |
-| **Atoms** | one decision each | `+box` `+row` `+gap` `+pad` `+border` `+radius` `+bg` `+ink` `+type` `+sticky` |
-| **Molecules** | graphs of atoms | `+stack` `+cluster` `+cover` `+frame` `+surface` `+cols` `+auto-grid` |
-| **Components / Layouts** | graphs of molecules | `.card` `.button` · `.grid-3` `.hero` `.holy-grail` `.docs` `.app-shell` |
+## Quickstart (shadcn-style Scaffolding)
 
-The one idea that makes it click:
-
-> **A utility class and a semantic component are the same fractal, consumed two ways.**
-> `.gap-m { +gap(m) }` binds the fractal to markup; `.hero { +cover; +stack(m) }`
-> composes it into a component. One vocabulary, you pick where each is used.
-
-## Install
+Scaffold the complete, customizable SASS design system directly into your project's `src/lib/styles`:
 
 ```bash
-pnpm add fractalstyler2
-```
+# Scaffold into src/lib/styles
+npx fractalstyler2 init
 
-## Use
+# Or using pnpm
+pnpm dlx fractalstyler2 init
+```
 
-**1 — Emit the ready-made stylesheet** (tokens, base reset, utility classes,
-blocks, layouts). Import once, globally (e.g. in your root `+layout.svelte`):
+### Next Steps in Your Project
 
+**1. Import the stylesheet in your root `+layout.svelte`:**
 ```svelte
 <script>
-	import 'fractalstyler2/styles';
+	import '$lib/styles/index.sass';
 </script>
 ```
 
-Then write thin, semantic markup:
-
-```svelte
-<div class="grid-3">
-	<article class="card"><h3 class="text-lg">Composable</h3></article>
-	<article class="card" data-elevated><h3 class="text-lg">Elevated</h3></article>
-	<article class="card"><h3 class="text-lg">Semantic</h3></article>
-</div>
-```
-
-**2 — Compose your own components from the fractals.** Import the pure API
-(emits nothing until called) inside any component's SASS:
-
+**2. Compose your components using the fractals:**
 ```svelte
 <style lang="sass">
-	@use 'fractalstyler2/fractals' as *
+	@use '$lib/styles/fractals' as *
 
 	.pricing-card
 		+surface(surface, l, 16, md)   // bg + border + radius + pad + shadow
@@ -67,48 +40,104 @@ Then write thin, semantic markup:
 </style>
 ```
 
-Values prefer the finite token scale and fall back to raw units in the same
-call: `+gap(m)` → `var(--space-m)`, `+gap(16)` → `16px`. No JIT class explosion.
+---
+
+## Alternative: Direct Package Dependency
 
-## What ships
+If you prefer importing from `node_modules` instead of scaffolding local files:
 
+```bash
+npm install fractalstyler2
+# or
+pnpm add fractalstyler2
 ```
-fractalstyler2/
-├─ styles         → the full emitted stylesheet (import 'fractalstyler2/styles')
-├─ fractals       → the mixin/function API (@use 'fractalstyler2/fractals' as *)
-├─ tokens         → just the custom properties (@use 'fractalstyler2/tokens')
-└─ (default)      → { version, setMode, toggleMode }
+
+Your app also needs `sass`:
+```bash
+npm install -D sass
+# or
+pnpm add -D sass
 ```
 
-Source layout: `src/lib/fractals/` (config, tokens, base, responsive, atoms,
-molecules, utilities), `src/lib/components/` (blocks, layouts),
-`src/lib/styles/` (the emit entry).
+### Use from `node_modules`:
 
-## Color mode
+```svelte
+<script>
+	import 'fractalstyler2/styles';
+</script>
 
-Light is the marker-free default (SSR-safe). Dark comes from
-`prefers-color-scheme` and from an explicit `data-mode="dark"` on `<html>`:
+<style lang="sass">
+	@use 'fractalstyler2/fractals' as *
+
+	.card
+		+surface(surface, s, 12)
+		+stack(s)
+</style>
+```
+
+---
+
+## The Model
+
+A fractal is a mixin: a tiny reusable styling decision that composes other
+fractals. They form four self-similar tiers — each tier is "a recipe of the one
+below":
+
+| Tier | What | Examples |
+| --- | --- | --- |
+| **Config** | scales-as-data + resolvers | `space()`, `radius()`, `align()`, `$breakpoints` |
+| **Atoms** | one decision each | `+box` `+row` `+gap` `+pad` `+border` `+radius` `+bg` `+ink` `+type` `+sticky` |
+| **Molecules** | graphs of atoms | `+stack` `+cluster` `+cover` `+frame` `+surface` `+cols` `+auto-grid` |
+| **Components / Layouts** | graphs of molecules | `.card` `.button` · `.grid-3` `.hero` `.holy-grail` `.docs` `.app-shell` |
+
+The one idea that makes it click:
+
+> **A utility class and a semantic component are the same fractal, consumed two ways.**
+> `.gap-m { +gap(m) }` binds the fractal to markup; `.hero { +cover; +stack(m) }`
+> composes it into a component. One vocabulary, you pick where each is used.
+
+---
+
+## Color Mode
+
+Light is the marker-free default (SSR-safe). Dark comes from `prefers-color-scheme` and from an explicit `data-mode="dark"` on `<html>`:
 
 ```js
 import { toggleMode, setMode } from 'fractalstyler2';
 toggleMode();       // flip light/dark
-setMode('dark');    // force
+setMode('dark');    // force mode
 ```
 
-## Included layouts
+---
+
+## CLI & MCP Server
+
+### Scaffolder CLI
+```bash
+fractalstyler2 init [dest] [options]
+
+Arguments:
+  dest          Target directory for SASS partials (default: src/lib/styles)
 
-`.grid-3` (responsive 1→2→3), `.card-grid` (intrinsic auto-fit), `.hero`,
-`.holy-grail`, `.docs`, `.app-shell` — each a few fractal calls in
-`src/lib/components/_layouts.sass`.
+Options:
+  -f, --force   Overwrite files if they already exist
+  -h, --help    Show help message
+```
 
-## Develop
+### Model Context Protocol (MCP) Server
+Use `fractalstyler2` directly with AI canvas tools (e.g. **OpenDesign**, **Pencil**), IDEs (**Cursor**, **Antigravity**), and assistants (**Claude Desktop**):
 
 ```bash
-pnpm install
-pnpm dev          # demo showcase at /
-pnpm run prepack  # build the distributable package into dist/
+# Start MCP server over stdio
+npx fractalstyler2-mcp
+# or
+npx fractalstyler2 mcp
 ```
 
+Exposes tools to compile fractals to live CSS, snap arbitrary canvas values to Utopia tokens, generate Svelte 5 + SASS components, and lint recipes. See [docs/10-mcp-server.md](docs/10-mcp-server.md) for configuration details.
+
+---
+
 ## License
 
 MIT

package/dist/cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/cli.js

@@ -0,0 +1,113 @@
+#!/usr/bin/env node
+import { existsSync, mkdirSync, readdirSync, copyFileSync } from 'node:fs';
+import { dirname, join, resolve, relative } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import process from 'node:process';
+function getTemplatesDir() {
+    const HERE = dirname(fileURLToPath(import.meta.url));
+    const candidates = [
+        join(HERE, '..', 'templates'),
+        join(HERE, '..', '..', 'templates'),
+        join(HERE, 'templates')
+    ];
+    for (const candidate of candidates) {
+        if (existsSync(candidate))
+            return candidate;
+    }
+    throw new Error(`Templates directory not found. Searched in: ${candidates.join(', ')}`);
+}
+function printUsage() {
+    console.log(`
+fractalstyler2 — SASS fractal design system scaffolder & MCP server
+
+Usage:
+  npx fractalstyler2 init [dest] [options]
+  npx fractalstyler2 mcp
+
+Commands:
+  init [dest]   Scaffold SASS partials into target directory (default: src/lib/styles)
+  mcp           Start the Model Context Protocol (MCP) server for OpenDesign, Claude, etc.
+
+Options:
+  -f, --force   Overwrite files if they already exist
+  -h, --help    Show this help message
+
+Examples:
+  npx fractalstyler2 init
+  npx fractalstyler2 init src/lib/styles --force
+  npx fractalstyler2 mcp
+`);
+}
+function init(destArg, force) {
+    const dest = destArg ?? 'src/lib/styles';
+    const cwd = process.cwd();
+    const targetDir = resolve(cwd, dest);
+    console.log(`\n▲ fractalstyler2 init\n`);
+    console.log(`Scaffolding SASS design system into: ${dest}\n`);
+    mkdirSync(targetDir, { recursive: true });
+    const templatesDir = getTemplatesDir();
+    const files = readdirSync(templatesDir).filter((f) => f.endsWith('.sass'));
+    let created = 0;
+    let overwritten = 0;
+    let skipped = 0;
+    for (const file of files) {
+        const targetFile = join(targetDir, file);
+        const relPath = relative(cwd, targetFile);
+        if (existsSync(targetFile)) {
+            if (force) {
+                copyFileSync(join(templatesDir, file), targetFile);
+                console.log(`  \x1b[33moverwrite\x1b[0m ${relPath}`);
+                overwritten++;
+            }
+            else {
+                console.log(`  \x1b[90mskip\x1b[0m      ${relPath} (already exists, use --force to overwrite)`);
+                skipped++;
+            }
+        }
+        else {
+            copyFileSync(join(templatesDir, file), targetFile);
+            console.log(`  \x1b[32mcreate\x1b[0m    ${relPath}`);
+            created++;
+        }
+    }
+    console.log(`\nDone: ${created} created, ${overwritten} overwritten, ${skipped} skipped.\n`);
+    const importPath = dest === 'src/lib/styles' ? '$lib/styles/index.sass' : `${dest}/index.sass`;
+    const fractalsPath = dest === 'src/lib/styles' ? '$lib/styles/fractals' : `${dest}/fractals`;
+    console.log(`Next steps:
+  1. Import the stylesheet once globally (e.g. in src/routes/+layout.svelte):
+       <script>
+         import '${importPath}';
+       </script>
+
+  2. Compose your components with fractal mixins:
+       <style lang="sass">
+         @use '${fractalsPath}' as *
+
+         .card
+           +surface(surface, s, 12)
+           +stack(s)
+       </style>
+`);
+}
+const args = process.argv.slice(2);
+const showHelp = args.includes('-h') || args.includes('--help');
+const force = args.includes('-f') || args.includes('--force');
+const positional = args.filter((a) => !a.startsWith('-'));
+const command = positional[0];
+if (showHelp || (command && !['init', 'mcp'].includes(command))) {
+    if (command && !['init', 'mcp'].includes(command)) {
+        console.error(`Unknown command: ${command}`);
+    }
+    printUsage();
+    process.exit(command && !['init', 'mcp'].includes(command) ? 1 : 0);
+}
+else if (command === 'mcp') {
+    import('./mcp/server.js');
+}
+else if (command === 'init') {
+    init(positional[1], force);
+}
+else {
+    // Default to init if no subcommand given (e.g., `npx fractalstyler2`)
+    init(positional[0], force);
+}

package/dist/mcp/server.d.ts

@@ -0,0 +1,7 @@
+#!/usr/bin/env node
+/**
+ * fractalstyler2 MCP Server
+ * Model Context Protocol server exposing design tokens, SASS mixin compilation,
+ * token snapping, component generation, and linting for OpenDesign, Claude Desktop, Cursor, etc.
+ */
+export {};