Once UI Handbook
Beginner Guides
What is Once UI?
Install & config
Page skeleton
Your first page
Build And Launch
How to launch a portfolio site that actually gets you hired
How to build a documentation site with MDX and Next.js
How to ship a landing page and dashboard with authentication in Next.js
How to launch a social app with Next.js and Supabase
Vibe Coding
Introduction to vibe coding
Set up your local dev environment
Essential tools for vibe coding
Build your first Once UI app
Common Patterns
Hero section
Static panel
Form layout
Highlighted card
Responsive stacking
Decoration layers
Dialog & modal
Toast & feedback
Tables & lists
Loading states
App shell navigation
Dashboard & charts
Chat & messaging
Auth & verification
Settings & split panels
Data filters & toolbar
Command palette
Pricing & plans
Accordion & FAQ
Media & uploads
Empty & error states
SEO, Open Graph, and structured data
Documentation code blocks with live preview
Carousels, galleries, and before/after comparisons
Date pickers and scheduling
Context menus and dropdown actions
Tags, chips, and multi-value inputs
Roadmap & kanban
Form inputs & controls
Progress, status & badges
Scrolling & feeds
Profile, avatars & identity
Social proof & logo clouds
Masonry & media grids
Table pagination, search & bulk selection
Banners & announcements
Footer layouts
Onboarding & first run
Waitlist & coming soon
Design Tips
Color & surfaces
Harness overview
Row, Column & Grid
Spacing & rhythm
Icons & buttons
Reveal & motion
Theme tokens, FOUC-free init, and runtime style controls
Tooltips and hover cards
Block updates
Block updates changelog
Agent Resources
Column, not Flex
Semantics over CSS
Typography scale
Common gotchas
Block anchors
Validate generated code
Pro block registry
Match task bundles
TrademarkTrademark
Ctrl k
Search...
Sign up
Once UI Handbook
Beginner Guides
What is Once UI?
Install & config
Page skeleton
Your first page
Build And Launch
How to launch a portfolio site that actually gets you hired
How to build a documentation site with MDX and Next.js
How to ship a landing page and dashboard with authentication in Next.js
How to launch a social app with Next.js and Supabase
Vibe Coding
Introduction to vibe coding
Set up your local dev environment
Essential tools for vibe coding
Build your first Once UI app
Common Patterns
Hero section
Static panel
Form layout
Highlighted card
Responsive stacking
Decoration layers
Dialog & modal
Toast & feedback
Tables & lists
Loading states
App shell navigation
Dashboard & charts
Chat & messaging
Auth & verification
Settings & split panels
Data filters & toolbar
Command palette
Pricing & plans
Accordion & FAQ
Media & uploads
Empty & error states
SEO, Open Graph, and structured data
Documentation code blocks with live preview
Carousels, galleries, and before/after comparisons
Date pickers and scheduling
Context menus and dropdown actions
Tags, chips, and multi-value inputs
Roadmap & kanban
Form inputs & controls
Progress, status & badges
Scrolling & feeds
Profile, avatars & identity
Social proof & logo clouds
Masonry & media grids
Table pagination, search & bulk selection
Banners & announcements
Footer layouts
Onboarding & first run
Waitlist & coming soon
Design Tips
Color & surfaces
Harness overview
Row, Column & Grid
Spacing & rhythm
Icons & buttons
Reveal & motion
Theme tokens, FOUC-free init, and runtime style controls
Tooltips and hover cards
Block updates
Block updates changelog
Agent Resources
Column, not Flex
Semantics over CSS
Typography scale
Common gotchas
Block anchors
Validate generated code
Pro block registry
Match task bundles
TrademarkTrademark
Once UIDocumentationBlog
© Once UI. All rights reserved.
Built with Aveiro
Design Tips

Harness overview

Agent codegen workflow — bootstrap, task routing, and validation.
Updated 19d ago
Color & surfaces
Row, Column & Grid
8 min · For agents
Load rules.compact.md + a task bundle (~8KB), not full doc pages. Generate, then validate mechanically.

Bootstrap (always)

Before any UI codegen task, load these two files: 
@once-ui-system/core/ai/rules.compact.md    (~2KB)
@once-ui-system/core/ai/catalog.json        (component index)
Or from the docs site:
  • rules.compact.md
  • catalog.json
Entry point listing all artifacts: manifest.json

Route by intent

Match the user's request to a task bundle via tasks/index.json:
Intent
Task bundle
Marketing hero`tasks/marketing-hero.json`
Pricing page`tasks/pricing.json`
Settings panel`tasks/settings.json`
Dashboard`tasks/dashboard.json`
Chat interface`tasks/chat.json`
Auth flow`tasks/auth.json`
Roadmap`tasks/roadmap.json`
Each bundle lists: required components, recipes, gotchas, quality targets, and Pro block references.

Progressive loading

Don't load everything. Per task:
  • rules.compact.md — layout, surfaces, typography, motion rules
  • Task bundle — component list + gotcha keys
  • Component slices — ai/components/{Name}.json on demand
  • Recipes — recipes.md sections referenced by the task
  • Gotchas — gotchas.json entries for components you'll use
  • Pro blocks — examples/blocks/manifest.json for production fidelity; link a specific example via block anchors, or install source via the Pro block registry when the user is subscribed
Target: under ~10KB context per task, not full doc pages.

Workflow

1. Load rules.compact.md
2. Resolve intent → pick task bundle
3. Fetch component slices listed in the bundle
4. Read gold example / Pro block for structure
5. Generate TSX
6. Validate: pnpm validate-ai-code path/to/file.tsx

What validate-ai-code catches

  • Flex direction= → should be Row/Column
  • fillWidth fillHeight → should be fill
  • Hex/rgb colors → should be token props
  • Invented icon names → must match IconName in spec
  • Default props that should be omitted

Context budget

Load
Size
When
`rules.compact.md`~2KBAlways
`catalog.json`~4KBComponent selection
Task bundle~1KBIntent matched
Component slice~0.5KB eachOn demand
Full doc page10–50KB**Avoid for codegen**

Humans vs agents

Need
Use
"How do I think about layout?"Once UI Learn (this site)
"What props does Grid accept?"docs.once-ui.com reference
"Build me a pricing page"Harness task bundles

Related

→ What is Once UI? → Column, not Flex → Block anchors → Pro block registry → Block updates changelog → Full harness docs: docs.once-ui.com/once-ui/ai-coding