From 7aa5cb8f8bf7850a2de5d56058993cd5adf913fd Mon Sep 17 00:00:00 2001 From: ImBenji Date: Fri, 9 Oct 2026 15:21:48 +0100 Subject: [PATCH] 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) Claude-Session: https://claude.ai/code/session_01FkzfwZf59HNP6R8jXcC1NR --- docs/garage-ui-style-guide.md | 71 ++++++++++++++++++++++ garage_auth/lib/src/garage_auth.dart | 11 +++- garage_ui/lib/garage_ui.dart | 1 + garage_ui/lib/page_heading.dart | 85 ++++++++++++++++++++++++++ garage_ui/lib/properties.dart | 17 +++--- garage_ui/lib/theme/theme_data.dart | 24 ++++++++ garage_ui/lib/theme/typography.dart | 90 ++++++++++++++++++++++++---- 7 files changed, 276 insertions(+), 23 deletions(-) create mode 100644 garage_ui/lib/page_heading.dart diff --git a/docs/garage-ui-style-guide.md b/docs/garage-ui-style-guide.md index db2c3c0..7d03de7 100644 --- a/docs/garage-ui-style-guide.md +++ b/docs/garage-ui-style-guide.md @@ -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. diff --git a/garage_auth/lib/src/garage_auth.dart b/garage_auth/lib/src/garage_auth.dart index ba511ac..1b22b94 100644 --- a/garage_auth/lib/src/garage_auth.dart +++ b/garage_auth/lib/src/garage_auth.dart @@ -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 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 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 signIn() => beginSignIn(); + Future 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 diff --git a/garage_ui/lib/garage_ui.dart b/garage_ui/lib/garage_ui.dart index f46e346..c716bfa 100644 --- a/garage_ui/lib/garage_ui.dart +++ b/garage_ui/lib/garage_ui.dart @@ -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"; diff --git a/garage_ui/lib/page_heading.dart b/garage_ui/lib/page_heading.dart new file mode 100644 index 0000000..1ae9ff7 --- /dev/null +++ b/garage_ui/lib/page_heading.dart @@ -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!, + ], + ), + ); + } +} diff --git a/garage_ui/lib/properties.dart b/garage_ui/lib/properties.dart index 9162217..55a7a61 100644 --- a/garage_ui/lib/properties.dart +++ b/garage_ui/lib/properties.dart @@ -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, diff --git a/garage_ui/lib/theme/theme_data.dart b/garage_ui/lib/theme/theme_data.dart index 9eef4e4..2b4867c 100644 --- a/garage_ui/lib/theme/theme_data.dart +++ b/garage_ui/lib/theme/theme_data.dart @@ -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 diff --git a/garage_ui/lib/theme/typography.dart b/garage_ui/lib/theme/typography.dart index d2f596c..da00c2b 100644 --- a/garage_ui/lib/theme/typography.dart +++ b/garage_ui/lib/theme/typography.dart @@ -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 "_", 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);