faststrap-app-builder

name

faststrap-app-builder

description

Use when building or redesigning real FastHTML applications with Faststrap, such as company websites, SaaS landing pages, dashboards, portals, auth flows, admin systems, or multi-page product sites. This skill guides Faststrap work toward production-grade results by using Faststrap components first, Bootstrap for structure, HTMX for interactivity, and custom CSS for polish rather than generic Bootstrap presentation.

Faststrap App Builder

Use this skill when the task is to build or significantly improve a real application with Faststrap + FastHTML.

First moves

Before writing code:

1. Inspect the current app's entrypoint, theme/defaults module, route layout, asset mount, and custom CSS.
2. If the user provides a Faststrap repo path, inspect:
   • AGENTS.md
   • README.md
   • the relevant component modules under src/faststrap/components/
   • the relevant docs pages under docs/components/
   • the most relevant files in examples/ and showcase/
3. If the user provides a reference app, inspect it before designing.
4. Match the page type to the closest reference:
   • start with references/reference-index.md
   • marketing/landing: use the reference index, then open references/reference-apps.md only if needed
   • dashboard/admin: use the reference index, then open references/reference-apps.md only if needed
   • auth/onboarding: see references/nis-patterns.md
5. Inventory the existing Faststrap component surface before inventing new UI structure. Faststrap has a large component library, so check what already exists for navigation, forms, data display, feedback, patterns, and layout before building custom HTML.
6. Follow the implementation order of precedence below before inventing custom structure.

Implementation order of precedence

Use this order unless the task clearly requires otherwise:

1. Faststrap components and Bootstrap-native layout/responsive utilities
2. HTMX for dynamic behavior and partial updates
3. Custom CSS for branding, atmosphere, and modern visual polish
4. JavaScript only when HTMX/Bootstrap cannot solve the problem cleanly or when browser/PWA APIs are required

This means:

• prefer Bootstrap spacing, grid, display, flex, container, offcanvas, modal, collapse, and utility classes before writing custom layout CSS
• prefer existing Faststrap components and patterns before creating bespoke wrappers or raw HTML structures
• prefer HTMX before custom JavaScript for interactivity, filtering, partial refresh, form flows, and inline actions
• use custom CSS to elevate visuals, not to reimplement Bootstrap responsiveness or hide/show behavior unnecessarily
• allow JavaScript for legitimate cases such as PWA flows, geolocation, service workers, media capture, complex charts/maps, or browser APIs HTMX cannot replace
• when two cards or columns sit side by side, define the mobile stack explicitly first with Row(..., cols=1, cols_md=2) or Row(..., cols=1, cols_lg=2) rather than assuming desktop structure will collapse well on its own
• if a supporting/highlight card is too content-heavy for mobile or tablet, hide it intentionally with Bootstrap display classes such as d-none d-lg-block instead of squeezing it into a weak small-screen composition

Non-negotiable standards

• Do not ship generic Bootstrap-looking pages.
• Do not default to plain white sections, weak typography, or boilerplate hero-card-grid-footer layouts unless the references support that exact direction.
• Choose one explicit primary reference before writing the page.
• Prefer composing existing Faststrap components and patterns first, then layer custom CSS for polish.
• Assume there is probably already a relevant Faststrap component or pattern somewhere in the 100+ component surface; check the framework before inventing a new one.
• Build shared theme tokens and layout structure before polishing individual pages.
• Keep the UI responsive, accessible, and visually intentional.
• Do not rely on external CSS CDNs for project styling. Keep styling in local project assets and Faststrap/Bootstrap.
• Treat JavaScript as the last interaction tool, not the first one.
• Before finishing, run a dedicated Bootstrap-smell pass and remove untouched default pills, soft default shadows, over-rounded surfaces, and generic section treatment.

Reference discipline

