Merge branch 'main' of https://github.com/VeryGoodOpenSource/very_good_ai_flutter_plugin into feat/animations-skill

B0berman · B0berman · commit ca21e8438b61 · 2026-04-01T10:46:33.000+02:00
diff --git a/.claude-plugin/plugin.json b/.claude-plugin/plugin.json
@@ -52,6 +52,7 @@
     "testing",
     "theming",
     "very-good-cli",
+    "ui-package",
     "wcag",
     "widget-testing",
     "sdk-upgrade",
diff --git a/.github/workflows/ci.yaml b/.github/workflows/ci.yaml
@@ -10,19 +10,19 @@ jobs:
     name: 📝 Markdown Quality
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v6
       - name: Lint Markdown
-        uses: DavidAnson/markdownlint-cli2-action@v19
+        uses: DavidAnson/markdownlint-cli2-action@v23
         with:
           globs: '**/*.md'
           config: 'config/custom.markdownlint.jsonc'
   spelling:
     name: ✍️ Spelling Check
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v6
       - name: Spell Check Code
-        uses: streetsidesoftware/cspell-action@v6
+        uses: streetsidesoftware/cspell-action@v8
         with:
           files: '**/*.md'
           config: 'config/cspell.json'
@@ -32,7 +32,7 @@ jobs:
     outputs:
       skills: ${{ steps.changed-skills.outputs.skills }}
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v6
         with:
           fetch-depth: 0
       - name: Get changed skills
@@ -57,7 +57,7 @@ jobs:
       matrix:
         skill: ${{ fromJson(needs.detect-changed-skills.outputs.skills) }}
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v6
       - name: Validate ${{ matrix.skill }}
         id: validate
         uses: Flash-Brew-Digital/validate-skill@v1
@@ -76,6 +76,6 @@ jobs:
     name: 📦 Manifest Validation
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v6
       - name: Validate Plugin Manifest
         run: bash ./scripts/validate_plugin_manifest.sh
diff --git a/CLAUDE.md b/CLAUDE.md
@@ -20,6 +20,7 @@ hooks/
     check-vgv-cli.sh   # Validates VGV CLI installed and >= 1.1.0
     format.sh          # Runs dart format on modified .dart files
     vgv-cli-common.sh  # Shared utilities for VGV CLI hook scripts
+    warn-missing-mcp.sh  # Warns at session start if VGV CLI is missing/outdated
 skills/
   accessibility/SKILL.md
   accessibility/reference.md
@@ -43,6 +44,7 @@ skills/
   static-security/reference.md
   testing/SKILL.md
   testing/reference.md
