Przejdź do treści
Biblioteka skilli
Programowanie · Budowanie i kod

flutter-app-engineering

/flutter-app-engineering

Buduje, przegląda i testuje aplikacje Flutter z tokenami designu, ThemeData i flutter_test.

Licencja
Apache-2.0
Ostatnia zmiana repozytorium
02.11.2026

Ocena i bezpieczeństwo

100/ 100Klasa: dobry
Format25 / 25
Frontmatter z nazwą i opisem, poprawna nazwa, opis do 1024 znaków, nazwa zgodna z folderem.
Odkrywalność25 / 25
Opis mówi, kiedy użyć skilla, ma sensowną długość i jest w 3. osobie.
Treść35 / 35
Co najmniej 150 słów i do 500 linii, nagłówki, listy kroków, przykłady albo kod.
Higiena15 / 15
Bez zaślepek typu TODO, bez ścieżek Windows, z licencją.
Ryzykobrak sygnałów w skanie
Pliki w paczce
4
Skrypty
0
Komentarze HTML
0
Adresy URL w SKILL.md
3
Przestarzałość

Brak sygnałów. Repozytorium zmienione 02.11.2026, bez odwołań do wycofanych modeli i API.

Licencja

Apache-2.0, otwarta: można używać i zmieniać, z zachowaniem licencji i informacji o zmianach.

Co robi i kiedy

Buduje, przegląda i testuje aplikacje Flutter z tokenami designu, ThemeData i flutter_test.

Oryginalny opis (EN)

Engineering skill: Flutter app — how to build and ship a cross-platform app with Flutter, Dart, ThemeData + a generated ThemeExtension for design tokens, flutter_test. Use when writing, reviewing, testing or releasing code in this stack, and when turning a Celestial design or experience skill into code.

Jak działa

  1. Stack
  2. Commands
  3. Structure
  4. Naming
  5. From design and experience skills
  6. Conventions
  7. Do
  8. Don't
  9. Quality gates
  10. Workflow
Sekcje z nagłówków SKILL.md, w oryginale · 175 linii, 1 989 słów
Podgląd SKILL.md
---
name: flutter-app-engineering
description: "Engineering skill: Flutter app — how to build and ship a cross-platform app with Flutter, Dart, ThemeData + a generated ThemeExtension for design tokens, flutter_test. Use when writing, reviewing, testing or releasing code in this stack, and when turning a Celestial design or experience skill into code."
type: engineering
stack: cross-platform
core: "1.0"
checked: 2026-10-26
---

# Flutter app

One Dart codebase drawn by Flutter on iOS and Android, with tokens as a theme extension, Riverpod for state and golden tests guarding every component.

For apps that want identical, custom-branded UI on both phones: fintech, health, retail and media apps. Flutter draws every pixel itself, so the design skill maps directly onto widgets; signed builds come out of CI and ship to both stores. Design-skill tokens become a ThemeExtension generated into Dart.

## Stack
- **Language:** Dart ^3.9 — Sound null safety, records and pattern matching keep state handling explicit.
- **Framework:** Flutter 3.35+ — One rendering engine and widget set for both platforms.
- **Styling:** ThemeData + a generated ThemeExtension for design tokens — Widgets read Theme.of(context); light and dark come from one token source.
- **State:** Riverpod with code generation ^3 — Testable providers, AsyncValue for loading and error, and no BuildContext needed for logic.
- **Data:** Dio client + freezed / json_serializable models; flutter_secure_storage for credentials Dio ^5 — Immutable typed models and a single place for interceptors and retries.
- **Build:** flutter build (appbundle and ipa) in CI 3.35+ — Signed release artefacts from the same pinned Flutter version every time.
- **Hosting:** App Store and Google Play, uploaded from CI to test tracks first — Testers get each build before a staged store rollout.
- **Package manager:** pub (with a version manager pinning Flutter per project) — Every machine and CI job builds with the same SDK.
- **Testing:** flutter_test (unit, widget and golden tests) bundled with Flutter — Fast widget tests and pixel comparisons for each component state.
- **Testing:** integration_test bundled with Flutter — Journey tests on real simulators and emulators.
- **Testing:** mocktail ^1 — Mocks without code generation for repositories and clients.