• Always open references/reference-index.md first when selecting a showcase reference.
• Pick one primary reference and at most one secondary reference.
• Prefer flagship references over legacy/simple ones unless the user explicitly asks for a simpler build.
• Reuse structure, responsiveness, and quality bar from the reference; do not copy text or brand voice.
• If the chosen reference is a legacy/simple example, compensate with stronger CSS and hierarchy decisions.

Bootstrap-smell audit

Run this pass before finishing any polished page:

• palette feels branded, not stock Bootstrap blue
• cards and sections have intentional surface treatment, not untouched default Bootstrap panels
• typography hierarchy is obvious across hero, section, body, and label text
• border radii feel deliberate rather than default Bootstrap rounding
• spacing rhythm is consistent across sections, cards, controls, and stacks
• primary buttons feel intentional, not flat defaults
• mobile layout is designed explicitly, not just desktop collapsed downward
• light and dark variants both remain legible and intentional when both are supported
• empty, loading, success, and error states exist for key flows
• HTMX is used where interaction is needed instead of defaulting to custom JavaScript
• no generic hero-card-grid-footer boilerplate survived untouched

Visual system rules

• Define a typography hierarchy before polishing components:
  • hero headline: large, tight line-height, deliberate tracking
  • section headline: clearly smaller than hero but still high-contrast
  • body copy: readable, quieter, and visibly distinct from headings
  • eyebrow/kicker text: compact and intentional, not decorative noise
• Establish spacing rhythm at the section level first:
  • major sections should feel intentionally separated
  • cards should have consistent internal padding
  • stacked controls should keep consistent gaps across breakpoints
• Use Bootstrap for structure, but do not leave Bootstrap's default radii, shadows, and surface treatment untouched on flagship pages.
• Give every polished page a clear surface strategy:
  • dark shell with lighter cards
  • soft light shell with elevated white cards
  • editorial split backgrounds
  • glass or layered atmosphere where it genuinely helps

States and UX coverage

• Do not finish a page without checking empty, loading, success, and error states for the main interactive surfaces.
• Empty states should explain what to do next, not just say "No data".
• Loading states should use Faststrap or Bootstrap primitives visibly rather than leaving dead-looking blank areas.
• Error states should be readable, specific, and visually integrated with the page.
• Forms should show validation feedback, helper text where needed, and clear submit affordances.

Accessibility rules

• Preserve semantic headings in descending order.
• Ensure interactive controls have discernible labels or aria-labels.
• Keep contrast strong enough in both light and dark themes.
• Do not hide important meaning in color alone.
• Preserve keyboard focus visibility; do not style it away.
• When using icon-only controls, provide accessible labels.
• Prefer buttons for actions and links for navigation; do not blur the two casually.

CSS organization rules

• For single-file showcases or isolated demos, inline Style(...) blocks are acceptable.
• For multi-route or production-style apps, move custom CSS into local asset files and mount them properly.
• Prefer a small production CSS shape such as:
  • _brand.css
  • _typography.css
  • _layout.css
  • _surfaces.css
  • _interactions.css
• Keep Bootstrap utilities for layout/responsiveness and custom CSS for brand identity, surface treatment, and advanced polish.
• Avoid scattering one-off inline style= strings across a codebase when the app is larger than a simple showcase.

See references/css-architecture.md for a recommended production CSS structure.

HTMX-first recipes

Prefer these patterns before reaching for custom JavaScript:

• ActiveSearch for live search/filtering
• AutoRefresh for polling dashboards or activity surfaces
• LazyLoad for deferred sections or below-the-fold content
• LoadingButton for async actions with visible feedback
• ConfirmDialog for destructive actions
• FormGroup + HTMX validation endpoints for live field feedback
• DataTable with built-in sort/search/pagination before inventing raw table wiring

When not to use HTMX as the primary tool:

• complex client-side charting behavior
• real-time collaboration
• browser/device APIs such as camera, geolocation, or push/service-worker flows

See references/htmx-recipes.md for concrete build patterns.

Component selection

Before inventing a wrapper or custom HTML structure, check references/component-selection.md.

