How to Build a Stories Rail Screen in Flutter (Full Code + Preview)
A stories strip squeezed into the top of a feed hides most of what your friends posted today. This tutorial builds Pulse's dedicated Stories screen in Flutter: a 112px horizontal rail led by an 'Add story' tile whose dashed indigo ring is drawn by `_DashedRingPainter`, followed by avatars wrapped in a `SweepGradient` unseen ring or a grey seen ring from `_RingAvatarPainter`. Below a hairline divider, a RECENT UPDATES list repeats the same people as full rows with handles, timestamps and a 7px unseen dot. Everything is pure Flutter, no images, and every tap is a nullable callback.
Watch the Flutter UI walkthrough
A short screen recording of Pulse · Stories Rail running, if you'd rather see it before you read the code. The written tutorial below covers everything in it.
Can't see the video? Watch it on YouTube.
What you'll build
- ✓A horizontal `ListView.separated` rail with a leading add tile that reports `-1` through the same `onStory` callback as real stories
- ✓`_RingAvatarPainter`, which strokes a `SweepGradient` ring rotated by `-math.pi / 2` for unseen stories and a `#3A3A46` grey ring for seen ones
- ✓`_DashedRingPainter`, a 22-segment dashed ring built from `drawArc` calls with a 34% gap fraction
- ✓A `_RingAvatar` widget that reuses one `_Story` model at two sizes (62px in the rail, 50px in the list) and computes initials from the name
- ✓An `_UpdateRow` list whose name colour, unseen dot and indented dividers all derive from the `unseen` flag
Step-by-step build
Create the file
Add a new file at lib/social_feed_stories_rail/social_feed_stories_rail_screen.dart in your Flutter project.
Register the bundled fonts
No external packages — this is pure Flutter. It does bundle its design font (Inter), so drop the font file into fonts/ and declare it in pubspec.yaml:
flutter:
fonts:
- family: Inter
fonts:
- asset: fonts/Inter-Regular.ttfBuild it, piece by piece
Here's how the screen goes together. Each block below is a real slice of the code with a plain-English explanation — paste them in order, or grab the whole file from the next section.
Callbacks, palette and the story data
import 'dart:math' as math;
import 'package:flutter/material.dart';
/// Stories Rail Detail — a dedicated Pulse screen that expands the stories
/// experience into a full horizontal tray plus a scrolling list of recent
/// story updates. The tray leads with an "Add story" tile, then painted
/// gradient unseen-rings and muted seen-rings around gradient monogram
/// avatars. Below, a "RECENT UPDATES" section lists per-person updates with
/// handles, timestamps and unseen indicators, led by a bordered "Add to your
/// story" card. Every action is a nullable callback so the gallery registry
/// wires navigation. Self-contained per CONVENTIONS.md: pure Flutter, bundled
/// Inter font, own dark theme, SafeArea, fully overflow-proof.
///
/// slug: social-feed-stories-rail
class SocialFeedStoriesRailScreen extends StatelessWidget {
const SocialFeedStoriesRailScreen({
super.key,
this.onBack,
this.onSettings,
this.onStory,
this.onAddStory,
this.onSeeAll,
});
final VoidCallback? onBack;
final VoidCallback? onSettings;
/// A story ring/update tap (index into the story list).
final ValueChanged<int>? onStory;
final VoidCallback? onAddStory;
final VoidCallback? onSeeAll;
static const String _font = 'Inter';
static const Color _bg = Color(0xFF0B0B0F);
static const Color _surface = Color(0xFF15151B);
static const Color _brand = Color(0xFF6E56F7);
static const Color _hairline = Color(0xFF26262F);
static const Color _textHi = Color(0xFFF4F4F7);
static const Color _textLo = Color(0xFFB5B5C2);
static const Color _muted = Color(0xFF8A8A99);
static const List<_Story> _stories = <_Story>[
_Story('Maya Chen', 'mayabuilds', '2h ago', 0xFF6E56F7, 0xFF9B8CFF,
unseen: true),
_Story('Dev Kapoor', 'devk', '3h ago', 0xFF34D399, 0xFF6E56F7,
unseen: true),
_Story('Lena Ortiz', 'lenaux', '4h ago', 0xFFF4476B, 0xFFFBBF24,
unseen: true),
_Story('Sam Ito', 'samito', '6h ago', 0xFF9B8CFF, 0xFF34D399,
unseen: false),
_Story('Priya Nair', 'priyan', '8h ago', 0xFFFBBF24, 0xFFF4476B,
unseen: true),
_Story('Theo Brandt', 'theob', '11h ago', 0xFF6E56F7, 0xFF34D399,
unseen: false),
_Story('Amara Osei', 'amara', '14h ago', 0xFF9B8CFF, 0xFF6E56F7,
unseen: true),
_Story('Kai Fisher', 'kaifisher', '19h ago', 0xFFF4476B, 0xFF9B8CFF,
unseen: false),
];`SocialFeedStoriesRailScreen` is a `StatelessWidget` because nothing on this screen mutates locally — seen/unseen state comes from the data, and every interaction leaves through a nullable callback: `onBack`, `onSettings`, `onAddStory`, `onSeeAll`, and `onStory`, which is a `ValueChanged<int>` carrying the index into the story list rather than a plain `VoidCallback`. The palette is the Pulse near-mono dark set: `_bg` `#0B0B0F`, `_surface` `#15151B`, `_hairline` `#26262F`, with a single indigo `_brand` `#6E56F7` and three text tiers (`_textHi`, `_textLo`, `_muted`). The eight `_Story` records hold two colour ints, `colorA` and `colorB`, instead of image URLs — those two colours drive both the avatar gradient and the ring sweep, so each person gets a consistent identity with zero network assets. Note the mix of `unseen: true` and `false` so both ring styles render in the preview.
Forcing a dark theme and composing the column
@override
Widget build(BuildContext context) {
return Theme(
data: ThemeData.dark(useMaterial3: true),
child: Scaffold(
backgroundColor: _bg,
body: SafeArea(
bottom: false,
child: Column(
children: <Widget>[
_TopBar(onBack: onBack, onSettings: onSettings),
_StoriesRail(stories: _stories, onTap: onStory),
const Divider(height: 1, color: _hairline),
Expanded(
child: ListView(
padding: const EdgeInsets.only(bottom: 28),
children: <Widget>[
_AddYourStoryCard(onTap: onAddStory),
_SectionHeader(onSeeAll: onSeeAll),
for (int i = 0; i < _stories.length - 1; i++) ...<Widget>[
_UpdateRow(
story: _stories[i],
onTap: () => onStory?.call(i),
),
if (i < _stories.length - 2)
const Divider(
height: 1,
thickness: 1,
indent: 78,
color: _hairline,
),
],
],
),
),
],
),
),
),
);
}
}`build` wraps the `Scaffold` in `Theme(data: ThemeData.dark(useMaterial3: true))` so the `IconButton` ripples, `TextButton` and `Divider` pick up dark defaults even if the host app is light. `SafeArea(bottom: false)` protects the top bar from the notch but lets the list run under the home indicator, with `EdgeInsets.only(bottom: 28)` on the `ListView` providing the breathing room instead. The layout is a `Column`: `_TopBar`, the fixed-height `_StoriesRail`, a 1px hairline `Divider`, then an `Expanded` `ListView`. The list loop runs `i < _stories.length - 1`, so seven of the eight people appear as rows, and the inner `if (i < _stories.length - 2)` stops a divider being drawn after the final row. Each `_UpdateRow` gets `() => onStory?.call(i)`, so tapping a row and tapping the same avatar in the rail fire the identical callback with the identical index. Dividers use `indent: 78` — 16px padding plus the 50px avatar plus the 12px gap — so the line starts under the text, not the avatar.
Top bar, story model and the horizontal rail
// ── top bar ──────────────────────────────────────────────────────────────────
class _TopBar extends StatelessWidget {
const _TopBar({this.onBack, this.onSettings});
final VoidCallback? onBack;
final VoidCallback? onSettings;
@override
Widget build(BuildContext context) {
return Container(
height: 56,
padding: const EdgeInsets.symmetric(horizontal: 6),
decoration: const BoxDecoration(
color: SocialFeedStoriesRailScreen._bg,
border: Border(
bottom: BorderSide(color: SocialFeedStoriesRailScreen._hairline),
),
),
child: Row(
children: <Widget>[
IconButton(
onPressed: onBack,
icon: const Icon(Icons.arrow_back_ios_new, size: 20),
color: SocialFeedStoriesRailScreen._textHi,
splashRadius: 22,
),
const Expanded(
child: Text(
'Stories',
style: TextStyle(
fontFamily: SocialFeedStoriesRailScreen._font,
fontSize: 19,
fontWeight: FontWeight.w800,
letterSpacing: -0.6,
color: SocialFeedStoriesRailScreen._textHi,
),
),
),
IconButton(
onPressed: onSettings,
icon: const Icon(Icons.settings_outlined, size: 22),
color: SocialFeedStoriesRailScreen._textHi,
splashRadius: 22,
),
],
),
);
}
}
// ── stories rail ─────────────────────────────────────────────────────────────
class _Story {
const _Story(
this.name,
this.handle,
this.time,
this.colorA,
this.colorB, {
required this.unseen,
});
final String name;
final String handle;
final String time;
final int colorA;
final int colorB;
final bool unseen;
}
class _StoriesRail extends StatelessWidget {
const _StoriesRail({required this.stories, this.onTap});
final List<_Story> stories;
final ValueChanged<int>? onTap;
@override
Widget build(BuildContext context) {
return SizedBox(
height: 112,
child: ListView.separated(
scrollDirection: Axis.horizontal,
padding: const EdgeInsets.fromLTRB(16, 14, 16, 12),
itemCount: stories.length + 1,
separatorBuilder: (BuildContext context, int _) =>
const SizedBox(width: 14),
itemBuilder: (BuildContext context, int i) {
if (i == 0) {
return _AddStoryTile(onTap: onTap);
}
final _Story s = stories[i - 1];
return _StoryItem(story: s, onTap: () => onTap?.call(i - 1));
},
),
);
}
}`_TopBar` is a fixed 56px `Container` with only 6px horizontal padding, because the `IconButton`s carry their own 48px tap targets; its bottom edge is a `Border(bottom: BorderSide(color: _hairline))` rather than a separate `Divider`. The 'Stories' title sits at 19px `w800` with `letterSpacing: -0.6` inside `Expanded`, claiming all space between the 20px back chevron and the 22px settings gear (sized differently to balance the denser chevron glyph). `_Story` is a plain const class with a named `required this.unseen`, forcing the seen state to be spelled out at every call site. `_StoriesRail` is a `SizedBox(height: 112)` around a horizontal `ListView.separated`; the fixed height lets it sit inside the parent `Column` without an unbounded-height error. `itemCount` is `stories.length + 1` and index 0 is special-cased to `_AddStoryTile`, so the add tile scrolls with the rail rather than being pinned. The `i - 1` offset appears twice, once to read `stories[i - 1]` and once in `onTap?.call(i - 1)`, so the index the callback reports matches the data list rather than rail positions. Separators are constant 14px `SizedBox`es.
The add tile and a story tile
class _AddStoryTile extends StatelessWidget {
const _AddStoryTile({this.onTap});
final ValueChanged<int>? onTap;
@override
Widget build(BuildContext context) {
return GestureDetector(
onTap: () => onTap?.call(-1),
behavior: HitTestBehavior.opaque,
child: SizedBox(
width: 66,
child: Column(
children: <Widget>[
SizedBox(
width: 62,
height: 62,
child: CustomPaint(
painter: _DashedRingPainter(),
child: const Center(
child: Icon(
Icons.add,
color: SocialFeedStoriesRailScreen._brand,
size: 26,
),
),
),
),
const SizedBox(height: 7),
const Text(
'Your story',
maxLines: 1,
overflow: TextOverflow.ellipsis,
style: TextStyle(
fontFamily: SocialFeedStoriesRailScreen._font,
fontSize: 11.5,
color: SocialFeedStoriesRailScreen._muted,
),
),
],
),
),
);
}
}
class _StoryItem extends StatelessWidget {
const _StoryItem({required this.story, this.onTap});
final _Story story;
final VoidCallback? onTap;
@override
Widget build(BuildContext context) {
return GestureDetector(
onTap: onTap,
behavior: HitTestBehavior.opaque,
child: SizedBox(
width: 66,
child: Column(
children: <Widget>[
_RingAvatar(story: story, size: 62),
const SizedBox(height: 7),
Text(
story.name.split(' ').first,
maxLines: 1,
overflow: TextOverflow.ellipsis,
style: TextStyle(
fontFamily: SocialFeedStoriesRailScreen._font,
fontSize: 11.5,
color: story.unseen
? SocialFeedStoriesRailScreen._textHi
: SocialFeedStoriesRailScreen._muted,
),
),
],
),
),
);
}
}Both tiles are 66px wide `Column`s inside a `GestureDetector` with `HitTestBehavior.opaque`, so the gap between the ring and the caption is tappable rather than falling through to the list. `_AddStoryTile` takes the same `ValueChanged<int>?` as real stories and reports `-1`, so a host app can route 'new story' through the single `onStory` handler without a second parameter — the registry's `onAddStory` is reserved for the larger card below. Its 62px `CustomPaint` uses `_DashedRingPainter` with a centred 26px indigo `Icons.add`. `_StoryItem` swaps in `_RingAvatar(size: 62)` and shows only `story.name.split(' ').first`, because a 66px tile has room for one name, with `maxLines: 1` and ellipsis as a guard for long first names. The caption colour flips with `story.unseen`: `_textHi` for unseen, `_muted` for seen, which is the same visual convention Instagram uses so users read it without thinking.
One ring avatar, two sizes
/// A gradient sweep (unseen) / grey (seen) ring around a gradient monogram.
class _RingAvatar extends StatelessWidget {
const _RingAvatar({required this.story, required this.size});
final _Story story;
final double size;
String get _initials {
final List<String> p = story.name.trim().split(RegExp(r'\s+'));
if (p.length == 1) return p.first.characters.first.toUpperCase();
return (p.first[0] + p.last[0]).toUpperCase();
}
@override
Widget build(BuildContext context) {
final double inner = size - 10;
return SizedBox(
width: size,
height: size,
child: CustomPaint(
painter: _RingAvatarPainter(
colorA: Color(story.colorA),
colorB: Color(story.colorB),
unseen: story.unseen,
),
child: Center(
child: Container(
width: inner,
height: inner,
decoration: BoxDecoration(
shape: BoxShape.circle,
gradient: LinearGradient(
begin: Alignment.topLeft,
end: Alignment.bottomRight,
colors: <Color>[Color(story.colorA), Color(story.colorB)],
),
),
child: Center(
child: Text(
_initials,
style: TextStyle(
fontFamily: SocialFeedStoriesRailScreen._font,
fontSize: inner * 0.33,
fontWeight: FontWeight.w700,
color: Colors.white,
),
),
),
),
),
),
);
}
}`_RingAvatar` is the piece that makes the rail and the update list feel like the same people. It takes a `size` and derives `inner = size - 10`, leaving a 5px gutter on each side for the painted ring and a gap between ring and disc. The `_initials` getter splits the name on `RegExp(r'\s+')`, so double spaces don't produce an empty part, and uses `characters.first` for the single-name case so a name starting with a multi-code-unit glyph doesn't get split mid-grapheme; two-part names take the first letter of the first and last parts. The `CustomPaint` layers `_RingAvatarPainter` behind a `Center`ed circular `Container` carrying a top-left to bottom-right `LinearGradient` from `colorA` to `colorB`. The initials are `inner * 0.33` in size, so text scales with the avatar rather than being hard-coded — at 62px the inner disc is 52px and the letters about 17px; at 50px they drop to roughly 13px automatically.
The 'Add to your story' card
// ── add-to-your-story card ───────────────────────────────────────────────────
class _AddYourStoryCard extends StatelessWidget {
const _AddYourStoryCard({this.onTap});
final VoidCallback? onTap;
@override
Widget build(BuildContext context) {
return Padding(
padding: const EdgeInsets.fromLTRB(16, 16, 16, 8),
child: GestureDetector(
onTap: onTap,
behavior: HitTestBehavior.opaque,
child: Container(
padding: const EdgeInsets.fromLTRB(14, 14, 12, 14),
decoration: BoxDecoration(
color: SocialFeedStoriesRailScreen._surface,
borderRadius: BorderRadius.circular(16),
border: Border.all(color: SocialFeedStoriesRailScreen._hairline),
),
child: Row(
children: <Widget>[
const _Monogram(
initials: 'YOU',
colorA: Color(0xFF6E56F7),
colorB: Color(0xFF9B8CFF),
size: 46,
),
const SizedBox(width: 14),
const Expanded(
child: Column(
crossAxisAlignment: CrossAxisAlignment.start,
children: <Widget>[
Text(
'Your story',
maxLines: 1,
overflow: TextOverflow.ellipsis,
style: TextStyle(
fontFamily: SocialFeedStoriesRailScreen._font,
fontSize: 15,
fontWeight: FontWeight.w700,
letterSpacing: -0.2,
color: SocialFeedStoriesRailScreen._textHi,
),
),
SizedBox(height: 3),
Text(
'Add to your story',
maxLines: 1,
overflow: TextOverflow.ellipsis,
style: TextStyle(
fontFamily: SocialFeedStoriesRailScreen._font,
fontSize: 12.5,
color: SocialFeedStoriesRailScreen._muted,
),
),
],
),
),
Container(
width: 40,
height: 40,
decoration: BoxDecoration(
color: SocialFeedStoriesRailScreen._brand
.withValues(alpha: 0.16),
shape: BoxShape.circle,
),
child: const Icon(
Icons.add_a_photo_outlined,
color: SocialFeedStoriesRailScreen._brand,
size: 20,
),
),
],
),
),
),
);
}
}`_AddYourStoryCard` is the first item in the scrolling list and the only bordered card on the screen, which visually promotes it above the flat rows beneath. It uses `_surface` `#15151B` with a 16px radius and a `_hairline` border, and padding of `fromLTRB(14, 14, 12, 14)` — the right side is 2px tighter because the 40px icon circle already carries visual weight. The leading avatar is a `_Monogram` with hard-coded 'YOU' initials in the brand gradient `#6E56F7` to `#9B8CFF`, which distinguishes the user from the friends' avatars without needing a profile photo. Two text lines, 'Your story' at 15px `w700` and 'Add to your story' at 12.5px muted, sit in an `Expanded` `Column` so long translations ellipsise instead of overflowing. The trailing `Icons.add_a_photo_outlined` sits in a circle tinted `_brand.withValues(alpha: 0.16)`, the two-layer accent pattern — soft tinted disc, saturated glyph — used across the Pulse kit.
Section header and the update rows
// ── section header ───────────────────────────────────────────────────────────
class _SectionHeader extends StatelessWidget {
const _SectionHeader({this.onSeeAll});
final VoidCallback? onSeeAll;
@override
Widget build(BuildContext context) {
return Padding(
padding: const EdgeInsets.fromLTRB(20, 14, 12, 8),
child: Row(
children: <Widget>[
const Expanded(
child: Text(
'RECENT UPDATES',
maxLines: 1,
overflow: TextOverflow.ellipsis,
style: TextStyle(
fontFamily: SocialFeedStoriesRailScreen._font,
fontSize: 11.5,
fontWeight: FontWeight.w700,
letterSpacing: 1.0,
color: SocialFeedStoriesRailScreen._muted,
),
),
),
TextButton(
onPressed: onSeeAll,
style: TextButton.styleFrom(
minimumSize: Size.zero,
padding: const EdgeInsets.symmetric(horizontal: 10, vertical: 6),
tapTargetSize: MaterialTapTargetSize.shrinkWrap,
),
child: const Text(
'See all',
style: TextStyle(
fontFamily: SocialFeedStoriesRailScreen._font,
fontSize: 13,
fontWeight: FontWeight.w600,
color: SocialFeedStoriesRailScreen._brand,
),
),
),
],
),
);
}
}
// ── update row ───────────────────────────────────────────────────────────────
class _UpdateRow extends StatelessWidget {
const _UpdateRow({required this.story, this.onTap});
final _Story story;
final VoidCallback? onTap;
@override
Widget build(BuildContext context) {
return GestureDetector(
onTap: onTap,
behavior: HitTestBehavior.opaque,
child: Padding(
padding: const EdgeInsets.fromLTRB(16, 12, 12, 12),
child: Row(
children: <Widget>[
_RingAvatar(story: story, size: 50),
const SizedBox(width: 12),
Expanded(
child: Column(
crossAxisAlignment: CrossAxisAlignment.start,
children: <Widget>[
Row(
children: <Widget>[
Flexible(
child: Text(
story.name,
maxLines: 1,
overflow: TextOverflow.ellipsis,
style: TextStyle(
fontFamily: SocialFeedStoriesRailScreen._font,
fontSize: 15,
fontWeight: FontWeight.w600,
letterSpacing: -0.2,
color: story.unseen
? SocialFeedStoriesRailScreen._textHi
: SocialFeedStoriesRailScreen._textLo,
),
),
),
if (story.unseen) ...<Widget>[
const SizedBox(width: 8),
Container(
width: 7,
height: 7,
decoration: const BoxDecoration(
color: SocialFeedStoriesRailScreen._brand,
shape: BoxShape.circle,
),
),
],
],
),
const SizedBox(height: 2),
Text(
'@${story.handle}',
maxLines: 1,
overflow: TextOverflow.ellipsis,
style: const TextStyle(
fontFamily: SocialFeedStoriesRailScreen._font,
fontSize: 12.5,
color: SocialFeedStoriesRailScreen._muted,
),
),
],
),
),
const SizedBox(width: 10),
Text(
story.time,
style: const TextStyle(
fontFamily: SocialFeedStoriesRailScreen._font,
fontSize: 12,
color: SocialFeedStoriesRailScreen._muted,
),
),
const SizedBox(width: 4),
const Icon(
Icons.chevron_right,
size: 20,
color: SocialFeedStoriesRailScreen._muted,
),
],
),
),
);
}
}`_SectionHeader` sets 'RECENT UPDATES' at 11.5px `w700` with `letterSpacing: 1.0`, the uppercase-tracked eyebrow style, next to a 'See all' `TextButton`. The button overrides `minimumSize: Size.zero`, `tapTargetSize: MaterialTapTargetSize.shrinkWrap` and a 10×6 padding, because Material's default 48px minimum would push the header row to almost twice its intended height. `_UpdateRow` reuses `_RingAvatar` at 50px next to a name/handle column and a trailing timestamp plus chevron. The name is wrapped in `Flexible` inside a `Row`, so it shrinks to make room for the 7px indigo unseen dot that follows it, rather than pushing the dot off screen for a long name; the dot and its 8px spacer only render inside `if (story.unseen)`. The name colour steps down from `_textHi` to `_textLo` for seen stories, a lighter demotion than the rail's `_muted`, because a list row still needs to be readable at a glance.
The monogram and the two painters
// ── monogram avatar ──────────────────────────────────────────────────────────
class _Monogram extends StatelessWidget {
const _Monogram({
required this.initials,
required this.colorA,
required this.colorB,
this.size = 42,
});
final String initials;
final Color colorA;
final Color colorB;
final double size;
@override
Widget build(BuildContext context) {
return Container(
width: size,
height: size,
decoration: BoxDecoration(
shape: BoxShape.circle,
gradient: LinearGradient(
begin: Alignment.topLeft,
end: Alignment.bottomRight,
colors: <Color>[colorA, colorB],
),
),
child: Center(
child: Text(
initials,
style: TextStyle(
fontFamily: SocialFeedStoriesRailScreen._font,
fontSize: size * 0.3,
fontWeight: FontWeight.w700,
color: Colors.white,
),
),
),
);
}
}
// ── painters ─────────────────────────────────────────────────────────────────
class _RingAvatarPainter extends CustomPainter {
_RingAvatarPainter({
required this.colorA,
required this.colorB,
required this.unseen,
});
final Color colorA;
final Color colorB;
final bool unseen;
@override
void paint(Canvas canvas, Size size) {
final Offset center = size.center(Offset.zero);
final double radius = size.width / 2 - 1.5;
if (unseen) {
canvas.drawCircle(
center,
radius,
Paint()
..style = PaintingStyle.stroke
..strokeWidth = 2.6
..shader = SweepGradient(
colors: <Color>[colorA, colorB, colorA],
transform: const GradientRotation(-math.pi / 2),
).createShader(Rect.fromCircle(center: center, radius: radius)),
);
} else {
canvas.drawCircle(
center,
radius,
Paint()
..style = PaintingStyle.stroke
..strokeWidth = 2.0
..color = const Color(0xFF3A3A46),
);
}
}
@override
bool shouldRepaint(covariant _RingAvatarPainter old) =>
old.unseen != unseen || old.colorA != colorA || old.colorB != colorB;
}
/// A dashed-look brand ring used for the "Add story" tile.
class _DashedRingPainter extends CustomPainter {
@override
void paint(Canvas canvas, Size size) {
final Offset center = size.center(Offset.zero);
final double radius = size.width / 2 - 1.5;
// Filled surface disc.
canvas.drawCircle(
center,
radius,
Paint()..color = const Color(0xFF15151B),
);
// Dashed brand ring.
final Paint dash = Paint()
..style = PaintingStyle.stroke
..strokeWidth = 2.2
..strokeCap = StrokeCap.round
..color = const Color(0xFF6E56F7);
const int segments = 22;
const double gap = 0.34; // fraction of each segment left empty
final double step = (2 * math.pi) / segments;
for (int i = 0; i < segments; i++) {
final double start = i * step;
canvas.drawArc(
Rect.fromCircle(center: center, radius: radius),
start,
step * (1 - gap),
false,
dash,
);
}
}
@override
bool shouldRepaint(covariant CustomPainter oldDelegate) => false;
}`_Monogram` is the standalone version of the avatar disc — a gradient circle with initials at `size * 0.3` — used only by the 'YOU' card. `_RingAvatarPainter` computes `radius = size.width / 2 - 1.5` so the 2.6px stroke doesn't clip at the edges. For unseen it builds a `SweepGradient` with `[colorA, colorB, colorA]` so the ring's start and end colours match and there is no visible seam, and rotates it by `GradientRotation(-math.pi / 2)` so the sweep begins at twelve o'clock instead of three. Seen rings are a thinner 2.0px `#3A3A46` stroke. `shouldRepaint` compares `unseen` and both colours, so scrolling doesn't repaint unchanged rings. `_DashedRingPainter` first fills a `#15151B` disc, then loops 22 times drawing arcs of `step * (1 - gap)` where `gap = 0.34`, leaving a third of each segment empty; `StrokeCap.round` softens the dash ends. It never repaints because it has no inputs.
Full code
The complete, ready-to-paste source. Free to use in your projects — one click copies it all.
import 'dart:math' as math;
import 'package:flutter/material.dart';
/// Stories Rail Detail — a dedicated Pulse screen that expands the stories
/// experience into a full horizontal tray plus a scrolling list of recent
/// story updates. The tray leads with an "Add story" tile, then painted
/// gradient unseen-rings and muted seen-rings around gradient monogram
/// avatars. Below, a "RECENT UPDATES" section lists per-person updates with
/// handles, timestamps and unseen indicators, led by a bordered "Add to your
/// story" card. Every action is a nullable callback so the gallery registry
/// wires navigation. Self-contained per CONVENTIONS.md: pure Flutter, bundled
/// Inter font, own dark theme, SafeArea, fully overflow-proof.
///
/// slug: social-feed-stories-rail
class SocialFeedStoriesRailScreen extends StatelessWidget {
const SocialFeedStoriesRailScreen({
super.key,
this.onBack,
this.onSettings,
this.onStory,
this.onAddStory,
this.onSeeAll,
});
final VoidCallback? onBack;
final VoidCallback? onSettings;
/// A story ring/update tap (index into the story list).
final ValueChanged<int>? onStory;
final VoidCallback? onAddStory;
final VoidCallback? onSeeAll;
static const String _font = 'Inter';
static const Color _bg = Color(0xFF0B0B0F);
static const Color _surface = Color(0xFF15151B);
static const Color _brand = Color(0xFF6E56F7);
static const Color _hairline = Color(0xFF26262F);
static const Color _textHi = Color(0xFFF4F4F7);
static const Color _textLo = Color(0xFFB5B5C2);
static const Color _muted = Color(0xFF8A8A99);
static const List<_Story> _stories = <_Story>[
_Story('Maya Chen', 'mayabuilds', '2h ago', 0xFF6E56F7, 0xFF9B8CFF,
unseen: true),
_Story('Dev Kapoor', 'devk', '3h ago', 0xFF34D399, 0xFF6E56F7,
unseen: true),
_Story('Lena Ortiz', 'lenaux', '4h ago', 0xFFF4476B, 0xFFFBBF24,
unseen: true),
_Story('Sam Ito', 'samito', '6h ago', 0xFF9B8CFF, 0xFF34D399,
unseen: false),
_Story('Priya Nair', 'priyan', '8h ago', 0xFFFBBF24, 0xFFF4476B,
unseen: true),
_Story('Theo Brandt', 'theob', '11h ago', 0xFF6E56F7, 0xFF34D399,
unseen: false),
_Story('Amara Osei', 'amara', '14h ago', 0xFF9B8CFF, 0xFF6E56F7,
unseen: true),
_Story('Kai Fisher', 'kaifisher', '19h ago', 0xFFF4476B, 0xFF9B8CFF,
unseen: false),
];
@override
Widget build(BuildContext context) {
return Theme(
data: ThemeData.dark(useMaterial3: true),
child: Scaffold(
backgroundColor: _bg,
body: SafeArea(
bottom: false,
child: Column(
children: <Widget>[
_TopBar(onBack: onBack, onSettings: onSettings),
_StoriesRail(stories: _stories, onTap: onStory),
const Divider(height: 1, color: _hairline),
Expanded(
child: ListView(
padding: const EdgeInsets.only(bottom: 28),
children: <Widget>[
_AddYourStoryCard(onTap: onAddStory),
_SectionHeader(onSeeAll: onSeeAll),
for (int i = 0; i < _stories.length - 1; i++) ...<Widget>[
_UpdateRow(
story: _stories[i],
onTap: () => onStory?.call(i),
),
if (i < _stories.length - 2)
const Divider(
height: 1,
thickness: 1,
indent: 78,
color: _hairline,
),
],
],
),
),
],
),
),
),
);
}
}
// ── top bar ──────────────────────────────────────────────────────────────────
class _TopBar extends StatelessWidget {
const _TopBar({this.onBack, this.onSettings});
final VoidCallback? onBack;
final VoidCallback? onSettings;
@override
Widget build(BuildContext context) {
return Container(
height: 56,
padding: const EdgeInsets.symmetric(horizontal: 6),
decoration: const BoxDecoration(
color: SocialFeedStoriesRailScreen._bg,
border: Border(
bottom: BorderSide(color: SocialFeedStoriesRailScreen._hairline),
),
),
child: Row(
children: <Widget>[
IconButton(
onPressed: onBack,
icon: const Icon(Icons.arrow_back_ios_new, size: 20),
color: SocialFeedStoriesRailScreen._textHi,
splashRadius: 22,
),
const Expanded(
child: Text(
'Stories',
style: TextStyle(
fontFamily: SocialFeedStoriesRailScreen._font,
fontSize: 19,
fontWeight: FontWeight.w800,
letterSpacing: -0.6,
color: SocialFeedStoriesRailScreen._textHi,
),
),
),
IconButton(
onPressed: onSettings,
icon: const Icon(Icons.settings_outlined, size: 22),
color: SocialFeedStoriesRailScreen._textHi,
splashRadius: 22,
),
],
),
);
}
}
// ── stories rail ─────────────────────────────────────────────────────────────
class _Story {
const _Story(
this.name,
this.handle,
this.time,
this.colorA,
this.colorB, {
required this.unseen,
});
final String name;
final String handle;
final String time;
final int colorA;
final int colorB;
final bool unseen;
}
class _StoriesRail extends StatelessWidget {
const _StoriesRail({required this.stories, this.onTap});
final List<_Story> stories;
final ValueChanged<int>? onTap;
@override
Widget build(BuildContext context) {
return SizedBox(
height: 112,
child: ListView.separated(
scrollDirection: Axis.horizontal,
padding: const EdgeInsets.fromLTRB(16, 14, 16, 12),
itemCount: stories.length + 1,
separatorBuilder: (BuildContext context, int _) =>
const SizedBox(width: 14),
itemBuilder: (BuildContext context, int i) {
if (i == 0) {
return _AddStoryTile(onTap: onTap);
}
final _Story s = stories[i - 1];
return _StoryItem(story: s, onTap: () => onTap?.call(i - 1));
},
),
);
}
}
class _AddStoryTile extends StatelessWidget {
const _AddStoryTile({this.onTap});
final ValueChanged<int>? onTap;
@override
Widget build(BuildContext context) {
return GestureDetector(
onTap: () => onTap?.call(-1),
behavior: HitTestBehavior.opaque,
child: SizedBox(
width: 66,
child: Column(
children: <Widget>[
SizedBox(
width: 62,
height: 62,
child: CustomPaint(
painter: _DashedRingPainter(),
child: const Center(
child: Icon(
Icons.add,
color: SocialFeedStoriesRailScreen._brand,
size: 26,
),
),
),
),
const SizedBox(height: 7),
const Text(
'Your story',
maxLines: 1,
overflow: TextOverflow.ellipsis,
style: TextStyle(
fontFamily: SocialFeedStoriesRailScreen._font,
fontSize: 11.5,
color: SocialFeedStoriesRailScreen._muted,
),
),
],
),
),
);
}
}
class _StoryItem extends StatelessWidget {
const _StoryItem({required this.story, this.onTap});
final _Story story;
final VoidCallback? onTap;
@override
Widget build(BuildContext context) {
return GestureDetector(
onTap: onTap,
behavior: HitTestBehavior.opaque,
child: SizedBox(
width: 66,
child: Column(
children: <Widget>[
_RingAvatar(story: story, size: 62),
const SizedBox(height: 7),
Text(
story.name.split(' ').first,
maxLines: 1,
overflow: TextOverflow.ellipsis,
style: TextStyle(
fontFamily: SocialFeedStoriesRailScreen._font,
fontSize: 11.5,
color: story.unseen
? SocialFeedStoriesRailScreen._textHi
: SocialFeedStoriesRailScreen._muted,
),
),
],
),
),
);
}
}
/// A gradient sweep (unseen) / grey (seen) ring around a gradient monogram.
class _RingAvatar extends StatelessWidget {
const _RingAvatar({required this.story, required this.size});
final _Story story;
final double size;
String get _initials {
final List<String> p = story.name.trim().split(RegExp(r'\s+'));
if (p.length == 1) return p.first.characters.first.toUpperCase();
return (p.first[0] + p.last[0]).toUpperCase();
}
@override
Widget build(BuildContext context) {
final double inner = size - 10;
return SizedBox(
width: size,
height: size,
child: CustomPaint(
painter: _RingAvatarPainter(
colorA: Color(story.colorA),
colorB: Color(story.colorB),
unseen: story.unseen,
),
child: Center(
child: Container(
width: inner,
height: inner,
decoration: BoxDecoration(
shape: BoxShape.circle,
gradient: LinearGradient(
begin: Alignment.topLeft,
end: Alignment.bottomRight,
colors: <Color>[Color(story.colorA), Color(story.colorB)],
),
),
child: Center(
child: Text(
_initials,
style: TextStyle(
fontFamily: SocialFeedStoriesRailScreen._font,
fontSize: inner * 0.33,
fontWeight: FontWeight.w700,
color: Colors.white,
),
),
),
),
),
),
);
}
}
// ── add-to-your-story card ───────────────────────────────────────────────────
class _AddYourStoryCard extends StatelessWidget {
const _AddYourStoryCard({this.onTap});
final VoidCallback? onTap;
@override
Widget build(BuildContext context) {
return Padding(
padding: const EdgeInsets.fromLTRB(16, 16, 16, 8),
child: GestureDetector(
onTap: onTap,
behavior: HitTestBehavior.opaque,
child: Container(
padding: const EdgeInsets.fromLTRB(14, 14, 12, 14),
decoration: BoxDecoration(
color: SocialFeedStoriesRailScreen._surface,
borderRadius: BorderRadius.circular(16),
border: Border.all(color: SocialFeedStoriesRailScreen._hairline),
),
child: Row(
children: <Widget>[
const _Monogram(
initials: 'YOU',
colorA: Color(0xFF6E56F7),
colorB: Color(0xFF9B8CFF),
size: 46,
),
const SizedBox(width: 14),
const Expanded(
child: Column(
crossAxisAlignment: CrossAxisAlignment.start,
children: <Widget>[
Text(
'Your story',
maxLines: 1,
overflow: TextOverflow.ellipsis,
style: TextStyle(
fontFamily: SocialFeedStoriesRailScreen._font,
fontSize: 15,
fontWeight: FontWeight.w700,
letterSpacing: -0.2,
color: SocialFeedStoriesRailScreen._textHi,
),
),
SizedBox(height: 3),
Text(
'Add to your story',
maxLines: 1,
overflow: TextOverflow.ellipsis,
style: TextStyle(
fontFamily: SocialFeedStoriesRailScreen._font,
fontSize: 12.5,
color: SocialFeedStoriesRailScreen._muted,
),
),
],
),
),
Container(
width: 40,
height: 40,
decoration: BoxDecoration(
color: SocialFeedStoriesRailScreen._brand
.withValues(alpha: 0.16),
shape: BoxShape.circle,
),
child: const Icon(
Icons.add_a_photo_outlined,
color: SocialFeedStoriesRailScreen._brand,
size: 20,
),
),
],
),
),
),
);
}
}
// ── section header ───────────────────────────────────────────────────────────
class _SectionHeader extends StatelessWidget {
const _SectionHeader({this.onSeeAll});
final VoidCallback? onSeeAll;
@override
Widget build(BuildContext context) {
return Padding(
padding: const EdgeInsets.fromLTRB(20, 14, 12, 8),
child: Row(
children: <Widget>[
const Expanded(
child: Text(
'RECENT UPDATES',
maxLines: 1,
overflow: TextOverflow.ellipsis,
style: TextStyle(
fontFamily: SocialFeedStoriesRailScreen._font,
fontSize: 11.5,
fontWeight: FontWeight.w700,
letterSpacing: 1.0,
color: SocialFeedStoriesRailScreen._muted,
),
),
),
TextButton(
onPressed: onSeeAll,
style: TextButton.styleFrom(
minimumSize: Size.zero,
padding: const EdgeInsets.symmetric(horizontal: 10, vertical: 6),
tapTargetSize: MaterialTapTargetSize.shrinkWrap,
),
child: const Text(
'See all',
style: TextStyle(
fontFamily: SocialFeedStoriesRailScreen._font,
fontSize: 13,
fontWeight: FontWeight.w600,
color: SocialFeedStoriesRailScreen._brand,
),
),
),
],
),
);
}
}
// ── update row ───────────────────────────────────────────────────────────────
class _UpdateRow extends StatelessWidget {
const _UpdateRow({required this.story, this.onTap});
final _Story story;
final VoidCallback? onTap;
@override
Widget build(BuildContext context) {
return GestureDetector(
onTap: onTap,
behavior: HitTestBehavior.opaque,
child: Padding(
padding: const EdgeInsets.fromLTRB(16, 12, 12, 12),
child: Row(
children: <Widget>[
_RingAvatar(story: story, size: 50),
const SizedBox(width: 12),
Expanded(
child: Column(
crossAxisAlignment: CrossAxisAlignment.start,
children: <Widget>[
Row(
children: <Widget>[
Flexible(
child: Text(
story.name,
maxLines: 1,
overflow: TextOverflow.ellipsis,
style: TextStyle(
fontFamily: SocialFeedStoriesRailScreen._font,
fontSize: 15,
fontWeight: FontWeight.w600,
letterSpacing: -0.2,
color: story.unseen
? SocialFeedStoriesRailScreen._textHi
: SocialFeedStoriesRailScreen._textLo,
),
),
),
if (story.unseen) ...<Widget>[
const SizedBox(width: 8),
Container(
width: 7,
height: 7,
decoration: const BoxDecoration(
color: SocialFeedStoriesRailScreen._brand,
shape: BoxShape.circle,
),
),
],
],
),
const SizedBox(height: 2),
Text(
'@${story.handle}',
maxLines: 1,
overflow: TextOverflow.ellipsis,
style: const TextStyle(
fontFamily: SocialFeedStoriesRailScreen._font,
fontSize: 12.5,
color: SocialFeedStoriesRailScreen._muted,
),
),
],
),
),
const SizedBox(width: 10),
Text(
story.time,
style: const TextStyle(
fontFamily: SocialFeedStoriesRailScreen._font,
fontSize: 12,
color: SocialFeedStoriesRailScreen._muted,
),
),
const SizedBox(width: 4),
const Icon(
Icons.chevron_right,
size: 20,
color: SocialFeedStoriesRailScreen._muted,
),
],
),
),
);
}
}
// ── monogram avatar ──────────────────────────────────────────────────────────
class _Monogram extends StatelessWidget {
const _Monogram({
required this.initials,
required this.colorA,
required this.colorB,
this.size = 42,
});
final String initials;
final Color colorA;
final Color colorB;
final double size;
@override
Widget build(BuildContext context) {
return Container(
width: size,
height: size,
decoration: BoxDecoration(
shape: BoxShape.circle,
gradient: LinearGradient(
begin: Alignment.topLeft,
end: Alignment.bottomRight,
colors: <Color>[colorA, colorB],
),
),
child: Center(
child: Text(
initials,
style: TextStyle(
fontFamily: SocialFeedStoriesRailScreen._font,
fontSize: size * 0.3,
fontWeight: FontWeight.w700,
color: Colors.white,
),
),
),
);
}
}
// ── painters ─────────────────────────────────────────────────────────────────
class _RingAvatarPainter extends CustomPainter {
_RingAvatarPainter({
required this.colorA,
required this.colorB,
required this.unseen,
});
final Color colorA;
final Color colorB;
final bool unseen;
@override
void paint(Canvas canvas, Size size) {
final Offset center = size.center(Offset.zero);
final double radius = size.width / 2 - 1.5;
if (unseen) {
canvas.drawCircle(
center,
radius,
Paint()
..style = PaintingStyle.stroke
..strokeWidth = 2.6
..shader = SweepGradient(
colors: <Color>[colorA, colorB, colorA],
transform: const GradientRotation(-math.pi / 2),
).createShader(Rect.fromCircle(center: center, radius: radius)),
);
} else {
canvas.drawCircle(
center,
radius,
Paint()
..style = PaintingStyle.stroke
..strokeWidth = 2.0
..color = const Color(0xFF3A3A46),
);
}
}
@override
bool shouldRepaint(covariant _RingAvatarPainter old) =>
old.unseen != unseen || old.colorA != colorA || old.colorB != colorB;
}
/// A dashed-look brand ring used for the "Add story" tile.
class _DashedRingPainter extends CustomPainter {
@override
void paint(Canvas canvas, Size size) {
final Offset center = size.center(Offset.zero);
final double radius = size.width / 2 - 1.5;
// Filled surface disc.
canvas.drawCircle(
center,
radius,
Paint()..color = const Color(0xFF15151B),
);
// Dashed brand ring.
final Paint dash = Paint()
..style = PaintingStyle.stroke
..strokeWidth = 2.2
..strokeCap = StrokeCap.round
..color = const Color(0xFF6E56F7);
const int segments = 22;
const double gap = 0.34; // fraction of each segment left empty
final double step = (2 * math.pi) / segments;
for (int i = 0; i < segments; i++) {
final double start = i * step;
canvas.drawArc(
Rect.fromCircle(center: center, radius: radius),
start,
step * (1 - gap),
false,
dash,
);
}
}
@override
bool shouldRepaint(covariant CustomPainter oldDelegate) => false;
}
Plus bundled 1 binary asset (fonts/images). The CLI and MCP install those for you automatically.
Two faster ways to add it
Copy-paste works, but you can skip it entirely.
1. FlutterKit CLI
One command drops this screen — and its fonts — straight into your project.
$ flutterkit add social-feed-stories-rail2. AI agent (MCP)
Connect FlutterKit's MCP server in Claude or Cursor and just ask your agent to install social-feed-stories-rail — it fetches and writes the files for you.
FAQ
Can I use this stories screen in a commercial app?
Yes. FlutterKit screens are free for personal and commercial projects under MIT-style terms. There is no licence key or attribution requirement — run `flutterkit add social-feed-stories-rail`, or copy the Dart above into your project, and ship it.
Does the screen need any pub packages or fonts?
No packages — it imports only `dart:math` and `package:flutter/material.dart`. The only asset is the Inter font, which `flutterkit add social-feed-stories-rail` bundles and registers in your pubspec. If you paste the code manually, either add Inter yourself or delete the `fontFamily` lines to fall back to the system font.
Which Flutter version does this need?
Flutter 3.22 or newer, because of `super.key` in the constructor and `_brand.withValues(alpha: 0.16)` on the add-a-photo circle. On an older 3.x SDK, change `withValues(alpha: 0.16)` to `withOpacity(0.16)` and replace `super.key` with `Key? key` plus `super(key: key)`.
How do I load real stories from a server instead of the static list?
The screen reads everything from `_stories`, a `static const List<_Story>`. Convert it to a constructor parameter (`final List<_Story> stories`) and pass it from your state layer, mapping each API record to `_Story(name, handle, time, colorA, colorB, unseen: ...)`. Both `_StoriesRail` and the update loop already take the list as input, so no other code changes. For profile photos, swap the gradient `Container` inside `_RingAvatar` for a `ClipOval` with your image while keeping the painter behind it.
Why does tapping the 'Add story' tile call `onStory(-1)` instead of `onAddStory`?
The rail is built from one `ValueChanged<int>` so every tile is handled uniformly, and `-1` is the sentinel for 'not a story index'. The bigger 'Add to your story' card below uses the dedicated `onAddStory`. If you prefer one handler, pass the same function to both and treat a negative index as the create action.