+  ui-package/SKILL.md
 ```
 
 ## Skill File Format
@@ -65,6 +67,7 @@ Every `SKILL.md` follows this structure:
 - Provide complete, copy-pasteable snippets, not fragments
 - Reference packages by full name (e.g., `package:mocktail`)
 - Include anti-patterns alongside correct patterns when helpful
+- Align pipe characters vertically in all markdown tables (enforced by markdownlint MD060)
 
 ## Adding a New Skill
 
@@ -75,7 +78,13 @@ Every `SKILL.md` follows this structure:
 
 ## Hooks
 
-The `hooks/` directory contains PreToolUse and PostToolUse hooks defined in `hooks.json`.
+The `hooks/` directory contains SessionStart, PreToolUse, and PostToolUse hooks defined in `hooks.json`.
+
+### SessionStart Hooks
+
+These run **when a session begins**:
+
+- `warn-missing-mcp.sh` — checks if Very Good CLI is installed and >= 1.1.0; outputs a warning to Claude's context if missing or outdated (non-blocking)
 
 ### PreToolUse Hooks
 
diff --git a/README.md b/README.md
@@ -38,6 +38,7 @@ For more details, see the [Very Good Claude Marketplace][marketplace_link].
 | [**Bloc**](skills/bloc/SKILL.md) | State management with Bloc/Cubit — sealed events & states, `BlocProvider`/`BlocBuilder` widgets, event transformers, and testing with `blocTest()` & `mocktail` |
 | [**Layered Architecture**](skills/layered-architecture/SKILL.md) | VGV layered architecture — four-layer package structure (Data, Repository, Business Logic, Presentation), dependency rules, data flow, and bootstrap wiring |
 | [**Security**](skills/static-security/SKILL.md) | Flutter-specific static security review — secrets management, `flutter_secure_storage`, certificate pinning, `Random.secure()`, `formz` validation, dependency vulnerability scanning with `osv-scanner`, and OWASP Mobile Top 10 guidance |
+| [**UI Package**](skills/ui-package/SKILL.md) | Flutter UI package creation — custom widget libraries with `ThemeExtension`-based theming, design tokens, barrel file exports, widget tests, Widgetbook catalog, and consistent API conventions |
 | [**License Compliance**](skills/license-compliance/SKILL.md) | Dependency license auditing — categorizes licenses (permissive, weak/strong copyleft, unknown), flags non-compliant or missing licenses, and produces a structured compliance report using Very Good CLI |
 | [**Dart/Flutter SDK Upgrade**](skills/dart-flutter-sdk-upgrade/SKILL.md) | Bump Dart and Flutter SDK constraints across packages — CI workflow versions, pubspec.yaml environment constraints, and PR preparation for SDK upgrades |
 
@@ -78,6 +79,7 @@ You can also invoke skills directly as slash commands:
 /vgv-navigation
 /vgv-static-security
 /vgv-testing
+/vgv-ui-package
 /vgv-license-compliance
 /vgv-dart-flutter-sdk-upgrade
 ```
diff --git a/config/cspell.json b/config/cspell.json
@@ -4,6 +4,7 @@
     "Bidirectionality",
     "Bienvenido",
     "bypassable",
+    "dartdoc",
     "CSPRNG",
     "dismissable",
     "elemento",
@@ -14,6 +15,7 @@
     "GHSA",
     "goldens",
     "hoverable",
+    "lerp",
     "jailbroken",
     "LTRB",
     "mapbox",
@@ -27,6 +29,8 @@
     "serialization",
     "stdio",
     "WCAG",
+    "widgetbook",
+    "Widgetbook",
     "xxlg"
   ],
   "flagWords": []
diff --git a/hooks/hooks.json b/hooks/hooks.json
@@ -1,6 +1,17 @@
 {
   "description": "Very Good AI Flutter Plugin hooks for Dart and Flutter development",
   "hooks": {
+    "SessionStart": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "bash ${CLAUDE_PLUGIN_ROOT}/hooks/scripts/warn-missing-mcp.sh",
+            "timeout": 10
+          }
+        ]
+      }
+    ],
     "PreToolUse": [
       {
         "matcher": "mcp__very-good-cli__.*",
diff --git a/hooks/scripts/warn-missing-mcp.sh b/hooks/scripts/warn-missing-mcp.sh
@@ -0,0 +1,20 @@
+#!/bin/bash
+# SessionStart hook: warn when Very Good CLI is missing or outdated.
+# Output is injected into Claude's context (not displayed in the terminal).
+# Non-blocking — always exits 0.
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+source "$SCRIPT_DIR/vgv-cli-common.sh"
+
+cli_status=$(check_vgv_cli)
+case "$cli_status" in
+  not_installed)
+    echo "⚠️ Very Good CLI is not installed. The Very Good CLI MCP server will not work without Very Good CLI >= ${MIN_VERSION}. Install with: dart pub global activate very_good_cli"
+    ;;
+  outdated:*)
+    version="${cli_status#outdated:}"
+    echo "⚠️ Very Good CLI ${version} is too old. The Very Good CLI MCP server requires >= ${MIN_VERSION}. Update with: dart pub global activate very_good_cli"
+    ;;
+esac
+
+exit 0
diff --git a/skills/bloc/SKILL.md b/skills/bloc/SKILL.md
@@ -30,7 +30,7 @@ Apply these standards to ALL Bloc/Cubit work:
 
 | Aspect            | Cubit                          | Bloc                                    |
 | ----------------- | ------------------------------ | --------------------------------------- |