## Commands
- dev: `flutter run`
- e2e: `flutter test integration_test`
- lint: `dart format --output=none --set-exit-if-changed . && flutter analyze`
- test: `flutter test`
- build: `flutter build appbundle --release && flutter build ipa --release`
- install: `flutter pub get`

## Structure
- `lib/main.dart + lib/app.dart` — Entry point, ProviderScope, router and theme setup
- `lib/features/<feature>/` — presentation/ (screens, widgets), application/ (providers), data/ (repository, DTOs)
- `lib/ui/` — Design-skill components as stateless widgets reading the theme
- `lib/theme/tokens.dart` — Generated ThemeExtension with light and dark token values
- `lib/core/` — HTTP client, secure storage, routing (go_router), analytics
- `test/` — Unit, widget and golden tests mirroring lib/
- `integration_test/` — One test per experience-skill journey

## Naming
- Files: snake_case.dart
- Tests: <file>_test.dart mirroring lib/; goldens in test/goldens/<component>_<state>_<theme>.png
- Branches: type/short-description, e.g. feat/card-freeze
- Components: UpperCamelCase widgets named after the design-skill component, e.g. AppButton

## From design and experience skills
When a Celestial design skill is in use, write its tokens as Flutter ThemeData in `lib/theme/tokens.dart`, and build its components in `lib/ui` with the same names and variants. Components read tokens only — no raw colours, sizes or font names.

When a Celestial experience skill is in use, give each journey one end-to-end test (happy path plus its error and empty states) and name analytics events `object_action` from its measures.

## Conventions
### Code
- Prefer small, pure functions and explicit types at module boundaries. _(Easier to test, review and change.)_
- No business logic or HTTP calls in build methods; screens watch providers, providers call repositories. _(Logic becomes testable without pumping widgets.)_

### Components
- Components read design tokens; no raw hex values, pixel sizes or font names in component code. _(One token change restyles the product.)_
- Widgets in lib/ui are stateless, take data and callbacks only, and read colours, spacing and type from the theme extension. _(Components stay reusable and restyle from one token change.)_

### Data
- Analytics events are object_action in snake_case and come from the experience skill’s measures. _(Names stay consistent across teams and tools.)_

### Errors
- Every async action has loading, empty, error and success states, matching the experience skill. _(Unhandled states are where users get stuck.)_
- Every async screen renders AsyncValue with when(data:, loading:, error:), and the error branch offers a retry. _(The compiler forces each state to be handled.)_

### Security
- Secrets never live in the repository; read them from the environment or a secret store. _(A leaked key outlives the commit that removed it.)_
- Validate every input on the server, even when the client already did. _(Clients can be bypassed.)_
- Web pages ship a Content-Security-Policy, HSTS, X-Frame-Options and nosniff. _(Cheap protection against the most common attacks.)_
- Credentials go in flutter_secure_storage; --dart-define carries only non-secret config such as the API base URL. _(Values compiled into the app can be extracted from the binary.)_

### Performance
- Use const constructors wherever possible and ListView.builder for long lists; profile in profile mode, never debug. _(Avoids needless rebuilds and keeps 60fps scroll on mid-range phones.)_

### Accessibility
- Use native elements first; add ARIA only when no native element fits. _(Native controls bring keyboard and screen-reader support for free.)_
- Icon-only buttons have a tooltip or Semantics label; text scales with the system setting without clipping up to 200%. _(Flutter draws its own UI, so semantics must be given explicitly.)_

## Do
- Write a golden test for every component state in light and dark
- Keep DTOs in data/ and map them to domain models before they reach the UI
- Run the analyzer with a strict lint set and treat infos as errors in CI

## Don't
- Hard-code Colors or EdgeInsets values inside lib/ui
- Use setState for data shared between screens
- Leave Platform checks scattered through screens; wrap them in one adaptive widget

## Quality gates
| Gate | Tool | Threshold | When |
|---|---|---|---|
| Lint and types | dart format + flutter analyze (strict lint set) | 0 errors, warnings or infos; formatting unchanged | Every pull request |
| Unit and component tests | The stack’s test runner | All pass; every design-skill component state covered | Every pull request |
| Journey tests | End-to-end runner | One test per experience-skill journey: happy path + error state | Every pull request |
| Accessibility | flutter_test accessibility guidelines (labeled tap targets, tap target size, text contrast) | All guidelines pass for every screen in the journey tests; WCAG 2.2 AA | Every pull request |
| Performance budget | Lab measurement in CI | Web: LCP ≤ 2.5s · INP ≤ 200ms · CLS ≤ 0.1 · ≤ 170KB JS per route. Mobile: cold start ≤ 2s · 60fps scroll | Every pull request |
| Dependency and secret scan | Dependency audit + secret scanner | No high or critical findings; no secrets | Every pull request and nightly |
| Golden tests | flutter_test matchesGoldenFile | Every design-skill component state has light and dark goldens; 0 unexpected diffs | Every pull request |

