add-component

name	add-component
description	Add a new Fonde UI widget — implement under lib/src/widgets, export from lib/fonde_ui.dart, register a catalog page in the example app, and update README. Use when adding or scaffolding a new component.

Add a new Fonde UI component

Follow this checklist when adding a new widget. Match the conventions of the nearest existing component rather than inventing new patterns.

0. Prerequisites

• Confirm the current branch is correct for this work (see CLAUDE.md "Before Committing").
• Read doc/design-policy.md and the relevant file(s) under doc/design/ for the component category (e.g. 07-button-roles-and-sizing.md, 10-table-view-guidelines.md).

1. Implement the widget

• Place source under lib/src/widgets/<area>/. Use an existing sibling directory as a template (e.g. lib/src/widgets/widgets/fonde_button.dart).
• Prefix the public class with Fonde (e.g. FondeFoo).
• Implementation rules from doc/design-policy.md:
  • Use FondeGestureDetector, not GestureDetector.
  • Use FondeRectangleBorder for rounded corners — never BorderRadius.circular or OutlineInputBorder with a plain BorderRadius.
  • Prefer const constructors; use spacing tokens (FondeSpacingValues, FondeSpacing).
• Add a doc comment with a usage Example: block (see doc/design/06-development.md).
• If the component needs localized strings, follow the localize skill.

2. Export it from the public API

Add an export line in lib/fonde_ui.dart (and lib/fonde_ui_riverpod.dart if it exposes Riverpod providers), keeping it grouped with related exports:

export 'src/widgets/<area>/<file>.dart';

3. Register a catalog page in example/

The example catalog wires components in three places:

1. Page widget — create example/lib/pages/<name>_page.dart (model it on an existing page such as example/lib/pages/button_page.dart).
2. Shell — in example/lib/shell/catalog_shell.dart: add the import, and add a '<id>' => const <Name>Page(), arm to the page switch.
3. Sidebar — in example/lib/shell/catalog_sidebar.dart: add a CatalogItem(id: '<id>', label: '<Label>') under the right group. The id must match the switch arm.

Optionally add a compact preview to example/lib/shell/catalog_samples.dart if it should appear on the welcome/overview screen.

4. Update docs

• Add the component to README.md (implemented-components list).
• Update doc/component-roadmap.md if the component was tracked there.

5. Verify

fvm dart format .
fvm flutter build <target>   # a real build — analyze is NOT a substitute (CLAUDE.md)

Run the catalog to eyeball it:

cd example && fvm flutter run

Do not commit until the build passes and fvm dart format . is clean. Ask before any git commit.