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:
```dart
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:
    ```bash
    make dev-mobile-launch
    ```