Flutter-AdaptiveCards

Semantics contract for Adaptive Card elements — how labels, headings, live regions, and decorative-vs-meaningful images are exposed to screen readers, and how to test them with `tester.ensureSemantics()`. Use when adding or changing any element, input, or action widget, and at code review.

Optional flutter_adaptive_cards_host_fs package — backend invoke serialization, PlainJson/Teams adapters, AdaptiveCardBackendHandlers, and response effects. Use when wiring Submit/Execute/Refresh/onChange to a flow-service or reviewing associatedInputs + invoke round-trips.

Use when finalizing a change in the Flutter-AdaptiveCards monorepo — before you propose, commit, or merge — as the manual or AI-assisted review gate. Checks monorepo hygiene, Adaptive Cards spec compliance, theming, widget keys, accessibility, and testing.

FVM rules for the Flutter-AdaptiveCards monorepo. Prefix every `flutter` and `dart` shell command with `fvm`. Use when vendored dart/flutter skills show bare commands, when installing or switching the pinned SDK, or before analyze, test, pub, or build_runner workflows.

Classify, audit, and enforce the Diátaxis documentation framework across the Flutter-AdaptiveCards canonical `docs/` and package READMEs. Keeps each doc in exactly one quadrant (tutorial / how-to / reference / explanation) and flags mixed-mode drift. Use when writing or reviewing a doc under `docs/`, adding a `doc_type:` front-matter tag, auditing the doc set for gaps or violations, or when the user mentions Diátaxis or documentation structure. Advisory only — it proposes splits, it does not silently move or rewrite files.

Use before adding a new Adaptive Card element type — implementing its widget, registering it, or testing it. Covers the StatefulWidget + mixin pattern, CardTypeRegistry registration, the extension API, and optional packages (charts).

Use when writing or reviewing model (de)serialization or theming in this repo, or before adding a `fromJson`/`toJson`. The library packages diverge from two things generic Flutter skills assume: they hand-write serialization (no `json_serializable` / code-gen) and style elements from HostConfig (not app-level `ThemeData`/`GoogleFonts`). Read this when a generic skill or habit points you at `@JsonSerializable`, `build_runner` for models, or `ColorScheme` app theming inside `packages/`.

Use before modifying styling, colors, spacing, fonts, or HostConfig parsing in any element. Explains how Adaptive Cards HostConfig maps to Flutter rendering, how ReferenceResolver bridges the two, and how light/dark themes are structured.

What "localized" means for the published packages — who owns which strings, why the library ships no `.arb` files, the injected `AdaptiveStrings` seam for library-owned chrome, and locale-correct `intl` formatting. Use when adding any user-visible string to a package under `packages/`, or when tempted to add `flutter_localizations` to the core.

Workspace layout, fvm usage, correct working directories for commands, and inter-package dependency relationships for the Flutter-AdaptiveCards monorepo. Use this whenever running flutter/dart commands or navigating the project structure.

Write public `///` documentation for exported Dart APIs. Use when adding or editing public classes, methods, getters, or fields in library packages (flutter_adaptive_cards_fs, flutter_adaptive_charts_fs, flutter_adaptive_cards_host_fs, flutter_adaptive_template_fs) or when reviewing doc-comment quality on exported APIs.

Use when cutting a release of the Flutter-AdaptiveCards packages — versioning, tagging, publishing to pub.dev, post-release minor bumps, changelog updates, or syncing pubspec.yaml dependency versions.

Use when upgrading the pinned Flutter/Dart SDK version across the monorepo — updating FVM config, GitHub Actions, pubspec.yaml SDK constraints, and changelogs so every package and CI pipeline stays in sync.

Use before implementing or reviewing any new element, action, template feature, or HostConfig behavior, to check parity with the official spec and other SDKs. Provides Adaptive Cards + Templating spec references and cross-SDK behavior notes (JavaScript, Android, iOS, .NET).

Use when implementing, using, or debugging Adaptive Card templating via flutter_adaptive_template_fs, or when a template feature seems missing or unsupported. Explains how the package implements templating, its architecture, and its known shortcomings versus the Templating spec.

Testing patterns, utilities, and golden image workflows for the flutter_adaptive_cards_fs library (and related package test dirs). Use this before writing or modifying tests under packages/flutter_adaptive_cards_fs/test/ or packages/flutter_adaptive_cards_host_fs/test/.

Example/sample program only: patterns and registry for widgetbook host-overlay demo pages (widgetbook/lib/*_overlay_page.dart). Use when adding or reviewing widgetbook knob demos — not for package overlay architecture (see reactive-riverpod, form-inputs).

Build, run, drive, and screenshot the adaptive_explorer macOS desktop app. Use when asked to start/launch/run adaptive_explorer, take a screenshot of it, confirm a change renders in the real app, or run its tests.

Build, run, drive, and screenshot the widgetbook sample app. Use when asked to start/launch/run widgetbook, take a screenshot of it, preview Adaptive Card samples or chart/overlay demos, or run its tests.