Theme Kit

Create themes you'll enjoy using 🎨.

Version 3.0 - Complete rewrite with CLI-based code generation (no Mason bricks required!)

🎉 New to Theme Kit 3.0? Check out What's New for a complete overview of changes.

🚀 Want to get started quickly? See the Quick Start Guide.

📚 Need detailed API documentation? Check the API Reference.

🔄 Migrating from 2.x? Read the Migration Guide.

Features ✨

✅ Easy to set dark and light themes.
✅ Use your own custom theme tokens on top of Material Design.
✅ Import your theme and seamlessly apply it to Material components.
✅ Enjoy autocompletion for every theme token.
✅ Fully customizable, the generated code is editable and yours!
✅ Includes definition of colors, text styles, font families and font weights.
✅ No dependencies required in your generated theme.
✅ No build runner needed 😉.
✅ Simple YAML configuration.
✅ CLI-based code generation (like flutter_flavorizr).

Getting Started 🚀

Installation

Add theme_kit as a dev dependency in your Flutter project:

flutter pub add --dev theme_kit

Or add it manually to your pubspec.yaml:

dev_dependencies:
  theme_kit: ^3.0.0

Configuration

Create a theme_kit.yaml file in the root of your project:

# Theme name (will be converted to snake_case for file names)
name: my_theme

# Prefix for generated classes (recommended 2-3 characters)
prefix: mt

# Optional description
description: My custom theme for Flutter app

# Font families to include in the theme
font_families:
  - Inter
  - Poppins

# Font weights to include
font_weights:
  - name: regular
    weight: 400
  - name: medium
    weight: 500
  - name: semibold
    weight: 600
  - name: bold
    weight: 700

# Color tokens for the theme
colors:
  primary:
    description: Primary brand color
  secondary:
    description: Secondary brand color
  success:
    description: Success state color
  warning:
    description: Warning state color
  error:
    description: Error state color
  background:
    description: Background color
  textPrimary:
    description: Primary text color
  textSecondary:
    description: Secondary text color

# Text styles with default font sizes
text_styles:
  - name: displayXL
    font_size: 48.0
  - name: displayL
    font_size: 36.0
  - name: bodyM
    font_size: 16.0
  - name: bodyS
    font_size: 14.0

Generate Your Theme

Run the generator:

dart run theme_kit:generate

Or with custom options:

dart run theme_kit:generate --config my_config.yaml --output lib/theme

Use Your Theme

Define your theme colors:

import 'package:flutter/material.dart';
import 'package:my_app/theme/my_theme.dart';

final lightTheme = MTTheme(
  primary: Colors.blue,
  secondary: Colors.blueGrey[200],
  success: Colors.green,
  warning: Colors.yellow,
  error: Colors.red,
  background: Colors.white,
  textPrimary: Colors.black,
  textSecondary: Colors.grey,
);

final darkTheme = MTTheme(
  primary: Colors.blue,
  secondary: Colors.blueGrey[700],
  success: Colors.green,
  warning: Colors.yellow,
  error: Colors.red,
  background: Colors.black,
  textPrimary: Colors.white,
  textSecondary: Colors.grey[400],
);

Wrap your app with the theme:

void main() {
  runApp(
    MyTheme(
      lightTheme: lightTheme,
      darkTheme: darkTheme,
      child: MaterialApp(
        title: 'My App',
        home: HomePage(),
      ),
    ),
  );
}

Use theme colors and text styles:

class HomePage extends StatelessWidget {
  @override
  Widget build(BuildContext context) {
    return Scaffold(
      backgroundColor: MTColor.background,
      body: Column(
        children: [
          MTText.displayXL("Hello World").styles(
            color: MTColor.primary,
          ),
          MTText.bodyM("This is body text").styles(
            color: MTColor.textPrimary,
          ),
          ElevatedButton(
            child: MTText.bodyM("Switch to Dark Theme"),
            onPressed: () {
              MyTheme.setDarkTheme();
            },
          ),
        ],
      ),
    );
  }
}

Generated Files 📁

The generator creates the following file structure (using my_theme and mt prefix as example):

lib/theme/
├── my_theme.dart              # Main export file
├── USAGE.md                   # Usage documentation
└── src/
    ├── colors/
    │   ├── mt_color.dart      # Color token accessors
    │   └── mt_theme.dart      # Theme configuration class
    ├── typography/
    │   ├── mt_font_family.dart # Font family constants
    │   ├── mt_font_weight.dart # Font weight constants
    │   └── mt_text.dart        # Text widget with styles
    └── theme/
        └── my_theme.dart       # Main theme InheritedWidget

