docs(website): Clean up and modernize all documentation examples

.github/workflows/preview-docs.yml

@@ -61,5 +61,8 @@ jobs:
       - name: Validate Preview Manifest
         run: cd website && pnpm run check:previews
 
+      - name: Validate Docs Frontmatter
+        run: cd website && pnpm run check:frontmatter
+
       - name: Build Website
         run: cd website && pnpm run build

.github/workflows/test.yml

@@ -34,6 +34,10 @@ jobs:
         with:
           flutter-version: ${{ steps.fvm-config-action.outputs.FLUTTER_VERSION }}
           channel: ${{ steps.fvm-config-action.outputs.FLUTTER_CHANNEL }}
+      - name: Install Melos
+        run: dart pub global activate melos
+      - name: Bootstrap packages
+        run: melos bootstrap
       - name: Check formatting
         run: dart format --set-exit-if-changed .
 

examples/lib/api/context_variants/selected.dart

@@ -30,10 +30,7 @@ class _ExampleState extends State<Example> {
         .height(100)
         .width(100)
         .borderRounded(10)
-        .variant(
-          ContextVariant.widgetState(.selected),
-          .color(Colors.blue),
-        );
+        .variant(ContextVariant.widgetState(.selected), .color(Colors.blue));
 
     return Pressable(
       onPress: () {

examples/lib/api/context_variants/selected_toggle.dart

@@ -48,10 +48,7 @@ class _ExampleState extends State<Example> {
         .fontSize(16)
         .fontWeight(.w600)
         .color(Colors.grey.shade700)
-        .variant(
-          ContextVariant.widgetState(.selected),
-          .color(Colors.white),
-        );
+        .variant(ContextVariant.widgetState(.selected), .color(Colors.white));
 
     return Pressable(
       onPress: () {

examples/lib/api/default_widgets/default_styled_text.dart

@@ -32,9 +32,7 @@ class Example extends StatelessWidget {
             StyledText('hello world'),
             StyledText(
               'Mix is awesome',
-              style: TextStyler().onHovered(
-                .color(Colors.deepPurple),
-              ),
+              style: TextStyler().onHovered(.color(Colors.deepPurple)),
             ),
             StyledIcon(icon: Icons.ac_unit),
           ],

examples/lib/api/ecosystem/tw_card_alert.dart

@@ -83,4 +83,5 @@ class Example extends StatelessWidget {
     );
   }
 }
+
 // #enddocregion example

examples/lib/components/chip_button.dart

@@ -13,10 +13,7 @@ final chipButtonContainer = BoxStyler()
     .color(Colors.blue)
     .borderRounded(20)
     .onHovered(.color(Colors.blue.shade700))
-    .variant(
-      ContextVariant.widgetState(.selected),
-      .color(Colors.black),
-    )
+    .variant(ContextVariant.widgetState(.selected), .color(Colors.black))
     .alignment(.center)
     .animate(.easeInOut(300.ms));
 

examples/lib/docs/guides/animations.dart

@@ -85,10 +85,7 @@ class _Section extends StatelessWidget {
       children: [
         Text(
           title,
-          style: const TextStyle(
-            fontSize: 18,
-            fontWeight: FontWeight.bold,
-          ),
+          style: const TextStyle(fontSize: 18, fontWeight: FontWeight.bold),
         ),
         const SizedBox(height: 12),
         ...children,
@@ -113,10 +110,7 @@ class _Card extends StatelessWidget {
         children: [
           Text(
             title,
-            style: const TextStyle(
-              fontSize: 14,
-              fontWeight: FontWeight.w500,
-            ),
+            style: const TextStyle(fontSize: 14, fontWeight: FontWeight.w500),
           ),
           const SizedBox(height: 8),
           child,

examples/lib/docs/guides/animations/implicit_state_counter.dart

@@ -24,7 +24,8 @@ class ImplicitStateCounterExample extends StatefulWidget {
       _ImplicitStateCounterExampleState();
 }
 
-class _ImplicitStateCounterExampleState extends State<ImplicitStateCounterExample> {
+class _ImplicitStateCounterExampleState
+    extends State<ImplicitStateCounterExample> {
   int _counter = 2;
 
   @override

examples/lib/docs/guides/styling.dart

@@ -5,7 +5,11 @@ import 'package:mix/mix.dart';
 
 void main() {
   // 1
-  final style = BoxStyler().width(240).height(100).color(Colors.blue).borderRounded(12);
+  final style = BoxStyler()
+      .width(240)
+      .height(100)
+      .color(Colors.blue)
+      .borderRounded(12);
 
   // 2
   final base = BoxStyler()

examples/lib/docs/guides/variants.dart

@@ -23,7 +23,11 @@ void main() {
 
   final styleB = styleA.onHovered(.color(Colors.green));
 
-  final result = BoxStyler().color(Colors.green).height(100).width(200).borderRounded(10);
+  final result = BoxStyler()
+      .color(Colors.green)
+      .height(100)
+      .width(200)
+      .borderRounded(10);
 
   // 3
   final hoverStyle = BoxStyler()

examples/lib/docs/overview/index.dart

@@ -28,9 +28,16 @@ class Example extends StatelessWidget {
 }
 
 // 1
-final boxStyle = BoxStyler().height(100).width(100).color(Colors.purple).borderRounded(10);
+final boxStyle = BoxStyler()
+    .height(100)
+    .width(100)
+    .color(Colors.purple)
+    .borderRounded(10);
 
-final textStyle = TextStyler().fontSize(20).fontWeight(.bold).color(Colors.black);
+final textStyle = TextStyler()
+    .fontSize(20)
+    .fontWeight(.bold)
+    .color(Colors.black);
 
 // 2
 final buttonStyle = BoxStyler()

examples/lib/preview_registry.dart

@@ -3,8 +3,10 @@ import 'package:flutter/widgets.dart';
 import 'api/ecosystem/tw_card_alert.dart' as tw_card_alert;
 import 'api/animation/implicit.curved.scale.dart' as auto_scale;
 import 'api/animation/implicit.spring.translate.dart' as spring_anim;
-import 'docs/guides/animations/implicit_state_counter.dart' as guide_implicit_counter;
-import 'docs/guides/animations/implicit_variant_hover.dart' as guide_implicit_hover;
+import 'docs/guides/animations/implicit_state_counter.dart'
+    as guide_implicit_counter;
+import 'docs/guides/animations/implicit_variant_hover.dart'
+    as guide_implicit_hover;
 import 'docs/guides/animations/keyframe_loop.dart' as guide_keyframe_loop;
 import 'docs/guides/animations/keyframe_switch.dart' as guide_keyframe_switch;
 import 'docs/guides/animations/phase_tap_compress.dart' as guide_phase_tap;
@@ -262,15 +264,18 @@ class PreviewRegistry {
     // Animations (guides — match animations.mdx)
     PreviewEntry(
       previewId: 'implicit-anim-counter',
-      sourcePath: 'examples/lib/docs/guides/animations/implicit_state_counter.dart',
+      sourcePath:
+          'examples/lib/docs/guides/animations/implicit_state_counter.dart',
       title: 'State-triggered Implicit Animation',
       description: 'Square grows each time you tap it',
       category: _animations,
-      builder: (_) => const guide_implicit_counter.ImplicitStateCounterExample(),
+      builder: (_) =>
+          const guide_implicit_counter.ImplicitStateCounterExample(),
     ),
     PreviewEntry(
       previewId: 'anim-hover-scale',
-      sourcePath: 'examples/lib/docs/guides/animations/implicit_variant_hover.dart',
+      sourcePath:
+          'examples/lib/docs/guides/animations/implicit_variant_hover.dart',
       title: 'Hover Scale Animation',
       description: 'Box that scales up smoothly when hovered',
       category: _animations,

guides/styler-api-guidelines.md

@@ -82,7 +82,7 @@ These are used mid-chain or at the end. They should remain as instance methods:
 | Modifiers | `wrap`, `phaseAnimation`, `keyframeAnimation` |
 | Compound spacing | `padding(.all(8))`, `padding(.horizontal(8))`, `padding(.vertical(8))`, `margin(.all(8))`, `margin(.horizontal(8))`, `margin(.vertical(8))`, `padding(.only(left: 8, right: 8))` |
 | Compound border | `border(.all())`, `border(.top())`, `borderRadius(.circular())` |
-| Compound box methods | `shadow(.color(...).blurRadius(...))`, `backgroundImageUrl` |
+| Compound box methods | `backgroundImageUrl` |
 | Text directives | `uppercase`, `titlecase`, `sentencecase`, `reverse` |
 | Variants | `onHovered`, `onPressed`, `onDark`, `onLight`, `onDisabled`, `onFocused`, `variant`, `onBreakpoint` |
 

packages/mix/lib/src/animation/animation_config.dart

@@ -310,21 +310,18 @@ sealed class AnimationConfig {
   const AnimationConfig();
 
   /// Creates animation data with default settings.
-  static CurveAnimationConfig withDefaults() {
-    return const CurveAnimationConfig(
-      duration: kDefaultAnimationDuration,
-      curve: Curves.linear,
-    );
-  }
+  factory AnimationConfig.withDefaults() => const CurveAnimationConfig(
+    duration: kDefaultAnimationDuration,
+    curve: Curves.linear,
+  );
 
   /// Creates a spring animation configuration with standard spring physics.
-  static SpringAnimationConfig springDescription({
+  factory AnimationConfig.springDescription({
     double mass = 1.0,
     double stiffness = 180.0,
     double damping = 12.0,
-    // Duration delay = Duration.zero,
     VoidCallback? onEnd,
-  }) => .new(
+  }) => SpringAnimationConfig(
     spring: SpringDescription(
       mass: mass,
       stiffness: stiffness,
@@ -333,33 +330,126 @@ sealed class AnimationConfig {
     onEnd: onEnd,
   );
 
-  static SpringAnimationConfig spring(
+  factory AnimationConfig.spring(
     Duration duration, {
     double bounce = 0,
-    // Duration delay = Duration.zero,
     VoidCallback? onEnd,
-  }) => .new(
+  }) => SpringAnimationConfig(
     spring: SpringDescription.withDurationAndBounce(
       duration: duration,
       bounce: bounce,
     ),
     onEnd: onEnd,
   );
 
-  static SpringAnimationConfig springWithDampingRatio({
+  factory AnimationConfig.springWithDampingRatio({
     double mass = 1.0,
     double stiffness = 180.0,
     double dampingRatio = 0.8,
-    // Duration delay = Duration.zero,
     VoidCallback? onEnd,
-  }) => .new(
+  }) => SpringAnimationConfig(
     spring: SpringDescription.withDampingRatio(
       mass: mass,
       stiffness: stiffness,
       ratio: dampingRatio,
     ),
     onEnd: onEnd,
   );
+
+  /// Creates a curve-based spring animation with duration and bounce.
+  factory AnimationConfig.springDurationBased(
+    Duration duration, {
+    double bounce = 0.0,
+    Duration delay = .zero,
+    VoidCallback? onEnd,
+  }) => CurveAnimationConfig.springDurationBased(
+    duration,
+    bounce: bounce,
+    delay: delay,
+    onEnd: onEnd,
+  );
+
+  /// Creates a curve-based spring animation with explicit physics parameters.
+  factory AnimationConfig.curveSpring(
+    Duration duration, {
+    double mass = 1.0,
+    double stiffness = 180.0,
+    double damping = 12.0,
+    Duration delay = .zero,
+    VoidCallback? onEnd,
+  }) => CurveAnimationConfig.spring(
+    duration,
+    mass: mass,
+    stiffness: stiffness,
+    damping: damping,
+    delay: delay,
+    onEnd: onEnd,
+  );
+
+  /// Creates a curve-based spring animation with damping ratio.
+  factory AnimationConfig.curveSpringWithDampingRatio(
+    Duration duration, {
+    double mass = 1.0,
+    double stiffness = 180.0,
+    double ratio = 0.8,
+    Duration delay = .zero,
+    VoidCallback? onEnd,
+  }) => CurveAnimationConfig.springWithDampingRatio(
+    duration,
+    mass: mass,
+    stiffness: stiffness,
+    ratio: ratio,
+    delay: delay,
+    onEnd: onEnd,
+  );
+
+  /// Creates a spring animation with standard physics parameters.
+  factory AnimationConfig.springStandard({
+    double mass = 1.0,
+    double stiffness = 180.0,
+    double damping = 12.0,
+    VoidCallback? onEnd,
+  }) => SpringAnimationConfig.standard(
+    mass: mass,
+    stiffness: stiffness,
+    damping: damping,
+    onEnd: onEnd,
+  );
+
+  /// Creates a spring animation with duration and bounce.
+  factory AnimationConfig.springWithDurationAndBounce({
+    Duration duration = const Duration(milliseconds: 500),
+    double bounce = 0.0,
+    VoidCallback? onEnd,
+  }) => SpringAnimationConfig.withDurationAndBounce(
+    duration: duration,
+    bounce: bounce,
+    onEnd: onEnd,
+  );
+
+  /// Creates a critically damped spring animation.
+  factory AnimationConfig.springCriticallyDamped({
+    double mass = 1.0,
+    double stiffness = 180.0,
+    VoidCallback? onEnd,
+  }) => SpringAnimationConfig.criticallyDamped(
+    mass: mass,
+    stiffness: stiffness,
+    onEnd: onEnd,
+  );
+
+  /// Creates an under-damped (bouncy) spring animation.
+  factory AnimationConfig.springUnderdamped({
+    double mass = 1.0,
+    double stiffness = 180.0,
+    double ratio = 0.5,
+    VoidCallback? onEnd,
+  }) => SpringAnimationConfig.underdamped(
+    mass: mass,
+    stiffness: stiffness,
+    ratio: ratio,
+    onEnd: onEnd,
+  );
 }
 
 /// Curve-based animation configuration with fixed duration.