AgentSkillsCN

Flutter Ui Design

借助 shadcn_ui_flutter,打造独具特色且具备生产级水准的 Flutter 界面。从设计思维出发,结合语义化标记、组件选型,以及专属于 Flutter 的设计模式,为您的 UI 决策提供全面指导。

SKILL.md
--- frontmatter
description: Create distinctive, production-grade Flutter interfaces using shadcn_ui_flutter. Guides UI decisions from design thinking through implementation with semantic tokens, component selection, and Flutter-specific patterns.

This skill guides creation of distinctive, production-grade Flutter interfaces using shadcn_ui_flutter. It covers design thinking, component selection, and implementation patterns for building memorable, cohesive UIs.

Design Thinking

Before coding, understand the context and commit to a BOLD aesthetic direction:

  • Purpose: What problem does this interface solve? Who uses it?
  • Tone: Pick an extreme: brutally minimal, maximalist chaos, retro-futuristic, organic/natural, luxury/refined, playful/toy-like, editorial/magazine, brutalist/raw, art deco/geometric, soft/pastel, industrial/utilitarian, etc.
  • Constraints: Technical requirements (Flutter, performance, accessibility).
  • Differentiation: What makes this UNFORGETTABLE? What's the one thing someone will remember?

CRITICAL: Choose a clear conceptual direction and execute it with precision. Bold maximalism and refined minimalism both work - the key is intentionality, not intensity.

Then implement working Flutter code using shadcn_ui that is:

  • Production-grade and functional
  • Visually striking and memorable
  • Cohesive with a clear aesthetic point-of-view
  • Meticulously refined in every detail

Flutter Design Tokens

Use semantic design tokens from the shadcn_ui theme extension:

TokenAccessExample
Typographycontext.typo.h1-h5, .large, .medium, .smallcontext.typo.h3
Colorscontext.shadColors.primary, .muted, .accentcontext.shadColors.primary
Spacingcontext.spacing.xs through xxlcontext.spacing.md
Radiuscontext.radiusSmall, .medium, .largecontext.radiusMedium
Semanticcontext.surfacePositive, .textWarningcontext.surfacePositive

Always use tokens - never hardcode colors or dimensions.


Shadcn UI Component Library

Form Components

ComponentWhen to Use
ShadButtonPrimary, secondary, outline, ghost, destructive variants
ShadIconButtonIcon-only actions (close, menu, navigation)
ShadInputSingle-line text input
ShadInputFormFieldText input with validation support
ShadTextareaMulti-line text input
ShadSelect<T>Dropdown selection (generic type-safe)
ShadSelectFormField<T>Select with form integration
ShadCombobox<T>Dropdown with search functionality
ShadCheckboxBoolean/ternary checkbox selection
ShadRadioGroup<T>Single choice from options
ShadRadio<T>Individual radio option
ShadSwitchToggle switch (on/off)
ShadSwitchFormFieldSwitch with form integration
ShadSliderRange/value selection slider
ShadInputOTPOTP/captcha character input

Date/Time Components

ComponentWhen to Use
ShadCalendarCalendar view for date selection
ShadDatePickerDate picker dialog
ShadTimePickerTime picker dialog

Display Components

ComponentWhen to Use
ShadCardContainer with optional title/description/footer
ShadBadgeStatus indicators, counts, labels
ShadAlertWarning/info/error banners with icons
ShadAvatarUser/profile images with fallback
ShadProgressProgress indicator (determinate/indeterminate)
ShadSeparatorVisual divider between content
ShadTableTabular data display

Navigation Components

ComponentWhen to Use
ShadTabsTab navigation (horizontal/vertical)
ShadBreadcrumbNavigation breadcrumbs
ShadMenubarMenu bar with dropdown items
ShadPopoverPopover menu (anchored positioning)
ShadTooltipHover tooltip (with delay)
ShadContextMenuRight-click context menu

Layout Components

ComponentWhen to Use
ShadDialogModal dialog (use showShadDialog)
ShadSheetBottom sheet drawer (use showShadSheet)
ShadResizableResizable panel layout

