# Webapp Gui Design > Use when designing or building a SaaS web-app shell, navigation, dashboard, table, form, dialog, auth, upload, or system state in React/Next/Tailwind or Bootstrap/Tabler/PHP. Do not use for marketing websites or backend-only work. - Skill: `peterbamuhigire/webapp-gui-design` (Agent Skill, multi-file: 17 files) - Install (CLI): `npx skillmds@latest add peterbamuhigire/webapp-gui-design` - Raw SKILL.md: https://api.skillmd.com/api/skills/peterbamuhigire/webapp-gui-design/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Marketing & Growth - Author: peterbamuhigire (https://skillmd.com/u/peterbamuhigire) - Updated: 2026-09-17 - Page: https://skillmd.com/skills/peterbamuhigire/webapp-gui-design --- # Web App GUI Design Acknowledgement: Shared by Peter Bamuhigire, techguypeter.com, +256 784 464178. ## Use When - Building or reviewing a SaaS web UI on React/Next.js/TypeScript/Tailwind - Standardising app shell, navigation, dashboards, or data-table patterns across products - Standardising authentication surfaces and the Super Admin experience for managed backgrounds, light/dark logos, and favicons - Working on the Bootstrap 5 + Tabler + PHP seeder stack — load `sections/01-overview.md` first ## Do Not Use When - Pure landing or marketing pages — use editorial/marketing layout guidance, not this app-shell skill - Mobile-native screens — use `android-ui-ux-design` or `ios-ui-ux-design` - Low-level Tailwind syntax questions — out of scope for this skill ## Required Inputs | Input | Source | Evidence | |---|---|---| | Roles, jobs, routes, and object model | Product and application contracts | Permission matrix, routes, entities, and critical tasks | | Target stack and existing components | Repository and engineering owner | Framework versions, design-system inventory, and constraints | | Data/state/error contracts | API and domain owners | Loading, empty, failure, permission, and concurrency states | The target surface (dashboard, CRUD table, form, settings), the auth/tenant model, and the data model for at least one screen. For the seeder stack, the `seeder-page.php` template path. ## Workflow 0. For premium, revenue-critical, dashboard-heavy, or executive-facing products, state the typeface(s) and palette intent first per `doctrine/design-doctrine.md` (§2 Anti-Slop Charter) and pick a deliberate, non-slop face from `doctrine/references/font-groups-and-usage.md` before choosing layout or visual direction. 1. Place the screen in the app shell (sidebar + topbar + content area). 2. Pick the layout primitive (dashboard grid, table, form, detail-with-tabs). 3. Wire data with React Query; never call `fetch` inside components. 4. Attach loading + error + empty states *before* connecting real data. 5. Check consistency against existing screens and primitives before adding a new pattern. 6. Extend shared primitives/components before creating a bespoke screen-only pattern. 7. For authentication or tenant-entry surfaces, apply the shared visual and asset-management contract in `references/auth-and-tenant-visual-standard.md`. 8. Run the a11y + responsive sweep (§15 checklist) before merge. ## Decision Rules | Condition | Choice | Wrong-choice failure | |---|---|---| | Users compare many records | Table with stable columns, filters, and bulk actions | Card grids slow scanning and hide relationships | | Task is contextual and reversible | Drawer or inline edit preserving place | Full navigation loses context and selection | | Permission or tenancy changes visibility | Server-authoritative guard plus clear UI state | Cosmetic hiding leaks capability or confuses access | ## Capability Contract - Must inspect repository, routes, data contracts, and existing components before implementation; review remains read-only unless changes are requested. - May edit and test in-scope UI. Do not mutate production data, weaken authorization, expose secrets, or deploy without separate authority. ## Degraded Mode - If roles, data contract, or target stack are missing, stop implementation and return the blocking contract questions. - If execution/rendering is unavailable, provide a patch/specification and test matrix marked unverified. Recover failed loading/error/auth states by preserving context, offering a truthful next action, and rerunning affected tests. ## Quality Standards - Every data screen has a loading, empty, error, and success state. - Every form uses React Hook Form + Zod with a single `FormField` primitive. - Every interactive widget is keyboard-operable (Tab, Enter, Escape, Arrow). - Shared patterns must resolve through documented tokens and components, not one-off screen styling. - Colour contrast ≥ 4.5:1 for body text, 3:1 for ≥18pt or bold text. - Buttons use the correct element: ` ); } ``` `FormField` owns the label, error, description, and the input. For field-level patterns across web + mobile, apply `interaction-design-patterns` (Deferred Choices, Good Defaults). --- ## 6. Modal & Drawer Patterns Modals for focused edits; slide-over drawers for "view-with-actions" where context behind matters. Never more than one stacked modal. Destructive actions always go through `ConfirmDialog` with a typed confirm label. ```tsx deleteWorkspace(id)} /> ``` Dialog content is always in a Radix `Dialog` — focus trap and escape-to-close are not negotiable. --- ## 7. Loading States Skeleton screens for initial route loads; spinners only for button-level pending states. Use Suspense boundaries around the content area so route transitions paint the shell immediately. ```tsx }> ``` Optimistic updates: React Query `onMutate` sets the new value; `onError` rolls back; `onSettled` invalidates. --- ## 8. Error Boundaries Every route has an error boundary. Global handler sends to Sentry; the UI offers "Try again" and a support channel link. ```tsx // app/(app)/orders/error.tsx 'use client'; export default function Error({ error, reset }: { error: Error; reset: () => void }) { useEffect(() => { Sentry.captureException(error); }, [error]); return ( ); } ``` Never show a raw stack in production. Log the `digest` to give support a lookup handle. --- ## 9. Toast Notifications Sonner for SaaS — one per result, stacked top-right. Success toasts auto-dismiss in 4 s; error toasts require dismissal. ```tsx toast.success('Invite sent', { description: values.email }); toast.error('Failed to save', { description: err.message, duration: Infinity }); const t = toast.loading('Uploading…'); upload().then(() => toast.success('Uploaded', { id: t })).catch(() => toast.error('Failed', { id: t })); ``` Never use toast for navigation-required errors — route to an error page or a banner instead. --- ## 10. Authentication Flow UI Login, register, forgot-password, reset-password, 2FA, expired-session recovery, and pre-auth tenant selection share one authored visual system. The default composition is a full-viewport managed image, an enlarged blurred image layer that prevents edge halos, a dark neutral veil, and a restrained glass card with an opaque fallback. Auth pages never render the application shell. Use `references/auth-and-tenant-visual-standard.md`; do not recreate this stack per page. ```tsx // app/(auth)/login/page.tsx export default function Login() { return (

Sign in

New here? Create an account

); } ``` Post-login redirect: honour `?redirect=` if same-origin; fall back to `/`. 2FA input is a 6-digit `` — no free-form text field. --- ## 11. Multi-Tenant Switcher Tenants identify by slug and appear in the URL: `/[tenant]/orders`. The `TenantSwitcher` lives top-left in the topbar, persists the last-chosen tenant, and shows a quick-filter for power users with many tenants. ```tsx router.push(`/${slug}${restOfPath}`)} options={tenants.map(t => ({ value: t.slug, label: t.name, meta: t.plan }))} placeholder="Switch workspace" /> ``` Tenant-scoped API requests derive the tenant from context; never from a client-provided header that the user could forge. (The backend tenant-isolation model is owned by the engineering catalog, not this design engine.) --- ## 12. Dark Mode Class strategy (`dark:`) with a tri-state switch (system / light / dark). Persist to `localStorage`; set on `` before first paint to avoid flicker. ```tsx // app/layout.tsx — inline script before hydration