메뉴
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.
기본적으로 소스를 먼저 확인하는 Prompt가 선택됩니다. 직접 명령으로 전환하거나 로컬 사본을 다운로드할 수도 있습니다.
설치 여부를 결정하기 전에 SKILL.md와 SkillsMP에 표시된 보조 파일을 읽어 보세요.
Codex 또는 Claude로 설치 이 Prompt를 복사해 Codex, Claude 또는 다른 어시스턴트에 붙여 넣으면 Skill 페이지를 검토하고 설치를 진행할 수 있습니다.
직접 명령은 검토 Prompt를 거치지 않습니다. 실행하기 전에 소스를 확인하세요.
npx skills add https://github.com/peterbamuhigire/design-system-skills --skill webapp-gui-design명령은 한 줄로 유지됩니다. 복사하기 전에 가로로 스크롤해 전체 내용을 확인하세요.
로컬 사본을 원하시나요? SkillsMP에서 현재 제공할 수 있는 파일을 다운로드하세요.
SOC 직업 분류 기준
SKILL.md 표시 중
| name | webapp-gui-design |
| description | 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. |
| metadata | {"portable":true,"category":"04-web-and-ui-design","compatible_with":["claude-code","codex"]} |
Acknowledgement: Shared by Peter Bamuhigire, techguypeter.com, +256 784 464178.
sections/01-overview.md firstandroid-ui-ux-design or ios-ui-ux-design| 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.
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.fetch inside components.references/auth-and-tenant-visual-standard.md.| 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 |
FormField primitive.<button> for actions, <a href> for navigation.doctrine/design-doctrine.md (deliberate, stated typeface and palette; no banned default).| Output | Consumer | Evidence and acceptance |
|---|---|---|
| Web-app UI implementation/specification | Product and engineering | Shell, navigation, objects, states, permissions, and responsive behaviour are explicit |
| Verification record | QA, security, accessibility | Build/tests, keyboard paths, roles, data states, and representative renders pass |
DataTable, FormField,
Dialog, EmptyState, StatusPill), and Tailwind theme tokens.doctrine/design-doctrine.md — the anti-slop charter; state the typeface and palette before building any screen.doctrine/references/ai-slop-banned-fonts.md — banned primary typefaces; choose a deliberate face from doctrine/references/font-groups-and-usage.md (04 Technical / Data / Code: IBM Plex Sans + JetBrains/IBM Plex Mono suits dashboard/technical SaaS).doctrine/references/pairing-principles.md and doctrine/references/type-scale-and-spacing.md — pairing, type scale, and spacing rhythm for the shell, tables, and forms.interaction-design-patterns, motion-design, design-audit, practical-ui-design, visual-product-slop-audit. (The former skills-web-dev siblings react-development, tailwind-css, responsive-design, form-ux-design, premium-ui-ux-design did not migrate; their visual concerns are covered by the doctrine references above.)references/interface-consistency.md when a new module risks drifting from the established UI language.references/auth-and-tenant-visual-standard.md for the canonical glass auth composition,
surface-aware logo rule, responsive states, and managed visual-asset administration.ui.shadcn.com), TanStack Table (tanstack.com/table), Atomic Design (atomicdesign.bradfrost.com), React Hook Form (react-hook-form.com), Zod (zod.dev).sections/01-overview.md and onwards.examples/app-shell-spec-worked.md — a worked, end-to-end SaaS app-shell spec (Ledger Relay, a payment-reconciliation tool): shell layout (nav rail + top bar), navigation IA, a dashboard view, a data-table view, key component states, design tokens/spacing, and responsive behaviour across breakpoints.examples/managed-auth-surface-worked.md — a worked auth journey and Super Admin visual-asset
manager applying the shared blur, logo, upload, ordering, accessibility, and fallback rules.This skill prescribes the component architecture and interaction patterns for a modern SaaS web UI. The house stack is Next.js App Router + React 19 + TypeScript + Tailwind with Shadcn/ui primitives and TanStack Query/Table/Form where appropriate. Every section below is a reusable primitive or a layout pattern; build once, compose everywhere.
Cardinal rule: every data surface has four states — loading, empty, error, success — wired up before real data arrives. Screens without all four leak into production as broken pages.
Three regions: sidebar (primary nav), topbar (tenant switcher, search, user menu), content. The shell is a route group layout.
// app/(app)/layout.tsx
import { Sidebar } from '@/components/shell/Sidebar';
import { Topbar } from '@/components/shell/Topbar';
export default function AppLayout({ children }: { children: React.ReactNode }) {
return (
<div className="grid min-h-screen grid-cols-[auto_1fr] bg-slate-50 dark:bg-slate-950">
<Sidebar />
<div className="flex min-w-0 flex-col">
<Topbar />
<main className="flex-1 overflow-x-hidden p-6">{children}</main>
</div>
</div>
);
}
The sidebar controls its own width with data-collapsed state persisted to localStorage. Never reach into the shell from a page — pages only fill main.
Sidebar: collapsible, per-section groups, active-route highlight, hover-expand on collapsed state. Mobile: off-canvas drawer behind a hamburger; closes on route change.
<Link
href={item.href}
aria-current={active ? 'page' : undefined}
className={cn(
'flex items-center gap-3 rounded-md px-3 py-2 text-sm',
'hover:bg-slate-100 dark:hover:bg-slate-800',
active && 'bg-slate-200 font-medium dark:bg-slate-700',
)}
>
<item.icon className="h-4 w-4 shrink-0" /> <span className="truncate">{item.label}</span>
</Link>
Breadcrumbs render from the matched route segments — never hand-coded per page. Use usePathname() + a routeTitles map.
12-column grid on lg:, stacking on sm:. Hero KPI strip (3–4 cards), chart area (8 cols), activity feed (4 cols), recent items table full-width below.
<div className="grid grid-cols-1 gap-4 lg:grid-cols-12">
<KpiCard label="MRR" value="$42.3k" trend="+8.2%" className="lg:col-span-3" />
<KpiCard label="Active users" value="1,284" trend="+3.1%" className="lg:col-span-3" />
<KpiCard label="Churn" value="1.9%" trend="-0.4%" className="lg:col-span-3" />
<KpiCard label="NRR" value="112%" trend="+2%" className="lg:col-span-3" />
<RevenueChart className="lg:col-span-8" />
<ActivityFeed className="lg:col-span-4" />
<RecentOrders className="lg:col-span-12" />
</div>
KPI cards show loading as shimmer blocks of the same height — never collapse vertical rhythm.
One DataTable<T> primitive. Column definitions live in the feature folder. Server-side pagination, sorting, filtering — client-side only when the dataset is bounded (<500 rows).
const columns: ColumnDef<Order>[] = [
{ accessorKey: 'number', header: 'Order' },
{ accessorKey: 'customer', header: 'Customer' },
{ accessorKey: 'total', header: 'Total',
cell: ({ row }) => formatCurrency(row.original.total, row.original.currency) },
{ id: 'actions', cell: ({ row }) => <RowActions order={row.original} /> },
];
const table = useReactTable({
data, columns,
pageCount, state: { pagination, sorting, columnFilters },
manualPagination: true, manualSorting: true, manualFiltering: true,
onPaginationChange: setPagination, onSortingChange: setSorting,
getCoreRowModel: getCoreRowModel(),
});
Row actions open a dropdown anchored to the row, never a global menu. Use stickyHeader on tables taller than a viewport.
Every form is a Zod schema + RHF hook + FormField primitives. Submit handlers are async and return a typed result — never throw into the void.
const schema = z.object({
name: z.string().min(2, 'Too short').max(60),
email: z.string().email(),
role: z.enum(['admin', 'editor', 'viewer']),
});
type Values = z.infer<typeof schema>;
export function InviteUserForm({ onSuccess }: { onSuccess: () => void }) {
const form = useForm<Values>({ resolver: zodResolver(schema) });
const mutation = useMutation({ mutationFn: inviteUser });
return (
<form onSubmit={form.handleSubmit(async (v) => {
await mutation.mutateAsync(v);
onSuccess();
})} className="space-y-4">
<FormField control={form.control} name="name" label="Full name" />
<FormField control={form.control} name="email" label="Email" type="email" />
<FormSelect control={form.control} name="role" label="Role"
options={[['admin','Admin'],['editor','Editor'],['viewer','Viewer']]} />
<Button type="submit" disabled={mutation.isPending}>
{mutation.isPending ? 'Sending…' : 'Send invite'}
</Button>
</form>
);
}
FormField owns the label, error, description, and the input. For field-level patterns across web + mobile, apply interaction-design-patterns (Deferred Choices, Good Defaults).
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.
<ConfirmDialog
open={open} onOpenChange={setOpen}
title="Delete workspace" description="This cannot be undone."
confirmLabel="Delete" destructive
onConfirm={() => deleteWorkspace(id)}
/>
Dialog content is always in a Radix Dialog — focus trap and escape-to-close are not negotiable.
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.
<Suspense fallback={<DashboardSkeleton />}>
<DashboardContent />
</Suspense>
Optimistic updates: React Query onMutate sets the new value; onError rolls back; onSettled invalidates.
Every route has an error boundary. Global handler sends to Sentry; the UI offers "Try again" and a support channel link.
// app/(app)/orders/error.tsx
'use client';
export default function Error({ error, reset }: { error: Error; reset: () => void }) {
useEffect(() => { Sentry.captureException(error); }, [error]);
return (
<EmptyState
icon={AlertTriangle}
title="Something went wrong"
description={error.message}
primary={{ label: 'Try again', onClick: reset }}
secondary={{ label: 'Contact support', href: '/support' }}
/>
);
}
Never show a raw stack in production. Log the digest to give support a lookup handle.
Sonner for SaaS — one per result, stacked top-right. Success toasts auto-dismiss in 4 s; error toasts require dismissal.
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.
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.
// app/(auth)/login/page.tsx
export default function Login() {
return (
<div className="mx-auto mt-24 max-w-sm space-y-6">
<BrandMark />
<h1 className="text-2xl font-semibold">Sign in</h1>
<LoginForm />
<p className="text-sm text-slate-500">
New here? <Link className="underline" href="/register">Create an account</Link>
</p>
</div>
);
}
Post-login redirect: honour ?redirect= if same-origin; fall back to /. 2FA input is a 6-digit <OTPInput> — no free-form text field.
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.
<Combobox
value={current.slug}
onChange={(slug) => 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.)
Class strategy (dark:) with a tri-state switch (system / light / dark). Persist to localStorage; set on <html> before first paint to avoid flicker.
// app/layout.tsx — inline script before hydration
<script dangerouslySetInnerHTML={{ __html: `
try {
const t = localStorage.getItem('theme');
if (t === 'dark' || (!t && matchMedia('(prefers-color-scheme: dark)').matches))
document.documentElement.classList.add('dark');
} catch {}
` }} />
Theme tokens live as CSS variables (--bg, --fg, --muted, --accent) so charts + third-party widgets can read them. Avoid hard-coded Tailwind greys in components — use semantic tokens.
Drag-and-drop zone with keyboard fallback (button + hidden <input type="file">). Client-side size + type validation before upload begins. Upload via a signed-URL path — never stream through the app server.
const { getRootProps, getInputProps, isDragActive } = useDropzone({
accept: { 'image/*': ['.png', '.jpg', '.jpeg', '.webp'] },
maxSize: 10 * 1024 * 1024,
onDrop: (files) => startUpload(files),
});
return (
<div {...getRootProps()} aria-label="Upload file"
className={cn('rounded-md border-2 border-dashed p-8 text-center',
isDragActive ? 'border-indigo-500 bg-indigo-50' : 'border-slate-300')}>
<input {...getInputProps()} />
<p>Drop files here or <span className="underline">browse</span></p>
</div>
);
Progress bars read from the XMLHttpRequest.upload progress event or from the signed-URL provider's SDK. Every upload is cancellable with AbortController.
Empty lists, empty dashboards, first-run onboarding. Three components: icon, short headline, concrete next action. Never just "No data."
<EmptyState
icon={Inbox}
title="No invoices yet"
description="When you bill a customer, invoices will appear here."
primary={{ label: 'Create invoice', href: '/invoices/new' }}
secondary={{ label: 'Read the billing guide', href: '/docs/billing' }}
/>
First-use onboarding: a checklist card on the dashboard; tick items as they complete; dismiss after all done with a "show me tips" toggle. See interaction-design-patterns (Instant Gratification, Safe Exploration) for the empty-state and first-run rules.
Non-negotiables at merge time:
:focus-visible outlines on all interactive elements. Tailwind's focus-visible:ring-2 focus-visible:ring-offset-2 focus-visible:ring-indigo-500 is the house token.aria-label; mark live regions (aria-live="polite") for toast containers; use aria-current="page" for active nav.axe in CI.prefers-reduced-motion. motion-safe: / motion-reduce: Tailwind variants.aria-invalid and aria-describedby.Responsive sweep: test at 360 px (mobile small), 768 px (tablet), 1280 px (laptop), 1920 px (desktop). No horizontal overflow, no content clipped behind fixed headers.
The repository's PHP seeder template uses Bootstrap 5 + Tabler + SweetAlert2 + DataTables + Flatpickr. The architecture, permissions, AJAX, photo, and responsive patterns for that stack are in the sections/ directory. Load them progressively:
The patterns in §§1–15 above apply to the React/Next.js stack; the sections/ deep-dives apply to the PHP stack. Pick the one your codebase uses — do not mix.