| 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:
- Page widget — create
example/lib/pages/<name>_page.dart (model it on an existing
page such as example/lib/pages/button_page.dart).
- Shell — in
example/lib/shell/catalog_shell.dart: add the import, and add a
'<id>' => const <Name>Page(), arm to the page switch.
- 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>
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.
