Implement a new Flet extension/control that wraps a third-party Flutter package end-to-end, including dependency selection, version pinning, compatibility checks, Python/Flutter integration, docs, examples, tests, and CI updates. Use when adding any flet_* package backed by an external pub.dev package.
91%
Does it follow best practices?
Run evals on this skill
Adds up to 20 points to the overall score
Passed
No findings from the security scan
Implement a Flet extension around an external Flutter package using existing flet_* packages as implementation templates.
flet_<extension>).package:flutter/material.dart or package:flutter/cupertino.dart, or take or return their types. Parts it doesn't use don't matter: shadcn_ui's ShadApp is built on the SDK MaterialApp, but flet-shadcn-ui never uses it. Flet renders with the material_ui and cupertino_ui packages, so SDK TextField, InkWell, ListTile and similar widgets fail at runtime ("No Material widget found"), and SDK ThemeData/ButtonStyle values don't type-check against Flet's helpers. Prefer a release built on material_ui/cupertino_ui or on widgets.dart only.LayoutControl for visual controls that participate in page/layout positioning.Control for simple visual controls that do not require page positioning or define their own positioning rules/props (for example Draggable, Divider, MenuBar, NavigationRail).sdk/python/packages/flet-audio, sdk/python/packages/flet-flashlight, sdk/python/packages/flet-secure-storage.LayoutControl, base Control, or Service base class according to classification.package:material_ui/material_ui.dart (and package:cupertino_ui/cupertino_ui.dart for Cupertino), never package:flutter/material.dart or package:flutter/cupertino.dart. Files that use no Material or Cupertino API import package:flutter/widgets.dart. Add material_ui (and cupertino_ui if used) to the extension's pubspec.yaml with the same constraints as packages/flet/pubspec.yaml.parseEnum() for enums — it's exported from package:flet/flet.dart. Call it as parseEnum(MyEnum.values, widget.control.getString("attr"), MyEnum.defaultVal)!. Do NOT write a custom _parseXxx() switch helper.widget.control.getBool()/getDouble()/... accessors.parseSomething() helpers.utils/<control>.dart; shared helpers in utils/<topic>.dart.parse-prefixed helper names when converting input to Flutter structures.Column: it loosens a fixed width, which shrinks button-like widgets.Properties with default values on the Python side are not sent to Flutter when unchanged from the default. Every Dart property read must provide the same default as its Python counterpart:
control.getDouble("size", 100.0)! when Python has size: float = 100.0control.getBool("animate", true)! when Python has animate: bool = TrueparseDuration(value["dur"], const Duration(milliseconds: 500))! when Python has dur: DurationValue = field(default_factory=lambda: Duration(milliseconds=500))control.get<List>("items")?.map(...).toList() ?? const [] when Python has items: list[str] = field(default_factory=list)Without matching defaults, Dart receives null and either crashes or silently uses the wrong value. This applies to all property types: bools, numbers, strings, enums, durations, collections, and nested @ft.value types.
client/pubspec.yaml: add flet_<ext>: path: ../sdk/python/packages/flet-<ext>/src/flutter/flet_<ext> under dependencies.client/lib/main.dart: add import 'package:flet_<ext>/flet_<ext>.dart' as flet_<ext>; and flet_<ext>.Extension() to the extensions list.sdk/python/pyproject.toml in two places: the dependencies list and [tool.uv.sources] as { workspace = true }.sdk/python/packages/flet/pyproject.toml in the [dependency-groups] extensions list.sdk/python/examples/apps/flet_build_test/pyproject.toml in three places: [project] dependencies, [tool.uv.sources] as { path = "...", editable = true }, and [tool.flet.dev_packages] as a relative path string.tools/crocodocs/pyproject.toml under [tool.crocodocs.packages] as <pkg_name> = "../../sdk/python/packages/<pkg-dir>/src". This fixes "Missing API entry" errors in the docs. Note: api-data.json is gitignored (generated at build time); only the pyproject.toml change needs committing..github/workflows/ci.yml in both places:
build_flet_extensions -> PACKAGES list.py_publish -> for pkg in ... publish loop.FLET_PACKAGES in sdk/python/packages/flet-cli/src/flet_cli/utils/project_dependencies.py, so flet build, flet debug and flet publish pin it to the Flet CLI version. A test fails if a folder in sdk/python/packages is missing from it..gitignore to Flutter extension project if missing.[tool.uv.sources] local path overrides from example pyproject.toml files before opening a PR (they are development-only conveniences).website/docs/controls/<name> for controls and website/docs/services/<name> for services.index.md for the overview (install instructions, examples, list of links) and individual <controlname>.md files for each control — consistent with flet-color-pickers and other extensions.<ClassSummary name="pkg.ClassName" /> and <ClassMembers name="pkg.ClassName" /> JSX from @site/src/components/crocodocs to render API docs.TableColumn/TableRow/TableCell in Table, MenuItem in ContextMenu/Menubar, Radio in RadioGroup, Tab in Tabs, AccordionItem in Accordion), not any control placed in another's controls/content. Never render a second class's <ClassSummary>/<ClassMembers> on the parent's page: each page must document exactly one class, otherwise it gets two "Properties"/"Events" headings with the same anchor and the table of contents breaks.
class_name and title, then <ClassSummary name={frontMatter.class_name} /> and <ClassMembers name={frontMatter.class_name} /> (no example/images needed); file name is the lowercased class name (tablecolumn.md).website/sidebars.yml (Table: {_index: .../table.md, TableColumn: .../tablecolumn.md, ...}), like core DataTable → DataCell. A sub-control shared by several parents (e.g. MenuItem for ContextMenu and Menubar) is listed once, under one parent.:class: roles in the parent's docstrings (class description or the property that holds them, e.g. items), which render as links to the sub-control page.image=/imageCaption=/imageWidth= on <ClassSummary> for non-visual services or controls that cannot be screenshotted (continuously animating ones).## Examples section, do NOT add ### subtitles above <CodeExample> blocks — titles are injected automatically from the example file itself.website/sidebars.yml navigation. List new extension controls under Reference → Controls → Extensions (alphabetically). Only an extension that brings its own design system gets its own folder next to Core/Material/Cupertino/Extensions, like Shadcn. See the "Sidebar Navigation" section of .agents/skills/docs-conventions/SKILL.md.codeeditor.md, not code_editor.md).sdk/python/examples/extensions/<name>/ for extension controls.import flet_<ext> as <short_alias> in examples (e.g., import flet_spinkit as spins). Keep alias short but readable.ft.Colors.SURFACE_CONTAINER_HIGHEST for card/cell backgrounds in showcase examples — it adapts to light and dark system themes automatically.page.theme_mode).packages/flet/integration_tests/extensions/<name>/ — not inside the extension package's own directory (no tests/ folder in the package itself, matching the pattern of flet-code-editor, flet-color-pickers, etc.).assert_control_screenshot or pump_and_settle — they will timeout waiting for animations to settle. Instead use await flet_app.tester.pump(duration=ft.Duration(milliseconds=500)) which advances the clock by a fixed amount. This still runs real Flutter rendering and catches crashes, without screenshot comparison.Every example gets an integration test, and the goldens it produces are the docs images. Follow sdk/python/packages/flet/integration_tests/examples/controls/material/test_checkbox.py.
Every docs image must be light and opaque. Screenshots are transparent by default: on the website's dark mode dark text becomes unreadable, and create_gif flattens transparency to black, so flow GIFs come out dark. For every screenshot used in docs:
page.theme_mode = ft.ThemeMode.LIGHT (and page.update() after launching an example);bgcolor=ft.Colors.SURFACE to assert_control_screenshot, wrap_page_controls_in_screenshot and take_page_controls_screenshot;sdk/python/packages/flet/integration_tests/examples/extensions/<name>/test_<control>.py. The file stem picks the golden folder (golden/macos/<control>/), so each control's images stay together.test_image_for_docs (uses flet_app_function): set page.theme_mode = ft.ThemeMode.LIGHT and call assert_control_screenshot(request.node.name, bgcolor=ft.Colors.SURFACE, control=...) with a compact showcase of the control (a few states/variants). Wrap rows in ft.Column(intrinsic_width=True, ...) so the image is not stretched to the page width.{"flet_app_main": example.main} and indirect=True:
page.theme_mode = ft.ThemeMode.LIGHT and page.update() (examples do not set a theme);tap, enter_text, mouse_hover) and assert the example's visible result (find_by_text(...).count == 1);take_page_controls_screenshot(bgcolor=ft.Colors.SURFACE) for a single image, or scr = await wrap_page_controls_in_screenshot(bgcolor=ft.Colors.SURFACE) + scr.capture(pixel_ratio=...) for several states;<example>_initial, <example>, ...) and combine them with create_gif([...], "<example>_flow", duration=1000).enter_text needs a finder on the input itself, so give example inputs (and other controls the test must target) a key= and use find_by_key.sdk/python: FLET_TEST_GOLDEN=1 uv run pytest -s packages/flet/integration_tests/examples/extensions/<name>. Open and review every PNG and GIF (dark or transparent background, stretched rows, cramped spacing, oversized icons, clipping), fix the test or example, regenerate, then re-run without FLET_TEST_GOLDEN to confirm the comparisons pass. Commit the golden/macos/<control>/* files.example_images: "test-images/examples/extensions/<name>/golden/macos/<control>" (crocodocs' test-images mapping already serves integration_tests);<ClassSummary name={frontMatter.class_name} image={frontMatter.example_images + '/image_for_docs.png'} imageCaption="<ClassName>" imageWidth="30%"/>, with the width tuned to the image;<CodeExample>: <Image src={frontMatter.example_images + '/<example>.png'} alt="<example>" width="45%" caption="<what the user did>" />, pointing to the _flow.gif for flows; import Image from @site/src/components/crocodocs.uv --directory ./tools/crocodocs run crocodocs generate from the repo root and check that the images appear under website/static/docs/test-images/... (generated, not committed)..github/workflows/macos-integration-tests.yml on purpose so CI runs only the new extension's suites: every entry of the suite: matrix is commented out and only the extension's suites are added (for example - examples/extensions/<name> and - extensions/<name>).examples/extensions and extensions suites already include the new tests.flet-dev/flet
1a1e121
If you maintain this skill, you can claim it as your own. Once claimed, you can manage eval scenarios, bundle related skills, attach documentation or rules, and ensure cross-agent compatibility.