feat(garage_ui): PageHeading, a real extraBold, and a mono that chains

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
This commit is contained in:
ImBenji
2026-10-09 15:21:48 +01:00
co-authored by Claude Opus 5
parent b5e5ed5b75
commit 7aa5cb8f8b
7 changed files with 276 additions and 23 deletions
+71
View File
@@ -393,6 +393,77 @@ 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's `GarageHeader(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 / 2` tall, contents left-aligned and centred
vertically in a `FittedBox(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 through
`theme.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 * 3` beside a rail, `gapMd` on a phone (sections add
their own `gapXs` on top). Cap at `density.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. `gapXl` under 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 `SettingsRow`s. Put a rule between them.
- A full-width `Divider(color: divider)` across the reading column, sitting
in the middle of the `gapXxl` before 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.
+9 -2
View File
@@ -102,7 +102,13 @@ class GarageAuth extends ChangeNotifier {
// completeSignIn() with the query params. on native it opens the system
// browser; the host app catches the inbound deep link and likewise calls
// completeSignIn(). this is the lower level half of signIn().
Future<void> beginSignIn() async {
//
// [handoff] is a code another build of your app minted with
// /auth/handoff/issue - the desktop app sending its user to the web one. It
// stands in for the sign in screen (and consent, when both clients are in
// the same project), so they dont have to sign in twice. A used or expired
// one just means they get the normal sign in.
Future<void> beginSignIn({String? handoff}) async {
if (clientId.isEmpty) {
throw AuthError("GarageAuth: clientId is empty.");
}
@@ -127,6 +133,7 @@ class GarageAuth extends ChangeNotifier {
"state": state,
"code_challenge": challenge,
"code_challenge_method": "S256",
if (handoff != null && handoff.isNotEmpty) "_handoff": handoff,
});
await _redirect.navigateTo(authUri.toString());
@@ -136,7 +143,7 @@ class GarageAuth extends ChangeNotifier {
// future never really "completes" (the page is leaving) — your callback route
// drives completeSignIn. on native it's the same begin step; the deep-link
// handler completes it. so think of signIn() as "start the flow".
Future<void> signIn() => beginSignIn();
Future<void> signIn({String? handoff}) => beginSignIn(handoff: handoff);
// finishes the exchange. callers pass the query params off the inbound
// callback url (web: go_router state.uri.queryParameters, native: parse the
+1
View File
@@ -35,6 +35,7 @@ export "misc.dart";
export "color_input.dart";
export "date_input.dart";
export "panel.dart";
export "page_heading.dart";
export "editor_chrome.dart";
export "context_menu.dart";
export "properties.dart";
+85
View File
@@ -0,0 +1,85 @@
import "package:flutter/widgets.dart";
import "surface.dart";
import "theme/garage_theme.dart";
import "theme/theme_data.dart";
/// The heading a page wears above its content.
///
/// The name a step up, a muted line under it saying what youre looking at,
/// both left aligned on the same margin as whatever follows. Promoted out of
/// the hub, where it was drawn over every section, because A&A's licence page
/// wanted the same thing and a lookalike drifts from the real one within a day
/// of being written.
///
/// Its a heading, not a bar - nothing chrome coloured, no rule under it, no
/// height of its own beyond what the two lines need. A pane that wants a strip
/// across the top of it wants [ChromeBar] instead.
class PageHeading extends StatelessWidget {
/// How tall this comes out, for a page that needs to know what room is
/// left under it.
///
/// Derived rather than measured: title on [Density.textLg] over a subtitle
/// on the ambient font, both on Geist's own line box, with a gapXs between.
/// A layout that has to wait for a frame to find this out cant use it on
/// the frame it needs it.
static double heightIn(Density d) =>
(d.textLg * Density.geistLineRatio).roundToDouble() +
d.gapXs +
(d.fontSize * Density.geistLineRatio).roundToDouble();
const PageHeading({
required this.title,
this.subtitle,
this.trailing,
super.key,
});
final String title;
final String? subtitle;
/// Sits at the far end of the heading, vertically centred on the whole
/// block rather than on the title line.
///
/// For the one action that belongs to the SUBJECT rather than to a section
/// of it - Disconnect on an agent, and the like.
final Widget? trailing;
@override
Widget build(BuildContext context) {
final theme = GarageTheme.of(context);
final density = theme.density;
final heading = Column(
crossAxisAlignment: CrossAxisAlignment.start,
mainAxisSize: MainAxisSize.min,
children: [
Text(title, style: theme.typography.normal).large(),
if (subtitle != null) ...[
const Gap.xs(),
Text(
subtitle!,
style: TextStyle(color: theme.colorScheme.mutedForeground),
),
],
],
);
// Nudged in by gapXs: thats the side margin a PropertiesSection carries on
// itself, and without it a heading starts LEFT of the sections it
// introduces - the sort of thing you cant unsee once youve seen it.
return Padding(
padding: EdgeInsets.symmetric(horizontal: density.gapXs),
child: trailing == null
? heading
: Row(
crossAxisAlignment: CrossAxisAlignment.center,
children: [
Expanded(child: heading),
Gap(density.gapMd),
trailing!,
],
),
);
}
}
+8 -9
View File
@@ -519,19 +519,18 @@ class PropertiesSection extends StatelessWidget {
color: scheme.mutedForeground,
);
return Container(
// bottom is gapLg, not gapXs: this margin is what separates one section
// from the NEXT one, and gapXs is the step used between ROWS INSIDE a
// section - so at gapXs a run of sections read as one striped block
// rather than as separate subjects, which is the whole point of giving
// each one its own. Three times the inner step, so the boundary between
// two sections is unambiguously bigger than the boundary between two
// rows. The sides stay gapXs; thats an inset from the pane edge, a
// different job.
// bottom is its own token, not gapXs: this margin is what separates one
// section from the NEXT one, and gapXs is the step used between ROWS
// INSIDE a section - so at gapXs a run of sections read as one striped
// block rather than as separate subjects, which is the whole point of
// giving each one its own. It used to be gapLg flat, which a dense
// editor pane full of sections wears badly, hence the dial. The sides
// stay gapXs; thats an inset from the pane edge, a different job.
margin: EdgeInsets.fromLTRB(
density.gapXs,
0,
density.gapXs,
density.gapLg,
density.propertiesSectionGap,
),
decoration: BoxDecoration(
color: scheme.card,
+24
View File
@@ -96,6 +96,7 @@ class Density {
// ---- container-level spacing (panels, popovers, dialogs) ----
this.containerGap = 8.0,
this.containerPadding = 16.0,
this.propertiesSectionGap = 6.0,
// ---- optical ----
this.controlTextOffset = 0.0,
@@ -123,6 +124,7 @@ class Density {
listRowIndent = 12.0,
containerGap = 10.0,
containerPadding = 20.0,
propertiesSectionGap = 15.0,
controlTextOffset = 0.0;
/// The product tier - for the Garage web apps rather than for A&A.
@@ -156,6 +158,7 @@ class Density {
listRowIndent = 10.0,
containerGap = 10.0,
containerPadding = 20.0,
propertiesSectionGap = 15.0,
controlTextOffset = 0.0;
/// Which tier this token set represents.
@@ -230,6 +233,19 @@ class Density {
/// and `baseContainerPadding`, which always held the same value.)
final double containerPadding;
/// What separates one properties section from the NEXT one.
///
/// Its own token rather than a step off the gap ladder, because the right
/// answer genuinely isnt the same at every density. A dashboard has a
/// handful of sections and wants air around each so they read as separate
/// subjects; an editor pane stacks eight of them down a 300px column and
/// the air is the thing thats in short supply. Same widget, opposite
/// pressures - so the number is a dial, not a derivation.
///
/// Whatever its set to it must stay clearly bigger than the gap between two
/// ROWS inside a section, or a run of sections reads as one striped block.
final double propertiesSectionGap;
// ---- optical ----
/// Downward nudge applied to control content so it sits on its optical
@@ -443,6 +459,14 @@ class Density {
/// The largest step - page-level separation, above the panel scale.
double get gapXxl => controlGap * 6;
/// The inset a page's reading column takes either side, beside a rail.
///
/// Off the font, not the gap ladder: its measured against the text it
/// frames, 48 at product. Wrong on a phone - a 390pt screen loses a quarter
/// of itself to it - so a phone page wants [gapMd] instead. Was a local
/// `fontSize * 3` in the hub and in every app copying the hub.
double get pageGutter => fontSize * 3;
}
/// Icon sizes. `small` is the control icon and is derived from the density's
+78 -12
View File
@@ -70,23 +70,89 @@ extension TextStyleExtension on Widget {
style: (t) => TextStyle(fontSize: t.density.textLg),
);
Widget medium() => _StyledText(
child: this,
style: (t) => const TextStyle(fontWeight: FontWeight.w500),
);
Widget semiBold() => _StyledText(
child: this,
style: (t) => const TextStyle(fontWeight: FontWeight.w600),
);
Widget bold() => _StyledText(
child: this,
style: (t) => const TextStyle(fontWeight: FontWeight.w700),
);
// these DONT go through _StyledText. Merging `fontWeight: w800` over an
// already resolved google_fonts family changes nothing about which font
// FILE gets used - the file is the weight - so skia synthesises instead,
// and skia has exactly one fake bold. w600, w700 and w800 all came out the
// same stroke, which is how extraBold ended up looking identical to bold.
Widget medium() => _WeightText(child: this, weight: FontWeight.w500);
Widget semiBold() => _WeightText(child: this, weight: FontWeight.w600);
Widget bold() => _WeightText(child: this, weight: FontWeight.w700);
/// Top of the ladder. A display weight - for a figure or a name somebody is
/// meant to read across a desk, not for body copy.
Widget extraBold() => _WeightText(child: this, weight: FontWeight.w800);
Widget muted() => _StyledText(
child: this,
style: (t) => TextStyle(color: t.colorScheme.mutedForeground),
);
/// Geist Mono, keeping whatever size, weight and colour are already in
/// scope.
///
/// Chains in either order - `.mono().bold()` and `.bold().mono()` both land
/// on the real mono bold, because the weight helpers re-resolve whichever
/// family they find in scope rather than assuming sans.
///
/// Only w300 and w700 are in main.dart's `pendingFonts`. Any other weight
/// resolves fine and lands a frame or two late.
Widget mono() => _MonoText(child: this);
}
// mono cant ride on _StyledText the way the weights do. those merge a style
// naming ONE property and dont care what else is in scope, so they compose in
// any order. A family out of google_fonts isnt one property - the family name
// encodes the weight - so this one has to read the inherited style first and
// hand the whole thing over to be re-resolved.
// re-resolves the family for the weight it's setting, keeping whichever face
// is already in scope. sans unless somebody put mono there first.
class _WeightText extends StatelessWidget {
const _WeightText({required this.child, required this.weight});
final Widget child;
final FontWeight weight;
@override
Widget build(BuildContext context) {
final theme = GarageTheme.of(context);
final inherited = DefaultTextStyle.of(context).style;
final wanted = inherited.copyWith(fontWeight: weight);
// google_fonts names a family "<Family>_<weight>", so the bit before the
// underscore is the face. taken off typography.mono rather than spelled
// out, so renaming the font doesnt quietly turn every .bold() on a mono
// run back into sans.
String? face(String? family) => family?.split("_").first;
final isMono = face(inherited.fontFamily) == face(theme.typography.mono.fontFamily);
return DefaultTextStyle.merge(
style: isMono
? theme.typography.monoStyle(wanted)
: theme.typography.sansStyle(wanted),
child: child,
);
}
}
class _MonoText extends StatelessWidget {
const _MonoText({required this.child});
final Widget child;
@override
Widget build(BuildContext context) {
final theme = GarageTheme.of(context);
// .of(context), not the theme: this is the point of the class. everything
// a caller stacked ABOVE this widget is already merged into here.
final inherited = DefaultTextStyle.of(context).style;
return DefaultTextStyle.merge(
style: theme.typography.monoStyle(inherited),
child: child,
);
}
}
typedef _StyleFromTheme = TextStyle Function(ThemeData theme);