Find essential principles and setup steps below. This guide serves as a recurring checklist for both new and experienced users starting a new application.
Editors note
This page is basically a summary / checklist about advanced onyx topics (layouts, grid, theming etc.) where one simple action is required from the user immediately for a new project. But the full principle is documented on a dedicated sub page (Read more link). Is there a nice way to visualize this?
Copy link to headline:Layout
Our layout components manage the application's structural complexity, including scroll behavior and navigation positioning. We highly recommend adopting these layouts to avoid manual implementation and maintain system standards.
Copy link to headline:App layout
Positioned at the root of your application, the App Layout serves as the shell for global navigation and main content. It also acts as a functional provider for system-level components like toasts and notifications.
Example implementation for App.vue for plain Vue and app/app.vue for Nuxt that includes a basic navigation bar and renders the current page :
Copy link to headline:Vue
Copy link to headline:Nuxt
For further information, available slots, customization etc., please visit the app layout documentation.
Copy link to headline:Page layout
Implement the Page Layout on every page to ensure standardized spacing and scroll handling. It provides dedicated slots for easily integrating sidebars, footers, and main content.
For recurring elements like sidebars or footers, wrap the PageLayout in a reusable component or Nuxt layout(opens in a new tab). This allows you to apply your custom layout globally to individual pages.
Refer to the page layout documentation for API details and customization options.
Copy link to headline:Grid
Another key step is configuring your application's layout grid. While we won't cover the technical details here, you can find everything you need to know in our grid documentation.
We recommend defining your content's maximum width and alignment early on.
On very large screens, stretching content across the entire width often degrades the user experience. Our standard recommendation is to cap the content at 1920px (the lg breakpoint) and use center alignment, as shown in the example below.
Copy link to headline:Typography
Our design system does not bundle any font families by default, giving you full flexibility in your choice of typography. Unless you have specific requirements, we recommend using 'Source Sans 3' as the primary font and 'Source Code Pro' for monospace content.
For further information, please visit our typography documentation.
Build-in themes
When using one of our build-in themes you don't need to setup the fonts manually since they will be included in the corresponding theme.
- Install the recommended font packages:
- Import the fonts into your entry point (e.g.,
main.ts):
Copy link to headline:Vue
Copy link to headline:Nuxt
Copy link to headline:Theming
The design system includes a default theme with a pre-configured color palette. For custom branding, you can either select one of our pre-defined themes](/introduction/foundation/colors) or create your own.
Custom themes
A dedicated generator is planned for the future. For now, please refer to our color documentation to manually override the theme variables.
Copy link to headline:Custom styles
Editors note
In my opinion, that does not belong here. Maybe we can make a "How-Tos" or "Tutorials" section where we explain such things? Can move it to "Support?"
Most use cases are covered by built-in component properties. For unique styling requirements, you can easily override our CSS. Use the browser's developer tools to inspect the component's structure and define your custom overrides accordingly.
Scoped styles & CSS overrides
The :deep() selector is necessary when using scoped styles(opens in a new tab) to target child components. While removing scoped allows you to omit :deep(), be aware that your CSS will become global and may cause unintended side effects across your application. For a deep dive, see Vue’s documentation on deep selectors(opens in a new tab).
Copy link to headline:Figma setup
Editors note
Migrate content from the existing Figma Onboarding(opens in a new tab) file.
- Enable the "Thumbnail Library - UX Schwarz IT".
- Apply the project thumbnail to your file.
- Structure your pages using flows and the "Screenflow Cover".
- Set the "Appearance" to your required Onyx theme and density.
- Insert a Full HD frame (1920 x 1080px).
- Apply
onyx/color/base/background/tintedas the fill color. - Enable the layout grid.