Repository navigation
Open
Labels
P2Important issues not at the top of the work listImportant issues not at the top of the work lista: fidelityMatching the OEM platforms betterMatching the OEM platforms bettera: typographyText rendering, possibly libtxtText rendering, possibly libtxtengineflutter/engine related. See also e: labels.flutter/engine related. See also e: labels.p: cupertino_uicupertino_ui package in flutter/packagescupertino_ui package in flutter/packagespackageflutter/packages repository. See also p: labels.flutter/packages repository. See also p: labels.platform-iosiOS applications specificallyiOS applications specificallyteam-iosOwned by iOS platform teamOwned by iOS platform teamtriaged-iosTriaged by iOS platform teamTriaged by iOS platform team
Description
Flutter's Text() has noticeably different letter spacing from iOS's Text() by default.
Background
iOS renders text with "SF Pro Text" font for font size <20, and "SF Pro Display" font for font size >= 20. In Flutter they're called "CupertinoSystemText" and "CupertinoSystemDisplay" respectively.
Comparison with current Flutter
(light grey Flutter, black native iOS)

Adjustment
I tried to apply letterSpacing to Flutter's text to get a result close to the native one. The needed adjustment turns out to be a non-linear curve, which is interpolated as a cubic polynomial.
Comparison after adjustment
(light grey Flutter, black native iOS)

