In 2026, your choice of code editor is your biggest leverage. While VS Code is the classic choice, Vibe Coding thrives in AI-first editors.Windsurf (Recommended): The first "Agentic IDE" that features the Cascade agent. Perfect for deep Once UI integration and much cheaper than Cursor.Cursor: A highly popular AI-native fork of VS Code. Excellent for codebase-wide indexing.
Create a new project
Create a project on GitHub. We recommend starting with the Once UI Starter which gives you access to 100+ Once UI components and a minimalistic Next.js setup. You can start with our more robust Magic templates that provide deployment-ready frontends.
Clone the project
On Github, click the "Code" button and copy the URL under the HTTPS tab. Then open the Fork app and clone the project to your local machine at File > Clone. Set the destination to your local machine, e.g. C:\Users\Username\git\your-project.Alternatively, you can clone the project using the terminal:
All Once UI repositories come with a package.json file that lists all dependencies. You can install them using the following command:
npm install
This creates a node_modules folder with all necessary dependencies. You need to run this command every time you clone a new project or change dependencies in the package.json file.It will also generate a package-lock.json file that locks the dependencies to specific versions. This ensures that everyone working on the project has the same dependencies installed.
Run your project
You can run your project on your local machine using the following command in terminal. You can open a terminal inside Windsurf or Cursor under the Terminal > New Terminal option, or use Command Prompt (Windows) or Terminal (macOS) on your machine.
npm run dev
This will start the development server and open your project in the default browser. By default, it will be accessible at http://localhost:3000.
Configure the MCP server
To vibe code effectively, your AI agent needs to move from "guessing" to "knowing." In 2026, this is achieved by providing the agent with direct access to the source of truth through a standardized protocol.
Once UI
Without proper setup, AI will default to generic, noisy patterns (Tailwind strings). With this setup, it becomes an expert Design Engineer that understands your specific architectural constraints.
Think of the Model Context Protocol (MCP) as the "USB port" for your AI. By connecting the Once UI MCP server, you allow Windsurf or Cursor to query live documentation and component specs without hallucination.
Navigate to File > Preferences > Windsurf settings > MCP Servers and add a new custom server:
Restart your IDE and run the following code in the chat:
This syncs the Once UI documentation with your local agent environment. To invoke the context, end your prompt with use context7.
Set up the Rules Protocol
This is the most critical step to prevent AI drift. You must tell the agent exactly how to behave within the Once UI ecosystem. Create a .windsurfrules (or .cursorrules) file in your project root.
This ruleset will guide the AI agent to build with our best practices when writing Once UI code. You can extend it with your own rules and preferences.
Make changes
Now everything is set up for you to prompt AI in the chat and get reliable code suggestions.
A good prompt describes what you want with as many context as you can provide. Use Control + L in Windsurf to add your current selection as a reference, or attach files you want to change.
You can also use AI to get a better understanding of the project. Just ask something like "How is this project structured and how can I change [...]?".
Bad prompts:
"Build an amazing landing page"
"Make this page look better"
"Add authentication to my project"
Good prompts:
"Create a landing page based on the attached design with each section as a separate component"
"Improve the spacings, colors and hierarchy of this page with recommendations for microcopy"
"Create a plan for integrating Supabase Auth into my project"
Committing changes
Once you are done with your changes, you can commit them to your repository. Select the changes in Fork, write a commit message and hit "Commit".
Alternatively, you can use the command line to commit your changes:
Deploy your site
Once you are done with your changes, you can deploy your site to a hosting platform like Vercel. Create a free account and connect your GitHub repository to Vercel. It will attempt to deploy your site automatically when you push to the main branch.
# Once UI Development Rules
## Core Philosophy
- You are a Design Engineer. We use Once UI for its semantic layout engine and design tokens.
- Priority 1: Semantic clarity. Use high-level atoms to build layouts and set styles (<Column>, <Row>, <Grid>, <Heading>, <Text>).
- Priority 2: Token consistency. Never use hex codes; Use Once UI props whenever possible. If you need additional customization, use inline styles.
- Priotity 3: Always scan for possible components. Once UI provides many generic, flexible and customizable components. The ones you need to create are mostly product-specific ones. Create them in a single folder with a barrel export in an index.ts file. The components should be built from Once UI primitives. You can use inline styles sparingly if the Flex props don't cover a ceretain use case. If excessive style overrides are needed, or the component needs to utilize selectors for states, use a standalone SCSS module. Components should almost always be fluid by default, with width either fitting the content or spanning 100%. Whenever possible, spread the <Row>, <Column> or <Grid> props on the component wrapper so style and size can be overriden from the outside, making them more flexible.
- Priority 4: No "Utility Noise". Avoid Tailwind classes and tools that are not part of the project already.
## Component & Layout Rules
- **Structure**: Never use <div>. Use <Column> for vertical stacking, <Row> for horizontal, and <Grid> for equally sized and distributed elements. The `horizontal` and `vertical` props for the <Row> and <Column> simplify flex layouts. They apply utility classes in the background and keep the main axis consistent, which means that `horizontal` will always set the content to "start", "center", "end", "between" or "around" regardless of direction. Same goes for `vertical`. Use the `center` shorthand to center children on both axis. `position="relative"` is the default for <Row>, <Column> and <Grid>, only add `position` to override it. Use `maxWidth` with "xs" -> "xl" values for page content and layout elements like header, or a number as REM for fixed max-widths. the `maxWidth` and `maxHeight` props automatically add `fillWidth` and `fillHeight` props for fluidity.
- **Spacing**: Use the `gap`, `padding`, `margin` props or shorthands like `paddingX` and `marginTop`. Value can be `SpacingToken` (e.g., "16", "24", "32") or a number that equals to REM. Use `gap="-1"` to collapse stacked borders. Use responsive paddings sparingly, when makes sense. For page paddings, `paddingX="l"` makes sense. For smaller spacings, static ones ("4", "8", "16"...) are usually fine.
- **Sizing**: Use the `fillWidth` and `fillHeight` props instead of `w-full` or `h-full`. Use `fill` as a shorthand for `fillWidth` and `fillHeight`. They automatically add `minWidth="0"` and `minHeight="0"` if not specified.
- **Text**: Use the <Heading> and <Text> component with the `variant` prop (e.g., "display-strong-s", "body-default-m"). A nested <Text> will inherit the parent variant. You can override the weight or size with the `weight` (default or strong) and `size` ("xs" -> "xl") props. Align text with the `align` property on `Text`, `Heading`, `Row` or `Column` (it adds the text-align property, NOT flex alignment!)
- **Colors**: Use the `background` and `onBackground` and `solid` and `onSolid` prop pairs for background + text (e.g., `background="neutral-medium" onBackground="neutral-weak"`) to ensure dark-mode compatibility. The `background` is for general purpose, low-contrast surfaces, and the solid is for high-contrast, usually interactive elements such as backgrounds. The `background` prop has a few additional values: "page", "surface" and "overlay". They behave differently based on theme. Usually the main site background is "page", with large layout elements, such as headers or sidebars being "surface" (but they can also be "page" depending on design aeshetics).
- **Components**: Most components are wrapped in a <Column> or <Row> with Flex props spread on the outer element, making it easy to override component defaults such as paddings, margins or borders.
- **Defaults**: There are several shorthands for styling with the <Row>, <Column> and <Grid>. For example, `border="neutral-alpha-medium"` will apply a 1px solid border if `borderWidth` and `borderStyle` is not specificed. Similarly, `position="sticky"` will apply `top="0"` if not specified otherwise. It's worth checking components, especially the `Flex` and `Grid` to understand which props are necessary and which aren't.
- **Responsive design**: Use the `s`, `m` and `l` breakpoint objects on the <Row>, <Column> and <Grid> components to override layouts and styles at breakpoints. Not all props are supported, but they support inline styles inside the breakpoint object (`<Row s={{style: {...}}}`). Hide and show elements based on breakpoint with the `hide` and `m={{hide: false}}` props. Show or hide elements with the `dark` and `light` props. They are especially important when using the <Logo> components, because the svg doesn't change theme automatically.
## Global Preferences
- Prefer **Functional Components** and **TypeScript**.
- Always ensure components are accessible (ARIA labels, semantic tags). Use `tooltip` for <IconButton> when the action is not necessary or using several buttons in a group.
## Design & Style
- Once UI has a unique, minimal aeshetics. It can vary based on project and implementation, but it always puts an emphasis on scale, contrast, clarity and proportions.
- Build hierarchy by grouping elements and carefully setting appropriate spacings: the amount of the spacing should be relative to the size of the elements.
- Once UI is a dark-mode first system that stands for extremely high quality. Think of Vercel, Linear and Raycast.
- The general style of Once UI is grounded, simple, performant. Motion is usually provided by atomic components for interactions and states rather than distruptive, layout-shifting, unnecessary animations.
## Recommendations
- The recommended size for <Button> and <IconButton> is `m`, only diverge when the UI is either spacious or very compact.
- Only use responsive spacings (gaps, margins and paddings) when distances need collapse on smaller screens. Most of the time, for general UI elements (cards, groups, etc.), static spacings are enough. Responsive spacings are reserved mostly for large layout elements, like the content area of the page, where 40px looks good on desktop but feels enormous on mobile.
- Always reach the documentation with the "use context7" protocol to find the right component or prop.
