docs(flutterbits): charter + structure/routing + registry/CLI specs & Button plan#44
Merged
Merged
Conversation
…specs Brainstormed and documented the move into the flutterbits component layer. Adds three design specs under docs/superpowers/specs and reconciles every doc that the plan extended or contradicted. New specs (2026-06-10): - flutterbits-charter — identity (shadcn parity + an opinionated, intention- revealing structure layer), the four tiers (primitives/structure/blocks/ templates; "tools" dropped), the full catalog with shadcn re-homing (sheet/dialog/sidebar/tabs become structure), mobile-first platform stance, unprefixed-component naming, and the per-component dependency policy. - flutterbits-structure-and-routing-design — Layout/Screen as composed widgets (not base classes; dissolves "ScreenSpec"), header/body/footer slots, typed hand-written routing over go_router (no codegen), FwRoute/FwRoutePattern, presentation-as-a-knob (FwPresentation page/sheet/dialog/fullScreen, deep-linkable), guards, transitions, imperative overlay helpers. - flutterbits-registry-cli-design — install-types (component/util/barrel), manifest schema, flutterbits.json, init/add/diff, barrel regen rules, the anchor/overlay substrate as flutterbits cn.ts, hosting via apps/docs. Reconciliations (no-drift, AGENTS.md s12): - AGENTS.md s1 identity expanded (structure layer + mobile-first); s4 scoped the Fw-prefix rule to the engine and made flutterbits components unprefixed (the old FwButton example contradicted this); s8 added init/barrel/install- types/flutterbits.json; s12 sanctioned go_router (+ by-demand flutter_svg). - README + apps/docs flutterbits overview updated to the same plan. - core-engine-design spec: FwButton -> Button example fixed. Decisions deferred by explicit sign-off: state-management conventions; the desktop-centric component set and SidebarLayout (by-demand); routing codegen. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
An independent Opus 4.8 agent reviewed the three specs against the Flutter SDK + AGENTS.md and found real defects (several verified against the SDK on disk). Applied the blocking + should-fixes; verified each rather than blindly accepting (one fix diverges from the reviewer's suggestion, noted below). Blocking fixes: - B1 (charter §5.1): the "zero clashes in a Material-free app" claim was FALSE — package:flutter/widgets.dart itself exports Form/Icon/Image/Table/ Title/Navigator/Page/etc. Rewrote to acknowledge both clash surfaces and made "check every component name against widgets.dart and rename collisions" a hard authoring rule (DataTable not Table; no Form/Icon/Image component). - B2 (charter §5, structure §3.3): FwStatusBar was mislabeled an *engine* type — it wraps services.dart, which the engine never touches. Reframed as a flutterbits structure value type (kept the Fw name for consistency with FwPresentation/FwTransition — this is where I diverged from the reviewer's "unprefix it", since unprefixing would split the routing value-type family). - B3 (structure §2.1/§3.1): Layout was conflated across root-app-host vs nested-shell vs plain-widget. Added the invariant: exactly one root Layout hosts the app+router; runApp(AppLayout()) works; a shell Layout compiles to a ShellRoute builder and must not re-host a router. - B4 (structure §4.3): demoted "a sheet is free / zero extra code" — go_router ships no Material-free sheet Page, so flutterbits authors custom FwSheetPage/FwDialogPage PopupRoutes that own scrim/safe-area/grabber/ drag-dismiss (feasible, scoped — §11b — not free). Added §4.3.1: deep-linked sheets require NESTED routes (children:), not flat siblings. - B5 (charter §4): "tablets — no new work" was a silent scope reduction; narrowed to "styling reuses responsive variants; adaptive navigation is by-demand structure work". Should-fixes: S2 push wiring (route.go ≡ context.go(location)); S3 web push<T>-result caveat; S4 guards are FutureOr<String?> (async); S5 barrel collision handling (authoring rule guarantees no widgets.dart clash); S6 registry versioning recorded as an accepted v1 limitation; S7 init theme.dart must match the generator's emit shape (drop-in); S8 layout pubDeps reconciled. Nits: N1 apps/example transition noted; N2 FwTone -> Tone; N4 anchor edge-flip positioning flagged as real work. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Decided: faithful golden-image previews as the always-on default + DartPad live/editable embeds where deps allow; React reimplementation rejected (would show a different artifact than the copied one); a Flutter-Web gallery deferred by-demand. Added to registry/CLI spec 7.1. Codegen routing stays rejected. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
…/example) User correction: flutterbits gets its OWN showcase/golden/compile app (apps/gallery); apps/example stays the flutterwindcss ENGINE showcase only. Reconciled AGENTS.md (S2 layout tree + prose, S6 checklist, S9 goldens, S10 commands), README repo layout, and all three flutterbits specs to point the component golden/compile target at apps/gallery while leaving engine-showcase references on apps/example intact. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
…its slice) TDD, bite-sized plan grounded in the real engine API (fw_style_ops.dart) and the existing golden harness. Scaffolds apps/gallery (new component target), authors the canonical Material-free Button (6 variants x 4 sizes, FocusableActionDetector + keyboard + focus ring + Semantics, semantic-token styling via .tw), full golden coverage, and a smoke test. Registry/manifest/build_registry explicitly deferred to the next plan (recorded, not silent). Notes the default->primary/md Dart reserved-word deviation + its charter/AGENTS reconciliation (Task 7). Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
…ps in Layout The gallery exists to showcase flutterbits, and Layout is its flagship/intended root; Button is built first only to de-risk the component pattern and give Layout something real to host. Labeled the WidgetsApp host as throwaway bootstrap that the structure plan replaces with Layout (and demos). Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
|
The latest updates on your projects. Learn more about Vercel for GitHub.
|
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Moves the project into the flutterbits component layer. This branch is design + plan only (the first code lands on a follow-up branch).
What's here
Three design specs (
docs/superpowers/specs/2026-06-10-*):Layout/Screenas composed widgets (not base classes; dissolves "ScreenSpec"),header/body/footerslots, typed hand-written routing overgo_router(no codegen), presentation-as-a-knob (deep-linkable sheets/dialogs), guards, transitions, imperative overlays.flutterbits.json,init/add/diff, barrel regen, theanchoroverlay substrate (flutterbits'cn.ts), preview strategy (golden images + DartPad).First implementation plan (
docs/superpowers/plans/2026-06-10-flutterbits-button-and-gallery.md) — TDD, grounded in the real engine API: scaffoldapps/gallery+ the canonicalButton.Key decisions (locked with the user)
go_router, typed hand-written routes, no codegen.Button/Screen); engine + routing value types stayFw.apps/galleryis the flutterbits component target;apps/examplestays the engine showcase.Reconciliations (no-drift)
AGENTS.md (§1/§2/§4/§6/§8/§9/§10/§12), README,
apps/docsflutterbits overview, and the core-engine spec were updated so nothing contradicts the new plan (e.g. theFw-prefix rule scoped to the engine;go_routersanctioned; component target →apps/gallery).Review note
The three specs were adversarially reviewed by an independent Opus 4.8 agent against the Flutter SDK; it caught real over-claims (a false "zero name-clashes" claim —
widgets.dartexportsForm/Icon/Image/…; "sheets are free" when a custom Material-freePopupRouteis needed; "tablets — no new work"). All fixed before this PR.🤖 Generated with Claude Code