Feedback Components

ComponentWhen to Use
ShadToastToast notifications (use showShadToast)
ShadSonnerModern notification (v0.24.0+)

Data Components

ComponentWhen to Use
ShadAccordionCollapsible sections (FAQ, details)
ShadFormForm with validation, dot notation support

Shadcn UI Best Practices

Composition Over Inheritance

dart
// CORRECT - Compose existing widgets
ShadCard(
  title: Text('Settings', style: context.typo.h4),
  description: Text('Manage your preferences', style: context.typo.small),
  child: Column(
    children: [
      ShadButton.outline(onPressed: () {}, child: Text('Reset')),
      ShadButton.primary(onPressed: () {}, child: Text('Save')),
    ],
  ),
)

// INCORRECT - Never extend widgets unnecessarily
class MyCustomCard extends StatelessWidget { ... }

Theme Usage

dart
// Use semantic colors
context.shadColors.primary
context.shadColors.muted
context.shadColors.accent
context.colors.destructive
context.colors.warning
context.colors.success

// NEVER hardcode colors
Color(0xFF0F766E)  // ❌
Colors.blue         // ❌

Typography

dart
// Use typo tokens
context.typo.h1  // Display heading
context.typo.h2  // Large heading
context.typo.h3  // Medium heading
context.typo.h4  // Small heading
context.typo.h5  // Caption heading
context.typo.large  // Large body
context.typo.medium // Medium body (default)
context.typo.small  // Small body
context.typo.muted  // Muted/secondary text

Animation

dart
// flutter_animate integration is built-in
// Use animated variants for micro-interactions
ShadButton(
  onPressed: () {},
  animationDuration: Duration(milliseconds: 200),
  child: Text('Submit'),
)

Flutter Motion Patterns

Implicit Animations

WidgetUse For
AnimatedContainerAnimate any container property
AnimatedOpacityFade in/out transitions
AnimatedCrossFadeCrossfade between two widgets
AnimatedDefaultTextStyleText style transitions
TweenAnimationBuilderCustom tween animations

Explicit Animations

WidgetUse For
AnimationControllerManual animation control
HeroShared element transitions between routes
CustomTweenSpecialized transition logic

High-Impact Moments

  • Page load: Staggered reveals using animationDelay in flutter_animate
  • Scroll: Triggered animations via NotificationListener
  • Navigation: Hero transitions for continuity between screens

Spatial Composition

PatternWidgetUse When
LinearRow, ColumnAligned, stacked content
OverlapStackLayered elements, overlays
ResponsiveLayoutBuilderAdaptive to parent constraints
ConstrainedConstrainedBox, SizedBoxFixed dimensions, limits
FlexibleFlexible, ExpandedFlex distribution, responsive sizing
AspectAspectRatio, FittedBoxAspect ratio preservation

Visual Details

EffectImplementation
GradientsShaderMask with LinearGradient or RadialGradient
Noise/TextureCustomPaint with noise image
ShadowsBoxShadow in BoxDecoration
BlurBackdropFilter with ImageFilter.blur
Clip shapesClipRRect, ClipPath, CustomClipper<Shape>

Performance-Sensitive Design

PatternWhy
const constructorsReduce rebuild overhead, improve performance
Key in listsProper element tracking, animation stability
RepaintBoundaryIsolate animated regions, reduce repaints
AutomaticKeepAlivePreserve scroll position in nested lists
LazyLoadingDefer loading of images/network assets

Anti-Patterns to Avoid

❌ Don't✅ Instead
Hardcoded colorscontext.shadColors.*
Material colors directlySemantic extensions from theme
Extend StatelessWidgetCompose existing shadcn widgets
print() debuggingLoggerService
Cross-feature importsKeep features isolated
Skip constUse const where possible

Integration Points

  • flutter-mcp-vibe-coding: For testing UIs with MCP tools
  • flutter-ui.md: Project-specific UI rules
  • api-design.md: Consistent naming conventions

References