# Once UI Handbook
> Master the Once UI design system with comprehensive beginner tutorials, agent best practices, and expert design tips. Build cohesive, accessible interfaces faster with our official documentation.

## Beginner Guides
- [What is Once UI?](/beginner-guides/what-is-once-ui.md): Philosophy and core ideas — semantics over CSS, tokens, and agent-first design.
- [Install & config](/beginner-guides/install-and-config.md): Install @once-ui-system/core and wrap your app in providers.
- [Page skeleton](/beginner-guides/page-skeleton.md): The reusable page structure every Once UI page starts from.
- [Your first page](/beginner-guides/your-first-page.md): Build a complete page with the Once UI skeleton in 10 minutes.

## Build And Launch
- [How to launch a portfolio site that actually gets you hired](/build-and-launch/launch-a-portfolio-site.md): Build and deploy a developer portfolio with Next.js — without spending weeks on design decisions.
- [How to build a documentation site with MDX and Next.js](/build-and-launch/build-a-documentation-site.md): Set up a fast, searchable documentation site with automatic navigation, MDX content, and zero configuration overhead.
- [How to ship a landing page and dashboard with authentication in Next.js](/build-and-launch/ship-a-landing-page-with-auth.md): Build a production-ready landing page with sign-up, login, and a dashboard — without stitching together five different libraries.
- [How to launch a social app with Next.js and Supabase](/build-and-launch/launch-a-social-app.md): Ship a full-stack social platform with posts, comments, feeds, notifications, and user profiles — without building everything from scratch.

## Vibe Coding
- [Introduction to vibe coding](/vibe-coding/introduction-to-vibe-coding.md): Defining the shift from writing syntax to orchestrating intent in 2026.
- [Set up your local dev environment](/vibe-coding/local-environment-setup.md): Install prerequisites and configure your local environment for AI-orchestrated development.
- [Essential tools for vibe coding](/vibe-coding/tools-for-vibe-coding.md): Configure your IDE and local environment to enable seamless AI-orchestrated development.
- [Build your first Once UI app](/vibe-coding/your-first-app.md): Create your first Once UI app.

## Common Patterns
- [Hero section](/common-patterns/hero-section.md): Hero composition — eyebrow, headline, actions, and optional ambient glow.
- [Static panel](/common-patterns/static-panel.md): The surface recipe for non-interactive panels — stats, settings, feature boxes.
- [Form layout](/common-patterns/form-layout.md): Stack fields, group sections, and place actions in Once UI forms.
- [Highlighted card](/common-patterns/highlighted-card.md): Interactive Card with brand glow for featured pricing tiers and CTAs.
- [Responsive stacking](/common-patterns/responsive-stacking.md): Breakpoint props for mobile stacking — no media queries needed.
- [Decoration layers](/common-patterns/decoration-layers.md): Absolute Background layers, glow budget, and placement rules.
- [Dialog & modal](/common-patterns/dialog-modal.md): Controlled dialogs with title, footer actions, and stacked multi-step flows.
- [Toast & feedback](/common-patterns/toast-and-feedback.md): Global toast notifications via ToastProvider and useToast — plus when to use inline Feedback.
- [Tables & lists](/common-patterns/tables-and-lists.md): Structured data with Table, simpler stacks with List — plus empty and loading states.
- [Loading states](/common-patterns/loading-states.md): Skeleton placeholders for content areas, spinners for actions — keep layout stable while data loads.
- [App shell navigation](/common-patterns/app-shell-navigation.md): Sticky headers, MegaMenu, Kbar command palette, and Pro block app chrome.
- [Dashboard & charts](/common-patterns/dashboard-and-charts.md): KPI stat rows, CountFx viewport latches, sparkline charts, and activity tables.
- [Chat & messaging](/common-patterns/chat-and-messaging.md): Multi-pane chat layouts with channel sidebars, feeds, composers, and streaming replies.
- [Auth & verification](/common-patterns/auth-and-verification.md): Split sign-up layouts, social auth, PasswordInput, and OTP verification in stacked dialogs.
- [Settings & split panels](/common-patterns/settings-and-split-panels.md): SplitView settings layout with section sidebar, form panels, toggles, and danger zones.
- [Data filters & toolbar](/common-patterns/data-filters-toolbar.md): Compose table toolbars with search, SegmentedControl view switchers, date ranges, and filter chips.
- [Command palette](/common-patterns/command-palette.md): Wire the Kbar module for searchable navigation, actions, and keyboard shortcuts in your app shell.
- [Pricing & plans](/common-patterns/pricing-and-plans.md): Three-tier pricing grids, billing toggles, comparison tables, and FAQ accordions from the pricing task bundle.
- [Accordion & FAQ](/common-patterns/accordion-and-faq.md): AccordionGroup for FAQ sections, split-column layouts, autoCollapse behavior, and standalone Accordion usage.
- [Media & uploads](/common-patterns/media-and-uploads.md): MediaUpload drag-and-drop, compression, preview, and profile photo patterns in settings forms.
- [Empty & error states](/common-patterns/empty-and-error-states.md): Compose empty, error, and filtered-empty states with Icon, Heading, Text, and Button — distinct from loading skeletons.
- [SEO, Open Graph, and structured data](/common-patterns/seo-and-metadata.md): generateMetadata, Schema JSON-LD, and server-side OG fetch — wire once in your layout.
- [Documentation code blocks with live preview](/common-patterns/code-blocks-and-previews.md): CodeBlock with prismjs, multi-file tabs, diff view, and side-by-side preview.
- [Carousels, galleries, and before/after comparisons](/common-patterns/carousel-and-compare-media.md): Carousel for rotators and galleries; CompareImage for draggable A/B sliders.
- [Date pickers and scheduling](/common-patterns/date-pickers-and-scheduling.md): DateInput for single dates, DateRangePicker for ranges — calendar UI with optional time selection.
- [Context menus and dropdown actions](/common-patterns/context-menus-and-dropdowns.md): Right-click ContextMenu and click Dropdown patterns for contextual actions without cluttering the UI.
- [Tags, chips, and multi-value inputs](/common-patterns/tags-chips-and-multi-value-inputs.md): TagInput, Chip, Tag, and Checkbox patterns for filters, labels, and multi-select form fields.
- [Roadmap & kanban](/common-patterns/roadmap-and-kanban.md): Status columns, task cards, StatusIndicator dots, and the roadmap task bundle — Roadmap1 Pro block as gold reference.
- [Form inputs & controls](/common-patterns/form-inputs-and-controls.md): Select, Switch, Checkbox, RadioButton, Textarea, and NumberInput — field types beyond basic Input stacking.
- [Progress, status & badges](/common-patterns/progress-status-and-badges.md): ProgressBar for completion, StatusIndicator for state dots, Badge for counts and labels.
- [Scrolling & feeds](/common-patterns/scrolling-and-feeds.md): Scroller for horizontal chip rails, InfiniteScroll for paginated feeds, and overflow patterns without scroll traps.
- [Profile, avatars & identity](/common-patterns/profile-and-avatars.md): Avatar sizes, status indicators, profile headers, AvatarGroup stacks, and member list rows.
- [Social proof & logo clouds](/common-patterns/social-proof-and-logo-clouds.md): LogoCloud rotation, static partner grids, testimonial panels, and trust strips under heroes.
- [Masonry & media grids](/common-patterns/masonry-and-media-grids.md): MasonryGrid for variable-height galleries; Grid vs masonry decision tree and portfolio cells.
- [Table pagination, search & bulk selection](/common-patterns/table-pagination-and-selection.md): Table1 Pro block patterns — search, page size, pagination footer, and bulk action bars.
- [Banners & announcements](/common-patterns/banners-and-announcements.md): Full-width Banner strips for product news, maintenance windows, and dismissible upgrade prompts.
- [Footer layouts](/common-patterns/footer-layouts.md): Minimal bars, CTA closers, and multi-column sitemap grids — Footer1–4 Pro block patterns.
- [Onboarding & first run](/common-patterns/onboarding-and-first-run.md): Welcome dialogs, setup checklists, guided empty dashboards, and profile completion nudges.
- [Waitlist & coming soon](/common-patterns/waitlist-and-coming-soon.md): Centered hero, email capture, RevealFx entry, and subscriber trust rows from Waitlist1.

