fractalstyler2 0.0.2 → 0.3.0

package/skills/style-migration/SKILL.md

@@ -0,0 +1,45 @@
+---
+name: style-migration
+description: Migrate legacy CSS, Tailwind utilities, or fractals-styler (v1) classes into modern fractalstyler2 SASS mixin recipes and token scales. Use when refactoring stylesheets, updating legacy components, or cleaning up utility class soup.
+---
+
+# Style Migration & Refactoring Skill
+
+This skill guides the refactoring and migration of existing styles into idiomatic `fractalstyler2`.
+
+---
+
+## 1. Quick Replacement Matrix
+
+| Legacy Pattern | Problem | fractalstyler2 Replacement |
+| :--- | :--- | :--- |
+| `gap8`, `gap16`, `gap24` | Dynamic JIT classes removed in v2 | Markup: `.gap-xs`, `.gap-s`, `.gap-m`<br>SASS: `+gap(8)` or `+gap(s)` |
+| `pad8`, `pad16`, `pad24` | Dynamic JIT classes removed in v2 | Markup: `.pad-xs`, `.pad-s`, `.pad-m`<br>SASS: `+pad(16)` or `+pad(m)` |
+| `<div class="center">` (as reading text column) | In v2, `.center` dead-centers items in a grid | SASS: `.reading-col { +center-column }` |
+| `<div class="stack">` | Markup class `.stack` does not exist | SASS: `.container { +stack(s) }` |
+| `<div class="cluster">` | Markup class `.cluster` does not exist | SASS: `.tag-row { +cluster(xs) }` |
+| `w100`, `h100` | Removed aliases | `.wfull`, `.hfull` |
+| `min-w-0`, `min-h-0` | Removed utilities | `.min0` |
+| `[data-variant='quiet']` | Renamed on button | `[data-variant='ghost']` |
+| `.appshell` | Renamed layout | `.app-shell` |
+
+---
+
+## 2. Refactoring Procedure
+
+1. **Identify the Container**: Is it a card, panel, button, reading column, or grid?
+2. **Select the Molecule**:
+   - Vertical list of items → `+stack(s)`
+   - Tag list / button row → `+cluster(xs)`
+   - Box with border/radius/padding → `+surface(surface, s, 12)`
+   - Full height hero → `+cover(80vh, xl)`
+3. **Strip Utility Soup from Markup**: Replace long class strings (`class="box pad16 gap12 w100 min-w-0 radius12 border"`) with a single semantic class (`class="card"` or `class="feed-item"`).
+4. **Move Decisions to `<style lang="sass">`**:
+   ```sass
+   @use '$lib/styles/fractals' as *
+
+   .feed-item
+     +surface(surface, s, 12)
+     +stack(s)
+   ```
+5. **Verify**: Use the MCP tool `validate_recipe` or `npx sass src/lib/styles/index.sass /tmp/check.css`.

package/templates/_00_tokens.sass

