Create Flet Example Projects

When to use

Use this skill when a user asks to:

• create one control/example folder (for example examples/controls/chip) in the project-per-example format
• migrate existing flat examples to the project-per-example format
• normalize a partially converted folder so all examples follow the same structure

Goal

Ensure each runnable example is a standalone project containing:

• main.py
• pyproject.toml with Gallery/MCP metadata
• assets/ (if the example uses local assets)

Workflow

1. Inspect source folder.

• Detect current state per example:
  • flat file: foo.py
  • project folder: foo/main.py
  • mixed/partial conversion: both styles present or missing metadata files
• Find candidate flat modules: *.py in the target folder (exclude helper files such as __init__.py).
• Keep existing media/ unless an example needs local assets copied into its own assets/.

2. Convert or normalize examples.

• For foo.py, create foo/ and move file to foo/main.py.
• If foo/main.py already exists, keep it and do not recreate/move files.
• If folder exists but main.py is missing, repair structure only when there is a clear source file.
• Do not create foo/__init__.py; import example modules directly in tests/docs (for example import examples.controls.foo.bar.main as bar or import examples.controls.foo.bar as bar when using namespace-package imports).
• When a control folder has been fully converted to project-per-example layout, delete the control-level examples/controls/<control>/__init__.py too. The converted folders should behave like namespace packages, matching prior migrations such as commit 7e65ad566.

3. Add pyproject.toml for each example project.

• Infer from path and code.
• Create missing pyproject.toml files for existing project folders.
• Update obviously stale metadata when migrating existing examples (for example wrong title/description/categories).
• Verify platform support before adding or omitting [tool.flet].platforms:
  • Check the local implementation and docs for explicit platform guards, support tables, or platform-specific exceptions.
  • If support is limited, add [tool.flet].platforms with only the supported platforms.
  • If support is broad/all-platform, omit [tool.flet].platforms.
• Required fields:
  • [project]: name, version, description, requires-python, keywords, authors, dependencies
  • [dependency-groups].dev: include flet-cli, flet-desktop, flet-web
  • [tool.flet.gallery].categories
  • [tool.flet.metadata]: title, controls, layout_pattern, complexity, features
  • [tool.flet]: org, company, copyright
• Add [tool.flet].platforms only when the example is platform-limited.
• Add permissions blocks only when code actually needs them.

4. Infer metadata.

• Title: readable version of file/folder intent.
• Short description: one line of what the example demonstrates.
• [project].description must be meaningful and example-specific; avoid generic placeholders like "Example N" or "<name> example for <control>".
• Description should mention the concrete behavior or interaction shown (for example: hover highlight, live updates, custom axes, event handling).
• Categories: typically control-based, e.g. Input/Chip, plus optional Apps/Basic controls.
• Tags: from control/topic/behavior words.
• Controls used: list key controls from code.
• Layout pattern: choose closest practical value (e.g. filter-bar, inline-actions, dashboard, list-detail).
• Complexity: basic unless logic/state/architecture is non-trivial.
• Features: notable behaviors only (click handling, selection, async loading, drag-and-drop, etc.).
• If an example supports exporting or downloading output, include "save to file" in [tool.flet.metadata].features.
• If an example module contains async def handlers or async control flow, append "async" to keywords.

5. Infer dependencies from imports.

• Always include flet for standard examples.
• Include extra packages if imported (for example extension packages).
• Do not add unused dependencies.

6. Make examples mobile-safe.

• If ft.context.disable_auto_update() is not used, do not add explicit page.update() unless strictly necessary.

• Apply this page.update() rule to all examples in the touched folder (new, migrated, and already converted).

• Wrap app content in ft.SafeArea so example renders correctly on mobile.

• Add expand=True to ft.SafeArea only when needed for correct layout/sizing (for example to avoid Infinity/NaN sizing issues), and avoid adding it when not necessary.

• When converting legacy page.add(a, b, ...) style examples, wrap the controls in ft.Column(controls=[...]) inside ft.SafeArea(content=...) rather than ft.Row, unless the original code explicitly used a row layout.

• Apply this to all examples in the touched folder (new, migrated, and already converted), not only files changed by moves.

• During validation, confirm every <example>/main.py in scope includes a top-level ft.SafeArea around rendered content.

• For declarative examples using @ft.component, do not pass component instances as regular control children (for example SafeArea(content=App())) because this can raise runtime attribute errors.

• In declarative examples, ensure the component itself returns regular controls (including SafeArea when needed) and render it at page level with page.render(App) in main().

7. Prefer @ft.control for custom controls in examples.

• If an example defines a custom control class inheriting from a Flet control (for example class MyThing(ft.Column)), prefer @ft.control style.
• Move constructor-style setup to declarative fields + init() where practical.
• Keep behavior unchanged and avoid refactors that alter public usage unless needed for compatibility.