Best Practices

How to get useful results when an agent writes stories in your project.

_Story, _Args, and _Scenario only exist after code generation. An agent writing against missing types produces code that does not compile, then guesses at fixes.

dart run build_runner watch

See Code Generation.

Write three to five stories by hand covering your real patterns: a widget with a callback, one with an enum, one screen with a mocked dependency. Point the agent at them.

Generic instructions produce generic stories. Your own files carry the conventions no prompt can state.

This is the same workflow the v4 Migration Guide uses.

Agents get these wrong without being told:

• Story variables start with $. The name minus $ becomes the display name.
• Every stories file needs a part 'name.stories.g.dart'; directive.
• Meta variables must be const. ComponentMeta with a docsBuilder must be final.
• Constructor parameters without a usable default must be passed in args.
• Callbacks belong in Arg.fixed(...), not an arg control.

Without Meta.argsType, the generator writes the builder for you. Custom args require a hand-written builder mapping args to the widget, which is more surface for an agent to get wrong.

Use custom args only when the constructor genuinely does not fit. See When to Use Custom Args.

Ask for a Scenario alongside each story. flutter test then captures a screenshot per state into build/.widgetbook.

This turns "the agent says it works" into an artifact you can look at.

Agents produce plausible stories for states that do not exist and skip the states that break. Check coverage against the widget's actual API: every enum value, every nullable path, empty and overflow content.