Nomo UI Kit Generator Assistant

An expert assistant for developing and maintaining the Nomo UI Kit Generator package, which provides build_runner generators for theme data, utilities, and reflection code generation in the NomoUIKit ecosystem.

Overview

This skill helps you work with a specialized Dart package that generates theme-related code for the Nomo UI Kit. The generator uses build_runner and source_gen to create theme data classes, utility functions, and reflection mappings from annotated source files.

Core Concepts

Generator Types

The package provides three main generators:

1. **Theme Data Builder** (`theme_data_builder`)

- Generates theme data classes from annotations

- Creates both nullable and non-nullable variants

- Outputs `*.theme_data.g.dart` files directly alongside source files

2. **Theme Utils Builder** (`theme_utils_builder`)

- Generates theme utility functions and extensions

- Outputs `*.theme_utils.g.part` files to cache

- Combined by source_gen

3. **Reflection Builder** (`reflection_builder`)

- Generates reflection data like icon mappings

- Outputs `*.reflection.g.part` files to cache

- Enables runtime lookups

Architecture

Key implementation files:

Instructions

When working with this package, follow these steps:

1. Understand the Context

First, identify what type of work you're doing:

2. Development Workflow

**Testing the generator:**

```bash

From generator package root

dart test

Build the generator

dart pub get

```

**Using in Nomo UI Kit:**

```bash

From nomo-ui-kit package root

flutter pub run build_runner build --delete-conflicting-outputs

Watch mode for active development

flutter pub run build_runner watch --delete-conflicting-outputs

```

3. Code Generation Flow

Understand the generation pipeline:

1. Annotated source files are scanned by model_visitor.dart

2. AST is parsed to extract properties and types

3. Generators create appropriate output:

- Nullable data classes (e.g., `NomoButtonColorDataNullable`)

- Non-nullable data classes with defaults (e.g., `NomoButtonColorData`)

- Combined theme data classes (e.g., `NomoButtonThemeData`)

- Extension methods and utility functions

4. Generated files are written to appropriate locations

5. Source_gen combines part files

4. Adding New Features

**To add a new annotation:**

1. Define it in `lib/annotations.dart`

2. Update `model_visitor.dart` to recognize it

3. Implement generation logic in appropriate generator

4. Add test coverage

5. Verify output in nomo-ui-kit

**To modify generation logic:**

1. Locate the relevant generator class

2. Update generation methods with proper null safety

3. Ensure imports are correctly generated

4. Test output compiles and works correctly

5. Verify backwards compatibility

5. Troubleshooting

**Generator not running:**

**Invalid generated code:**

**Build order issues:**

6. Best Practices

Always follow these principles:

7. Testing Changes

Complete testing checklist:

1. Run generator unit tests (`dart test`)

2. Run generator on nomo-ui-kit

3. Verify generated code compiles without errors

4. Check example app still works

5. Ensure no regression in existing components

6. Test with `--delete-conflicting-outputs` flag

8. Understanding Build Configuration

The `build.yaml` file controls:

Build order is critical: theme_data must generate before theme_utils.

Common Patterns

Generated Code Structure

For a component like NomoButton, the generator creates:

```dart

// Nullable variant for composition

class NomoButtonColorDataNullable {

final Color? backgroundColor;

final Color? foregroundColor;

// ...

}

// Non-nullable variant with defaults

class NomoButtonColorData implements NomoButtonColorDataNullable {

final Color backgroundColor;

final Color foregroundColor;

const NomoButtonColorData({

this.backgroundColor = Colors.blue,

this.foregroundColor = Colors.white,

});

NomoButtonColorData copyWith({...}) => ...;

}

// Similar structure for sizing

class NomoButtonSizingDataNullable { /* ... */ }

class NomoButtonSizingData implements NomoButtonSizingDataNullable { /* ... */ }

// Combined theme data

class NomoButtonThemeData {

final NomoButtonColorData color;

final NomoButtonSizingData sizing;

const NomoButtonThemeData({

required this.color,

required this.sizing,

});

}

```

Important Notes

Example Usage

When a developer asks you to help with this generator, you should:

1. Clarify what they want to accomplish

2. Identify which generator(s) are involved

3. Locate the relevant source files

4. Explain the generation flow for their use case

5. Provide specific code changes if needed

6. Guide them through testing the changes

7. Help troubleshoot any build or generation issues

Remember: This is a meta-development tool. You're helping developers build the tool that generates code for the UI kit, not building the UI kit itself.