docs(website): Clean up and modernize all documentation examples by leoafarias · Pull Request #869 · btwld/mix

leoafarias · 2026-02-26T19:43:53Z

Summary

This PR removes internal Prop implementation details from user-facing documentation and standardizes all examples to use the fluent API. After comprehensive review of all 26 documentation pages, this update ensures users learn the correct public API without being exposed to internal plumbing.

Changes

Key Changes:

Removed internal Prop patterns from user-facing examples (introduction.mdx, design-token.mdx)
Fluent API is now the primary pattern across all docs (BoxStyler().color(...).padding(...))
Token call syntax used instead of Prop.token() ($primary() instead of Prop.token($primary))
Prop.value() / Prop.token() shown only in number directives context (.multiply(), .clamp())
Fixed animation API usage (springDurationBased has bounce parameter, not spring)
Consistent use of Dart 3.11+ dot-shorthand in typed contexts
Removed verbose class name prefixes (WidgetModifierConfig, AnimationConfig, BorderRadiusGeometryMix)

Files Modified: 20 documentation pages

Core guides: introduction.mdx, design-token.mdx, directives.mdx, animations.mdx, widget-modifiers.mdx
Tutorials: creating-a-widget.mdx, creating-context-variants.mdx, controlling-widget-state.mdx, theming.mdx
Widget guides: box.mdx, flexbox.mdx, stack.mdx, icon.mdx, image.mdx, text.mdx, stylewidgets.mdx
Overview pages: best-practices.mdx, getting-started.mdx, migration.mdx, utility-first.mdx

Test Plan

Verified all documentation examples follow the fluent API pattern
Confirmed no internal Prop patterns remain in user-facing docs
Tested dot-shorthand patterns resolve correctly in typed contexts
Cross-referenced against Mix 2.0 API and styler-api-policy.md

Verification Checklist

Documentation Updates: All examples use the fluent API with dot-shorthand where applicable
Consistency: Reviewed all 26 documentation pages for consistency
API Correctness: Verified animation methods and their parameters match actual API
No Breaking Changes: Documentation-only changes, no impact to code

…stently This comprehensive documentation update removes internal Prop implementation details from user-facing examples across 20 documentation pages. Changes ensure: - Fluent API is the primary pattern (BoxStyler().color(...).padding(...)) - Token call syntax is used instead of Prop.token() ($primary() instead of Prop.token($primary)) - Prop.value() / Prop.token() shown only in number directives context (.multiply(), .clamp()) - Corrected animation API usage (springDurationBased has bounce parameter, not spring) - Consistent use of Dart 3.11+ dot-shorthand in typed contexts - Removed verbose class name prefixes (WidgetModifierConfig, AnimationConfig, BorderRadiusGeometryMix) Files modified: - introduction.mdx: Removed Prop-Based API sections; fixed dot-shorthand - design-token.mdx: Removed Prop.token subsection - animations.mdx: Fixed spring() → springDurationBased() for bounce parameter - creating-a-widget.mdx: Replaced TextStyleMix wrapping with fluent API - widget-modifiers.mdx: Replaced Prop.token with token call syntax - Plus 15 additional documentation files for consistency pass This ensures users learn the correct public API without internal implementation details, improving documentation clarity and learning curve.

docs-page · 2026-02-26T19:43:59Z

To view this pull requests documentation preview, visit the following URL:

docs.page/btwld/mix~869

Documentation is deployed and generated using docs.page.

vercel · 2026-02-26T19:44:00Z

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
mix-docs	Ready	Preview, Comment	Feb 27, 2026 7:47pm

…details Remove .create()/Prop patterns from introduction and directives guide, fix build_runner command in tutorial, add frontmatter descriptions, fix code examples, and add frontmatter validation CI step.

The dart formatter needs package resolution to read the language version from pubspec.yaml. Without it, dot-shorthand syntax fails to parse.

