How open code works
What the remix CLI installs, who owns it, and how presets, themes, and customization fit together
For a guided walkthrough with screenshots and runnable sample projects, start with Build a settings screen. The rest of this section is split by task:
- Install and add your first item goes from
flutter pub addto a renderedUiButton. - CLI reference lists every command, option, and exit code, plus the
remix.yamlkeys. - Updating and migrating moves registry pins and brings older installs forward.
- Preset catalogs lists the items each preset installs.
Open code copies a theme and component recipes into your application.
From that moment your team owns those files: no wrapper, no subclass, and no
package-level theme override standing between you and the source. Choose the
small vanilla preset, the full Fortaleza-inspired fortal preset, or the
HeroUI-inspired heroui preset when you initialize the project.
Remix keeps everything that is genuinely hard: rendering, pointer and keyboard handling, focus management, accessibility semantics, and the loading/disabled interaction rules. The installed file only decides what things look like.
remix_cli has its own version and release schedule.
The Fortal preset does not add a remix_fortal dependency.
Choose a preset
vanilla | fortal | heroui | |
|---|---|---|---|
| Design language | Neutral and minimal, inspired by shadcn/ui | Independent, Fortaleza-inspired, with flat controls and solid panels | HeroUI web 3.2.6 |
| Theme | 32 color tokens, a radius scale, and a type scale | Seven generated palettes, neutral Orla defaults, scaling, radius, and panel modes | HeroUI's 68 color roles, derived like its CSS variables, and a radius scale |
| Component axes | Small default vocabulary | solid, soft, surface, outline, and ghost where applicable; floating toast also has classic | HeroUI's primary, secondary, tertiary, soft, and ghost vocabulary where applicable |
| Best for | A house system you intend to shape | A complete system with contrast-tested colors and consistent focus rings | Starting from a HeroUI-like system |
Every choice installs local Dart under lib/, uses Remix for behavior, and uses
the same add --diff / add --overwrite review workflow. They cannot be mixed
inside one initialized source tree because their tokens and variant
vocabularies are different.
What lands in your app
lib/ui/
├── ui.dart # managed barrel — CLI owns the marker block
├── theme/
│ ├── tokens.dart # token and scale surface the recipe reads
│ ├── theme_data.dart # light() / dark() / copyWith()
│ ├── theme_scope.dart # inherited theme widget and lookup
│ └── effects.dart # tints, shadows, focus ring
└── components/
├── button.dart # the recipe — yours to edit
└── button.g.dart # generated adapter — do not editEvery later add drops one more pair into components/ and extends the
barrel's marker block. Existing authored source stays untouched. The focused
build also includes every installed generated adapter, so a dependency change
cannot remove an earlier generated part.
button.dart is a styler function plus two enums:
import 'package:flutter/widgets.dart';
import 'package:mix_annotations/mix_annotations.dart';
import 'package:remix/remix.dart';
enum UiButtonVariant { primary, secondary, outline, ghost, destructive }
enum UiButtonSize { small, medium, large }
@MixWidget(target: RemixButton.new)
ButtonStyler uiButtonStyle({
UiButtonVariant variant = UiButtonVariant.primary,
UiButtonSize size = UiButtonSize.medium,
ButtonStyler style = const ButtonStyler.create(),
}) {
return _base(size)
.merge(_variantStyle(variant))
.onDisabled(
ButtonStyler().wrap(WidgetModifierConfig.opacity(0.5)),
)
.merge(style);
}
ButtonStyler _base(UiButtonSize size) => ButtonStyler().minHeight(
switch (size) {
UiButtonSize.small => 32,
UiButtonSize.medium => 36,
UiButtonSize.large => 40,
},
);
ButtonStyler _variantStyle(UiButtonVariant variant) => switch (variant) {
UiButtonVariant.primary => ButtonStyler().color(const Color(0xFF171717)),
_ => ButtonStyler(),
};@MixWidget generates UiButton into button.g.dart, including one named
constructor per variant (UiButton.primary, .secondary, .outline,
.ghost, .destructive).
The Fortal preset
Initialize Fortal once, then use the same item commands and ownership workflow:
remix init --prefix Acme --preset fortal
remix add buttonThe application receives AcmeTheme, AcmeTokens, AcmeButton, and
acmeButtonStyle; no installed identifier is named Fortal. Button brings its
shared base_button recipe, while the theme arrives as a complete local layer:
lib/ui/
├── ui.dart
├── theme/
│ ├── theme.dart
│ ├── fortal_colors.dart
│ ├── palette.dart
│ ├── computed.dart
│ ├── control_styles.dart
│ ├── tokens.dart
│ ├── theme_data.dart
│ ├── theme_scope.dart
│ └── surface_frame.dart
└── components/
├── base_button.dart
├── button.dart
└── button.g.dartPlace AcmeTheme below the application host. For a routed WidgetsApp, wrap
the child of WidgetsApp.builder with AcmeTheme. Routes and dialogs then
inherit its tokens and text defaults. The theme example lives in
lib/ui/theme/theme_scope.dart.
These are application files, not forwarding wrappers around a package. The
authored recipes and generated OKLCH palettes are copied from the same source
checked by Fortal's specification, contrast tests, and owned goldens.
remix remains the behavior and styling-engine boundary;
mix_annotations, build_runner, and mix_generator support adapter
generation. icons additionally installs remix_ui_icons, and chart installs mix_chart. The preset adds no direct mix, naked_ui, or
remix_fortal dependency.
The source is deliberately editable. Change the token map, add an accent or
variant, or merge a one-instance styler last. Future CLI versions never merge
over those decisions automatically: inspect remix add <item> --diff, then
use --overwrite only when you want the new authored file wholesale.
Application host and appearance
Open Code documentation and runnable examples use WidgetsApp. For a routed
application, install the generated theme widget in WidgetsApp.builder and pass
its child through. That child is the Navigator; keeping the theme above it
makes the active theme available to routes, dialogs, and overlays. See the
complete routed host example.
The generated theme widgets expose theme, darkTheme, and mode. A root without
arguments supplies the preset's light and dark defaults and follows the system.
A nested theme inherits its parent's configured pair and active selection. It
installs its own complete token set rather than merging with the scope above it,
so a token override made with MixScope.inherit does not apply below a nested
theme; place the override inside the nested scope.
| Preset | Theme widget | Theme values and modes |
|---|---|---|
vanilla | AcmeTheme | AcmeThemeData.light(), .dark(), and AcmeThemeMode |
fortal | AcmeTheme | AcmeThemeData.light(), .dark(), and AcmeThemeMode |
heroui | AcmeTheme | AcmeThemeData.light(), .dark(), and AcmeThemeMode |
Use your configured prefix in place of Acme. The same parameters apply to
every preset:
AcmeTheme(
theme: const AcmeThemeData.light(),
darkTheme: const AcmeThemeData.dark(),
mode: AcmeThemeMode.system,
child: child,
)For Fortal, its AcmeTheme and AcmeThemeData constructors also accept
accent, gray, radius, scaling, panel background, and background visibility.
Set shared design options on both appearances when customizing the pair.
mode accepts system, light, and dark. The root reacts to platform
brightness changes in system mode. An explicit mode overrides the system;
a nested scope with no mode inherits the parent's active selection, even if a
nearer MediaQuery reports a different system brightness. Nested scopes can
explicitly select another mode from the inherited pair.
theme is the base and fallback. When you supply a custom theme without a
darkTheme, it is used in both modes; colors are not automatically inverted.
Supplying only darkTheme retains the inherited or generated light theme and
does not force dark mode. Supplying neither retains both preset defaults.
Generated themes take a child. Keep WidgetsApp.builder above the Navigator
and use its child; no builder constructor is required. To read
the newly installed theme while building, put Flutter's Builder below the
theme and use that callback's context.
The downloadable tutorial apps show the same API
in the Vanilla and Fortal presets. Their generated theme files are editable application source;
regeneration still preserves existing authored files unless you explicitly use
--overwrite. The CLI installs the theme layer, not a complete app host or
appearance picker. Selection controls and persistence belong to the application.
The dashboard is a reference consumer of the same theme behavior.
The theme API has a hard cutoff: theme constructors accept theme, darkTheme,
and mode. The default theme's data parameter, FortalTheme's brightness
parameter, and the config createScope shortcut have been removed. Use theme
for a fixed theme and mode for appearance selection. Direct Fortal design
options such as accent still override the supplied theme values.
The three levels of customization
Edit the recipe: change it for the whole app, permanently. It is your file.
Retheme a subtree: one copyWith restyles every button beneath it, because
the recipe reads tokens and the theme decides what tokens resolve to:
import 'package:flutter/widgets.dart';
import 'ui/ui.dart';
Widget rounded(Widget child) => UiTheme(
theme: const UiThemeData.light().copyWith(
primary: const Color(0xFF4F46E5),
radius: const Radius.circular(999),
),
child: child,
);Override one instance: style is merged last, so it beats the resolved
recipe without forking it:
import 'package:flutter/widgets.dart';
import 'package:remix/remix.dart';
import 'ui/ui.dart';
Widget publishButton(VoidCallback publish) => UiButton.primary(
label: 'Just this one',
style: ButtonStyler()
.color(const Color(0xFF7C3AED))
.onHovered(ButtonStyler().color(const Color(0xFF5B21B6))),
onPressed: publish,
);State fragments merge by state, not by depth. An override that must beat the
recipe's hover fill has to be declared as a hover fragment too; a bare
.color(...) only replaces the idle one.