The Accessibility gate checks Celestial accessibility core v1.0 (WCAG 2.2 AA); it can change tool but is never skipped. Automated: A11Y-C1, A11Y-F1, A11Y-I1, A11Y-N1, A11Y-N2, A11Y-S1, A11Y-L2, A11Y-P1 (partly). Manual pass before release: A11Y-K1, A11Y-G1, A11Y-R1, A11Y-M1, A11Y-O1, A11Y-V1, A11Y-E1, A11Y-U1, A11Y-L1 — keyboard-only run, screen reader on each journey step, 200% zoom and 320px width, reduced motion, captions on any media. Requirement IDs come from the design and experience skills this code builds. This layer owns: **A11Y-F1** A visible focus indicator on every interactive element, never hidden behind sticky bars (WCAG 2.4.7, 2.4.11); **A11Y-R1** Text works at 200% zoom, at 320px width, with increased text spacing and in either orientation (WCAG 1.4.4, 1.4.10, 1.4.12, 1.3.4); **A11Y-M1** Motion respects the reduced-motion setting; anything moving for over 5 seconds can be paused; nothing flashes more than 3 times a second (WCAG 2.2.2, 2.3.1, 2.3.3 (AAA, advised)); **A11Y-O1** Tooltips and pop-overs shown on hover or focus can be dismissed, hovered and stay until dismissed (WCAG 1.4.13); **A11Y-I1** Images, icons and charts have text alternatives (empty for decoration); text is never an image (WCAG 1.1.1, 1.4.5); **A11Y-V1** Video and audio have captions, transcripts or audio description; nothing plays sound automatically for over 3 seconds (WCAG 1.2.1, 1.2.2, 1.2.3, 1.2.4, 1.2.5, 1.4.2); **A11Y-K1** Every action works by keyboard in a logical order, with no keyboard traps; single-key shortcuts can be turned off or remapped (WCAG 2.1.1, 2.1.2, 2.1.4, 2.4.3); **A11Y-G1** Nothing is drag-, gesture- or motion-only: each has a single tap or click alternative, and actions fire on release so they can be cancelled (WCAG 2.5.1, 2.5.2, 2.5.4, 2.5.7); **A11Y-N1** Every page has a clear title, headings, landmarks and a skip link, and can be found more than one way (WCAG 2.4.1, 2.4.2, 2.4.5, 2.4.6); **A11Y-N2** Controls have visible labels and instructions; links say where they go; the accessible name contains the visible label (WCAG 2.4.4, 2.5.3, 3.3.2); **A11Y-S1** Status, results and errors are announced to screen readers (WCAG 4.1.3); **A11Y-E2** Never ask for the same information twice in one flow; personal fields declare their purpose so they can be autofilled (WCAG 3.3.7, 1.3.5); **A11Y-U1** Focusing or changing a field never moves the person somewhere else or submits without warning (WCAG 3.2.1, 3.2.2); **A11Y-W1** Time limits warn first and can be extended (WCAG 2.2.1); **A11Y-L2** The page language, and any passage in another language, is declared in code (WCAG 3.1.1, 3.1.2); **A11Y-P1** Structure, order, names, roles and states are in the code: native elements first, ARIA only following the WAI-ARIA patterns (WCAG 1.3.1, 1.3.2, 4.1.2).

## Workflow
- Branching: Trunk-based: short-lived branches off main, squash-merged within two days.

**Review checklist**
- Correctness: does it do what the issue asks, including edge cases?
- Readability: could a new teammate change it safely?
- Architecture: is it in the right place, with the right boundaries?
- Security: inputs, secrets, permissions, dependencies
- Performance: budgets, queries, bundle size
- Tests fail when the code is broken (flip a condition and re-run)
- One approving review; two for auth, payments or new platform plugins
- Golden diffs are reviewed as images, not approved in bulk