## Design Tips
- [Color & surfaces](/design-tips/color-and-surfaces.md): Color schemes, the static panel recipe, and when to use Card.
- [Harness overview](/design-tips/harness-overview.md): Agent codegen workflow — bootstrap, task routing, and validation.
- [Row, Column & Grid](/design-tips/layout-row-column-grid.md): Layout decision tree — when to use Row, Column, Flex, and Grid.
- [Spacing & rhythm](/design-tips/spacing-and-rhythm.md): Section gaps, inner gaps, and the spacing token scale.
- [Icons & buttons](/design-tips/icons-and-buttons.md): Valid icon names, prefixIcon patterns, semantic colors, and button variants.
- [Reveal & motion](/design-tips/reveal-and-motion.md): RevealFx entry animation, CountFx pairing, and the ambient decoration budget.
- [Theme tokens, FOUC-free init, and runtime style controls](/design-tips/theme-tokens-and-runtime-style.md): ThemeInit, ThemeProvider, data-* attributes, and DataThemeProvider for charts.
- [Tooltips and hover cards](/design-tips/tooltips-and-hover-cards.md): Tooltip for inline hints; HoverCard for rich previews on hover — keep discoverability without modal noise.

## Block updates
- [Block updates changelog](/block-updates/july-2026-pro-blocks.md): Every Once UI Pro block release, newest first — one running changelog instead of a page per batch.

## Agent Resources
- [Column, not Flex](/agent-resources/column-not-flex.md): Use Row and Column for static layouts — Flex only when direction changes.
- [Semantics over CSS](/agent-resources/semantics-over-css.md): Style by meaning with design tokens — not arbitrary CSS values.
- [Typography scale](/agent-resources/typography-scale.md): Display, heading, body, and label variants — and when to use each.
- [Common gotchas](/agent-resources/common-gotchas.md): Codegen mistakes from gotchas.json — layout, surfaces, motion, and component traps.
- [Block anchors](/agent-resources/block-anchors.md): Link agents to specific Pro block examples with category URL fragments.
- [Validate generated code](/agent-resources/validate-generated-code.md): Run pnpm validate-ai-code after codegen — what it catches and how to pair with gotchas.json.
- [Pro block registry](/agent-resources/pro-block-registry.md): Install Pro blocks via shadcn CLI — @once-ui registry namespace, access tokens, and when to use vs block anchors.
- [Match task bundles](/agent-resources/match-task-bundles.md): Route user intent to harness task bundles, gold examples, and Pro blocks.