@@ -0,0 +1,177 @@
+// =============================================================================
+// 00_TOKENS — the single source of truth for runtime CSS 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 explicit [data-mode='dark'].
+// =============================================================================
+
+:root
+	color-scheme: light
+
+	// Fonts
+	--font-sans: "Google Sans Flex", sans-serif
+	--font-mono: "JetBrains Mono", 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 (Concentric 2px, 3px, 4px, 6px hierarchy)
+	--radius-0: 0
+	--radius-2: 2px
+	--radius-3: 3px
+	--radius-4: 4px
+	--radius-6: 6px
+	--radius-8: 6px
+	--radius-12: 6px
+	--radius-16: 6px
+	--radius-24: 6px
+	--radius-full: 9999px
+
+	// Control Heights
+	--control-h-sm: 26px
+	--control-h-md: 32px
+	--control-h-lg: 38px
+
+	// 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: 48px
+	--footer-height: 56px
+	--measure: 65ch
+
+	// Light palette (marker-free default)
+	--bg: #fdfefe
+	--bg-surface: #f8f7f7
+	--bg-raised: #f1f5f9
+	--bg-panel: #F1F3F5
+	--bg-footer: #E9ECEF
+	--bg-popover: #FFFFFF
+	--bg-dialog: #FFFFFF
+	--bg-terminal: #0F172A
+	--bg-input: #FFFFFF
+	--bg-canvas: #F8F9FA
+	--text-primary: #0f172a
+	--text-secondary: #5b6472
+	--text-muted: #929497
+	--text-inverse: #ffffff
+	--state-hover: #E2E8F0
+	--state-hover-subtle: #F1F5F9
+	--state-selected: #CBD5E1
+	--border: #E2E8F0
+	--border-subtle: #EDF2F7
+	--theme-color: #04825B
+	--theme-color-alt: #047857
+	--theme: var(--theme-color)
+	--theme-hover: var(--theme-color-alt)
+	--ring: rgba(0, 127, 78, 0.35)
+
+@media (prefers-color-scheme: dark)
+	:root:not([data-mode='light'])
+		color-scheme: dark
+		--bg: #0E1118
+		--bg-surface: #141824
+		--bg-raised: #1C2232
+		--bg-panel: #101420
+		--bg-footer: #0B0D14
+		--bg-popover: #20273A
+		--bg-dialog: #20273A
+		--bg-terminal: #080A0F
+		--bg-input: #121622
+		--bg-canvas: #0E1118
+		--border: #28324A
+		--border-subtle: #1E2538
+		--text-primary: #EDF2F7
+		--text-secondary: #9BB0C7
+		--text-muted: #5D7087
+		--state-hover: #263047
+		--state-hover-subtle: #1B2233
+		--state-selected: #32405E
+		--theme-color: #38BDF8
+		--theme-color-alt: #0EA5E9
+		--theme: var(--theme-color)
+		--theme-hover: var(--theme-color-alt)
+		--text-inverse: #0E1118
+		--ring: rgba(16, 185, 129, 0.4)
+
+[data-mode='dark']
+	color-scheme: dark
+	--bg: #0E1118
+	--bg-surface: #141824
+	--bg-raised: #1C2232
+	--bg-panel: #101420
+	--bg-footer: #0B0D14
+	--bg-popover: #20273A
+	--bg-dialog: #20273A
+	--bg-terminal: #080A0F
+	--bg-input: #121622
+	--bg-canvas: #0E1118
+	--border: #28324A
+	--border-subtle: #1E2538
+	--text-primary: #EDF2F7
+	--text-secondary: #9BB0C7
+	--text-muted: #5D7087
+	--state-hover: #263047
+	--state-hover-subtle: #1B2233
+	--state-selected: #32405E
+	--theme-color: #38BDF8
+	--theme-color-alt: #0EA5E9
+	--theme: var(--theme-color)
+	--theme-hover: var(--theme-color-alt)
+	--text-inverse: #0E1118
+	--ring: rgba(16, 185, 129, 0.4)
+
+[data-mode='light']
+	color-scheme: light
+	--bg: #fdfefe
+	--bg-surface: #f8f7f7
+	--bg-raised: #f1f5f9
+	--bg-panel: #F1F3F5
+	--bg-footer: #E9ECEF
+	--bg-popover: #FFFFFF
+	--bg-dialog: #FFFFFF
+	--bg-terminal: #0F172A
+	--bg-input: #FFFFFF
+	--bg-canvas: #F8F9FA
+	--text-primary: #0f172a
+	--text-secondary: #5b6472
+	--text-muted: #929497
+	--text-inverse: #ffffff
+	--state-hover: #E2E8F0
+	--state-hover-subtle: #F1F5F9
+	--state-selected: #CBD5E1
+	--border: #E2E8F0
+	--border-subtle: #EDF2F7
+	--theme-color: #04825B
+	--theme-color-alt: #047857
+	--theme: var(--theme-color)
+	--theme-hover: var(--theme-color-alt)
+	--ring: rgba(0, 127, 78, 0.35)

