RemixRemix

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:

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

vanillafortalheroui
Design languageNeutral and minimal, inspired by shadcn/uiIndependent, Fortaleza-inspired, with flat controls and solid panelsHeroUI web 3.2.6
Theme32 color tokens, a radius scale, and a type scaleSeven generated palettes, neutral Orla defaults, scaling, radius, and panel modesHeroUI's 68 color roles, derived like its CSS variables, and a radius scale
Component axesSmall default vocabularysolid, soft, surface, outline, and ghost where applicable; floating toast also has classicHeroUI's primary, secondary, tertiary, soft, and ghost vocabulary where applicable
Best forA house system you intend to shapeA complete system with contrast-tested colors and consistent focus ringsStarting 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 edit

Every 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 button

The 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.dart

Place 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.

PresetTheme widgetTheme values and modes
vanillaAcmeThemeAcmeThemeData.light(), .dark(), and AcmeThemeMode
fortalAcmeThemeAcmeThemeData.light(), .dark(), and AcmeThemeMode
herouiAcmeThemeAcmeThemeData.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.

View page source on GitHub

On this page