fractalstyler2 0.1.0 → 0.3.0

package/README.md

@@ -1,15 +1,14 @@
 # fractalstyler2
 
-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.**
+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.**
 
-Use it either as a **shadcn-style scaffolder** (copying editable SASS into your project's `src/lib/styles`) or as a **direct package dependency**.
+Use it either as a **shadcn-style scaffolder** (copying editable SASS directly into your project's `src/lib/styles`) or as a **direct package dependency**.
 
 ---
 
 ## Quickstart (shadcn-style Scaffolding)
 
-Scaffold the complete, customizable SASS design system directly into your project's `src/lib/styles`:
+Scaffold the complete, customizable SASS design system directly into your project:
 
 ```bash
 # Scaffold into src/lib/styles
@@ -21,22 +20,27 @@ pnpm dlx fractalstyler2 init
 
 ### Next Steps in Your Project
 
-**1. Import the stylesheet in your root `+layout.svelte`:**
+**1. Import the stylesheet once globally in your root `src/routes/+layout.svelte`:**
 ```svelte
 <script>
 	import '$lib/styles/index.sass';
 </script>
 ```
 
-**2. Compose your components using the fractals:**
+**2. Compose your components using the pure mixin barrel:**
 ```svelte
+<div class="pricing-card">
+	<span class="badge" data-status="released">Pro Plan</span>
+	<h3>$29/mo</h3>
+	<p>Full access to all fractal components and layouts.</p>
+</div>
+
 <style lang="sass">
 	@use '$lib/styles/fractals' as *
 
 	.pricing-card
-		+surface(surface, l, 16, md)   // bg + border + radius + pad + shadow
-		+stack(m, center)              // flex-column + gap + centered
-		text-align: center
+		+surface(surface, m, 6, md)    // bg + border + radius(6px) + padding + shadow
+		+stack(s, start)               // flex-column + gap(s) + top-anchored flow
 </style>
 ```
 
@@ -47,15 +51,7 @@ pnpm dlx fractalstyler2 init
 If you prefer importing from `node_modules` instead of scaffolding local files:
 
 ```bash
-npm install fractalstyler2
-# or
 pnpm add fractalstyler2
-```
-
-Your app also needs `sass`:
-```bash
-npm install -D sass
-# or
 pnpm add -D sass
 ```
 
@@ -70,37 +66,54 @@ pnpm add -D sass
 	@use 'fractalstyler2/fractals' as *
 
 	.card
-		+surface(surface, s, 12)
+		+surface(surface, s, 6)
 		+stack(s)
 </style>
 ```
 
 ---
 
-## The Model
+## The Physical Scale Hierarchy
+
+The design system files in `src/lib/styles/` are numbered sequentially from indivisible math to page layouts:
 
-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":
+```
+index.sass             ──► Master Entrypoint (Forwards fractals + loads CSS cascade)
+_fractals.sass         ──► Pure Mixin Barrel (Emits 0 bytes CSS)
+
+── Phase 1: Pure Functions & Math (Zero CSS Emitted) ─────────────────────────
+_00_tokens.sass        ──► Raw CSS custom properties on :root & theme modes
+_01_config.sass        ──► Scales, maps, resolvers (space, radius, surface, ink)
+_02_fonts.sass         ──► Local @font-face declarations
+_03_responsive.sass    ──► Breakpoint helpers (+at, +below, +between)
+_04_atoms.sass         ──► Single-decision primitives (+box, +row, +bg, +ink, +pad, +gap)
+_05_molecules.sass     ──► Compositions of atoms (+stack, +cluster, +surface, +cols)
+_06_recipes.sass       ──► Macro component archetypes (=control, =select, =card, =partition)
+
+── Phase 2: CSS Cascade Emitters (Loaded once globally by index.sass) ─────────
+_07_base.sass          ──► Global HTML element resets
+_08_blocks.sass        ──► Semantic component classes (.surface, .panel, .select, .badge)
+_09_utilities.sass     ──► 1:1 atomic markup projections (.pad-*, .pad-top-*, .gap-*, .hide-desktop)
+_10_layouts.sass       ──► Page layout templates (.docs, .card-grid, .hero, .holy-grail)
+_11_own.sass           ──► Bespoke local project overrides
+```
 
-| 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:
+## The Strict 21-Token Contract
 
-> **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.
+All themes and surface colors resolve from the 21 variables defined in `_00_tokens.sass`:
+
+- **Surfaces**: `--bg`, `--bg-surface`, `--bg-raised`, `--bg-panel`, `--bg-footer`, `--bg-popover`, `--bg-dialog`, `--bg-terminal`, `--bg-input`, `--bg-canvas`
+- **Text & Ink**: `--text-primary`, `--text-secondary`, `--text-muted`, `--text-inverse`
+- **States & Feedback**: `--state-hover`, `--state-hover-subtle`, `--state-selected`
+- **Borders & Accents**: `--border`, `--border-subtle`, `--theme-color`, `--theme-color-alt` *(aliased to `--theme`)*
 
 ---
 
 ## 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>`:
+Light is the marker-free default (SSR-safe). Dark mode is activated via `prefers-color-scheme: dark` or explicitly via `data-mode="dark"` on `<html>`:
 
 ```js
 import { toggleMode, setMode } from 'fractalstyler2';
@@ -110,31 +123,20 @@ setMode('dark');    // force mode
 
 ---
 
-## CLI & MCP Server
-
-### Scaffolder CLI
-```bash
-fractalstyler2 init [dest] [options]
-
-Arguments:
-  dest          Target directory for SASS partials (default: src/lib/styles)
-
-Options:
-  -f, --force   Overwrite files if they already exist
-  -h, --help    Show help message
-```
-
-### Model Context Protocol (MCP) Server
-Use `fractalstyler2` directly with AI canvas tools (e.g. **OpenDesign**, **Pencil**), IDEs (**Cursor**, **Antigravity**), and assistants (**Claude Desktop**):
-
-```bash
-# 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.
+## Documentation Index
+
+| Guide | Description |
+|---|---|
+| [01. Philosophy](docs/01-philosophy.md) | The fractal model, self-similarity, and dual consumption |
+| [02. Structure](docs/02-structure.md) | File anatomy, the 12-file numbered scale, and cascade order |
+| [03. Getting Started](docs/03-getting-started.md) | Scaffolding, imports, and wiring into SvelteKit |
+| [04. Fractals Reference](docs/04-fractals-reference.md) | Comprehensive reference for every atom and molecule mixin |
+| [05. Tokens & Theming](docs/05-tokens-and-theming.md) | Fluid scales, the 21-variable contract, and dark mode |
+| [06. Utilities Reference](docs/06-utilities.md) | Generated atomic classes, directional padding, and visibility |
+| [07. Components & Layouts](docs/07-components-and-layouts.md) | Shipped blocks, cards, and page layout templates |
+| [08. Recipes & Patterns](docs/08-recipes.md) | Worked examples: pricing card, responsive docs shell, dialog |
+| [09. Migration from v1](docs/09-migration-from-v1.md) | Upgrading from older unnumbered stylesheets |
+| [DESIGN.md](DESIGN.md) | Golden UI invariants, card containment laws, and defect prevention |
 
 ---
 

package/dist/cli.js

@@ -23,19 +23,24 @@ fractalstyler2 — SASS fractal design system scaffolder & MCP server
 Usage:
   npx fractalstyler2 init [dest] [options]
   npx fractalstyler2 mcp
+  npx fractalstyler2 mcp:install
+  npx fractalstyler2 mcp:export [dest]
 
 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.
+  init [dest]         Scaffold SASS partials into target directory (default: src/lib/styles)
+  mcp                 Start the Model Context Protocol (MCP) server for OpenDesign, Claude, etc.
+  mcp:install         Automatically install MCP schemas & config into Antigravity & OpenCode
+  mcp:export [dest]   Export static MCP tool schema JSON files to target directory (default: .mcp)
 
 Options:
-  -f, --force   Overwrite files if they already exist
-  -h, --help    Show this help message
+  -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
+  npx fractalstyler2 mcp:install
+  npx fractalstyler2 mcp:export ~/.gemini/antigravity/mcp/fractalstyler2
 `);
 }
 function init(destArg, force) {
@@ -84,7 +89,7 @@ function init(destArg, force) {
          @use '${fractalsPath}' as *
 
          .card
-           +surface(surface, s, 12)
+           +surface(surface, s, 6)
            +stack(s)
        </style>
 `);
@@ -94,16 +99,49 @@ 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)) {
+const VALID_COMMANDS = ['init', 'mcp', 'mcp:export', 'mcp:install'];
+if (showHelp || (command && !VALID_COMMANDS.includes(command))) {
+    if (command && !VALID_COMMANDS.includes(command)) {
         console.error(`Unknown command: ${command}`);
     }
     printUsage();
-    process.exit(command && !['init', 'mcp'].includes(command) ? 1 : 0);
+    process.exit(command && !VALID_COMMANDS.includes(command) ? 1 : 0);
 }
 else if (command === 'mcp') {
     import('./mcp/server.js');
 }
+else if (command === 'mcp:export') {
+    import('./mcp/export.js').then(({ exportSchemas }) => {
+        const dest = positional[1] || '.mcp/fractalstyler2';
+        const { created, dir } = exportSchemas(dest);
+        console.log(`\n▲ Exported ${created} MCP schema files to: ${dir}\n`);
+    });
+}
+else if (command === 'mcp:install') {
+    import('./mcp/export.js').then(({ installToAntigravity, installToOpenCode }) => {
+        console.log(`\n▲ Installing fractalstyler2 MCP schemas & configuration...\n`);
+        try {
+            const agy = installToAntigravity();
+            console.log(`  \x1b[32m✔\x1b[0m Antigravity MCP schemas: ${agy.dir}`);
+        }
+        catch (e) {
+            console.log(`  \x1b[90m-\x1b[0m Antigravity install skipped (${e.message})`);
+        }
+        try {
+            const oc = installToOpenCode();
+            if (oc.success) {
+                console.log(`  \x1b[32m✔\x1b[0m OpenCode MCP configured: ${oc.configPath}`);
+            }
+            else {
+                console.log(`  \x1b[90m-\x1b[0m OpenCode config not found (skipped)`);
+            }
+        }
+        catch (e) {
+            console.log(`  \x1b[90m-\x1b[0m OpenCode install skipped (${e.message})`);
+        }
+        console.log(`\nDone! fractalstyler2 MCP is ready.\n`);
+    });
+}
 else if (command === 'init') {
     init(positional[1], force);
 }

package/dist/index.d.ts

@@ -1,6 +1,37 @@
-export declare const version = "0.0.1";
+export declare const version = "0.3.0";
 export type Mode = 'light' | 'dark';
 /** Set the color mode by writing the [data-mode] marker on <html>. */
 export declare function setMode(mode: Mode): void;
 /** Toggle between light and dark, returning the new mode. */
 export declare function toggleMode(): Mode;
+export declare const breakpoints: {
+    readonly sm: "640px";
+    readonly md: "768px";
+    readonly lg: "1024px";
+    readonly xl: "1240px";
+};
+export declare const spaceScale: readonly ["3xs", "2xs", "xs", "s", "m", "l", "xl", "2xl", "3xl", "s-l"];
+export declare const typographyScale: readonly ["xs", "sm", "md", "lg", "xl", "2xl", "3xl", "4xl"];
+export declare const radiusSteps: readonly ["0", "2", "3", "4", "6", "8", "12", "16", "24", "full"];
+export declare const surfaceRoles: readonly ["bg", "surface", "raised", "panel", "footer", "popover", "dialog", "terminal", "input", "canvas"];
+export declare const inkRoles: readonly ["primary", "secondary", "muted", "inverse", "theme-color", "theme-color-alt"];
+export declare const tokens: {
+    readonly version: "0.3.0";
+    readonly breakpoints: {
+        readonly sm: "640px";
+        readonly md: "768px";
+        readonly lg: "1024px";
+        readonly xl: "1240px";
+    };
+    readonly spaceScale: readonly ["3xs", "2xs", "xs", "s", "m", "l", "xl", "2xl", "3xl", "s-l"];
+    readonly typographyScale: readonly ["xs", "sm", "md", "lg", "xl", "2xl", "3xl", "4xl"];
+    readonly radiusSteps: readonly ["0", "2", "3", "4", "6", "8", "12", "16", "24", "full"];
+    readonly surfaceRoles: readonly ["bg", "surface", "raised", "panel", "footer", "popover", "dialog", "terminal", "input", "canvas"];
+    readonly inkRoles: readonly ["primary", "secondary", "muted", "inverse", "theme-color", "theme-color-alt"];
+};
+export type Breakpoint = keyof typeof breakpoints;
+export type SpaceStep = (typeof spaceScale)[number];
+export type TypographyStep = (typeof typographyScale)[number];
+export type RadiusStep = (typeof radiusSteps)[number];
+export type SurfaceRole = (typeof surfaceRoles)[number];
+export type InkRole = (typeof inkRoles)[number];

package/dist/index.js

@@ -1,12 +1,11 @@
 // fractalstyler2 — a fractal-composition styling system for SvelteKit.
 //
-// The product is the SASS in ./fractals and ./components, surfaced as:
+// The product is the SASS in ./fractals and ./styles, surfaced as:
 //   import 'fractalstyler2/styles'          // emit the full stylesheet
 //   @use 'fractalstyler2/fractals' as *     // compose your own with the mixins
 //
-// This entry ships only tiny runtime helpers. There is deliberately no CSS-in-JS
-// and no component coupling — the styling layer is framework-agnostic SASS.
-export const version = '0.0.1';
+// This entry ships runtime helpers and token metadata.
+export const version = '0.3.0';
 /** Set the color mode by writing the [data-mode] marker on <html>. */
 export function setMode(mode) {
     if (typeof document === 'undefined')
@@ -20,3 +19,73 @@ export function toggleMode() {
     setMode(next);
     return next;
 }
+// Design Token Metadata
+export const breakpoints = {
+    sm: '640px',
+    md: '768px',
+    lg: '1024px',
+    xl: '1240px'
+};
+export const spaceScale = [
+    '3xs',
+    '2xs',
+    'xs',
+    's',
+    'm',
+    'l',
+    'xl',
+    '2xl',
+    '3xl',
+    's-l'
+];
+export const typographyScale = [
+    'xs',
+    'sm',
+    'md',
+    'lg',
+    'xl',
+    '2xl',
+    '3xl',
+    '4xl'
+];
+export const radiusSteps = [
+    '0',
+    '2',
+    '3',
+    '4',
+    '6',
+    '8',
+    '12',
+    '16',
+    '24',
+    'full'
+];
+export const surfaceRoles = [
+    'bg',
+    'surface',
+    'raised',
+    'panel',
+    'footer',
+    'popover',
+    'dialog',
+    'terminal',
+    'input',
+    'canvas'
+];
+export const inkRoles = [
+    'primary',
+    'secondary',
+    'muted',
+    'inverse',
+    'theme-color',
+    'theme-color-alt'
+];
+export const tokens = {
+    version,
+    breakpoints,
+    spaceScale,
+    typographyScale,
+    radiusSteps,
+    surfaceRoles,
+    inkRoles
+};

package/dist/mcp/export.d.ts

@@ -0,0 +1,13 @@
+export declare function getSchemasDir(): string;
+export declare function exportSchemas(targetDir: string): {
+    created: number;
+    dir: string;
+};
+export declare function installToAntigravity(): {
+    success: boolean;
+    dir: string;
+};
+export declare function installToOpenCode(): {
+    success: boolean;
+    configPath: string;
+};

package/dist/mcp/export.js

@@ -0,0 +1,76 @@
+import { existsSync, mkdirSync, copyFileSync, readdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { dirname, join, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import os from 'node:os';
+export function getSchemasDir() {
+    const HERE = dirname(fileURLToPath(import.meta.url));
+    const candidates = [
+        join(HERE, 'schemas'),
+        join(HERE, '..', 'mcp', 'schemas'),
+        join(HERE, '..', '..', 'src', 'lib', 'mcp', 'schemas'),
+        join(process.cwd(), 'src', 'lib', 'mcp', 'schemas'),
+        join(process.cwd(), 'dist', 'mcp', 'schemas')
+    ];
+    for (const candidate of candidates) {
+        if (existsSync(candidate))
+            return candidate;
+    }
+    throw new Error(`Schemas directory not found. Searched: ${candidates.join(', ')}`);
+}
+export function exportSchemas(targetDir) {
+    const resolvedTarget = resolve(process.cwd(), targetDir);
+    mkdirSync(resolvedTarget, { recursive: true });
+    const schemasDir = getSchemasDir();
+    const files = readdirSync(schemasDir);
+    let created = 0;
+    for (const file of files) {
+        const srcFile = join(schemasDir, file);
+        const destFile = join(resolvedTarget, file);
+        copyFileSync(srcFile, destFile);
+        created++;
+    }
+    return { created, dir: resolvedTarget };
+}
+export function installToAntigravity() {
+    const home = os.homedir();
+    const agyMcpDir = join(home, '.gemini', 'antigravity', 'mcp', 'fractalstyler2');
+    const agyConfigPath = join(home, '.gemini', 'antigravity', 'mcp_config.json');
+    exportSchemas(agyMcpDir);
+    // Update mcp_config.json if it exists or create it
+    let config = { mcpServers: {} };
+    if (existsSync(agyConfigPath)) {
+        try {
+            config = JSON.parse(readFileSync(agyConfigPath, 'utf8'));
+        }
+        catch { }
+    }
+    if (!config.mcpServers)
+        config.mcpServers = {};
+    config.mcpServers.fractalstyler2 = {
+        command: 'node',
+        args: [join(dirname(fileURLToPath(import.meta.url)), 'server.js')],
+        env: {}
+    };
+    writeFileSync(agyConfigPath, JSON.stringify(config, null, 2), 'utf8');
+    return { success: true, dir: agyMcpDir };
+}
+export function installToOpenCode() {
+    const home = os.homedir();
+    const ocConfigPath = join(home, '.config', 'opencode', 'opencode.json');
+    if (existsSync(ocConfigPath)) {
+        try {
+            const config = JSON.parse(readFileSync(ocConfigPath, 'utf8'));
+            if (!config.mcp)
+                config.mcp = {};
+            config.mcp.fractalstyler2 = {
+                type: 'local',
+                command: ['node', join(dirname(fileURLToPath(import.meta.url)), 'server.js')],
+                enabled: true
+            };
+            writeFileSync(ocConfigPath, JSON.stringify(config, null, 2), 'utf8');
+            return { success: true, configPath: ocConfigPath };
+        }
+        catch { }
+    }
+    return { success: false, configPath: ocConfigPath };
+}

package/dist/mcp/schemas/compile_fractals.json

@@ -0,0 +1,20 @@
+{
+  "name": "compile_fractals",
+  "description": "Compiles indented SASS fractal mixins into CSS. Useful for live preview in OpenDesign, web apps, or verifying style output.",
+  "parameters": {
+    "type": "object",
+    "properties": {
+      "sassCode": {
+        "type": "string",
+        "description": "Indented SASS code. Can use any fractal mixin (+surface, +stack, +gap, etc.)."
+      },
+      "className": {
+        "type": "string",
+        "description": "Optional CSS class name to wrap the mixins under (e.g. 'preview-card'). Defaults to 'element'."
+      }
+    },
+    "required": [
+      "sassCode"
+    ]
+  }
+}

package/dist/mcp/schemas/css_to_fractals.json

@@ -0,0 +1,16 @@
+{
+  "name": "css_to_fractals",
+  "description": "Converts raw CSS declarations (from Figma/OpenDesign inspection) into idiomatic fractalstyler2 SASS mixin recipes (+surface, +stack, +cluster, etc.).",
+  "parameters": {
+    "type": "object",
+    "properties": {
+      "css": {
+        "type": "string",
+        "description": "Raw CSS block or declaration lines"
+      }
+    },
+    "required": [
+      "css"
+    ]
+  }
+}

package/dist/mcp/schemas/generate_component.json

@@ -0,0 +1,45 @@
+{
+  "name": "generate_component",
+  "description": "Generates a production-ready Svelte 5 component with runes and scoped SASS fractal mixins.",
+  "parameters": {
+    "type": "object",
+    "properties": {
+      "name": {
+        "type": "string",
+        "description": "Component name (e.g. PricingCard, UserAvatar, HeroBanner)"
+      },
+      "type": {
+        "type": "string",
+        "enum": [
+          "card",
+          "panel",
+          "button",
+          "badge",
+          "modal",
+          "hero",
+          "nav",
+          "custom"
+        ],
+        "description": "Type of component recipe."
+      },
+      "elevation": {
+        "type": "string",
+        "enum": [
+          "none",
+          "sm",
+          "md",
+          "lg"
+        ],
+        "description": "Surface elevation."
+      },
+      "description": {
+        "type": "string",
+        "description": "Detailed description of component purpose and props."
+      }
+    },
+    "required": [
+      "name",
+      "type"
+    ]
+  }
+}

package/dist/mcp/schemas/get_design_tokens.json

@@ -0,0 +1,23 @@
+{
+  "name": "get_design_tokens",
+  "description": "Returns the complete structured JSON design tokens (fluid Utopia space scales, typography, radii, shadows, surfaces, ink colors, breakpoints).",
+  "parameters": {
+    "type": "object",
+    "properties": {
+      "category": {
+        "type": "string",
+        "enum": [
+          "all",
+          "space",
+          "typography",
+          "radius",
+          "shadows",
+          "surfaces",
+          "ink",
+          "breakpoints"
+        ],
+        "description": "Optional category filter (all, space, typography, radius, shadows, surfaces, ink, breakpoints). Defaults to 'all'."
+      }
+    }
+  }
+}

package/dist/mcp/schemas/instructions.md

@@ -0,0 +1,18 @@
+# fractalstyler2 MCP Server
+
+The fractalstyler2 MCP server provides tools to inspect design tokens, snap canvas pixel values to Utopia tokens, compile indented SASS fractal mixins to live CSS, generate Svelte 5 runes components with scoped SASS, and lint style recipes.
+
+## Available Tools:
+1. **compile_fractals**: Compiles indented SASS fractal mixins (+surface, +stack, +gap, etc.) into live CSS.
+2. **get_design_tokens**: Returns structured JSON for fluid space scale (3xs..3xl), typography, radii, shadows, surfaces, and ink roles.
+3. **snap_to_tokens**: Snaps raw pixel measurements (gap, padding, radius, fontSize) from canvas/inspection to the closest design tokens.
+4. **css_to_fractals**: Converts raw CSS declarations into idiomatic fractal mixin recipes.
+5. **generate_component**: Generates complete Svelte 5 components with runes and scoped SASS fractals.
+6. **validate_recipe**: Lints code against golden rules (flags legacy v1 classes like gap8/pad16, hardcoded pixels, modifier classes).
+7. **list_fractals**: Catalogs all atom & molecule mixins with signatures.
+
+## Golden Rules:
+- Never hardcode values that tokens cover; use `+gap(m)`, `+radius(6)`, `+bg(surface)`.
+- Compose fractals (`+surface`, `+stack`, `+cluster`); write raw CSS only for unique lines.
+- Express component state on `data-*` / `aria-*` attributes, never modifier classes.
+- No legacy v1 classes (e.g. `gap8`, `pad16`, `w100`, `.stack` in markup).

package/dist/mcp/schemas/list_fractals.json

@@ -0,0 +1,20 @@
+{
+  "name": "list_fractals",
+  "description": "Returns the catalog of all available atom & molecule mixins and layout templates with their signatures and descriptions.",
+  "parameters": {
+    "type": "object",
+    "properties": {
+      "tier": {
+        "type": "string",
+        "enum": [
+          "all",
+          "atoms",
+          "molecules",
+          "recipes",
+          "layouts"
+        ],
+        "description": "Filter by fractal tier (all, atoms, molecules, recipes, layouts)."
+      }
+    }
+  }
+}