Skip to main content

utopia_ui_tools 0.1.0 copy "utopia_ui_tools: ^0.1.0" to clipboard
utopia_ui_tools: ^0.1.0 copied to clipboard

CLI for the utopia_ui design protocol: validate design tokens, generate the Flutter theme, HTML twin and component manifest, and catch design drift in CI.

Utopia UI Tools

pub publisher license style: utopia_lints

utopia_ui_tools #

Command-line tooling for the Utopia Design Protocol: token validation and repair, theme and design-surface codegen, and component-manifest generation for Flutter apps built on utopia_ui.

It is what keeps an AI-assisted design workflow honest: the token document, the generated Flutter theme, the HTML twin and the component manifest are checked against each other, so a design that drifts from the code - or code that drifts from the design - fails a command instead of reaching review.

Install as a dev dependency in a project that uses utopia_ui:

flutter pub add --dev utopia_ui_tools

Every command follows one contract: exit 0 = success, 1 = validation/generation failure (findings on stdout, one per line, ERROR <path>: <message> / WARN <path>: <message>, summary last), 2 = usage or I/O error. Every command accepts --json for machine-readable output. Generated files are deterministic: the same input produces byte-identical output.

Consumer commands (run inside your project) #

Command What it does
dart run utopia_ui_tools:validate_tokens Validates design/tokens.json against the protocol gates (schema, aliases, scale coherence, color coherence). --fix mechanically repairs base-unit derivations and color hex after a rescale. Prints a bootstrap copy command when no token document exists yet.
dart run utopia_ui_tools:generate_theme Generates lib/theme/utopia_theme.g.dart with a buildUtopiaTheme() factory from your token document. Validates first; refuses to write on errors. Wire it: UtopiaTheme(data: buildUtopiaTheme(), child: ...).
dart run utopia_ui_tools:generate_twin Regenerates the design surface (tokens.css, tokens.tailwind.css, DESIGN.md front matter) from your token document into ./twin.
dart run utopia_ui_tools:validate_twin Lints a twin bundle: token-literal violations in hand-authored CSS, component-id coverage against the manifest, tokens.css freshness. On a generated-only twin (no components.html) the coverage gate auto-skips.
dart run utopia_ui_tools:validate_manifest Validates a component manifest; with zero arguments it checks the shipped utopia_ui manifest against your resolved package version (the drift gate). Point it at design/merged.manifest.json to validate a merged view.
dart run utopia_ui_tools:generate_manifest --project Registers your project's custom components (opt-in via design/overlay/<component>.yaml) and writes design/project.manifest.json plus the merged view design/merged.manifest.json for design tools.

Maintainer commands (require the utopia-ui repo checkout) #

Command What it does
dart run utopia_ui_tools:export_tokens Exports UtopiaThemeData.defaultTheme to the canonical tokens/utopia.tokens.json (captures live values via flutter test, so it needs the Flutter SDK and this repo).
dart run utopia_ui_tools:generate_manifest Regenerates the shipped component manifest from lib/ + the curated overlays.
tool/utopia_ui_tools/smoke/run.sh The end-to-end smoke harness (in-repo pass, CLI regression, external-app e2e, screenshot captures).

Where the contracts live #

The protocol artifacts themselves (canonical token document, component manifest, HTML twin) ship inside the utopia_ui package and are resolved from your pub cache - these tools find them through .dart_tool/package_config.json, no configuration needed.

Package What it adds
utopia_ui The design system these tools validate and generate for
utopia_hooks State management with hooks
utopia_arch The full architecture bundle

Built by Utopiasoft.

License #

BSD-3-Clause. See LICENSE.

4
likes
140
points
345
downloads

Documentation

API reference

Publisher

unverified uploader

Weekly Downloads

CLI for the utopia_ui design protocol: validate design tokens, generate the Flutter theme, HTML twin and component manifest, and catch design drift in CI.

Repository (GitHub)
View/report issues

Topics

#design-tokens #design-system #cli #codegen

License

BSD-3-Clause (license)

Dependencies

analyzer, args, dart_style, flutter, json_schema, path, utopia_ui, yaml

More

Packages that depend on utopia_ui_tools