The weight helpers went through _StyledText, which merges a style naming one property and lets everything else in scope stand. That works for a colour and it doesnt work for a weight: google_fonts encodes the weight in the family NAME, so merging w800 over an already resolved family changes no font file and skia synthesises instead. Skia has one fake bold, so w600, w700 and w800 all came out the same stroke and extraBold was indistinguishable from bold. They re-resolve the family now, keeping whichever face is in scope, so .mono().bold() and .bold().mono() both land on the real mono bold. PageHeading is lifted out of the hub, where it was drawn by hand above every section. A&A's licence page wanted the same block and a lookalike drifts from the original inside a day. pageGutter and propertiesSectionGap are new density tokens. Both were local magic numbers - `fontSize * 3` copied into every app that copied the hub, and a flat gapLg that a dense editor pane full of sections wears badly. garage_auth takes an optional handoff code on signIn/beginSignIn and sends it as _handoff, so a desktop build can hand its user to the web one without a second sign in. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01FkzfwZf59HNP6R8jXcC1NR
22 KiB
garage_ui style guide
How to build a screen out of garage_ui so it actually looks like a Garage app. The API is in the source. This is the other half: which widget, which variant, where — and, mostly, what to leave alone.
It's written from the two apps that are the reference:
- Arcs & Angles, blender mode (
metro_map_maker,lib/pages/blender/) — a dense desktop editor on thecompactdensity. - The Garage hub (
garage_dashboard_portal) — a web product on theproductdensity.
Where those two do something the guide says not to, it's listed at the end under Dont copy these. An existing call site is not precedent.
The one rule: let the theme speak
garage_ui already knows what everything should look like. The colour scheme, the density and the variant between them decide every colour, font size, weight, icon size, padding, radius and gap. Your job is to pick the widget and the variant. Then stop.
So, inside or around a garage_ui component, don't:
- pass a
TextStylewith afontSize,fontWeightorcolor - give an
Iconasize:orcolor: - write a literal
EdgeInsets,SizedBox,Gap(8)orBorderRadius.circular(8) - pass
alignment:to a button that doesnt need it - force
density: ControlDensity.compacton a control to make it "fit" - wrap a dialog's content in a
ConstrainedBox(maxWidth: 360) - build a
Containerwith a fill, border and radius to make a badge, a pill, a warning box or a popover
Every one of those is a number or a colour that was chosen once, per call site, and stops agreeing with the rest of the app the moment the density, scheme or accent changes. The components are built as families — outline buttons share text fields' fill, stroke and radius on purpose so they "read as one family instead of each getting styled by hand per call site". One override breaks the family.
When something looks wrong, the fix is a different variant, a different
widget, or a change in garage_ui so every app gets it. Not a local
override. That's how ButtonStyle.ghostDestructive came about: apps kept
hand-colouring ghost buttons red, so it became a variant.
What you can reach for, when a component doesnt cover it:
Gap.xs()…Gap.xxl()anddensity.gapXs… for space between thingsdensity.textXxs…density.textLg, or the text extensions, for text sizetheme.typography.medium/.semiBoldfor weightscheme.<slot>for colour, when you're drawing something garage_ui doesnt have a widget for
These are tokens — they move with the theme. A literal never does.
Setting up
final theme = ThemeData(
colorScheme: GarageSchemes.carbon, // or your own, see below
density: const Density.product(), // or .compact() / .normal()
);
GarageApp.router(routerConfig: router, theme: theme);
GarageApp is built on WidgetsApp, not MaterialApp, and installs
GarageTheme plus the scroll behaviour and scrollbar. Nothing in garage_ui
touches Material. If a file reaches for package:flutter/material.dart, it has
left the system.
Leave the rest of ThemeData on its defaults — scaling 1.0, radius 0.5
(so radiusSm 4, radiusMd 6), panelRadius 10, panelGap 5. Both
reference apps do.
Read the theme with GarageTheme.of(context): .colorScheme, .density,
.typography, .iconTheme, .radiusMd and friends.
Colour schemes
Don't hand-author 37 colours. GarageSchemes ships dark, light and
carbon (the one the Garage apps run), and ColourScheme.derive builds a
complete scheme from four:
ColourScheme.derive(
brightness: Brightness.dark,
background: ...,
foreground: ...,
primary: ...,
)
Every other slot is derived on a perceptual lightness ladder — surfaces step
up or down from the background, strokes are measured off the surface they
outline, text is a fraction of the background-to-foreground span. Any derived
slot can be pinned by passing it. schemes.dart is the worked example.
A user-picked accent goes through scheme.withAccent(colour), which swaps
primary, primaryHovered, ring and a contrasting primaryForeground, and
nothing else.
Density: pick the tier, don't tune it
compact |
normal |
product |
|
|---|---|---|---|
| For | dense desktop tools | the same, roomier | web / product apps |
| Used by | Arcs & Angles | A&A "Comfortable" | the hub |
fontSize |
10 | 10 | 12 |
controlHeight |
23 | 27 | 33 |
chromeBarHeight |
31 | 37 | 43 |
Use the named constructor. Density() is the same as Density.compact(),
which is a trap for a product app.
Density's fields are the only hand-set pixel values in the system; padding,
icon size and line boxes are derived from them. If a tier feels wrong, that's
a conversation about the tier, not a reason to set sizes at call sites.
Controls follow the theme's tier. A per-control density: override exists for
exactly one job — a header bar that has to match a 23px menu bar — and even
then it mixes tiers (compact geometry, the theme's font). Don't use it to make
something smaller.
Colour: what the slots are for
You mostly wont touch these — the components read them. When you do draw something yourself, pick the slot by what the thing is.
| Slot | What it is |
|---|---|
background / foreground |
the page ground and default text. Also a Panel's fill |
chrome |
header and footer bars, and the gutter between panels |
surfaceSunken |
one step below the ground — side rails, panel bodies, list backgrounds |
card |
raised surface — cards, properties sections, dialogs |
muted / mutedForeground |
de-emphasised fill / secondary text, hints, units |
rowText / rowHovered |
a row's resting label colour / hovered row, in lists and menus |
popover / popoverBorder |
menus, select popups, anything floating |
tooltipBackground / tooltipBorder |
tooltips, which sit above everything |
primary (+Hovered, Foreground) |
the accent. The one thing that's on or chosen |
secondary (+Hovered, Foreground) |
a neutral filled control |
destructive |
delete, revoke, discard |
controlFill (+Hovered, Focused), controlBorder |
the shared fill and stroke of every control — fields, selects, outline buttons, checkboxes |
switchTrackInactive |
a Switch while off |
border / divider |
general outline / a seam between things |
panelBorder / panelBorderHighlighted |
a Panel's edge, resting / the lit one |
propertiesSectionBorder |
a properties section's edge |
ring |
keyboard focus |
popoverItemHovered |
hover inside select and date popups |
chart1–chart5 |
data visualisation |
There is no panel, input*, explorerRow*, menuItem* or canvas* slot any
more. App-specific colours (A&A's canvas) belong in the app, derived with
shiftLstar so they sit on the same ladder.
Space
- Between siblings:
Gap.xxs()…Gap.xxl(). They resolve against the density at build time. - In padding:
density.gapXs…density.gapXxl,containerGap,containerPadding. - Never a literal.
Gap(8)is 8 in compact and wrong everywhere else.
xxs |
xs |
sm |
md |
lg |
xl |
xxl |
|
|---|---|---|---|---|---|---|---|
| compact | 2 | 4 | 6 | 8 | 12 | 16 | 24 |
| normal, product | 3 | 5 | 8 | 10 | 15 | 20 | 30 |
A lot of the spacing is already in the components. PropertiesSection carries
its own margin (gapXs either side, gapLg below), so a stack of sections
needs no gaps between them. SettingsList insets its own rows. Don't add
padding around things that already have it.
Type
- The ambient text is
fontSizeat w300. PlainText("...")is already right for body copy. - Controls render their own labels at w400; primary buttons at w600 as optical compensation. Don't bold a button label.
- Size steps are the extensions:
.xSmall()(textXs),.small()(textSm),.large()(textLg). Weight:.medium(),.semiBold(),.bold(). Secondary text:.muted(). - The step below the control font,
textXxs, has no extension; readdensity.textXxswhen you need it (group captions). - Numbers and readouts:
theme.typography.monoStyle(...).
| Job | How |
|---|---|
| Page title | Text(title).large() |
| Page / section subtitle | muted text under it |
| Section heading inside a page | .small().semiBold() |
| Nav group caption | density.textXxs, w600, .muted() |
| Hint, unit, empty-state line | .muted() (hub list text: .xSmall().muted()) |
| Footer stats, perf readouts | monoStyle, muted |
.muted() colours text only. It does nothing to an Icon.
Icons
- Lucide only:
LucideIcons.x. - Inside a control's
leading/trailing/iconslot: a bareconst Icon(LucideIcons.x). The control sizes and colours it — the variant's icon theme is merged over everything inside the button. - Outside a control,
.iconSmall/.iconMedium/.iconLargeset size only (never colour).iconSmallequalsfontSize: 10 compact, 12 product. - No literal
size: 13.
Surfaces and layout
Both apps are the same shape: a chrome ground, Panels standing on it, and
panelGap gutters between them.
ColoredBox(chrome)
Padding(panelGap)
Row[ Panel(rail), SizedBox(width: panelGap), Expanded(Panel(workspace)) ]
A&A gets this from GarageShell (header, footer, main, a sidebar split top and
bottom). The hub builds the same shape by hand because it needs a nav rail.
Only one panel is lit at a time (panelBorderHighlighted).
ChromeBarfor a header or footer — it'schromeBarHeighttall onchrome.Panelfor a docked region. Flat,backgroundfill, 1.15 border.PanelHeader(icon, title, scheme, trailing:)at the top of a panel body. A&A's panel pages are allColoredBox(surfaceSunken)→PanelHeader(bottomPadding: 0)→ScrollEdgeFade(ListView(...)).Card/SurfaceCardfor a raised block (cardfill,radiusXl).OutlinedContainerfor a bordered box that isn't a card.- Flat. No shadows on anything — the border and the surface step are what separate things. The package's sheet, menu and popup surfaces are all shadowless.
Buttons
Variants mean something
| Variant | Means |
|---|---|
primary |
the one action, or the thing that's on / chosen. One per view, ideally |
secondary |
a neutral filled control — a resting toggle, a button welded to a field, the selected item in a nav |
outline |
a normal action that isn't the main one — Cancel, Retry, Previous / Next |
ghost |
chrome, toolbars, nav items, row actions — anything that shouldn't compete |
destructive |
the confirm button of a destructive dialog |
ghostDestructive |
a destructive trigger that isnt a filled slab — Remove, Revoke, Delete in a row |
link / text |
inline, in running copy |
Button.primary(...), Button.ghostDestructive(...) etc. take a style:;
the PrimaryButton / OutlineButton / … wrappers take density: directly.
By context
| Where | What |
|---|---|
| Icon only, anywhere | IconButton.<variant>, never a Button with just an icon in it |
| Panel header actions | IconButton.ghost, each in a Tooltip |
| Nav rail item | ButtonStyle.ghost, secondary when selected (never primary), alignment: centerLeft, leading: Icon |
| Toolbar / header toggle | IconButton.primary when on, outline when off (secondary off for a master switch whose off state matters) |
| Segmented choice | ButtonGroup.horizontal, Expanded children, chosen one primary, rest secondary, alignment: center |
| Button welded to a field | ButtonGroup.horizontal[field, IconButton.secondary] |
| Action inside a PropertyRow | ButtonStyle.secondary (the row doesnt force buttons, you pick it) |
| Action in a SettingsRow | ghost |
| Dialog | Cancel outline, confirm Button.primary or Button.destructive |
| Retry after an error | outline |
| Empty-state call to action | outline, centred |
| Full-width stacked flow buttons (auth) | primary last, every one alignment: Alignment.center |
Alignment
Leave alignment: off unless the button is stretched wider than its label.
Then:
Alignment.centerfor full-width buttons and segments.Alignment.centerLeftonly for nav and list rows, and only with a leading icon.
Never centerLeft with a trailing-only icon. When alignment is set and exactly
one of leading / trailing is present, Button puts an invisible spacer on the
empty side so the label lands on the true centre — with centerLeft that just
indents the label behind a phantom icon.
Toggles
Toggle is the package's on/off button: ghost while off, secondary while on.
Editor toolbars use the primary-on pattern above instead. Pick one per surface.
Inputs
Text fields
- Default (
outline) for free text: names, search, a composer, a form. secondaryfor numeric property values and read-only values.- Inside a
PropertyRowyou don't choose — the row wraps its child in aPropertySlotScopeandTextField,SelectandDateInputare forced to secondary. An explicitvariant:loses. (Buttons aren't forced.) - Numeric editor fields (A&A): secondary,
textAlign: center,InputFeature.scrub(...), a unit as a trailing mutedText. Put trailing features beforescrub— list order is render order. - A read-only value is a
TextField(readOnly: true, enabled: false), never a bareText(see below).
Select
SelectVariant.secondary in property rows (forced anyway), ghost in a
SettingsRow or where the select reports a value rather than offering a
control, default outline elsewhere.
Booleans
A&A uses Checkbox throughout. The hub uses Switch in rows. Either is
fine; don't mix them within one surface.
Errors
Use the row's error: slot (PropertyRow and SettingsRow both have one).
It reddens the outline, never the fill. Don't hand-roll a red Text under a
field. "Required" goes in the row's action: slot.
Properties and settings
The two list shapes, and the hub's two page archetypes.
PropertiesSection + PropertyRow — a boxed card of label/value rows. For
inspectors, account and security pages, and lists of records (one collapsible
section per record, then the hub's Pager).
- The value slot is always a field or a control, never bare
Text. A read-only value is a secondaryTextField(readOnly: true, enabled: false)— the hub wraps that asValueField. Beside real fields, bare text reads as a caption and the column goes ragged. - A button in the value slot goes in
Align(centerLeft)so it doesn't stretch. - Controls here are secondary.
- Editor rows carry
PropertyActions(right-click reset / copy / paste). - A status badge or count goes in the section's
trailing, which stays visible when collapsed. - Actions go in the section's
actions:band.
SettingsList + SettingsRow — unboxed rows ruled between entries, on
the page ground. For forms: products, coupons, clients.
- There's no card, so filled controls would float. Selects, buttons and icon buttons are ghost; text fields are the default outline — read-only ones too.
Converting one to the other means changing the variants, not just the container.
Subtitle vs description
subtitleis a short static line saying what the thing is. Never live data: no counts, dates, names, emails, statuses or "3 of 5". This holds everywhere — page headings, section headings, rows, and record cards in a list. A record's identifying data goes in its rows.descriptionis longer copy about a setting.
Dialogs, sheets, panes, overlays
- Confirm / small dialog:
showDialog→AlertDialog(title, content, actions: [cancel, confirm]). It'scard-filled, capped atkDialogMaxWidth(350) and renders the actions in its own band. Don't constrain its width yourself, and don't build the action row by hand. - Bottom sheet:
showSheet(...)withSheetRows. - Big pane (settings, export — A&A):
showPaneOverlay, blurred scrim, inside the same chrome → Panel → gutter shape as the editor. - Toasts:
showAppToast(context: context, title: ..., subtitle: ..., severity: ...). - Tooltips:
Tooltip(tooltip: (_) => TooltipContainer(child: Text(msg))), unstyled. - Menus:
MenuButton,MenuDivider,MenuLabel;showContextMenufor right-click; app menus asAppMenuItemdata.
Loading, empty, error
- Loading: a
CircularProgressIndicator. No skeletons, no shimmer. - Empty: one muted line.
- Error: the message muted, and an outline Retry.
Plainest thing that works. If a page wants more, it's asking for a new garage_ui component, not a one-off.
Rules and paradigms
The sections above say which widget. These say what a screen is for — the calls that aren't visible from the API, learned the hard way from apps that used the right widgets and still came out wrong.
The rail header is the app, not the page
The band at the top of a nav rail says whose app this is. It is never the current section's name — that's already the selected nav item, and saying it twice in the accent turns the header into a page title stuck in the wrong place.
- The app's name as a wordmark: all caps, the black cut (w900), default
foreground. Not
primary, not.large(). - One muted w600 line under it,
textXs, and the wordmark sized so it's exactly as wide as that line (measure both, scale by the ratio, clamp). The hub'sGarageHeader(fillWidth: true)is the reference. - The line under it is the app's context — the company for the hub, the stand you're working for an app bound to one. This is the one place a name is allowed in a subtitle-shaped line, because it's identity, not a heading.
- The band is
railWidth / 2tall, contents left-aligned and centred vertically in aFittedBox(scaleDown)so a long context line shrinks the pair rather than overflowing. - A full-width
Divider(color: panelBorder)under it — the wordmark isn't a destination, so it's ruled off from the list, not sat in it. - A weight above
.extraBold()isn't an extension. Go throughtheme.typography.sansStyle(TextStyle(fontWeight: ...))so the weight picks the font file;copyWith(fontWeight:)on the ambient style gets skia's fake bold.
A page breathes: the page frame owns its spacing
A page is a centred reading column: gutter either side, gapXxl above the
PageHeading, gapXxl under it, gapXxl at the bottom. The gap under
the heading is the biggest on the page on purpose: it separates "what page
this is" from everything on it, so it must be bigger than any gap between
things on the page (sections are gapXxl apart; nothing inside one is).
- Gutter:
fontSize * 3beside a rail,gapMdon a phone (sections add their owngapXson top). Cap atdensity.contentMax. - The heading gap belongs to whatever builds the page frame (the hub's shell,
an app's page scaffold), not to each screen. Left to screens, every one
picks its own
Gap.xl()/Gap.lg()/ nothing, and the pages stop lining up with each other. - So the first section heading under a page heading adds no space above itself, because the frame already put it there. Stacking both is how a gap comes out right on one screen and doubled on the next.
- When in doubt, err roomy.
gapXlunder a title looks fine alone and cramped beside the hub.
Rule between sections, not just space
When a page is a stack of separate jobs (fill in the sheet, share it,
check it), whitespace alone doesn't separate them. A heading after a big gap
still reads as a continuation of the section above it, especially when that
section ends in unboxed SettingsRows. Put a rule between them.
- A full-width
Divider(color: divider)across the reading column, sitting in the middle of thegapXxlbefore the next section heading. Not instead of the gap, and not tight under the heading. - Between sections only. None above the first (the page heading gap is already there) and none under the last. A rule with nothing after it is fencing off empty space.
- It's part of the section heading, not something each screen drops in by hand, so the spacing either side is the same on every page.
Dont copy these
Known overrides in the reference apps. They're debt, not patterns.
Arcs & Angles
IconButton.ghost(icon: Icon(x, size: 13))in panel headers, the tab strip and the agent composer — should be a bareIcon.- Tooltip text forced to
foregroundorbackground, customTooltipContainerpadding. - Literal font sizes in the agent panel and the download modal.
- The hand-rolled snap popover,
PaneDialogtitle bar and properties tab strip. - Plain
Textvalues in settings and downloadPropertyRows. - Literal
SizedBox/EdgeInsetsspacing outside the settings modal.
The hub
- Ghost and link buttons hand-coloured
destructive("Remove", "Revoke", "Refund", "Delete?") — useButtonStyle.ghostDestructive. TextStyle(fontWeight: w600)on primary labels in the older auth steps.- Four competing badges (disabled compact buttons, disabled coloured
IconButtons,SandboxTag,Pill), and hand-built warning boxes (FlowError, the delete-account box,_Banner). ConstrainedBox(maxWidth: 360/380)around dialog content.- Literal widths on toolbar selects.
- Outline text fields and ghost selects inside
PropertiesSections; secondary fields insideSettingsLists. - Record-card and detail-page subtitles carrying data (sku · price, buyer · date, counts, emails).
- About 37 hand-written copies of
ValueField, and a bareTextvalue in two role rows. - Hand-built toasts (
showToast+SurfaceCard+ literal padding) instead ofshowAppToast. ControlDensity.compacton ordinary buttons outside a header.