utopia_ui 0.1.0
utopia_ui: ^0.1.0 copied to clipboard
A token-driven Flutter design system for AI and HTML design workflows: an HTML twin, a component manifest and design tokens keep every screen on reusable components.
utopia_ui #
A token-driven Flutter design system built for AI-assisted, HTML-based design workflows: every component ships with a machine-readable contract, so a screen designed in HTML by an AI designer lands in your app as the same reusable components - not as a pile of one-off widgets.

Motivation #
AI design tools think in HTML. Handing their output to a Flutter codebase usually ends one of two ways: someone re-implements the design by hand as screen-local widgets, or an agent translates it literally and the project fills up with near-duplicate buttons and hard-coded colors. Either way the design system erodes one screen at a time, and every later rebrand or redesign costs more than the last.
utopia_ui closes that gap with a contract both sides read, shipped inside the package and version-matched
to it:
- An HTML twin for the designer.
twin/renders every component from the same tokens as Flutter (above: Flutter left, twin right). An AI designer composes screens from real, id-tagged components instead of inventing markup, andtwin/DESIGN.mdtells it the rules. - A component manifest for the coding agent.
manifest/utopia.manifest.jsonlists every widget with a stable id, its props, states and token bindings. An agent looks up what already exists before it writes anything, and maps each element of a design to the widget that implements it. - Tokens instead of literals. No component hard-codes a color, gap or radius. A rebrand is a token edit
that the app and the twin both follow, and
validate_twinflags literal values in hand-written CSS. - Drift is a build failure. Tokens, manifest and twin are generated from the Flutter source, and CI regenerates and byte-compares them on every push - the contract cannot silently fall behind the code.
The payoff is maintainability: new screens are assembled from the same audited components, visual changes happen in one place, and a reviewer can tell from the manifest whether a design reuses the system or forks it.
Flexible by design #
A design system that keeps a project consistent must not also lock it in. utopia_ui is the visual layer and
nothing else - it imposes no architecture, data layer or navigation scheme, and every layer of it can be
extended rather than forked:
- No domain logic. It doesn't know what a
JsonMapis, doesn't assume a delegate or a backend, and ships no CRUD logic. Components are generic over your own model types (UtopiaTable<T>,UtopiaRadio<T>) and driven by plain values and callbacks. - Fully controlled. Components render state and report interaction; they never own app state. Keep it in
whatever state management you already use - helpers like
useUtopiaTableStateare opt-in. - No navigation opinions. The sidebar never pushes routes or closes its own drawer, and the dialog helpers
are thin wrappers over plain
showDialog. - Any brand, any scale. Swap the palette, re-derive the whole spatial scale from one base unit with
UtopiaTokens.fromBase,copyWithany slot, or re-theme a single subtree with a nestedUtopiaTheme. Every component also works zero-config, without aUtopiaThemeancestor, and the selection controls are Material-free, so a hostMaterialApptheme never leaks in. - Build your own on the same foundation. The tokens and field chrome are public API -
context.spacing,context.radius,context.fieldDecoration,UtopiaFieldWrapper- so a project-specific widget looks native to the system. Register it withgenerate_manifest --projectand it gets a stable id next to the library's own components, visible to the same agents and design tools.
If your project needs a themed table, button or dialog but has its own models, its own data layer and its own brand, you can adopt this package without forking it.
Install #
flutter pub add utopia_ui
or add it to pubspec.yaml directly:
dependencies:
utopia_ui: ^0.1.0
60-second start #
Wrap your app (or just the subtree that needs it) in a UtopiaTheme, then use any component from the barrel
import - everything renders correctly even without a UtopiaTheme ancestor, but wrapping one is how you brand it.
import 'package:flutter/material.dart';
import 'package:utopia_ui/utopia_ui.dart';
void main() => runApp(const MyApp());
class MyApp extends StatelessWidget {
const MyApp({super.key});
@override
Widget build(BuildContext context) {
return MaterialApp(
home: UtopiaTheme(
data: UtopiaThemeData.defaultTheme,
child: Scaffold(
body: Center(
child: UtopiaButton(
onTap: () {},
child: const Text('Get started'),
),
),
),
),
);
}
}
Design tokens & theming #
Every visual constant a component reads comes from one context-resolved root: UtopiaThemeData, carried by the
UtopiaTheme inherited widget. Components never hardcode a color, a font, a gap or a radius; if a component
needs a new visual constant, it's added to the token system, never inlined into a widget.
The token scale. All dimensional values derive from a single base unit, UtopiaTokens.x (4 logical pixels
by default). UtopiaTokens groups the foundational families:
| Family | Type | Steps |
|---|---|---|
spacing |
UtopiaSpacingTokens |
xxs 2 · xs 4 · sm 8 · md 12 · lg 16 · xl 24 · xxl 32 · xxxl 48 |
radius |
UtopiaRadiusTokens |
xs 4 · sm 6 · md 8 · lg 12 · xl 16 · full, each with a BorderRadius preset (smAll, ...) |
borders |
UtopiaBorderTokens |
hairline 1 · thin 1.5 · thick 2 |
shadows |
UtopiaShadowTokens |
sm · md · lg elevation presets |
fontWeights |
UtopiaFontWeightTokens |
regular · medium · semiBold · bold |
durations |
UtopiaDurationTokens |
xs 100ms · sm 150 · md 200 · lg 300 · xl 400 |
breakpoints |
UtopiaBreakpointTokens |
tabletMin 600 · webMin 900 · sidebarMin 1000 |
UtopiaTokens.fromBase(5) re-derives the spatial families from a new base - the whole system rescales from one
number. The token identifiers double as the canonical names for mirroring the scale into external tools (Figma
variables, CSS custom properties).
The theme. UtopiaThemeData carries the token scale plus the color and type families and a small set of
semantic slots - values that encode a design decision beyond "which token":
tokens- theUtopiaTokensscale abovecolors(UtopiaThemeColors) -primary,text,surface,border,hover,hint, ...textStyles(UtopiaThemeTextStyles) -header,title,text,label,button,captionborderRadius,cardRadius- which radius step controls and cards sit onfieldContentPadding,fieldMinHeight,pageTopPadding,tileHeight- field/page/table metrics
Pure token aliases (cardShadow, menuShadow, cardBorderWidth, dividerThickness, chipRadius) are derived
getters, so they always track tokens and can never go stale.
UtopiaThemeData.fromTokens(colors:, textStyles:, tokens:) is the canonical constructor - it derives every
dimensional slot from the token scale so the whole theme sits on one grid.
Distribution. UtopiaTheme is a plain InheritedWidget, like Theme or DefaultTextStyle - no provider
dependency:
UtopiaTheme.of(context)returns the closest ancestor'sUtopiaThemeData, silently falling back toUtopiaThemeData.defaultThemewhen there is none. Every component works zero-config.UtopiaTheme.maybeOf(context)returnsnullinstead of falling back, for callers that need to tell the two cases apart.- Nested
UtopiaThemes re-theme (or rescale) just their subtree.
Ergonomic lookups are context extensions, backed by UtopiaTheme.of:
context.theme; // UtopiaThemeData
context.colors; // UtopiaThemeColors
context.textStyles; // UtopiaThemeTextStyles
context.tokens; // UtopiaTokens
context.spacing; // UtopiaSpacingTokens e.g. context.spacing.md
context.radius; // UtopiaRadiusTokens e.g. context.radius.lgAll
context.fieldDecoration; // BoxDecoration for a field's background
To rebrand an app, construct your own UtopiaThemeData (via UtopiaThemeData.fromTokens(...) or
UtopiaThemeData.defaultTheme.copyWith(...)) and pass it to a UtopiaTheme at the root - every descendant
re-themes automatically.
Dark mode #
A theme is fully determined by its palette: the type family takes its three foreground tones from
colors.text / colors.textBody / colors.onPrimary, and every elevation preset is painted in
colors.shadow. Nothing else has to change, so dark mode is one line:
UtopiaTheme(
data: MediaQuery.platformBrightnessOf(context) == Brightness.dark
? UtopiaThemeData.darkTheme
: UtopiaThemeData.defaultTheme,
child: child,
)
A branded app writes its own dark palette instead of the shipped one - the type ramp and elevation follow it automatically:
final dark = UtopiaThemeData.fromTokens(colors: myDarkColors);
// Keeping a custom type ramp? Re-tint it rather than rebuilding it:
final branded = dark.copyWith(
textStyles: UtopiaThemeTextStyles.fromColors(myDarkColors, base: myTypeRamp),
);
Two things carry a dark ground that a light theme leaves to shadow: a stepped
canvas -> surface -> rowAlt -> hover ramp, and a border light enough to read (on a dark
ground "stronger" means lighter, so the light theme's border-darker-than-divider rule inverts).
UtopiaThemeColors.darkTheme is a worked example of both.
Design protocol #
utopia_ui is the reference implementation of the Utopia Design Protocol - the first open,
bidirectional design-system protocol for Flutter. A shared, generic contract (design tokens plus
stable component ids) lets a design surface and a Flutter app stay in sync in both directions,
instead of a one-way "design-to-code" handoff.
The Flutter app and the HTML twin render the same components from the same tokens. Rebrand the tokens and both surfaces follow - here the default theme becomes a pink gradient brand with one token edit:
The package ships three protocol artifacts, version-matched to the utopia_ui release you resolve:
- Tokens - a DTCG 2025.10 token document at
tokens/utopia.tokens.json, the canonical export of the default theme. - Manifest - a component registry at
manifest/utopia.manifest.jsonmapping everyutopia_uiwidget to a stable id, its props and its states. - Twin - a static HTML/CSS mirror of the component library at
twin/, for design tools and reviewers that never open Flutter.
The consumer loop #
- Bootstrap
design/tokens.jsonin your project via the command printed by the tools (a copy of the packaged default DTCG document). - Edit or rebrand it - change token values to match your brand. Color tokens carry both a
hexand matchingcomponentsvalues - edit both (validate_tokensnames the expected value when they disagree). - Validate it:
dart run utopia_ui_tools:validate_tokens(add--fixto re-derive rescaled values after changing the base unit). - Generate the theme and wire it:
dart run utopia_ui_tools:generate_theme, then pass the result to your root widget -UtopiaTheme(data: buildUtopiaTheme(), child: ...). - Optionally,
dart run utopia_ui_tools:generate_twinto re-derive the twin's generated stylesheets (tokens.css, a Tailwind variant,DESIGN.mdfront matter) from your tokens - pair them with the packaged twin's gallery/components HTML to view your brand (the sync skill documents the copy step), anddart run utopia_ui_tools:generate_manifest --projectto register your own custom components with stable ids alongside the library's.
v0 limits (roadmap) #
Stated up front, not discovered later:
- Single-context. The protocol carries one theme at a time - there is no dark-mode pairing
yet. A future version will add a second linked context. This is a protocol limit, not a
library one:
utopia_uishipsUtopiaThemeData.darkThemeand any palette re-themes the whole system (see Dark mode); what a single token document cannot yet do is carry the light and dark palettes together. Until it can, the token document drives the light theme (buildUtopiaTheme()) and the dark palette stays in Dart (UtopiaThemeData.darkThemeorUtopiaThemeData.fromTokens(colors: myDarkColors)). - Closed token tree. The token document covers
utopia_ui's own scale and slots. Project-specific values (a one-off brand color used nowhere else, a bespoke metric) live as plain constants in your project code; custom components earn a manifest id through the project manifest (generate_manifest --project), not by growing the shared token tree.
What is generated, what is hand-authored #
The repo carries both generator output and hand-curated design work; the split is explicit so "thousands of lines of JSON" reads as build product, not maintenance burden:
| Artifact | Provenance | Regenerated by |
|---|---|---|
tokens/utopia.tokens.json |
generated | export_tokens (from UtopiaThemeData.defaultTheme) |
manifest/utopia.manifest.json |
generated (prose from dartdoc + overlay/*.yaml) |
generate_manifest |
twin/tokens.css, twin/tokens.tailwind.css, DESIGN.md front matter |
generated | generate_twin |
twin/gallery.html |
composed - do not edit | generate_twin (from gallery.src.html + components.html) |
twin/components.html, twin/components.css, twin/gallery.src.html |
hand-authored | - (curated per SPEC 4.4/4.5) |
protocol/ (spec + schemas) |
hand-authored | - (normative) |
Generated files are marked linguist-generated in .gitattributes, and CI regenerates all
of them on every push and fails on any byte difference - a stale artifact cannot reach main.
Install the tools #
flutter pub add --dev utopia_ui_tools
See utopia_ui_tools for the full command list.
Learn more #
The table #
UtopiaTable<T> is a general-purpose, data-shape-agnostic table generic over a row type T of your choosing. It
is fully controlled: you pass rows, sort state and callbacks, and it renders and reports interaction - it never
owns app state itself. It's also sliver-first, so it composes into a CustomScrollView alongside your page's
other content rather than requiring its own scroll view.
Columns are declared as UtopiaTableEntry<T>:
UtopiaTableEntry<T>({
required Widget Function(BuildContext, T) cellBuilder,
String? id, // falls back to `title` via `effectiveId`
String? title,
int? flex = 2, // flexes like Expanded.flex
Comparable<Object?>? Function(T)? sortBy, // enables toggle-sort
String? Function(T)? searchBy, // enables client-side search
List<UtopiaTableSortOption<T>>? sortOptions, // named-orderings dropdown instead of a toggle
})
UtopiaTableEntry<T>.fixed({
required Widget Function(BuildContext, T) cellBuilder,
required double width, // fixed instead of flexing
// ... same optional fields as above
})
Sorting is controlled: UtopiaTable.currentSort (a ({String columnId, bool descending}) record) says which
column is active, and onSortPressed / onSortSelected report taps back to you. If you don't need
server-side sorting or search, the useUtopiaTableState hook gives you both for free, entirely client-side:
final tableState = useUtopiaTableState<TeamMember>(rows: members, entries: entries);
UtopiaTable<TeamMember>(
rows: tableState.visibleRows, // search-filtered, then sorted
entries: entries,
rowKey: (row) => row.name,
currentSort: tableState.currentSort,
onSortPressed: tableState.onSortPressed,
onSortSelected: tableState.onSortSelected,
searchPanel: UtopiaTableSearchPanel(
searchField: UtopiaSearchField(
value: tableState.searchState.value,
hint: 'Search by name or role',
onChanged: (value) => tableState.searchState.value = value ?? '',
),
),
)
rows: null renders a skeleton loader that mirrors the real row layout; an empty (non-null) list renders
emptyWidget (or UtopiaTableEmpty / a themed default "No items" message). Rows are matched across rebuilds by
rowKey, so reordering or inserting rows doesn't tear down unrelated row state.
Because it's a sliver, UtopiaTable is placed inside a CustomScrollView:
CustomScrollView(
slivers: [
SliverPadding(
padding: const EdgeInsets.fromLTRB(20, 16, 20, 20),
sliver: UtopiaTable<TeamMember>(
rows: tableState.visibleRows,
entries: entries,
rowKey: (row) => row.name,
currentSort: tableState.currentSort,
onSortPressed: tableState.onSortPressed,
),
),
],
)
Dialogs #
UtopiaDialog is adaptive dialog chrome: a full-screen surface on mobile widths, a centered rounded card
everywhere else - it resolves its own size class internally, so it works from any call site.
UtopiaDialog(title:, builder:)- the raw constructor, full control of the body below the title row.UtopiaDialog.form(title:, sliver:, bottom:)- the common case: a scrollable sliver of fields with a pinned bottom action bar.UtopiaConfirmDialog- a neutral confirm/cancel prefab (no baked-in copy; you supply your own strings).
UtopiaButton(
onTap: () => UtopiaDialog.show<void>(context, builder: (_) => const EditProfileDialog()),
child: const Text('Edit profile'),
);
class EditProfileDialog extends StatelessWidget {
const EditProfileDialog();
@override
Widget build(BuildContext context) {
return UtopiaDialog.form(
title: const Text('Edit profile'),
sliver: SliverPadding(
padding: const EdgeInsets.fromLTRB(20, 20, 20, 12),
sliver: SliverList.list(
children: [
UtopiaTextField(value: 'Ava Chen', label: const Text('Name'), onChanged: (_) {}),
const SizedBox(height: 14),
UtopiaSwitchField(value: true, title: 'Active', onChanged: (_) {}),
],
),
),
bottom: Padding(
padding: const EdgeInsets.fromLTRB(20, 12, 20, 20),
child: UtopiaButton(onTap: () => Navigator.of(context).maybePop(), child: const Text('Done')),
),
);
}
}
A confirm prompt is a one-liner:
final confirmed = await UtopiaConfirmDialog.show(
context,
title: 'Remove member?',
subtitle: 'This cannot be undone.',
confirmLabel: 'Remove',
);
Theme re-attachment. UtopiaDialog.show and UtopiaConfirmDialog.show are thin wrappers over vanilla
showDialog - the only navigation opinion they take is capturing UtopiaTheme.of(context) before pushing the
route and re-wrapping the pushed builder in a UtopiaTheme with that data. This matters because showDialog
roots its route at the app Navigator, outside of any UtopiaTheme ancestor in your widget tree - without the
re-attachment, the dialog subtree would silently fall back to UtopiaThemeData.defaultTheme instead of inheriting
whatever theme is scoped around the call site. If you push a dialog through some other route mechanism, do the
same: capture UtopiaTheme.of(context) and wrap your builder's result in a UtopiaTheme with it.
Sidebar #
UtopiaSidebar is an adaptive navigation sidebar: a collapsible hover/pin rail on wide screens, a flush full-width
drawer body on small screens. It carries no data-layer or navigation opinions - it never pushes routes and
never closes its own drawer; "selected" means nothing more than selectedId matching a destination's id.
Items are one of three kinds:
UtopiaSidebarDestination(id: 'home', icon: const Icon(Icons.home_outlined), label: const Text('Home'));
UtopiaSidebarAction(icon: const Icon(Icons.logout), label: const Text('Sign out'), onPressed: signOut);
UtopiaSidebarCustom(builder: (context) => const Divider());
UtopiaSidebar(
selectedId: selectedId,
presentation: isWide ? UtopiaSidebarPresentation.rail : UtopiaSidebarPresentation.drawer,
onDestinationPressed: (destination) => onSelect(destination.id),
items: [
UtopiaSidebarDestination(id: 'home', icon: const Icon(Icons.home_outlined), label: const Text('Home')),
UtopiaSidebarDestination(id: 'settings', icon: const Icon(Icons.settings_outlined), label: const Text('Settings')),
UtopiaSidebarAction(icon: const Icon(Icons.logout), label: const Text('Sign out'), onPressed: signOut),
],
)
presentation chooses rail (default: collapsed by default, peeks open on hover, pins open via the top toggle
icon) or drawer (always full and flush - host it in your own Scaffold.drawer and close it yourself after a
tap). Resolve isWide from the window width against tokens.breakpoints.sidebarMin (1000 by default) - the
shell breakpoint is measured before the sidebar takes its share, unlike the content size classes. style
(UtopiaSidebarStyle) is opt-in branding: a backgroundColors gradient and a headerBuilder for a logo pinned
above the items; leaving both unset renders a plain surface card matching the content card.
Pinning items to the bottom. The sidebar's body sizes itself to the larger of the viewport and its content,
which means Expanded / Spacer items are supported as direct entries and will consume the free space left
when the items above are shorter than the viewport - the way to push trailing items (e.g. "Sign out", a version
label) down to the sidebar's bottom edge is a UtopiaSidebarCustom spacer between the two groups:
items: [
UtopiaSidebarDestination(id: 'home', icon: const Icon(Icons.home_outlined), label: const Text('Home')),
UtopiaSidebarDestination(id: 'settings', icon: const Icon(Icons.settings_outlined), label: const Text('Settings')),
const UtopiaSidebarCustom(builder: _buildSpacer),
UtopiaSidebarAction(icon: const Icon(Icons.logout), label: const Text('Sign out'), onPressed: signOut),
],
// top-level function or static method
Widget _buildSpacer(BuildContext context) => const Spacer();
A UtopiaSidebarCustom builder is safe to build with a LayoutBuilder (the body deliberately avoids
IntrinsicHeight, which cannot be computed through one) - useful for custom entries that need their own
constraints-aware layout.
Component index #
Everything below is exported from the single barrel, package:utopia_ui/utopia_ui.dart - there are no
per-family barrels and no deep imports into src/.
Theme & tokens
UtopiaTheme, UtopiaThemeData, UtopiaThemeColors, UtopiaThemeTextStyles, UtopiaTokens (with the
UtopiaSpacingTokens / UtopiaRadiusTokens / UtopiaBorderTokens / UtopiaShadowTokens / UtopiaFontWeightTokens /
UtopiaDurationTokens / UtopiaBreakpointTokens families), and the context.theme / context.colors /
context.textStyles / context.tokens / context.spacing / context.radius / context.fieldDecoration extensions.
Buttons
UtopiaButton - the primary call-to-action button, with an inline loading state.
UtopiaGhostButton - the low-emphasis companion, e.g. the cancel action next to a confirm.
UtopiaRemoveIconButton - a small "x" affordance to remove/clear a value.
Chips
UtopiaChip, UtopiaChipList - themed tags, with overflow collapsing on UtopiaChipList.
Fields
UtopiaTextField, UtopiaSearchField, UtopiaDropdownField, UtopiaDatePicker, UtopiaFieldWrapper (shared field
chrome), UtopiaLabeledField (read-only, "picked value" field chrome used by dropdowns and the date picker).
Selection controls
UtopiaCheckbox (with an indeterminate state), UtopiaRadio<T>, UtopiaCheckRow, UtopiaSwitch, UtopiaSwitchField,
UtopiaSlider - fully controlled and Material-free.
Dialogs
UtopiaDialog (raw and .form), UtopiaConfirmDialog.
Sidebar
UtopiaSidebar, UtopiaSidebarDestination, UtopiaSidebarAction, UtopiaSidebarCustom, UtopiaSidebarStyle,
UtopiaSidebarPresentation.
Table
UtopiaTable<T>, UtopiaTableEntry<T>, UtopiaTableSort, UtopiaTableSortOption<T>, UtopiaTableSearchPanel,
UtopiaTableEmpty, UtopiaTableState<T> / useUtopiaTableState.
Layout
UtopiaBreakpoints, UtopiaPageWrapper, UtopiaPageType, UtopiaCard, UtopiaDivider, UtopiaGradientBackground,
UtopiaFormLayout (scrollable content over a pinned bottom bar, with a scroll-aware fade bar).
Misc
UtopiaCollapsible (axis-collapse animation wrapper), UtopiaMultiWidget (flattens deeply nested wrapper widgets).
Loading
UtopiaLoader, UtopiaLoadingBox (skeleton placeholder), UtopiaThreeBounce (the indicator inside UtopiaButton).
Overlay
UtopiaOverlayAnchor - an anchored popup/dropdown follower built on native Flutter, no extra dependency.
Text
UtopiaTitle, UtopiaHeader, UtopiaCopyableText (tap-to-copy text with a confirmation).
Utilities
UtopiaDateTimeExtension - DateTime display-formatting and calendar arithmetic used by UtopiaDatePicker. Plus
IList / FicIterableExtension (from fast_immutable_collections), re-exported since they appear in this
package's own public API (UtopiaTable.rows, entry lists, useUtopiaTableState).
AI assistants #
This package ships the utopia-design skill entry point alongside the artifacts an agent works from -
manifest, tokens, twin and DESIGN.md - usable from any agentic coding tool (Claude, Codex, Cursor, ...).
The full workflows (rebrand tokens, import an external design, sync generated surfaces, build screens from
the manifest) are the utopia-design plugin of the
Utopia skills marketplace; enable it with
utopia init skills or install the marketplace directly.
Related packages #
| Package | What it adds |
|---|---|
| utopia_ui_tools | Token validation, theme and twin codegen, manifest drift gates |
| utopia_hooks | State management with hooks |
| utopia_arch | The full architecture bundle |
| utopia_cms | A CMS framework for admin panels: delegates, entries, CRUD flows |
Built by Utopiasoft.
Contributing #
👾 Contributions are welcome - open an issue to discuss a change, or send a pull request.
License #
BSD-3-Clause. See LICENSE.