# Bootstrap Guide — Humain Foundation UI Scaffolding, framework setup, starter templates for `@humain/ui`. --- ## Framework Setup ### Vite + React (Recommended) ```bash # 1. Scaffold npm create vite@latest my-app -- --template react-ts cd my-app # 2. Install library npm install @humain/ui lucide-react # 3. Replace index.css import in main.tsx ``` **`src/main.tsx`** ```tsx import { StrictMode } from 'react'; import { createRoot } from 'react-dom/client'; import '@humain/ui/styles.css'; import { ThemeProvider } from '@humain/ui'; import App from './App.tsx'; createRoot(document.getElementById('root')!).render( , ); ``` --- ### Next.js App Router ```bash # 1. Scaffold npx create-next-app@latest my-app --typescript --tailwind --app cd my-app # 2. Install library npm install @humain/ui lucide-react ``` **`app/globals.css`** — replace entire file: ```css @import '@humain/ui/styles.css'; ``` **`app/layout.tsx`** ```tsx import type { Metadata } from 'next'; import { ThemeProvider, ThemeScript } from '@humain/ui'; import './globals.css'; export const metadata: Metadata = { title: 'My App', }; export default function RootLayout({ children, }: { children: React.ReactNode; }) { return ( {/* Prevents flash of wrong theme on SSR */} {children} ); } ``` > `suppressHydrationWarning` on `` required — `ThemeScript` adds class before hydration. > If you customize `defaultTheme` or `storageKey`, pass the same values to `ThemeScript` and `ThemeProvider`. --- ### Remix ```bash # 1. Scaffold (existing Remix project) npm install @humain/ui lucide-react ``` **`app/root.tsx`** — add styles import, wrap with providers: ```tsx import { Links, Meta, Outlet, Scripts, ScrollRestoration } from '@remix-run/react'; import { ThemeProvider, ThemeScript } from '@humain/ui'; import stylesheet from '@humain/ui/styles.css?url'; export const links = () => [{ rel: 'stylesheet', href: stylesheet }]; export default function App() { return ( ); } ``` --- ## Recommended Project Structure ``` src/ ├── app/ # Routes / pages │ ├── layout.tsx # Root layout with ThemeProvider │ ├── (auth)/ # Auth routes composed from PageBackground + form primitives │ └── (app)/ # Authenticated app (AppShell + AppSidebar layout) ├── components/ # App-specific components only ├── lib/ # Utilities, API clients └── hooks/ # Custom hooks ``` **Do NOT create `components/ui/`** — primitives come from library. Only add app-specific components. --- ## Starter Templates ### Full App with Sidebar Uses `AppShell` + `AppSidebar` compound API with `SidebarProvider` wrapping. ```tsx import { AppShell, AppShellCard, AppSidebar, SidebarProvider, } from '@humain/ui'; import { LayoutDashboard, Users, Settings, MessageCircle, } from 'lucide-react'; export default function AppLayout({ children }: { children: React.ReactNode }) { return ( Dashboard
{children}
 ); } function AppSidebarNav() { return ( My App} collapsible="icon"> } label="Dashboard" href="/dashboard" isActive /> } label="Users" href="/users" /> } label="Chat" href="/chat" badge="New" /> } label="Settings" href="/settings" /> ); } ``` --- ### Auth Routes Auth and standalone routes use `bg-app` as the default page canvas; layer `PageBackground` or cards on top, and use `bg-background` only for an intentionally flat solid page. ```tsx import { Button, Card, Input, PageBackground } from '@humain/ui'; import { useNavigate } from 'react-router-dom'; // or Next.js router // Login export function LoginRoute() { const navigate = useNavigate(); return (
Sign in Continue to your workspace.
{ event.preventDefault(); // call your auth API }} >
); } // Signup export function SignupRoute() { return (
Create account Start with your work email.
); } ``` --- ### Dashboard with Metrics ```tsx import { AppShellCard, Button, DataTable, MetricCard, type ColumnDef, } from '@humain/ui'; interface User { id: string; name: string; email: string; role: string; } const columns: ColumnDef[] = [ { accessorKey: 'name', header: 'Name' }, { accessorKey: 'email', header: 'Email' }, { accessorKey: 'role', header: 'Role' }, ]; const users: User[] = [ { id: '1', name: 'Jane Smith', email: 'jane@example.com', role: 'Admin' }, { id: '2', name: 'John Doe', email: 'john@example.com', role: 'Member' }, ]; export function DashboardPage() { return (
Dashboard Overview of your workspace
`$${n.toLocaleString()}`} /> `${n}%`} />
Recent users Users added in the last 30 days row.id} enableSorting enablePagination pageSize={10} />
); } ``` --- ### AI Chat Interface ```tsx import { useState } from 'react'; import { AIContainer, AIEmptyState, AIPromptSuggestion, AIMessage, } from '@humain/ui'; import type { ChatMessage } from '@humain/ui'; import { Sparkles } from 'lucide-react'; export function ChatPage() { const [messages, setMessages] = useState([]); const handleSend = (text: string) => { if (!text.trim()) return; const userMessage: ChatMessage = { id: crypto.randomUUID(), role: 'user', content: text, }; setMessages((prev) => [...prev, userMessage]); // Simulate AI response setTimeout(() => { const aiMessage: ChatMessage = { id: crypto.randomUUID(), role: 'assistant', content: `You said: ${text}`, }; setMessages((prev) => [...prev, aiMessage]); }, 800); }; const suggestions = [ 'Summarize this document', 'Generate a report', 'Help me write an email', ]; return (
} title="How can I help you?" description="Powered by HumainOne" >
{suggestions.map((s) => ( handleSend(s)} showArrow > {s} ))}
} />
); } ``` --- ### Form Page with Validation Smart field props — pass `label` and `error` to `Input`/`Select`/`Checkbox`, auto-wraps in `Field`. ```tsx import { useState } from 'react'; import { Card, Input, Select, Checkbox, Button, } from '@humain/ui'; interface FormValues { name: string; email: string; role: string; agreeToTerms: boolean; } interface FormErrors { name?: string; email?: string; role?: string; agreeToTerms?: string; } export function CreateUserPage() { const [values, setValues] = useState({ name: '', email: '', role: '', agreeToTerms: false, }); const [errors, setErrors] = useState({}); const [loading, setLoading] = useState(false); const validate = (): FormErrors => { const errs: FormErrors = {}; if (!values.name.trim()) errs.name = 'Name is required'; if (!values.email.includes('@')) errs.email = 'Valid email required'; if (!values.role) errs.role = 'Please select a role'; if (!values.agreeToTerms) errs.agreeToTerms = 'You must accept the terms'; return errs; }; const handleSubmit = async (e: React.FormEvent) => { e.preventDefault(); const errs = validate(); if (Object.keys(errs).length > 0) { setErrors(errs); return; } setLoading(true); // call API... setLoading(false); }; return (
Create Account Fill in the details below to get started.
{/* Smart field props: label + error auto-creates Field wrapper */} setValues((v) => ({ ...v, name: e.target.value })) } error={errors.name} /> setValues((v) => ({ ...v, email: e.target.value })) } error={errors.email} />