package/{dist/styles/_config.sass → templates/_01_config.sass}

@@ -1,5 +1,5 @@
 // =============================================================================
-// CONFIG — the finite vocabulary every fractal draws from.
+// 01_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 —
@@ -11,15 +11,17 @@
 @use 'sass:meta'
 @use 'sass:list'
 
-// --- Scales (mirror the custom properties in _tokens.sass) --------------------
+// --- Scales (mirror the custom properties in _00_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
+$radius-steps: 0 2 3 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
+
+// Surfaces mapped to the 21 theme token contract
+$surface-roles: bg surface raised panel footer popover dialog terminal input canvas
+$ink-roles: primary secondary muted inverse theme-color theme-color-alt
 
 $align-map: (start: flex-start, end: flex-end, center: center, between: space-between, around: space-around, evenly: space-evenly, stretch: stretch, baseline: baseline)
 
@@ -59,12 +61,16 @@ $align-map: (start: flex-start, end: flex-end, center: center, between: space-be
 @function surface($role)
 	@if $role == bg
 		@return var(--bg)
+	@else if list.index($surface-roles, $role)
+		@return var(--bg-#{$role})
 	@else
 		@return var(--bg-#{$role})
 
 @function ink($role)
 	@if $role == primary
 		@return var(--text-primary)
+	@else if list.index($ink-roles, $role)
+		@return var(--text-#{$role})
 	@else
 		@return var(--text-#{$role})
 

package/templates/_02_fonts.sass

@@ -0,0 +1,13 @@
+// =============================================================================
+// 02_FONTS — local webfont declarations & font-family fallbacks.
+// -----------------------------------------------------------------------------
+// Downstream projects customize their font loading here.
+// =============================================================================
+
+// Define custom @font-face rules or load Google / local webfonts as needed:
+// @font-face
+// 	font-family: 'YourFont'
+// 	src: url('/fonts/YourFont.woff2') format('woff2')
+// 	font-weight: 100 900
+// 	font-style: normal
+// 	font-display: swap

package/templates/_03_responsive.sass

@@ -0,0 +1,31 @@
+// =============================================================================
+// 03_RESPONSIVE — the breakpoint mixins. Viewport-aware conditional styling.
+// -----------------------------------------------------------------------------
+// Mobile-first defaults; use +at($bp) for min-width media queries.
+// =============================================================================
+
+@use '01_config' as *
+
+=at($bp)
+	$width: bp($bp)
+	@if $width
+		@media (min-width: $width)
+			@content
+	@else
+		@media (min-width: $bp)
+			@content
+
+=below($bp)
+	$width: bp($bp)
+	@if $width
+		@media (max-width: ($width - 1px))
+			@content
+	@else
+		@media (max-width: $bp)
+			@content
+
+=between($min-bp, $max-bp)
+	$min: bp($min-bp)
+	$max: bp($max-bp)
+	@media (min-width: $min) and (max-width: ($max - 1px))
+		@content

package/templates/{_atoms.sass → _04_atoms.sass}

@@ -1,11 +1,11 @@
 // =============================================================================
-// ATOM FRACTALS — the indivisible units. One visual decision each.
+// 04_ATOMS — 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.
+// _09_utilities.sass project it to a utility class. Same fractal, two consumers.
 // =============================================================================
 
-@use 'config' as *
+@use '01_config' as *
 
 // --- Flow: the two axes of layout ------------------------------------------
 // A box is a vertical stack, a row is horizontal. Optional semantic alignment:
@@ -102,7 +102,7 @@
 	@else
 		border-#{$side}: 1px solid $color
 
-=radius($v: 12)
+=radius($v: 4)
 	border-radius: radius($v)
 
 =shadow($v: md)

package/{dist/styles/_molecules.sass → templates/_05_molecules.sass}

@@ -1,14 +1,15 @@
 // =============================================================================
-// MOLECULE FRACTALS — self-similar: each is a small graph of atom fractals.
+// 05_MOLECULES — 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 *
+@use 'sass:string'
+@use '01_config' as *
+@use '04_atoms' as *
+@use '03_responsive' as *
 
 // Stack — vertical rhythm with one shared gap.
 =stack($gap: xs, $x: null)
@@ -38,11 +39,13 @@
 		+my-auto
 
 // Frame — fixed aspect-ratio media box.
-=frame($ratio: 16 / 9)
-	aspect-ratio: $ratio
+=frame($ratio: '16 / 9')
+	aspect-ratio: string.unquote('#{$ratio}')
 	overflow: hidden
-	> :is(img, video, iframe)
+	position: relative
+	> *
 		+full
+	> :is(img, video, iframe)
 		object-fit: cover
 
 // Reel — horizontal scroll-snap rail.
@@ -69,13 +72,14 @@
 		flex-grow: 999
 		min-width: $min
 
-// Surface — the "material" fractal: skin + elevation in one call.
+// Surface — the "material" fractal: skin + border + optional radius + optional padding + elevation.
 // The building block of every card/panel/popover.
-=surface($bg: surface, $pad: s, $radius: 12, $elevation: none)
+=surface($bg: surface, $pad: null, $radius: 6, $elevation: none)
 	+bg($bg)
-	+border
-	+radius($radius)
-	+pad($pad)
+	@if $radius != null
+		+radius($radius)
+	@if $pad != null
+		+pad($pad)
 	@if $elevation != none
 		+shadow($elevation)
 

package/templates/_06_recipes.sass

@@ -0,0 +1,189 @@
+// =============================================================================
+// 06_RECIPES — macro mixins. Compositions of molecules and atoms.
+// -----------------------------------------------------------------------------
+// Recipes are mixins, NOT locked CSS classes. They take arguments and allow
+// custom components to compose standard patterns with flexible parameters.
+// =============================================================================
+
+@use '01_config' as *
+@use '04_atoms' as *
+@use '05_molecules' as *
+
+// Universal interactive control primitive (Button, Select trigger, Accordion header)
+=control($size: md, $radius: 4)
+	+row(null, center)
+	+gap(2xs)
+	+radius($radius)
+	+border(all, var(--border))
+	+bg(surface)
+	+ink(primary)
+	+weight(500)
+	user-select: none
+	cursor: pointer
+	text-decoration: none
+	transition: background 120ms ease, border-color 120ms ease, transform 80ms ease
+
+	@if $size == sm
+		height: var(--control-h-sm, 26px)
+		+px(2xs)
+		+type(xs)
+	@else if $size == lg
+		height: var(--control-h-lg, 38px)
+		+px(s)
+		+type(md)
+	@else
+		height: var(--control-h-md, 32px)
+		+px(xs)
+		+type(sm)
+
+	&:hover
+		+bg(raised)
+		border-color: var(--border-subtle)
+
+	&:active
+		transform: scale(0.985)
+
+	&:focus-visible
+		+ring
+
+	&:disabled, &[aria-disabled='true']
+		opacity: 0.5
+		cursor: not-allowed
+		pointer-events: none
+
+// Select input recipe (with embedded SVG chevron and optical line-height)
+=select($size: md, $radius: 4)
+	+control($size, $radius)
+	appearance: none
+	-webkit-appearance: none
+	padding-right: 28px
+	background-image: url("data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' width='12' height='12' viewBox='0 0 24 24' fill='none' stroke='%237F91AA' stroke-width='2' stroke-linecap='round' stroke-linejoin='round'%3E%3Cpolyline points='6 9 12 15 18 9'%3E%3C/polyline%3E%3C/svg%3E")
+	background-repeat: no-repeat
+	background-position: right 8px center
+	line-height: 1.2
+	cursor: pointer
+	width: 100%
+
+// Partition divider recipe with guaranteed breathing room
+=partition($side: top, $pad: s)
+	@if $side == top
+		margin-top: auto
+		padding-top: space($pad)
+		border-top: 1px solid var(--border)
+	@else if $side == bottom
+		margin-bottom: space($pad)
+		padding-bottom: space($pad)
+		border-bottom: 1px solid var(--border)
+
+// Pure CSS collapsible transition (0fr -> 1fr grid transition)
+=collapsible
+	display: grid
+	grid-template-rows: 0fr
+	transition: grid-template-rows 140ms cubic-bezier(0.16, 1, 0.3, 1)
+
+	&[data-open='true'], &[aria-expanded='true']
+		grid-template-rows: 1fr
+
+	> .collapsible-inner
+		overflow: hidden
+		min-height: 0
+
+// Marquee animation recipe
+=marquee($speed: 30s, $gap: 1rem)
+	overflow: hidden
+	display: flex
+	user-select: none
+	gap: $gap
+	position: relative
+
+	&[data-fade='true']
+		mask-image: linear-gradient(to right, transparent 0%, black 10%, black 90%, transparent 100%)
+
+	> [data-slot='marquee-track']
+		display: flex
+		flex-shrink: 0
+		justify-content: space-around
+		gap: $gap
+		min-width: 100%
+		animation: marquee-scroll $speed linear infinite
+
+	&[data-pause='true']:hover > [data-slot='marquee-track']
+		animation-play-state: paused
+
+// Card recipe — surface material + top-anchored vertical stack
+=card($bg: surface, $pad: null, $radius: 6, $elevation: none)
+	+surface($bg, $pad, $radius, $elevation)
+	+box(stretch, start)
+	+gap(s)
+	height: 100%
+	text-align: left
+
+// Button recipe
+=button($size: md, $radius: 4)
+	+control($size, $radius)
+	justify-content: center
+
+// Badge recipe — compact pill chip with subtle border
+=badge
+	+row(center, center)
+	display: inline-flex
+	+gap(3xs)
+	+px(2xs)
+	+type(xs)
+	+weight(500)
+	+radius(3)
+	+bg(raised)
+	+ink(secondary)
+	+border(all, var(--border))
+	padding-block: 2px
+
+// Input recipe — text entry field
+=input
+	display: block
+	+w(100%)
+	+px(xs)
+	+type(sm)
+	+leading(1.5)
+	+border(all, var(--border))
+	+radius(4)
+	+bg(input)
+	+ink(primary)
+	height: var(--control-h-md, 32px)
+	transition: border-color 120ms ease, box-shadow 120ms ease
+	&:focus-visible, &:focus
+		outline: none
+		border-color: var(--theme-color)
+		box-shadow: 0 0 0 2px var(--ring)
+
+// Keycap recipe
+=kbd
+	display: inline-block
+	+px(3xs)
+	+type(xs)
+	+leading(1)
+	+radius(3)
+	+bg(raised)
+	border: 1px solid var(--border)
+	font-family: var(--font-mono)
+	padding-block: 2px
+
+// Overlay & Dialog surfaces
+=dialog-surface
+	+bg(dialog)
+	+border(all, var(--border))
+	+radius(6)
+	+shadow(lg)
+	max-width: min(92vw, 540px)
+	width: 100%
+
+=popover-surface
+	+bg(popover)
+	+border(all, var(--border))
+	+radius(6)
+	+shadow(md)
+
+// Divider recipe
+=divider
+	border: none
+	+border(top)
+	margin-block: space(s)

package/templates/{_base.sass → _07_base.sass}

@@ -1,5 +1,5 @@
 // =============================================================================
-// BASE — a minimal, opinionated reset so the tokens actually reach the page.
+// 07_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.
 // =============================================================================
 
@@ -8,6 +8,7 @@
 
 html
 	-webkit-text-size-adjust: 100%
+	font-family: var(--font-sans)
 
 body
 	margin: 0
@@ -32,7 +33,7 @@ body
 
 :where(a)
 	color: inherit
-	text-decoration-color: var(--border-strong)
+	text-decoration-color: var(--border-subtle)
 
 :where(button, input, select, textarea)
 	font: inherit