-| API               | Functions → `emit(state)`      | Events → `on<Event>` → `emit(state)`   |
+| API               | Functions → `emit(state)`      | Events → `on<Event>` → `emit(state)`    |
 | Complexity        | Low                            | Higher                                  |
 | Traceability      | Less (no event log)            | Full (events + transitions)             |
 | When to use       | Simple state, UI-driven logic  | Complex flows, event-driven, transforms |
@@ -76,13 +76,13 @@ class CounterBloc extends Bloc<CounterEvent, int> {
 
 **Pattern:** `BlocSubject` + `Noun` + `VerbPastTense`
 
-| Event class name              | Meaning                          |
-| ----------------------------- | -------------------------------- |
-| `TodoListSubscriptionRequested` | Subscribing to todo list stream |
-| `TodoListTodoDeleted`         | Deleting a specific todo         |
-| `TodoListUndoDeletionRequested` | Undoing the last deletion      |
-| `LoginFormSubmitted`          | Submitting the login form        |
-| `ProfilePageRefreshed`        | Refreshing the profile page      |
+| Event class name                | Meaning                          |
+| ------------------------------- | -------------------------------- |
+| `TodoListSubscriptionRequested` | Subscribing to todo list stream  |
+| `TodoListTodoDeleted`           | Deleting a specific todo         |
+| `TodoListUndoDeletionRequested` | Undoing the last deletion        |
+| `LoginFormSubmitted`            | Submitting the login form        |
+| `ProfilePageRefreshed`          | Refreshing the profile page      |
 
 ```dart
 sealed class TodoListEvent extends Equatable {
diff --git a/skills/bloc/references/patterns.md b/skills/bloc/references/patterns.md
@@ -60,7 +60,7 @@ class SearchBloc extends Bloc<SearchEvent, SearchState> {
 ```
 
 | Transformer       | Behavior                                              |
-| ------------------ | ---------------------------------------------------- |
+| ------------------| ----------------------------------------------------- |
 | `concurrent()`    | Process all events concurrently (default)             |
 | `sequential()`    | Process events one at a time in order                 |
 | `droppable()`     | Ignore new events while one is processing             |
diff --git a/skills/bloc/references/testing.md b/skills/bloc/references/testing.md
@@ -4,14 +4,14 @@
 
 | Parameter  | Type                        | Purpose                                        |
 | ---------- | --------------------------- | ---------------------------------------------- |
-| `build`    | `() => Bloc/Cubit`         | Creates the Bloc/Cubit under test              |
-| `act`      | `(bloc) => void`           | Interacts with the Bloc/Cubit                  |
-| `expect`   | `() => List<State>`        | Expected states emitted (in order)             |
-| `seed`     | `() => State`              | Initial state before `act`                     |
-| `setUp`    | `() => void`               | Runs before `build`                            |
-| `verify`   | `(bloc) => void`           | Additional verifications after `expect`        |
-| `errors`   | `() => List<Matcher>`      | Expected errors thrown                         |
-| `wait`     | `Duration`                 | Wait duration before asserting (for debounce)  |
+| `build`    | `() => Bloc/Cubit`          | Creates the Bloc/Cubit under test              |
+| `act`      | `(bloc) => void`            | Interacts with the Bloc/Cubit                  |
+| `expect`   | `() => List<State>`         | Expected states emitted (in order)             |
+| `seed`     | `() => State`               | Initial state before `act`                     |
+| `setUp`    | `() => void`                | Runs before `build`                            |
+| `verify`   | `(bloc) => void`            | Additional verifications after `expect`        |
+| `errors`   | `() => List<Matcher>`       | Expected errors thrown                         |
+| `wait`     | `Duration`                  | Wait duration before asserting (for debounce)  |
 
 ## Cubit Test Example
 
diff --git a/skills/bloc/references/widgets.md b/skills/bloc/references/widgets.md
@@ -1,23 +1,23 @@
 # Flutter Widgets
 
-| Widget              | Purpose                                                    |
-| ------------------- | ---------------------------------------------------------- |
-| `BlocProvider`      | Creates and provides a Bloc/Cubit to the subtree           |
-| `BlocBuilder`       | Rebuilds widget when state changes                         |
+| Widget              | Purpose                                                      |
+| ------------------- | ------------------------------------------------------------ |
+| `BlocProvider`      | Creates and provides a Bloc/Cubit to the subtree             |
+| `BlocBuilder`       | Rebuilds widget when state changes                           |
 | `BlocListener`      | Executes side effects (navigation, snackbar) on state change |
-| `BlocConsumer`      | Combines `BlocBuilder` + `BlocListener`                    |
-| `BlocSelector`      | Rebuilds only when a selected property changes             |
-| `MultiBlocProvider` | Provides multiple Blocs/Cubits without nesting             |
-| `MultiBlocListener` | Registers multiple listeners without nesting               |
-| `RepositoryProvider`| Provides a repository to the subtree                       |
+| `BlocConsumer`      | Combines `BlocBuilder` + `BlocListener`                      |
+| `BlocSelector`      | Rebuilds only when a selected property changes               |
+| `MultiBlocProvider` | Provides multiple Blocs/Cubits without nesting               |
+| `MultiBlocListener` | Registers multiple listeners without nesting                 |
+| `RepositoryProvider`| Provides a repository to the subtree                         |
 
 ## Context Extensions
 
-| Extension          | Purpose                                          | Rebuilds? |
-| ------------------ | ------------------------------------------------ | --------- |
-| `context.read<T>()`   | Access Bloc/Cubit instance (one-time read)   | No        |
-| `context.watch<T>()`  | Access Bloc/Cubit and subscribe to changes   | Yes       |
-| `context.select<T, R>()` | Subscribe to a specific state property    | Yes (selective) |
+| Extension                | Purpose                                          | Rebuilds?       |
+| ------------------------ | ------------------------------------------------ | --------------- |
+| `context.read<T>()`      | Access Bloc/Cubit instance (one-time read)       | No              |
+| `context.watch<T>()`     | Access Bloc/Cubit and subscribe to changes       | Yes             |
+| `context.select<T, R>()` | Subscribe to a specific state property           | Yes (selective) |
 
 - Use `context.read` in callbacks (`onPressed`, `onTap`, `initState`)
 - Use `context.watch` or `BlocBuilder` in `build` methods
diff --git a/skills/internationalization/SKILL.md b/skills/internationalization/SKILL.md
@@ -23,10 +23,10 @@ Apply these standards to ALL internationalization work:
 
 ## Key Definitions
 
-| Term                          | Definition                                                                                  |
-| ----------------------------- | ------------------------------------------------------------------------------------------- |
-| **Locale**                    | Set of properties defining user region, language, and preferences (currency, time, numbers)  |
-| **Localization (l10n)**       | Process of adapting software for a specific language by translating text and adding regional layouts |
+| Term                            | Definition                                                                                            |
+| ------------------------------- | ----------------------------------------------------------------------------------------------------- |
+| **Locale**                      | Set of properties defining user region, language, and preferences (currency, time, numbers)           |
+| **Localization (l10n)**         | Process of adapting software for a specific language by translating text and adding regional layouts  |
 | **Internationalization (i18n)** | Process of designing software so it can be adapted to different languages without engineering changes |
 
 ## Setup Pipeline and ARB File Format
@@ -138,17 +138,17 @@ See [references/backend.md](references/backend.md) for multi-language content st
 
 ## Quick Reference
 
-| Package                    | Purpose                                |
-| -------------------------- | -------------------------------------- |
-| `flutter_localizations`    | Flutter's built-in localization support |
-| `intl`                     | Internationalization utilities          |
+| Package                 | Purpose                                 |
+| ----------------------- | --------------------------------------- |
+| `flutter_localizations` | Flutter's built-in localization support |
+| `intl`                  | Internationalization utilities          |
 
-| Command              | Purpose                                     |
-| -------------------- | ------------------------------------------- |
-| `flutter gen-l10n`   | Generate localization classes from ARB files |
+| Command            | Purpose                                      |
+| ------------------ | -------------------------------------------- |
+| `flutter gen-l10n` | Generate localization classes from ARB files |
 
-| File               | Purpose                                          |
-| ------------------ | ------------------------------------------------ |
+| File               | Purpose                                            |
+| ------------------ | -------------------------------------------------- |
 | `l10n.yaml`        | Localization configuration (ARB dir, output, etc.) |
-| `app_en.arb`       | Template ARB file (source of truth)              |
-| `app_<locale>.arb` | Translated ARB file for each locale              |
+| `app_en.arb`       | Template ARB file (source of truth)                |
+| `app_<locale>.arb` | Translated ARB file for each locale                |
diff --git a/skills/internationalization/references/directionality.md b/skills/internationalization/references/directionality.md
@@ -19,10 +19,10 @@ Retrieve the current direction: `Directionality.of(context)`
 
 ## Visual vs Directional Widgets
 
-| Widget Type     | Direction Terms       | Use Case                                    |
-| --------------- | --------------------- | ------------------------------------------- |
-| **Visual**      | top, left, right, bottom | Absolute positioning that never changes    |
-| **Directional** | top, start, end, bottom  | Relative to text direction (respects RTL)  |
+| Widget Type     | Direction Terms            | Use Case                                  |
+| --------------- | -------------------------- | ----------------------------------------- |
+| **Visual**      | top, left, right, bottom   | Absolute positioning that never changes   |
+| **Directional** | top, start, end, bottom    | Relative to text direction (respects RTL) |
 
 ## `EdgeInsetsDirectional` vs `EdgeInsets`
 
diff --git a/skills/material-theming/SKILL.md b/skills/material-theming/SKILL.md
@@ -162,12 +162,12 @@ See [references/spacing.md](references/spacing.md) for the full `AppSpacing` cla
 | `cardTheme`               | Card default styling                         |
 | `dialogTheme`             | Dialog default styling                       |
 
-| Material 3 Color Role | Typical Use                          |
-| ---------------------- | ------------------------------------ |
-| `primary`              | Key UI elements, FAB, active states  |
-| `onPrimary`            | Text/icons on primary color          |
-| `secondary`            | Less prominent UI elements           |
-| `surface`              | Card, sheet, dialog backgrounds      |
-| `onSurface`            | Text/icons on surface color          |
-| `error`                | Error indicators, destructive actions |
-| `outline`              | Borders, dividers                    |
+| Material 3 Color Role | Typical Use                           |
+| --------------------- | ------------------------------------- |
+| `primary`             | Key UI elements, FAB, active states   |
+| `onPrimary`           | Text/icons on primary color           |
+| `secondary`           | Less prominent UI elements            |
+| `surface`             | Card, sheet, dialog backgrounds       |
+| `onSurface`           | Text/icons on surface color           |
+| `error`               | Error indicators, destructive actions |
+| `outline`             | Borders, dividers                     |
diff --git a/skills/navigation/SKILL.md b/skills/navigation/SKILL.md
diff --git a/skills/static-security/references/packages.md b/skills/static-security/references/packages.md
diff --git a/skills/ui-package/SKILL.md b/skills/ui-package/SKILL.md
diff --git a/skills/ui-package/reference.md b/skills/ui-package/reference.md
