Performance & Rendering

Const-First: Every widget that can be
```
const
```
MUST be
```
const
```
.
Lazy Rendering: Mandatory use of lazy-loading constructs (
```
SliverList.builder
```
or
```
SliverGrid.builder
```
) for any list exceeding 10 items.
Repaint Boundaries: Wrap complex animations or heavy UI sections in
```
RepaintBoundary
```
to optimize Impeller frame budget.
Isolate Parsing: Mandate
```
compute()
```
or
```
Isolate
```
for JSON parsing exceeding 1MB to avoid main-thread jank.
Optimize image handling with
```
cached_network_image
```
Handle asynchronous operations cleanly with proper cancellation during widget disposal
Minimize unnecessary rebuilds using memoization techniques
Implement pagination for large data sets
Flatten widget hierarchies where reasonable for better rendering performance
BuildContext Safety: Check
```
mounted
```
before using
```
context
```
across async gaps to prevent
```
setState
```
after dispose.

Design System

See design-system/SKILL.md for full token definitions (colors, spacing, radius, typography), reusable component rules, theming standards, and accessibility. Always use design tokens — never hardcode values.

Widget Patterns

Widget Extraction: STRICTLY prohibit private
```
_build*()
```
methods that return widgets. Extract them into separate
```
StatelessWidget
```
or
```
StatefulWidget
```
classes (can be private with
```
_
```
prefix). This ensures better testability, reusability, and composition.
Sliver Preference: Prefer
```
CustomScrollView
```
with
```
Slivers
```
over
```
SingleChildScrollView
```
for any non-trivial scrollable layout to ensure lazy loading and avoid jank. Use
```
SliverList.builder
```
or
```
SliverList.separated
```
and
```
SliverGrid.builder
```
for mixed content types.

Prominently use Sliver widgets:

SliverAppBar

SliverList

SliverGrid

SliverToBoxAdapter

SliverPadding

SliverPersistentHeader

SliverFillRemaining

SliverFixedExtentList

SliverAnimatedList

SliverFillViewport

SliverOpacity

SliverIgnorePointer

SliverLayoutBuilder

SliverPrototypeExtentList

SliverVisibility

No Unnecessary Containers: Reduce usage of
```
Container
```
. Use chained widgets like
```
DecoratedBox
```
,
```
Padding
```
,
```
SizedBox
```
, etc. Prefer
```
SizedBox
```
over
```
Container
```
for simple spacing.
Use inbuilt animated widgets where applicable (
```
AnimatedContainer
```
,
```
AnimatedOpacity
```
,
```
AnimatedSwitcher
```
,
```
AnimatedPositioned
```
, etc.) before resorting to explicit
```
AnimationController
```
.
Keep widgets focused and composable with clear responsibilities
Widget Keys: Assign
```
Key('feature_action_id')
```
to interactive widgets for test access. Use
```
ValueKey(item.id)
```
(not
```
ValueKey(index)
```
) for list items.

UI States

Use a loading indicator while fetching data
Use an error indicator with appropriate messaging for error displays
Handle empty states gracefully in UI with clear messaging

Interaction Patterns

FAB Usage: Use Floating Action Buttons (FAB) for primary positive actions (Add, Create, Generate, Save) on a screen. Avoid inline primary buttons when a FAB is more appropriate for the screen context.
Scroll Padding: ALWAYS add dynamic bottom padding to
```
SliverList.builder
```
or
```
SingleChildScrollView
```
when a FAB or Bottom Navigation Bar is present. Use
```
MediaQuery.of(context).padding.bottom + kFloatingActionButtonMargin + 56
```
(or
```
AppSpacing.xxl
```
) to prevent content overlap.
Screen vs Sheet: Prefer full
```
Scaffold
```
screens over
```
ModalBottomSheet
```
for complex forms, especially those with text inputs, to ensure proper keyboard handling and deep linking capability.
Deep Linking: Complex flows should be addressable via deep links (e.g.,
```
/strategy/:id
```
instead of just a bottom sheet).

Adaptive & Responsive Design

Design mobile first
Use
```
LayoutBuilder
```
and
```
MediaQuery
```
for adaptive layouts
Design for different screen sizes and orientations using responsive breakpoints

Adaptive Workflow (Abstract → Measure → Branch)

Abstract: Identify widgets needing adaptability. Share common data (e.g.,
```
Destination
```
for both
```
NavigationBar
```
and
```
NavigationRail
```
).
Measure: Use
```
MediaQuery.sizeOf(context)
```
for app-level layout decisions;
```
LayoutBuilder
```
for widget-specific constraints.
Branch: Apply breakpoints —
```
< 600
```
mobile,
```
600–840
```
tablet,
```
>= 840
```
desktop (Material guidelines).

Adaptive Rules

Never lock orientation; support both portrait and landscape
Never use
```
Platform.isIOS
```
/
```
Platform.isAndroid
```
for layout decisions; use window size
Don't use
```
OrientationBuilder
```
for layout changes; use
```
MediaQuery.sizeOf
```
or
```
LayoutBuilder
```
with breakpoints
On large screens, avoid full-width content; constrain content width for readability
Support keyboard navigation, mouse hover effects, and focus handling for custom widgets

ui-and-design

NPX Install

Tags

SKILL.md Content

Performance & Rendering

Design System

Widget Patterns

UI States

Interaction Patterns

Adaptive & Responsive Design

Adaptive Workflow (Abstract → Measure → Branch)

Adaptive Rules