Design & Test Synchronization

Shepherd Tag

Type-safe UI Interaction Contracts for Flutter. Bridge the gap between your Design System and Automated Tests.

Pub.dev Docs CLI

@ShepherdTag(
  id: 'US-001',
  description: 'Login flow'
)
class AuthTags {
  static const emailField = 'auth_email_field';
  static const submitBtn  = 'auth_submit_btn';
}

class LoginPage extends StatelessWidget {
  @override
  Widget build(BuildContext context) {
    return ShepherdPageKey(
      id: 'US-001',
      child: ShepherdElementKey(
        id: AuthTags.emailField,
        child: TextField(...)
      )
    );
  }
}

# Generate Maestro flow automatically
shepherd test gen --story US-001

// Generates: .maestro/flows/auth/us001_login.yaml

🏷️

@ShepherdTag

Annotates a contract/constants file with a story ID, linking code directly to business requirements.

🔑

ShepherdPageKey

Embeds the Story ID into the widget tree via Semantics, making it detectable by Maestro and the Shepherd CLI.

⚡

Zero Overhead

Zero runtime dependencies beyond the Flutter SDK. No impact on UI layout, behavior or performance.

How it Works

Define the Contract

Create a constants file and annotate it with the Story ID. This creates a source of truth for all interaction keys.

Wrap the UI

Use ShepherdPageKey and ShepherdElementKey to expose these identifiers to the automation suite.

Generate Tests

Run shepherd test gen to automatically create Maestro flows based on your annotated story IDs.

Ready to standardize your UI?

Get started with Shepherd Tag and never lose track of your UI interaction contracts.

dart pub add shepherd_tag