…y across 24 pages - Fix pressable.mdx compile error (.border → .borderAll) - Fix introduction.mdx MixScope to use canonical typed maps pattern - Add missing H1 heading to introduction.mdx - Document elevation enum values in box.mdx - Document TextStyleToken.mix() pattern in design-token.mdx - Replace all "here" anchor text with descriptive links in stylewidgets.mdx - Add Related sections with internal links to all guide and widget pages - Add variant types disambiguation table in dynamic-styling.mdx - Document BoxStyler.create() vs BoxStyler() and style vs styleSpec in styling.mdx - Add auto-tracking scope table in controlling-widget-state.mdx - Add DEPRECATED markers to migration.mdx code blocks - Replace passive voice, marketing language, and colloquialisms across docs - Standardize to direct second-person voice (remove we/let's) - Expand widget meta descriptions to 150+ chars for SEO - Add prerequisites to tutorial pages - Fix image alt text in theming.mdx and creating-a-widget.mdx - Fix animations.mdx: remove non-standard id frontmatter, add imports - Fix utility-first.mdx: "Declarative Semantic" → "Declarative Semantics" - Add early development callout to mix-schema.mdx - Fix widget-modifiers.mdx: use custom ModifierMix in Step 3, add shorthand callout - Fix migration.mdx: use .wrap(.opacity()) shorthand instead of OpacityModifierMix - Fix comparison.mdx: use dot-shorthand in onHovered variant - Fix creating-context-variants.mdx: use dot-shorthand and arrow functions - Clean v2 API leakage from 0.0.7→1.0.0 migration table

- Fix .capitalize() description (capitalizes first letter only, not each word) - Fix BoxStyler.create(width:) examples that won't compile (width/height not valid params) - Replace sealed Variant subclassing with enum-based pattern in best-practices - Correct modifier ordering docs (framework enforces predefined order, not chain order) - Fix wrong mouse cursor (SystemMouseCursors.forbidden, not basic) in pressable - Fix broken GitHub links to removed deprecations.dart in migration - Fix missing semicolon syntax error in controlling-widget-state - Add $prefix token convention note to theming tutorial - Add MaterialApp wrapper to theme switching example - Convert old switch statements to switch expressions in creating-a-widget - Add BoxShadowMix explanatory comment - Fix [onBuilder] dartdoc syntax to backtick-quoted across 6 widget pages - Fix ModifierMix terminology to WidgetModifierConfig where appropriate - Fix comparison page heading hierarchy and colloquialisms

theming.mdx used <Callout> without importing it, causing the Next.js build to fail. Also run dart format on 8 example files flagged by CI.

…ar, update version - styling.mdx: Replace invalid width: parameter in BoxStyler.create() example with padding: (a valid .create() param) - _meta.js: Add missing StackBox entry to widgets sidebar navigation - getting-started.mdx: Update version from 2.0.0-rc.0 to 2.0.0-rc.1

Fix code examples to use correct Mix 2.0 API patterns (static styler access, BorderRadiusMix, EdgeInsetsGeometryMix, TextStyleMix), simplify modifier ordering docs, remove redundant description frontmatter and Related sections, and update creating-a-widget tutorial with switch statement syntax.

Copilot

Pull request overview

This PR modernizes all Mix documentation to consistently use the fluent Styler API pattern and adds proper frontmatter metadata to all documentation pages. The changes systematically replace internal Prop implementation details with public-facing fluent API patterns, ensuring users learn the correct API without being exposed to internal plumbing.

Changes:

Standardized all code examples to use BoxStyler() with parentheses followed by method chains (.color(), .padding(), etc.)
Added frontmatter blocks with title and description to 20 documentation pages for improved SEO and discoverability
Fixed animation API to use correct method name (springDurationBased with bounce parameter instead of spring)
Added frontmatter validation script and CI integration to enforce documentation metadata standards
Updated all examples to use Dart 3.11+ dot-shorthand syntax in typed contexts (.solid, .bold, etc.)
Replaced deprecated withOpacity() with withValues(alpha:) API

Reviewed changes

Copilot reviewed 43 out of 43 changed files in this pull request and generated no comments.

Show a summary per file

File	Description
website/src/content/documentation/widgets/*.mdx	Added frontmatter and standardized fluent API examples across all widget reference pages
website/src/content/documentation/tutorials/*.mdx	Added frontmatter and modernized tutorial examples with fluent API patterns
website/src/content/documentation/overview/*.mdx	Added frontmatter and updated all overview pages with consistent API patterns
website/src/content/documentation/guides/*.mdx	Added frontmatter and corrected animation API usage
website/src/content/documentation/ecosystem/*.mdx	Added frontmatter to ecosystem documentation
website/scripts/check-docs-frontmatter.mjs	New validation script to enforce frontmatter requirements
.github/workflows/*.yml	Integrated frontmatter validation and Melos bootstrap steps
website/package.json	Added `check:frontmatter` script
guides/documentation-quality-checklist.md	New quality checklist for documentation PRs
examples/lib/*/.dart	Reformatted code examples for consistency

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

…horthand support Convert static methods (spring, springDescription, springWithDampingRatio, withDefaults) to factory constructors and add new factories for all CurveAnimationConfig and SpringAnimationConfig spring variants so that Dart dot-shorthands resolve correctly when the expected type is AnimationConfig.

website/src/content/documentation/overview/comparison.mdx

website/src/content/documentation/overview/getting-started.mdx

website/src/content/documentation/overview/migration.mdx

website/src/content/documentation/tutorials/controlling-widget-state.mdx

- Use Duration extension shorthand (100.ms) in comparison.mdx examples - Fix Dart 3.11 explanation: required for factory bug fix, not where dot-shorthands were introduced - Replace hardcoded version pin with ^<latest> in getting-started.mdx - Clarify callable stylers description in migration.mdx - Remove SizedBox() placeholder child in controlling-widget-state.mdx

Copilot

Pull request overview

Copilot reviewed 45 out of 45 changed files in this pull request and generated 3 comments.

Comments suppressed due to low confidence (5)

website/src/content/documentation/overview/best-practices.mdx:36

This section still claims button.variant.dart contains a CustomButtonVariant class and Variant instances, but the updated “Defining Variants” section switches to plain Dart enums and no longer defines a Mix Variant type. Please reconcile the file-structure guidance with the new approach (either update/remove the button.variant.dart description, or reintroduce the Variant-based example).

- `button.dart` - This file will contain the CustomButton class and define the component's structure.

- `button.variant.dart` - Contains the CustomButtonVariant class and all its Variant instances.

website/src/content/documentation/widgets/stylewidgets.mdx:91

The new “Callable Pattern” snippet isn’t copy/pasteable Dart as written because the box(child: ...) call is missing a trailing semicolon. Please terminate the statement (or assign it to a variable) so the example compiles as-is.
website/src/content/documentation/widgets/stylewidgets.mdx:95
This callable example is missing a trailing semicolon after text('Hello'), which makes the snippet invalid Dart when copied. Please add the semicolon (or show it assigned to a widget variable).
website/src/content/documentation/widgets/stylewidgets.mdx:99
This callable example is missing a trailing semicolon after icon(...), which prevents copy/paste compilation. Please add the semicolon (or assign the result).
website/src/content/documentation/widgets/stylewidgets.mdx:86
The statement “All Styler classes support a callable pattern” appears too broad: some *Styler types (e.g., FlexStyler, StackStyler) don’t define a call operator. Consider rephrasing to explicitly scope this to widget stylers / StyleWidgets (e.g., BoxStyler, TextStyler, IconStyler, etc.).

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

Copilot · 2026-02-27T15:50:04Z

website/src/content/documentation/overview/getting-started.mdx

 ```yaml
 dependencies:
-  mix: ^2.0.0-rc.0
+  mix: ^<latest>


mix: ^<latest> isn’t valid YAML/version syntax and will confuse users. Please replace it with a concrete version constraint (e.g., the current stable/RC) or link to the pub.dev install instructions if you want to avoid hardcoding.

Suggested change

mix: ^<latest>

mix: ^2.0.0

Copilot · 2026-02-27T15:50:04Z

website/src/content/documentation/overview/migration.mdx

 | `Mix`   | `Style` |
-| `Mix.withVariant` | Use `.variant()` on Styler classes |
-| `Mix.withManyVariants` | Use multiple `.variant()` calls |
+| `Mix.withVariant` | `Style.withVariant()` |
+| `Mix.withManyVariants` | `Style.withManyVariants()` |


The migration table says Mix.withVariant / Mix.withManyVariants map to Style.withVariant() / Style.withManyVariants(), but there is no Style.withVariant API in packages/mix/lib/src/core/style.dart. This mapping looks incorrect; please update the doc to point to the actual v2 approach (e.g., .variant(...) on Styler classes / styles, depending on the intended target).

Copilot · 2026-02-27T15:50:05Z

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

@@ -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,
  );


Changing AnimationConfig.withDefaults()/springDescription()/spring()/springWithDampingRatio() from static ... methods returning concrete config types into factory AnimationConfig... constructors weakens the return type to AnimationConfig. This is a source-breaking API change for callers that previously relied on CurveAnimationConfig/SpringAnimationConfig members without casting. Consider keeping typed static helpers (possibly under different names) alongside the new factory wrappers, or provide typed alternatives so downstream code doesn’t need as CurveAnimationConfig / as SpringAnimationConfig.

…meter propagation tests Remove shadow from chain-only methods table since it already exists as a factory constructor. Add tests verifying AnimationConfig factories properly propagate parameter values, not just return types.

github-actions bot added the documentation Improvements or additions to documentation label Feb 26, 2026

vercel bot deployed to Preview February 26, 2026 19:46 View deployment

docs(website): improve documentation quality and remove internal API …

05c3d5a

…details Remove .create()/Prop patterns from introduction and directives guide, fix build_runner command in tutorial, add frontmatter descriptions, fix code examples, and add frontmatter validation CI step.

github-actions bot added the repo label Feb 26, 2026

vercel bot deployed to Preview February 26, 2026 20:32 View deployment

chore(examples): fix dart format violations

e3aad18

github-actions bot added the examples label Feb 26, 2026

vercel bot deployed to Preview February 26, 2026 20:45 View deployment

ci: bootstrap packages before format check for dot-shorthand support

3232658

The dart formatter needs package resolution to read the language version from pubspec.yaml. Without it, dot-shorthand syntax fails to parse.

vercel bot deployed to Preview February 26, 2026 22:03 View deployment

vercel bot deployed to Preview February 26, 2026 22:34 View deployment

vercel bot had a problem deploying to Preview February 26, 2026 22:58 Failure

fix(website): add missing Callout import and format Dart examples

da44f2c

theming.mdx used <Callout> without importing it, causing the Next.js build to fail. Also run dart format on 8 example files flagged by CI.

vercel bot deployed to Preview February 26, 2026 23:06 View deployment

vercel bot deployed to Preview February 26, 2026 23:20 View deployment

vercel bot deployed to Preview February 26, 2026 23:33 View deployment

docs(website): add missing docs frontmatter metadata

d32ecab

vercel bot deployed to Preview February 26, 2026 23:45 View deployment

leoafarias requested a review from Copilot February 27, 2026 14:48

Copilot started reviewing on behalf of leoafarias February 27, 2026 14:49 View session

Copilot AI reviewed Feb 27, 2026

View reviewed changes

github-actions bot added the mix label Feb 27, 2026

vercel bot deployed to Preview February 27, 2026 15:22 View deployment

leoafarias commented Feb 27, 2026

View reviewed changes

vercel bot deployed to Preview February 27, 2026 15:38 View deployment

leoafarias requested a review from Copilot February 27, 2026 15:41

Copilot started reviewing on behalf of leoafarias February 27, 2026 15:41 View session

Copilot AI reviewed Feb 27, 2026

View reviewed changes

vercel bot deployed to Preview February 27, 2026 16:27 View deployment

docs(website): fix migration API mappings and snippet validity

fe4e5c9

vercel bot deployed to Preview February 27, 2026 16:30 View deployment

test(mix): apply dart format to animation config tests

3842f03

vercel bot deployed to Preview February 27, 2026 19:29 View deployment

docs: remove documentation quality checklist guide

93d8304

vercel bot deployed to Preview February 27, 2026 19:47 View deployment

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

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

docs(website): Clean up and modernize all documentation examples#869
leoafarias wants to merge 16 commits intomainfrom
leoafarias/docs-website-improve

leoafarias commented Feb 26, 2026

Uh oh!

docs-page bot commented Feb 26, 2026

Uh oh!

vercel bot commented Feb 26, 2026 •

edited

Loading

Uh oh!

Copilot AI left a comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Copilot AI left a comment

Uh oh!

Copilot AI Feb 27, 2026

Uh oh!

Copilot AI Feb 27, 2026

Uh oh!

Copilot AI Feb 27, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Conversation

leoafarias commented Feb 26, 2026

Summary

Changes

Test Plan

Verification Checklist

Uh oh!

docs-page bot commented Feb 26, 2026

Uh oh!

vercel bot commented Feb 26, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Copilot AI Feb 27, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Feb 27, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Feb 27, 2026

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

vercel bot commented Feb 26, 2026 •

edited

Loading