**Definition of done**
- Acceptance criteria met and demoed on the preview link
- Tests added for new behaviour and every state
- Accessibility and performance gates green
- Analytics events named from the experience skill
- Docs or changelog updated when behaviour changes
- Checked on iOS and Android at the largest system text size

**Release**
- Small pull requests (aim for under 400 changed lines)
- CI green before review
- Squash-merge to main; main is always deployable
- Every release has a written rollback path
- Builds from main go to internal test tracks; store release every two weeks with staged rollout
- Flutter SDK upgrades land in their own pull request with refreshed goldens

**Incidents**
- Halt the staged rollout and promote the previous build; ship a hotfix from main
- Write a blameless note within 48 hours: what happened, impact, fix, prevention

## Overrides of the engineering core
- Preview deploy: Replaced by an internal test-track build per merge to main — Mobile apps have no web link; testers install the build instead.
- Performance budget: Mobile thresholds apply: cold start ≤ 2s · 60fps scroll, measured in profile mode — Debug mode is much slower and misstates real performance.

## Examples
### Component reading the token extension (`lib/ui/app_button.dart`)

```dart
import 'package:flutter/material.dart';
import '../theme/tokens.dart';

class AppButton extends StatelessWidget {
  const AppButton({super.key, required this.label, required this.onPressed, this.primary = true});

  final String label;
  final VoidCallback? onPressed;
  final bool primary;

  @override
  Widget build(BuildContext context) {
    final t = Theme.of(context).extension<AppTokens>()!;
    return ConstrainedBox(
      constraints: BoxConstraints(minHeight: t.controlHeight, minWidth: 48),
      child: FilledButton(
        onPressed: onPressed,
        style: FilledButton.styleFrom(
          backgroundColor: primary ? t.primary : t.surface,
          foregroundColor: primary ? t.onPrimary : t.ink,
          shape: RoundedRectangleBorder(borderRadius: BorderRadius.circular(t.radiusControl)),
        ),
        child: Text(label, style: t.labelStyle),
      ),
    );
  }
}
```

## Further reading
- [Flutter documentation](https://docs.flutter.dev/) — Widgets, theming, testing (including goldens) and release builds.
- [Dart documentation](https://dart.dev/guides) — Language features, effective Dart style and the analyzer.
- [WCAG standards and guidelines](https://www.w3.org/WAI/standards-guidelines/wcag/) — The success criteria behind the accessibility gate.
Pliki w paczce (4)
  • AGENTS.md 7 KB
  • README.md 2 KB
  • SKILL.md 14 KB
  • rules/flutter-app-engineering.mdc 5 KB

Wersje

RepozytoriumWynikLicencja
Ta strona · anandartin/celestial-skills100Apache-2.0
lofingoindia/codex-engineering-skills100MIT

Migawka bazy z 13.11.2026 · wersja paczki 44fae72e4dfa (skrót SHA-256 całej paczki)

Pobrania w ostatnich 30 dniach: 0 · ranking

Zgłoś problem z tym skillem: szkodliwa treść, błędny opis albo prośba autora o usunięcie.

Podobne skille

  • 100django-app-engineering
    Opisuje, jak budować i wysyłać aplikacje webowe w Django: zmienne CSS z designu, osobny CSS dla komponentów i testy pytest.
  • 100react-web-app-engineering
    Wspiera pisanie, testowanie i wydawanie aplikacji webowej w React, TypeScript, Tailwind CSS i Vitest.
  • 100dart-n-flutter
    Prowadzi pisanie kodu Dart i Flutter zgodnie z oficjalnymi zaleceniami dla plików .dart.
  • 100dart-expert
    Pomaga w Dart i Flutter przy aplikacjach mobilnych i wieloplatformowych, w tym widgetach i frameworku Flutter.
  • 100flutter-package-development
    Tworzy, rozwija i testuje pakiety Dart i wtyczki Flutter do dystrybucji, z przygotowaniem do publikacji.
  • 100flutter-release-engineering
    Pomaga ustawić lub zrecenzować wydawanie aplikacji Flutter: flavory i konfiguracja środowisk, podpisywanie, macierz builda, numery wersji, metadane sklepów i aktualizacje OTA przez Shorebird.

Uwagi i zgłoszenia

Wiadomość trafi do Bartosza Sokolińskiego. Adres e-mail jest potrzebny tylko do odpowiedzi. Szczegóły w polityce prywatności.