stitch-to-flutter

name	stitch_to_flutter
description	Instructions for translating Google Stitch designs (HTML/Tailwind) into production-ready Flutter/Dart code.

Stitch to Flutter Skill

This skill documents how to translate UI designs generated by Google Stitch (which come as HTML and Tailwind CSS) into Flutter widgets, ensuring alignment with your Flutter project architecture and design system.

Core Conversion Principles

1. Structure Mapping:

   • <div> with flex -> Column, Row, or Flex.
   • <div> with max-w-md mx-auto -> Center + ConstrainedBox or Container with maxWidth.
   • padding (p-4, px-6) -> Padding widget or padding property in Container/ListView.
   • space-y-4 -> ListView with gap (if available) or Column with SizedBox between items.

2. Style Mapping:

   • Colors: Use Theme.of(context).colorScheme for dynamic colors. Map Tailwind custom colors (e.g., primary: "#F97316") to the project's brand colors in lib/core/theme/.
   • Typography: Map Tailwind font weights (font-bold) and sizes (text-3xl) to TextTheme scale tokens.
     • CRITICAL: Never used hardcoded fontSize. Always use Theme.of(context).textTheme.

Typography Mapping Table

Tailwind / Style	M3 Type Scale Token	Usage
text-4xl, text-5xl	displayLarge/Medium/Small	Large hero text, brand elements
text-2xl, text-3xl	headlineLarge/Medium/Small	High-emphasis page headers
text-xl, font-bold	titleLarge/Medium/Small	Section headers, card titles
text-base, text-sm	bodyLarge/Medium/Small	Long-form reading, descriptions
text-xs, uppercase	labelLarge/Medium/Small	Buttons, badges, captions

*   **Shadows**: Map `shadow-lg` to `BoxShadow` in `BoxDecoration`.
*   **Border Radius**: Map `rounded-2xl` to `BorderRadius.circular(16)`.

3. Component Mapping: * button -> ElevatedButton, TextButton, or custom Material + InkWell for complex cards. * header -> SliverAppBar or a custom AppBar. * nav -> BottomNavigationBar or a custom navigation widget. * span.material-icons-round -> Icon(Icons.<icon_name>).

4. Tailwind Class to Flutter Decoration Table:

Tailwind Class	Flutter Equivalent
bg-white	color: Colors.white
rounded-xl	borderRadius: BorderRadius.circular(12)
shadow-md	BoxShadow(color: Colors.black12, blurRadius: 4, offset: Offset(0, 2))
border	border: Border.all(color: Colors.grey[200]!)
flex items-center	Row(crossAxisAlignment: CrossAxisAlignment.center)
flex flex-col	Column()

Implementation Patterns

Complex Action Cards

For cards like "Informar de un animal vulnerable", use:

Material(
  color: color,
  borderRadius: BorderRadius.circular(24),
  child: InkWell(
    onTap: onTap,
    child: Padding(
      padding: const EdgeInsets.all(24),
      // ... content
    ),
  ),
)

Dynamic Theme Usage

Always prioritize using Theme.of(context) to support Dark Mode automatically, as the Stitch designs often include dark: classes.

Atomic Design Mapping

When translating designs, follow the Atomic Design methodology to ensure components are reusable and well-structured:

Level	Definition	Stitch/HTML Example	Flutter Equivalent
Atoms	Basic building blocks.	<button>, <input>, <span>, <img>	AppButton, AppTextInput, AppBadge, Icon
Molecules	Simple groups functioning together.	Labeled input, Icon + Text pair.	LabeledInput, StatItem, StatusIndicator
Organisms	Complex UI sections.	Personal Data Grid, Header with Avatar & Name.	ProfileHeader, FormSection, ActionGrid
Templates	Page structure without content.	Page with Header and Sticky Footer.	ProfilePageLayout
Pages	Completed page.	Entire screen.	ProfilePage

Rules for Components:

1. Atoms should be generic and stateless. They only import from theme/quarks.
2. Molecules combine atoms and provide specific layout/logic for those atoms.
3. Organisms handle layout of multiple molecules and may connect to state/data.
4. Composition over duplication: If a pattern repeats in Stitch (e.g., an input card), extract it as a Molecule.

Dynamic Color & Branding

When converting designs, always use Theme.of(context).colorScheme tokens. The app uses Brand-Based Dynamic Color, meaning the entire ColorScheme is generated from the Brand Primary seed.

1. NEVER hardcode hex colors for surfaces, containers, or secondary elements.
2. Harmonized Colors: For semantic colors like "Warning" or "Success" that come from Stitch, use the harmonized() extension if you need them to feel more integrated with the brand theme.
3. Semantic Mapping:
   • bg-primary -> colorScheme.primary
   • bg-primary-light -> colorScheme.primaryContainer
   • text-on-primary -> colorScheme.onPrimary
   • bg-surface -> colorScheme.surface

Workflow

1. Read the .html file from Stitch.
2. Examine the .png screenshot to understand visual hierarchy and spacing.
3. Deconstruct into Atoms/Molecules: Identify repeated UI patterns (e.g., the input cards with labels).
4. Generate the Dart code following the Atomic Design structure.
5. Verify on Device: Execute the debug launch script to see the new screen in action:

   make dev-mobile-launch