CLI Options

Usage: dart run theme_kit:generate [options]

Options:
  -c, --config    Path to the theme configuration file
                  (defaults to "theme_kit.yaml")
  -o, --output    Output directory for generated theme files
                  (defaults to "lib/theme")
  -h, --help      Display this help message

Example:
  dart run theme_kit:generate
  dart run theme_kit:generate --config my_theme.yaml --output lib/gen

Configuration Reference

Basic Configuration

# Required: Name of your theme
name: my_theme

# Required: Prefix for generated classes (2-3 characters recommended)
prefix: mt

# Optional: Description of your theme
description: My custom app theme

Font Configuration

# Define available font families
font_families:
  - Inter
  - Poppins
  - Roboto

# Define font weights with their numeric values
font_weights:
  - name: regular
    weight: 400
  - name: medium
    weight: 500
  - name: semibold
    weight: 600
  - name: bold
    weight: 700

Color Configuration

colors:
  primary:
    description: Primary brand color
  secondary:
    description: Secondary brand color
  # Add as many colors as needed
  customColor:
    description: My custom color token

Text Style Configuration

text_styles:
  - name: displayXL
    font_size: 48.0
  - name: bodyM
    font_size: 16.0
  # Add as many text styles as needed

Advanced Usage

Custom Output Directory

Generate theme files in a custom location:

dart run theme_kit:generate --output packages/my_theme/lib

Multiple Configurations

You can maintain different theme configurations for different projects or variants:

dart run theme_kit:generate --config themes/light_theme.yaml --output lib/themes/light
dart run theme_kit:generate --config themes/dark_theme.yaml --output lib/themes/dark

Using in Package Projects

Theme Kit works great for creating reusable theme packages:

Create a new package:

flutter create --template=package my_company_theme

Add theme_kit as dev dependency
Create theme_kit.yaml in package root
Generate theme with --output lib
Publish your theme package

Best Practices

Preventing Theme Widget Mixing with Lints

When using Theme Kit, it's common to accidentally use raw Flutter widgets instead of your theme-specific widgets (e.g., using Text or Color instead of MTText or MTColor). The leancode_lint package provides lint rules to prevent this and enforce consistent design system usage. It can also help prevent mixing widgets from different themes in projects that use multiple themes.

Installation

Add leancode_lint and custom_lint to your dev dependencies:

dev_dependencies:
  leancode_lint: ^19.0.0
  custom_lint: ^0.8.0

Then run:

flutter pub get

Configuration

Configure the use_design_system_item rule in your analysis_options.yaml to enforce usage of your theme widgets:

include: package:flutter_lints/flutter.yaml

analyzer:
  plugins:
    - custom_lint

custom_lint:
  rules:
    use_design_system_item:
      # Enforce MTText instead of plain Text widget
      - preferredItem: MTText
        instead_of: Text
      # Enforce MTColor instead of Colors or hardcoded colors
      - preferredItem: MTColor
        instead_of: Colors
      # Add more mappings as needed for your theme

What This Catches

The lint rule will warn you when:

Using Text directly instead of your theme's text widget (MTText, ATText, etc.)
Using Colors or hardcoded colors instead of your theme's color tokens (MTColor, ATColor, etc.)
Mixing widgets from different themes (configure multiple rules for each theme)

Example

❌ Bad - Using raw Flutter widgets:

Text('Hello World', style: TextStyle(color: Colors.blue));

✅ Good - Using theme widgets:

MTText.bodyM('Hello World').styles(color: MTColor.primary);

Benefits

Consistency: Ensures all UI elements use your design system
Type Safety: Prevents mixing widgets from different themes
Maintainability: Makes theme updates easier by catching all usages
Team Alignment: Helps new team members follow the correct patterns

For more information about leancode_lint and its rules, visit the package documentation.

Migration from 2.x

If you're upgrading from theme_kit 2.x (Mason bricks), here are the key changes:

What Changed

2.x (Mason)	3.0 (CLI)
`mason make theme_kit`	`dart run theme_kit:generate`
Mason brick dependency	Dev dependency only
Interactive prompts	YAML configuration
Creates package structure	Generates files only
Requires Mason installed	Works with dart/flutter only

Migration Steps

Remove Mason dependencies:

# Remove from pubspec.yaml
# No need for mason_cli anymore

Add theme_kit 3.0:
```
dev_dependencies:
  theme_kit: ^3.0.0
```