Use it to answer:

• which card/data surface fits this need?
• is there already a form or validation helper?
• should this be a navigation component, a layout primitive, or a preset?
• is this actually a CSS problem rather than a missing component?

Working pattern

1. Establish the app shell

• Create or inspect the FastHTML app entrypoint.
• Wire add_bootstrap(app, ...).
• Mount project assets.
• Add shared custom CSS after Faststrap.

2. Establish shared design language

• Put brand colors and global component defaults in a single theme module.
• Define layout wrappers before page-level sections.
• Use custom CSS for depth: gradients, glass, section contrast, spacing rhythm, shadows, image treatment, and state styling.
• Keep structural responsiveness primarily in Bootstrap/Faststrap usage, not hand-written media-query-heavy layout rewrites unless clearly necessary.
• Treat mobile as the base layout. Build the one-column version first, then opt into multi-column layouts at md/lg breakpoints where the content can breathe.

3. Build pages from references, not from scratch

• Pick the nearest reference app.
• Reuse its structural ideas, not its text.
• Preserve the user's domain and content hierarchy.

4. Favor production composition

• Split layouts, shared UI, and routes cleanly.
• Use route modules rather than oversized single-file pages when the app has multiple screens.
• Keep business logic out of presentation modules when possible.

5. Verify before finishing

• Check mobile and desktop structure.
• Check that Faststrap theme/defaults are actually applied.
• Check empty states, CTA clarity, spacing consistency, and contrast.
• Run the Bootstrap-smell audit explicitly.
• Run relevant tests; if the project has none, add at least focused smoke or route tests when practical.

Finish checklist

Before you consider the UI done, verify:

• typography hierarchy is deliberate
• spacing rhythm is consistent
• mobile layout is intentional, not just collapsed desktop
• empty/loading/error states exist for key flows
• accessibility labels and focus states remain intact
• at least one final pass was made specifically to remove Bootstrap-default visual leakage

See also:

• references/visual-design-rules.md
• references/troubleshooting.md
• references/form-workflow.md

Design bar

Good Faststrap app work should feel:

• branded rather than template-like
• structured rather than improvised
• spacious rather than cramped
• editorial and intentional rather than default Bootstrap
• polished enough to resemble the provided showcase apps

Anti-patterns

• dumping everything into one route file
• using only stock Faststrap examples without adapting the visual language
• relying on raw inline styles everywhere instead of shared CSS
• ignoring the user's reference projects
• making every page look like the same SaaS starter
• reaching for JavaScript before HTMX
• replacing Bootstrap layout/responsive utilities with avoidable custom CSS
• importing third-party styling CDNs for things Faststrap/Bootstrap and local CSS should handle
• forcing dense secondary cards, stat panels, or highlight boxes to remain visible on mobile when Bootstrap display utilities can preserve a cleaner small-screen hierarchy

Read these references as needed

• references/reference-index.md: canonical first-stop guide for picking the right showcase or production reference by page type and quality bar
• references/htmx-recipes.md: concrete HTMX-first interaction patterns for search, refresh, validation, confirm, lazy loading, and inline editing
• references/component-selection.md: practical guide for choosing existing Faststrap components before inventing new ones
• references/css-architecture.md: production CSS file organization and token structure
• references/form-workflow.md: complete form, validation, submit, and success/error flow patterns
• references/visual-design-rules.md: baseline design quality bar for typography, surfaces, spacing, and responsiveness
• references/troubleshooting.md: common failure modes and how to correct them quickly
• references/nis-patterns.md: real production-style project wiring and theming patterns from the user's NIS, Final-Year, and SIWES apps
• references/mmercyj-patterns.md: polished company-site composition and mobile-first responsive simplification patterns from mmercyj_beddings
• references/reference-apps.md: which local Faststrap showcase files to inspect by page type
• references/project-agents-template.md: template instructions to place in fresh app repos so future sessions start with the right guardrails