adaptive-cards-flutter-standard-practices

name

adaptive-cards-flutter-standard-practices

description

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/`.

Flutter Standard Practices (this repo)

Two conventions here differ from generic Flutter guidance. Applying the generic pattern produces code that does not match the codebase — this skill records the divergence so you follow the repo's actual approach.

---

1. Serialization — hand-written fromJson/toJson, no code-gen

The packages do not use json_serializable/json_annotation. There is no @JsonSerializable annotation and no .g.dart model file anywhere under packages/ — every model is parsed and emitted by hand (flutter_adaptive_cards_fs alone has ~39 hand-written fromJson factories).

Follow these conventions:

• Manual factory + method. factory X.fromJson(Map<String, dynamic> json) and Map<String, dynamic> toJson(). Do not add json_serializable, json_annotation, or a build_runner code-gen step for models.
• Read Adaptive Cards keys verbatim. Card JSON keys are the spec's camelCase names (isVisible, backgroundImage, associatedInputs). Read them as-is — never FieldRename.snake.
• Null-safe reads with typed casts and defaults: json['title'] as String? ?? '', json['value']?.toString() ?? ''.
• Immutable value types. @immutable, const constructor, and value equality (== / hashCode).
• Parse arrays with a small top-level helper that guards bad entries rather than assuming the list is well-formed.

@immutable
class Choice {
  const Choice({required this.title, required this.value});

  /// Parses an Adaptive Cards `Input.Choice` object from card JSON.
  factory Choice.fromJson(Map<String, dynamic> json) {
    return Choice(
      title: json['title'] as String? ?? '',
      value: json['value']?.toString() ?? '',
    );
  }

  final String title;
  final String value;

  Map<String, dynamic> toJson() => {'title': title, 'value': value};
}

/// List helper: guards non-map entries instead of trusting the array.
List<Choice> choicesFromJsonList(Object? raw) {
  if (raw is! List) return const [];
  return raw
      .whereType<Map>()
      .map((e) => Choice.fromJson(Map<String, dynamic>.from(e)))
      .toList();
}

The generic flutter-implement-json-serialization skill's manual dart:convert approach is directionally correct here — but follow the conventions above, and do not reach for json_serializable.

---

2. Theming — HostConfig-driven in packages, not app ThemeData

Element styling under packages/ comes from Adaptive Cards HostConfig, resolved through ReferenceResolver — not from a MaterialApp ThemeData, ColorScheme.fromSeed, or GoogleFonts. Before changing colors, spacing, or fonts in an element, use adaptive-cards-hostconfig-theme.

The sample apps are different: widgetbook/ and adaptive_explorer/ are ordinary Flutter apps and legitimately set a MaterialApp theme (ThemeData.light()/dark(), ColorScheme.fromSeed). That is sample-app scope only — it is never how library elements pick up style.

---

Related skills

Skill	Role
adaptive-cards-hostconfig-theme	How elements resolve theme-aware color/font/spacing from HostConfig
adaptive-cards-element-registry	Implementing a new element (where fromJson lives)
adaptive-cards-public-api-docs	/// docs for the public model/factory APIs