(Yes, I know line height at small font size still deviates noticeably.)
Note
- If I understand correctly, Flutter's text rendering is handled by Skia, which delegates text shaping to HarfBuzz. There's an issue on HarfBuzz (link), which complained about HarfBuzz's text tracking deviates from that of macOS in 2019. Although I don't quite get the content in that page and whether the issue was considered fixed.
Reproduction code
Dart code
import 'dart:math';
import 'package:flutter/cupertino.dart';
void main() => runApp(const Main());
class Main extends StatelessWidget {
const Main({super.key});
@override
Widget build(BuildContext context) {
return CupertinoPageScaffold(
child: SafeArea(
child: Center(
child: Transform.translate(
offset: const Offset(0, -0),
child: Container(
width: 400,
height: 500,
decoration: BoxDecoration(
border: Border.all(),
),
child: Center(
child: Column(
mainAxisAlignment: MainAxisAlignment.center,
children: <Widget>[
...<double>[3, 4, 5, 7, 8, 9, 10, 11, 13, 15, 17, 19].map(
(double i) => Text(
'CupertinoSystemText size ${i.round()}',
style: TextStyle(
fontFamily: 'CupertinoSystemText',
fontSize: i,
letterSpacing: smallFontSpacingMap(i),
),
)
),
...<double>[20, 22, 25, 28, 32, 36].map(
(double i) => Text(
'SystemDisplay size ${i.round()}',
style: TextStyle(
fontFamily: 'CupertinoSystemDisplay',
fontSize: i,
letterSpacing: bigFontSpacingMap(i),
),
)
),
],
),
),
),
),
),
),
);
}
}
double smallFontSpacingMap(double i) {
return switch (i) {
// Experimental value
3 => 0.11,
4 => 0.16,
5 => 0.178,
7 => 0.2,
8 => 0.173,
9 => 0.142,
10 => 0.1,
11 => 0.03,
13 => -0.05,
15 => -0.21,
17 => -0.44,
19 => -0.54,
// Interpolation curve
_ => -0.158 + 0.123 * i * (1 - 0.0983 * i * (1 - 0.0195 * i)),
};
}
double bigFontSpacingMap(double i) {
return switch (i) {
// Experimental value
20 => 0.395,
22 => 0.325,
25 => 0.26,
28 => 0.34,
32 => 0.355,
36 => 0.335,
// Interpolation curve
_ => ((double j) =>
7.05 - 0.73 * i * (1 - 0.0353 * i * (1 - 0.0116 * i))
)(min(36, i)), // Extrapolate flatly above 36
};
}SwiftUI code
import SwiftUI
struct ContentView: View {
var body: some View {
Rectangle()
.fill(Color.white)
.frame(width: 400, height: 500)
.overlay(
VStack {
ForEach([3, 4, 5, 7, 8, 9, 10, 11, 13, 15, 17, 19], id: \.self) { i in
Text(String(format: "CupertinoSystemText size %d", Int(i)))
.font(.system(size: i))
.foregroundColor(.black)
}
ForEach([20, 22, 25, 28, 32, 36], id: \.self) { i in
Text(String(format: "SystemDisplay size %d", Int(i)))
.font(.system(size: i))
.foregroundColor(.black)
}
}
)
}
}
#Preview {
ContentView()
}Related issues:
Reacted by JHubi1, Jakub Krąpiec, Lukasz Piliszczuk, Paul Grandperrin, Paurakh Sharma Humagain, Ricardo Boss, Haijun, Hasan M. Hallak, Federico Magnani, selcuksezer and 21 more
Reacted by Jon Mountjoy, Federico Magnani and Greg Price
Metadata
Metadata
Assignees
Labels
P2Important issues not at the top of the work listImportant issues not at the top of the work lista: fidelityMatching the OEM platforms betterMatching the OEM platforms bettera: typographyText rendering, possibly libtxtText rendering, possibly libtxtengineflutter/engine related. See also e: labels.flutter/engine related. See also e: labels.p: cupertino_uicupertino_ui package in flutter/packagescupertino_ui package in flutter/packagespackageflutter/packages repository. See also p: labels.flutter/packages repository. See also p: labels.platform-iosiOS applications specificallyiOS applications specificallyteam-iosOwned by iOS platform teamOwned by iOS platform teamtriaged-iosTriaged by iOS platform teamTriaged by iOS platform team
Activity
dkwingsmt commentedon Jun 26, 2024
cc @jmagman
jmagman commentedon Jun 26, 2024
@jason-simmons do you know how the letter spacing is controlled?
jason-simmons commentedon Jun 26, 2024
The initial positioning of glyphs is done by HarfBuzz.
Additional letter spacing specified by
TextStyle.letterSpacingis applied by SkParagraph'sRun::addSpacesEvenly.@Rusino
Rusino commentedon Jun 26, 2024
Yes, positioning is done by harfbuzz (and is defined by harfbuzz logic and the font metrics). The letter spacing is done by SkParagraph.
makoConstruct commentedon Oct 28, 2024
The harfbuzz maintainers say they decided to keep track of the issue via this chrome issue, which was marked fixed January 2020.
delfme commentedon Feb 27, 2025
@dkwingsmt thanks for pointing me here.
It may sound unusual, but instead of formula, it appears to be a table with values from point 6 to 96 (see attached pics)
They disclosed values in the SF Symbol and Typography WWDC sessions and this doc
https://developer.apple.com/design/human-interface-guidelines/typography#Specifications
IIRC, we couldnt use those values exactly in flutter and had to fine tune them, though I might be mistaken. Additionally, the issue #120857 also affects letter spacing by increasing/reducing the space between characters. This is why you might see me sometime cross-commenting on "text-related" issues.
Regarding the height at smaller size, we found that Apple takes a similar approach, there's no formula and the height is adjusted ad hoc to match their preferred aestethics.
khaledhosny commentedon Feb 28, 2025
It might be worth testing with HarfBuzz 10.3.0, it fixed a few issues related to letter spacing in Apple fonts with
traktable.delfme commentedon May 31, 2025
Hi, HarfBuzz likely isn’t a factor here.
As mentioned earlier, the difference in letter spacing also ties into the font weight issue: #120857
Essentially, when the text renders thinner (e.g., about 0.25px thinner), it increases the perceived space between letters and words. So the final visual result is a combination of both bugs interacting at the same time. The same rationale applies when testing text fidelity in dark mode - there, the text appears 0.25px thicker, which makes the letter spacing look tighter compared to native rendering.
So I guess #150824 and
#120857 should be grouped into one PR, something like "Fix text rendering fidelity on iOS".
@dkwingsmt text height is also off, and might go in the same PR. To spot that issue, please test with a multiline text.
delfme commentedon May 31, 2025
@dkwingsmt you can also try your sample #150824 (comment) in dark mode with white text - you’ll likely see a different letter spacing, which is related to #120857.
dkwingsmt commentedon May 31, 2025
cc @MitchellGoodwin