Create configuration file (theme_kit.yaml):

name: my_theme  # Same as before
prefix: mt      # Same as before

# Copy your previous configuration here
font_families: [Inter, Poppins]
# ... other settings

Generate theme:

dart run theme_kit:generate --output lib

Update imports:
- If you generated in a different location, update your import paths
- The generated file structure is the same, just the location may differ

Benefits of 3.0

✅ No external tools required (no Mason installation)
✅ Version-controlled configuration (YAML file)
✅ Easier CI/CD integration
✅ More flexible output location
✅ Simpler workflow
✅ Better for team collaboration

Troubleshooting

For detailed troubleshooting steps, see TROUBLESHOOTING.md.

"Configuration file not found"

Make sure theme_kit.yaml exists in your project root, or specify the path:

dart run theme_kit:generate --config path/to/config.yaml

"The method 'generate' isn't defined for the class"

Make sure you've run the theme generator before trying to use the theme:

dart run theme_kit:generate

Generated files not found in IDE

After generating, restart your IDE or run:

flutter pub get

Import errors

Ensure your imports match the generated file location:

// If generated in lib/theme/ (default)
import 'theme/my_theme.dart';

// If generated in custom location
import 'custom/path/my_theme.dart';

For more issues and solutions, see the complete troubleshooting guide.

FAQ

Q: Do I need Mason installed?
A: No! Version 3.0 doesn't require Mason at all. Just add theme_kit as a dev dependency.

Q: Can I customize the generated code?
A: Yes! The generated code is yours to modify. However, regenerating will overwrite your changes.

Q: How do I add new colors after generation?
A: Update your theme_kit.yaml and regenerate. You'll need to update your theme definitions in your app too.

Q: Can I use this in production?
A: Yes! Theme Kit generates production-ready code with no runtime dependencies.

Q: Does this work with Flutter Web/Desktop?
A: Yes! Theme Kit generates pure Dart/Flutter code that works on all platforms.

Q: Can I have multiple themes in one app?
A: Yes! Generate multiple configurations with different --output directories.

Q: How do I update to a new version of Theme Kit?
A: Update the dependency, then regenerate your theme. Review the CHANGELOG for any breaking changes.

Examples

Check out the /example directory for a complete working example.

Contributing

We welcome contributions! Please see CONTRIBUTING.md for guidelines.

Support

Changelog

See CHANGELOG.md for version history and updates.

MIT License

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

Name		Name	Last commit message	Last commit date
Latest commit History 67 Commits
.vscode		.vscode
bin		bin
examples		examples
lib		lib
test		test
.fvmrc		.fvmrc
.gitignore		.gitignore
.metadata		.metadata
API.md		API.md
CHANGELOG.md		CHANGELOG.md
CODE_QUALITY_REVIEW.md		CODE_QUALITY_REVIEW.md
CODE_REVISION_SUMMARY.md		CODE_REVISION_SUMMARY.md
CONTRIBUTING.md		CONTRIBUTING.md
FLAWS_FIXED.md		FLAWS_FIXED.md
LICENSE		LICENSE
MIGRATION.md		MIGRATION.md
MIGRATION_SUMMARY.md		MIGRATION_SUMMARY.md
QUICKSTART.md		QUICKSTART.md
README.md		README.md
TROUBLESHOOTING.md		TROUBLESHOOTING.md
WHATS_NEW.md		WHATS_NEW.md
analysis_options.yaml		analysis_options.yaml
check.sh		check.sh
pubspec.yaml		pubspec.yaml
theme_kit.yaml		theme_kit.yaml

License

RaulColino/theme_kit

Folders and files

Latest commit

History

Repository files navigation

Theme Kit

Features ✨

Getting Started 🚀

Installation

Configuration

Generate Your Theme

Use Your Theme

Generated Files 📁

CLI Options

Configuration Reference

Basic Configuration

Font Configuration

Color Configuration

Text Style Configuration

Advanced Usage

Custom Output Directory

Multiple Configurations

Using in Package Projects

Best Practices

Preventing Theme Widget Mixing with Lints

Installation

Configuration

What This Catches

Example

Benefits

Migration from 2.x

What Changed

Migration Steps

Benefits of 3.0

Troubleshooting

"Configuration file not found"

"The method 'generate' isn't defined for the class"

Generated files not found in IDE

Import errors

FAQ

Examples

Contributing

Support

Changelog

About

Resources

License

Contributing

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Contributors 2

Uh oh!

Languages

Packages