fractalstyler2 0.0.1 → 0.0.2

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":
+## Quickstart (shadcn-style Scaffolding)
 
-| 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.
-
-## 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,91 @@ 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
+```
 
+Your app also needs `sass`:
+```bash
+npm install -D sass
+# or
+pnpm add -D sass
 ```
-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 }
+
+### Use from `node_modules`:
+
+```svelte
+<script>
+	import 'fractalstyler2/styles';
+</script>
+
+<style lang="sass">
+	@use 'fractalstyler2/fractals' as *
+
+	.card
+		+surface(surface, s, 12)
+		+stack(s)
+</style>
 ```
 
-Source layout: `src/lib/fractals/` (config, tokens, base, responsive, atoms,
-molecules, utilities), `src/lib/components/` (blocks, layouts),
-`src/lib/styles/` (the emit entry).
+---
 
-## Color mode
+## The Model
 
-Light is the marker-free default (SSR-safe). Dark comes from
-`prefers-color-scheme` and from an explicit `data-mode="dark"` on `<html>`:
+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
+---
 
-`.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`.
-
-## Develop
+## CLI Options
 
 ```bash
-pnpm install
-pnpm dev          # demo showcase at /
-pnpm run prepack  # build the distributable package into dist/
+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
 ```
 
+---
+
 ## License
 
 MIT

package/dist/cli.d.ts

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

package/dist/cli.js

@@ -0,0 +1,108 @@
+#!/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
+
+Usage:
+  npx 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 this help message
+
+Examples:
+  npx fractalstyler2 init
+  npx fractalstyler2 init src/lib/styles --force
+  npx fractalstyler2 init src/styles
+`);
+}
+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 && command !== 'init')) {
+    if (command && command !== 'init') {
+        console.error(`Unknown command: ${command}`);
+    }
+    printUsage();
+    process.exit(command && command !== 'init' ? 1 : 0);
+}
+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/{components → styles}/_blocks.sass

@@ -4,7 +4,7 @@
 // State is expressed with data-*/aria-*, never modifier classes.
 // =============================================================================
 
-@use '../fractals' as *
+@use 'fractals' as *
 
 .card
 	+surface(surface, s, 12)

package/dist/{fractals/index.sass → styles/_fractals.sass}

@@ -1,7 +1,9 @@
 // =============================================================================
 // FRACTALS — the pure API barrel. Emits NO css on its own.
 // -----------------------------------------------------------------------------
-// In any component partial:  @use '../fractals' as *
+// In any component partial or Svelte component:
+//   @use '$lib/styles/fractals' as *
+//   (or @use './fractals' as *)
 // then call fractals freely:  +surface(...)  +stack(...)  space(m) ...
 // =============================================================================
 

package/dist/{components → styles}/_layouts.sass

@@ -4,7 +4,7 @@
 // hero, a holy-grail, a docs template. Each is a short composition of fractals.
 // =============================================================================
 
-@use '../fractals' as *
+@use 'fractals' as *
 
 // 1. Responsive grid of 3 columns — 1 → 2 → 3 across breakpoints.
 .grid-3

package/dist/styles/index.sass

@@ -2,18 +2,19 @@
 // STYLES ENTRY — the full emitted stylesheet in cascade order.
 // -----------------------------------------------------------------------------
 //   1. tokens      the CSS custom properties (only literal values)
-//   2. utilities   atom fractals projected to markup classes (optional layer)
-//   3. blocks      components composed from fractals
-//   4. layouts     page templates composed from fractals
+//   2. base        fluid reset
+//   3. utilities   atom fractals projected to markup classes (optional layer)
+//   4. blocks      components composed from fractals
+//   5. layouts     page templates composed from fractals
 //
-// Consume from a SvelteKit app:  import 'fractalstyler2/styles'
-// or, from SASS:                 @use 'fractalstyler2/styles'
+// Consume from a SvelteKit app:  import '$lib/styles/index.sass'
+// or from package:               import 'fractalstyler2/styles'
 // The fractal mixins/functions themselves emit nothing until called, so output
 // contains only what you use.
 // =============================================================================
 
-@use '../fractals/tokens'
-@use '../fractals/base'
-@use '../fractals/utilities'
-@use '../components/blocks'
-@use '../components/layouts'
+@use './tokens'
+@use './base'
+@use './utilities'
+@use './blocks'
+@use './layouts'

package/package.json

@@ -1,20 +1,25 @@
 {
 	"name": "fractalstyler2",
-	"version": "0.0.1",
+	"version": "0.0.2",
 	"description": "A fractal-composition styling system for SvelteKit — every style unit is a SASS mixin, and components and layouts are recipes of smaller fractals.",
+	"bin": {
+		"fractalstyler2": "./dist/cli.js",
+		"fractalstyler": "./dist/cli.js"
+	},
 	"scripts": {
 		"dev": "vite dev",
 		"build": "vite build && npm run prepack",
 		"preview": "vite preview",
 		"prepare": "svelte-kit sync || echo ''",
-		"prepack": "svelte-kit sync && svelte-package && publint",
+		"prepack": "svelte-kit sync && svelte-package && chmod +x dist/cli.js && publint",
 		"check": "svelte-kit sync && svelte-check --tsconfig ./tsconfig.json",
 		"check:watch": "svelte-kit sync && svelte-check --tsconfig ./tsconfig.json --watch"
 	},
 	"files": [
 		"dist",
 		"!dist/**/*.test.*",
-		"!dist/**/*.spec.*"
+		"!dist/**/*.spec.*",
+		"templates"
 	],
 	"sideEffects": [
 		"**/*.css"
@@ -28,8 +33,9 @@
 			"svelte": "./dist/index.js"
 		},
 		"./styles": "./dist/styles/index.sass",
-		"./fractals": "./dist/fractals/index.sass",
-		"./tokens": "./dist/fractals/_tokens.sass",
+		"./styles/*": "./dist/styles/*",
+		"./fractals": "./dist/styles/_fractals.sass",
+		"./tokens": "./dist/styles/_tokens.sass",
 		"./package.json": "./package.json"
 	},
 	"peerDependencies": {
@@ -40,6 +46,7 @@
 		"@sveltejs/kit": "^2.63.0",
 		"@sveltejs/package": "^2.5.8",
 		"@sveltejs/vite-plugin-svelte": "^7.1.2",
+		"@types/node": "^26.2.0",
 		"publint": "^0.3.21",
 		"sass": "^1.102.0",
 		"svelte": "^5.56.1",

package/templates/_atoms.sass

@@ -0,0 +1,155 @@
+// =============================================================================
+// ATOM FRACTALS — the indivisible units. One visual decision each.
+// -----------------------------------------------------------------------------
+// Every atom is a mixin. Call it inside a class to compose, or let
+// _utilities.sass project it to a utility class. Same fractal, two consumers.
+// =============================================================================
+
+@use 'config' as *
+
+// --- Flow: the two axes of layout ------------------------------------------
+// A box is a vertical stack, a row is horizontal. Optional semantic alignment:
+//   +box(center)          → items centered on the cross axis
+//   +row(between, center) → spread on main axis, centered on cross axis
+=box($x: null, $y: null)
+	display: flex
+	flex-direction: column
+	@if $x
+		align-items: align($x)
+	@if $y
+		justify-content: align($y)
+
+=row($x: null, $y: null)
+	display: flex
+	flex-direction: row
+	@if $x
+		justify-content: align($x)
+	@if $y
+		align-items: align($y)
+
+=wrap
+	flex-wrap: wrap
+
+=grid($cols: 1)
+	display: grid
+	grid-template-columns: repeat($cols, minmax(0, 1fr))
+
+// A grid that reflows on its own — no breakpoints, no counting columns.
+=auto-grid($min: 15rem, $gap: s)
+	display: grid
+	grid-template-columns: repeat(auto-fit, minmax(min(#{$min}, 100%), 1fr))
+	gap: space($gap)
+
+// Dead-center anything (grid is the one-liner that works for a single child).
+=center
+	display: grid
+	place-items: center
+
+// --- Spacing ---------------------------------------------------------------
+=gap($v: s)
+	gap: space($v)
+
+=pad($v: s)
+	padding: space($v)
+
+=px($v: s)
+	padding-inline: space($v)
+
+=py($v: s)
+	padding-block: space($v)
+
+=mx-auto
+	margin-inline: auto
+
+=my-auto
+	margin-block: auto
+
+// --- Size ------------------------------------------------------------------
+=w($v: 100%)
+	width: $v
+
+=h($v: 100%)
+	height: $v
+
+=full
+	width: 100%
+	height: 100%
+
+=square($v)
+	width: $v
+	height: $v
+
+=grow($n: 1)
+	flex-grow: $n
+
+=shrink($n: 0)
+	flex-shrink: $n
+
+=min0
+	min-width: 0
+	min-height: 0
+
+// --- Surface & skin --------------------------------------------------------
+=bg($role: surface)
+	background-color: surface($role)
+
+=ink($role: primary)
+	color: ink($role)
+
+=border($side: all, $color: var(--border))
+	@if $side == all
+		border: 1px solid $color
+	@else
+		border-#{$side}: 1px solid $color
+
+=radius($v: 12)
+	border-radius: radius($v)
+
+=shadow($v: md)
+	box-shadow: shadow($v)
+
+// --- Position --------------------------------------------------------------
+=relative
+	position: relative
+
+=absolute($inset: null)
+	position: absolute
+	@if $inset
+		inset: $inset
+
+=sticky($top: 0)
+	position: sticky
+	top: $top
+
+=fill
+	position: absolute
+	inset: 0
+
+// --- Type ------------------------------------------------------------------
+=type($v)
+	font-size: text-size($v)
+
+=weight($w: 500)
+	font-weight: $w
+
+=leading($lh: 1.5)
+	line-height: $lh
+
+=truncate
+	overflow: hidden
+	white-space: nowrap
+	text-overflow: ellipsis
+
+=clamp-lines($n: 2)
+	display: -webkit-box
+	-webkit-line-clamp: $n
+	-webkit-box-orient: vertical
+	overflow: hidden
+
+// --- Motion ----------------------------------------------------------------
+=transition($props: all, $dur: 150ms, $ease: ease)
+	transition: $props $dur $ease
+
+=ring($color: var(--ring))
+	outline: 2px solid $color
+	outline-offset: 1px

package/templates/_base.sass

@@ -0,0 +1,43 @@
+// =============================================================================
+// BASE — a minimal, opinionated reset so the tokens actually reach the page.
+// Kept tiny: box model, sane media defaults, and wiring body to the palette.
+// =============================================================================
+
+*, *::before, *::after
+	box-sizing: border-box
+
+html
+	-webkit-text-size-adjust: 100%
+
+body
+	margin: 0
+	min-height: 100vh
+	font-family: var(--font-sans)
+	font-size: var(--text-md)
+	line-height: 1.5
+	color: var(--text-primary)
+	background-color: var(--bg)
+	-webkit-font-smoothing: antialiased
+
+:where(h1, h2, h3, h4, h5, h6, p, figure, blockquote)
+	margin: 0
+
+:where(h1, h2, h3, h4)
+	line-height: 1.15
+	text-wrap: balance
+
+:where(img, picture, video, canvas, svg)
+	display: block
+	max-width: 100%
+
+:where(a)
+	color: inherit
+	text-decoration-color: var(--border-strong)
+
+:where(button, input, select, textarea)
+	font: inherit
+	color: inherit
+
+:where(:focus-visible)
+	outline: 2px solid var(--ring)
+	outline-offset: 2px

package/templates/_blocks.sass

@@ -0,0 +1,88 @@
+// =============================================================================
+// BLOCKS — components as recipes of fractals. Note how little CSS is here:
+// each block is a handful of fractal calls plus its own genuinely-unique lines.
+// State is expressed with data-*/aria-*, never modifier classes.
+// =============================================================================
+
+@use 'fractals' as *
+
+.card
+	+surface(surface, s, 12)
+	+stack(s)
+	&[data-elevated]
+		+shadow(md)
+
+.panel
+	+surface(raised, m, 16)
+	+stack(m)
+
+.badge
+	+row(center, center)
+	display: inline-flex
+	+px(2xs)
+	+type(xs)
+	+weight(500)
+	+radius(full)
+	+bg(raised)
+	+ink(secondary)
+	padding-block: 2px
+
+.avatar
+	+center
+	+square(var(--avatar-size, 40px))
+	+radius(full)
+	+bg(raised)
+	+ink(secondary)
+	overflow: hidden
+
+.input
+	display: block
+	+w(100%)
+	+px(2xs)
+	+type(md)
+	+leading(1.5)
+	+border
+	+radius(6)
+	+bg(bg)
+	+ink(primary)
+	padding-block: 8px
+	&:focus-visible
+		+ring
+
+.button
+	+row(center, center)
+	+gap(2xs)
+	+px(s)
+	+radius(6)
+	+weight(500)
+	+transition(background-color)
+	cursor: pointer
+	padding-block: 8px
+	user-select: none
+	// Exceptions: variants live on data-variant, not in the class name.
+	&[data-variant='primary']
+		background: var(--theme)
+		color: var(--text-inverse)
+		&:hover
+			background: var(--theme-hover)
+	&[data-variant='ghost']
+		background: transparent
+		+ink(secondary)
+		&:hover
+			+bg(raised)
+
+.divider
+	border: none
+	+border(top)
+	margin-block: space(s)
+
+.kbd
+	display: inline-block
+	+px(3xs)
+	+type(xs)
+	+leading(1)
+	+radius(4)
+	+bg(raised)
+	border: 1px solid var(--border-strong)
+	font-family: var(--font-mono)
+	padding-block: 2px

package/templates/_config.sass

@@ -0,0 +1,78 @@
+// =============================================================================
+// CONFIG — the finite vocabulary every fractal draws from.
+// -----------------------------------------------------------------------------
+// Scales live here as Sass data; resolvers turn a keyword-or-raw value into the
+// right token var() or unit. Fractals never hardcode a px or a token name —
+// they route through space(), radius(), etc. so the system speaks one language.
+// =============================================================================
+
+@use 'sass:map'
+@use 'sass:math'
+@use 'sass:meta'
+@use 'sass:list'
+
+// --- Scales (mirror the custom properties in _tokens.sass) --------------------
+$breakpoints: (sm: 640px, md: 768px, lg: 1024px, xl: 1240px)
+
+$space-steps: 3xs 2xs xs s m l xl 2xl 3xl s-l
+$radius-steps: 0 2 4 6 8 12 16 24 full
+$text-steps: xs sm md lg xl 2xl 3xl 4xl
+$shadow-steps: sm md lg
+$surface-roles: bg surface raised
+$ink-roles: primary secondary muted inverse
+
+$align-map: (start: flex-start, end: flex-end, center: center, between: space-between, around: space-around, evenly: space-evenly, stretch: stretch, baseline: baseline)
+
+// --- Resolvers ----------------------------------------------------------------
+
+// space(m) → var(--space-m) | space(18) → 18px | space(2rem) → 2rem
+@function space($v)
+	@if $v == null
+		@return null
+	@else if list.index($space-steps, $v)
+		@return var(--space-#{$v})
+	@else if meta.type-of($v) == number and math.is-unitless($v)
+		@return #{$v}px
+	@else
+		@return $v
+
+@function radius($v)
+	@if list.index($radius-steps, $v)
+		@return var(--radius-#{$v})
+	@else if meta.type-of($v) == number and math.is-unitless($v)
+		@return #{$v}px
+	@else
+		@return $v
+
+@function text-size($v)
+	@if list.index($text-steps, $v)
+		@return var(--text-#{$v})
+	@else
+		@return $v
+
+@function shadow($v)
+	@if list.index($shadow-steps, $v)
+		@return var(--shadow-#{$v})
+	@else
+		@return $v
+
+@function surface($role)
+	@if $role == bg
+		@return var(--bg)
+	@else
+		@return var(--bg-#{$role})
+
+@function ink($role)
+	@if $role == primary
+		@return var(--text-primary)
+	@else
+		@return var(--text-#{$role})
+
+@function align($v)
+	$m: map.get($align-map, $v)
+	@if $m
+		@return $m
+	@return $v
+
+@function bp($name)
+	@return map.get($breakpoints, $name)

package/templates/_fractals.sass

@@ -0,0 +1,13 @@
+// =============================================================================
+// FRACTALS — the pure API barrel. Emits NO css on its own.
+// -----------------------------------------------------------------------------
+// In any component partial or Svelte component:
+//   @use '$lib/styles/fractals' as *
+//   (or @use './fractals' as *)
+// then call fractals freely:  +surface(...)  +stack(...)  space(m) ...
+// =============================================================================
+
+@forward 'config'
+@forward 'responsive'
+@forward 'atoms'
+@forward 'molecules'

package/templates/_layouts.sass

@@ -0,0 +1,108 @@
+// =============================================================================
+// LAYOUTS — the largest fractals. Same recipe move, page scale.
+// These are the concrete deliverables you named: a responsive 3-col grid, a
+// hero, a holy-grail, a docs template. Each is a short composition of fractals.
+// =============================================================================
+
+@use 'fractals' as *
+
+// 1. Responsive grid of 3 columns — 1 → 2 → 3 across breakpoints.
+.grid-3
+	+cols((base: 1, sm: 2, lg: 3), m)
+
+// A grid that never needs breakpoints: it fits as many columns as will hold
+// the min track. Reach for this before .grid-3 when column count is negotiable.
+.card-grid
+	+auto-grid(16rem, m)
+
+// 2. Hero — full-viewport cover with a centered, measured message.
+.hero
+	+cover(80vh, xl)
+	> .center
+		+stack(m, center)
+		text-align: center
+		max-width: 45ch
+
+// 3. Holy grail — header / (nav · main · aside) / footer.
+.holy-grail
+	display: grid
+	min-height: 100vh
+	grid-template-rows: auto 1fr auto
+	grid-template-areas: 'header' 'main' 'footer'
+	> .hg-header
+		grid-area: header
+	> .hg-footer
+		grid-area: footer
+	> .hg-body
+		grid-area: main
+		display: grid
+		grid-template-columns: 1fr
+		+gap(m)
+		+pad(m)
+	+at(lg)
+		> .hg-body
+			grid-template-columns: var(--nav-w, 220px) minmax(0, 1fr) var(--aside-w, 260px)
+			> .hg-nav
+				+sticky(var(--space-m))
+				align-self: start
+			> .hg-aside
+				+sticky(var(--space-m))
+				align-self: start
+
+// 4. Docs template — sidebar nav + reading column + on-page TOC.
+.docs
+	display: grid
+	min-height: 100vh
+	grid-template-columns: 1fr
+	> .docs-nav
+		display: none
+	> .docs-toc
+		display: none
+	> .docs-main
+		+min0
+		+stack(m)
+		+center-column(72ch, s-l)
+		+py(l)
+	+at(md)
+		grid-template-columns: var(--docs-nav-w, 240px) minmax(0, 1fr)
+		> .docs-nav
+			+box
+			+sticky(0)
+			+py(l)
+			+px(s)
+			height: 100vh
+			overflow-y: auto
+			+border(right)
+	+at(xl)
+		grid-template-columns: var(--docs-nav-w, 240px) minmax(0, 1fr) var(--docs-toc-w, 220px)
+		> .docs-toc
+			+box
+			+sticky(0)
+			+py(l)
+			+px(s)
+			height: 100vh
+			overflow-y: auto
+			+ink(secondary)
+
+// 5. App shell — sticky header, fluid body, footer. The frame most apps live in.
+.app-shell
+	+box
+	+relative
+	isolation: isolate
+	min-height: 100vh
+	> .app-header
+		+row(null, center)
+		+sticky(0)
+		+px(m)
+		z-index: var(--z-sticky)
+		height: var(--header-height)
+		+bg(surface)
+		+border(bottom)
+	> .app-main
+		+grow
+		+min0
+	> .app-footer
+		+row(null, center)
+		+px(m)
+		min-height: var(--footer-height)
+		+border(top)

package/templates/_molecules.sass

@@ -0,0 +1,93 @@
+// =============================================================================
+// MOLECULE FRACTALS — self-similar: each is a small graph of atom fractals.
+// -----------------------------------------------------------------------------
+// This is the payoff of the model. A molecule reads like a recipe of atoms,
+// and a component (next layer up) reads like a recipe of molecules. Same move
+// at every scale — that is the "fractal" in fractalstyler2.
+// =============================================================================
+
+@use 'config' as *
+@use 'atoms' as *
+@use 'responsive' as *
+
+// Stack — vertical rhythm with one shared gap.
+=stack($gap: xs, $x: null)
+	+box($x)
+	+gap($gap)
+
+// Cluster — wrapping row of chips/tags/buttons.
+=cluster($gap: xs, $x: start, $y: center)
+	+row($x, $y)
+	+wrap
+	+gap($gap)
+
+// Center — a centered reading column bounded by a measure.
+=center-column($max: var(--measure, 60ch), $pad: s)
+	max-width: $max
+	+mx-auto
+	+px($pad)
+
+// Cover — fills a min-height with a centered focal child.
+=cover($min: 100vh, $pad: s)
+	+box
+	min-height: $min
+	+pad($pad)
+	> *
+		margin-block: 0
+	> .center
+		+my-auto
+
+// Frame — fixed aspect-ratio media box.
+=frame($ratio: 16 / 9)
+	aspect-ratio: $ratio
+	overflow: hidden
+	> :is(img, video, iframe)
+		+full
+		object-fit: cover
+
+// Reel — horizontal scroll-snap rail.
+=reel($gap: xs)
+	+row
+	+gap($gap)
+	overflow-x: auto
+	overscroll-behavior-inline: contain
+	scroll-snap-type: inline mandatory
+	> *
+		scroll-snap-align: start
+		flex: 0 0 auto
+
+// Sidebar — an intrinsic rail beside a fluid main; wraps when tight.
+=with-sidebar($rail: 240px, $gap: s, $min: 60%)
+	+row
+	+wrap
+	+gap($gap)
+	> .rail
+		flex-basis: $rail
+		flex-grow: 1
+	> .flow
+		flex-basis: 0
+		flex-grow: 999
+		min-width: $min
+
+// Surface — the "material" fractal: skin + elevation in one call.
+// The building block of every card/panel/popover.
+=surface($bg: surface, $pad: s, $radius: 12, $elevation: none)
+	+bg($bg)
+	+border
+	+radius($radius)
+	+pad($pad)
+	@if $elevation != none
+		+shadow($elevation)
+
+// Responsive column grid from a per-breakpoint map:
+//   +cols((base: 1, sm: 2, lg: 3))
+=cols($map, $gap: s)
+	display: grid
+	grid-auto-flow: row
+	+gap($gap)
+	@each $bp, $n in $map
+		@if $bp == base
+			grid-template-columns: repeat($n, minmax(0, 1fr))
+		@else
+			+at($bp)
+				grid-template-columns: repeat($n, minmax(0, 1fr))

package/templates/_responsive.sass

@@ -0,0 +1,43 @@
+// =============================================================================
+// RESPONSIVE FRACTALS — the units that let any other fractal grow with the page.
+// -----------------------------------------------------------------------------
+// These are self-similar too: +at(md) wraps any block of fractal calls in a
+// breakpoint, so a "responsive component" is just a component whose fractals
+// are re-stated inside +at(...).
+// =============================================================================
+
+@use 'sass:map'
+@use 'config' as *
+
+// +at(md) — mobile-first min-width query by name (sm/md/lg/xl) or raw length.
+=at($name)
+	$edge: $name
+	@if map.has-key($breakpoints, $name)
+		$edge: bp($name)
+	@media (min-width: #{$edge})
+		@content
+
+// +until(md) — max-width query (one below the named edge).
+=until($name)
+	$edge: $name
+	@if map.has-key($breakpoints, $name)
+		$edge: bp($name)
+	@media (max-width: #{$edge})
+		@content
+
+// Container-query fractals — component-scoped responsiveness.
+=cq
+	container-type: inline-size
+
+=cq-at($width)
+	@container (min-width: #{$width})
+		@content
+
+=cq-until($width)
+	@container (max-width: #{$width})
+		@content
+
+// Motion / preference-aware fractal.
+=reduce-motion
+	@media (prefers-reduced-motion: reduce)
+		@content

package/templates/_tokens.sass

@@ -0,0 +1,127 @@
+// =============================================================================
+// TOKENS — the only place literal values live. Everything else is a fractal
+// that consumes these custom properties. Light is the marker-free default so
+// tokens stay defined during SSR and with JS disabled; dark comes from
+// prefers-color-scheme and from an explicit [data-mode='dark'].
+// =============================================================================
+
+:root
+	color-scheme: light
+
+	// Fonts
+	--font-sans: system-ui, -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif
+	--font-mono: ui-monospace, SFMono-Regular, Menlo, Monaco, Consolas, monospace
+
+	// Fluid type scale (Utopia 360→1240)
+	--text-xs: 0.75rem
+	--text-sm: clamp(0.9375rem, 0.9119rem + 0.1136vw, 1rem)
+	--text-md: clamp(1.125rem, 1.0739rem + 0.2273vw, 1.25rem)
+	--text-lg: clamp(1.35rem, 1.2631rem + 0.3864vw, 1.5625rem)
+	--text-xl: clamp(1.62rem, 1.4837rem + 0.6057vw, 1.9531rem)
+	--text-2xl: clamp(1.944rem, 1.7405rem + 0.9044vw, 2.4414rem)
+	--text-3xl: clamp(2.3328rem, 2.0387rem + 1.3072vw, 3.0518rem)
+	--text-4xl: clamp(2.7994rem, 2.384rem + 1.8461vw, 3.8147rem)
+
+	// Fluid space scale
+	--space-3xs: clamp(0.3125rem, 0.3125rem + 0vw, 0.3125rem)
+	--space-2xs: clamp(0.5625rem, 0.5369rem + 0.1136vw, 0.625rem)
+	--space-xs: clamp(0.875rem, 0.8494rem + 0.1136vw, 0.9375rem)
+	--space-s: clamp(1.125rem, 1.0739rem + 0.2273vw, 1.25rem)
+	--space-m: clamp(1.6875rem, 1.6108rem + 0.3409vw, 1.875rem)
+	--space-l: clamp(2.25rem, 2.1477rem + 0.4545vw, 2.5rem)
+	--space-xl: clamp(3.375rem, 3.2216rem + 0.6818vw, 3.75rem)
+	--space-2xl: clamp(4.5rem, 4.2955rem + 0.9091vw, 5rem)
+	--space-3xl: clamp(6.75rem, 6.4432rem + 1.3636vw, 7.5rem)
+	--space-s-l: clamp(1.125rem, 0.5625rem + 2.5vw, 2.5rem)
+
+	// Radius
+	--radius-0: 0
+	--radius-2: 2px
+	--radius-4: 4px
+	--radius-6: 6px
+	--radius-8: 8px
+	--radius-12: 12px
+	--radius-16: 16px
+	--radius-24: 24px
+	--radius-full: 9999px
+
+	// Shadow
+	--shadow-sm: 0 1px 2px rgba(15, 23, 42, 0.06)
+	--shadow-md: 0 4px 12px rgba(15, 23, 42, 0.08)
+	--shadow-lg: 0 12px 32px rgba(15, 23, 42, 0.12)
+
+	// Layering
+	--z-base: 0
+	--z-raised: 10
+	--z-sticky: 100
+	--z-modal: 200
+	--z-toast: 300
+
+	// Layout
+	--header-height: 64px
+	--footer-height: 56px
+	--measure: 65ch
+
+	// Light palette (marker-free default)
+	--bg: #fdfefe
+	--bg-surface: #f8f7f7
+	--bg-raised: #f1f5f9
+	--text-primary: #0f172a
+	--text-secondary: #5b6472
+	--text-muted: #929497
+	--text-inverse: #ffffff
+	--border: #e2e8f0
+	--border-strong: #cbd5e1
+	--theme: #007f4e
+	--theme-hover: #00663f
+	--theme-active: #005031
+	--ring: rgba(0, 127, 78, 0.35)
+
+@media (prefers-color-scheme: dark)
+	:root:not([data-mode='light'])
+		color-scheme: dark
+		--bg: #131313
+		--bg-surface: #1e1e1e
+		--bg-raised: #2b2b2b
+		--text-primary: #f9fafb
+		--text-secondary: #a7adb7
+		--text-muted: #6b7280
+		--text-inverse: #0b0f17
+		--border: #2f3030
+		--border-strong: #4a4b4b
+		--theme: #10b981
+		--theme-hover: #34d399
+		--theme-active: #059669
+		--ring: rgba(16, 185, 129, 0.4)
+
+[data-mode='dark']
+	color-scheme: dark
+	--bg: #131313
+	--bg-surface: #1e1e1e
+	--bg-raised: #2b2b2b
+	--text-primary: #f9fafb
+	--text-secondary: #a7adb7
+	--text-muted: #6b7280
+	--text-inverse: #0b0f17
+	--border: #2f3030
+	--border-strong: #4a4b4b
+	--theme: #10b981
+	--theme-hover: #34d399
+	--theme-active: #059669
+	--ring: rgba(16, 185, 129, 0.4)
+
+[data-mode='light']
+	color-scheme: light
+	--bg: #fdfefe
+	--bg-surface: #f8f7f7
+	--bg-raised: #f1f5f9
+	--text-primary: #0f172a
+	--text-secondary: #5b6472
+	--text-muted: #929497
+	--text-inverse: #ffffff
+	--border: #e2e8f0
+	--border-strong: #cbd5e1
+	--theme: #007f4e
+	--theme-hover: #00663f
+	--theme-active: #005031
+	--ring: rgba(0, 127, 78, 0.35)

package/templates/_utilities.sass

@@ -0,0 +1,125 @@
+// =============================================================================
+// UTILITY PROJECTION — the *other* way to consume a fractal.
+// -----------------------------------------------------------------------------
+// A fractal is a mixin. Here we bind a subset of them to class names so they
+// stay usable straight from markup (`class="box gap-m pad-l"`). This is the
+// key idea: utility classes are not a separate system — they are a generated
+// projection of the exact same fractals your components compose. Emit only the
+// atoms you want in markup; delete this whole file if you go SASS-only.
+// =============================================================================
+
+@use 'config' as *
+@use 'atoms' as *
+@use 'molecules' as *
+@use 'responsive' as *
+
+// --- Flow ------------------------------------------------------------------
+.box
+	+box
+.row
+	+row
+	&.wrap
+		+wrap
+
+// Alignment modifiers, semantic and axis-aware.
+.box
+	&.xcenter
+		align-items: center
+	&.xleft
+		align-items: flex-start
+	&.xright
+		align-items: flex-end
+	&.ycenter
+		justify-content: center
+	&.ytop
+		justify-content: flex-start
+	&.ybot
+		justify-content: flex-end
+
+.row
+	&.ycenter
+		align-items: center
+	&.ytop
+		align-items: flex-start
+	&.ybot
+		align-items: flex-end
+	&.xbetween
+		justify-content: space-between
+	&.xevenly
+		justify-content: space-evenly
+	&.xleft
+		justify-content: flex-start
+	&.xright
+		justify-content: flex-end
+
+// Fixed column grids.
+@for $n from 1 through 6
+	.grid-cols-#{$n}
+		+grid($n)
+
+.center
+	+center
+
+// --- Spacing scale → gap-* / pad-* -----------------------------------------
+@each $s in $space-steps
+	.gap-#{$s}
+		+gap($s)
+	.pad-#{$s}
+		+pad($s)
+	.px-#{$s}
+		+px($s)
+	.py-#{$s}
+		+py($s)
+
+// --- Radius / shadow / surface ---------------------------------------------
+@each $r in $radius-steps
+	.radius-#{$r}
+		+radius($r)
+
+@each $s in $shadow-steps
+	.shadow-#{$s}
+		+shadow($s)
+
+@each $role in $surface-roles
+	.bg-#{$role}
+		+bg($role)
+
+.border
+	+border
+@each $side in top right bottom left
+	.border-#{$side}
+		+border($side)
+
+// --- Type ------------------------------------------------------------------
+@each $t in $text-steps
+	.text-#{$t}
+		+type($t)
+
+.truncate
+	+truncate
+
+// Semantic type primitives — so you stop retyping `.text-sm .lh15 .muted`.
+.body
+	+type(md)
+	+leading(1.6)
+	+ink(primary)
+.muted
+	+ink(secondary)
+.eyebrow
+	+type(sm)
+	+ink(muted)
+	text-transform: uppercase
+	letter-spacing: 0.06em
+	font-weight: 500
+
+// --- Sizing shortcuts ------------------------------------------------------
+.wfull
+	+w(100%)
+.hfull
+	+h(100%)
+.full
+	+full
+.grow
+	+grow
+.min0
+	+min0

package/templates/index.sass

@@ -0,0 +1,20 @@
+// =============================================================================
+// STYLES ENTRY — the full emitted stylesheet in cascade order.
+// -----------------------------------------------------------------------------
+//   1. tokens      the CSS custom properties (only literal values)
+//   2. base        fluid reset
+//   3. utilities   atom fractals projected to markup classes (optional layer)
+//   4. blocks      components composed from fractals
+//   5. layouts     page templates composed from fractals
+//
+// Consume from a SvelteKit app:  import '$lib/styles/index.sass'
+// or from package:               import 'fractalstyler2/styles'
+// The fractal mixins/functions themselves emit nothing until called, so output
+// contains only what you use.
+// =============================================================================
+
+@use './tokens'
+@use './base'
+@use './utilities'
+@use './blocks'
+@use './layouts'