Skip to content

QUICKSTART.md

Latest commit

 

History

History
134 lines (99 loc) · 3.55 KB

QUICKSTART.md

File metadata and controls

134 lines (99 loc) · 3.55 KB
Raw

Quick Start Guide

Get started with ShellUI Native in under 5 minutes.

Prerequisites

  • .NET 10.0 SDK (see global.json)
  • A .NET MAUI project (dotnet new maui) or an Avalonia 12 project (dotnet new avalonia.app)

Installation

1. Install the CLI Tool

ShellUI Native is in prerelease, so include --prerelease:

dotnet tool install -g ShellUI.Native.CLI --prerelease

2. Navigate to Your Project

cd YourProject

3. Initialize ShellUI Native

shellui-native init --yes

This will:

  • Detect your project type (MAUI, Avalonia, WinUI, or WPF — see ARCHITECTURE.md § Platform Detection)
  • Create the Components/UI/ folder (Components/Native/ when the project also has ShellUI for Blazor, see BLAZOR_HYBRID.md)
  • Install the Shell.cs utility
  • Create shellui-native.json configuration
  • Generate theme resources (MAUI)

Templates exist for MAUI and Avalonia. In a WinUI or WPF project, init skips the Shell.cs utility and add reports that the component has no template for that platform.

4. Add Components

# Add a single component
shellui-native add button

# Add multiple components
shellui-native add button input card

# Add with comma separation
shellui-native add button,input,card

5. Load the Theme

Publish the theme tokens before the first page loads. In a MAUI app, in App.xaml.cs:

public App()
{
    InitializeComponent();
    Components.UI.ShellTheme.EnsureInitialized();
}

In an Avalonia app, in App.axaml.cs:

public override void Initialize()
{
    AvaloniaXamlLoader.Load(this);
    Components.UI.ShellTheme.EnsureInitialized();
}

Components also do this on first use, but calling it early lets your own {DynamicResource ShellUI*} references resolve on the first page. See COMPONENTS.md § Theming for switching and customizing the theme.

6. Use Components in Your App

<!-- Add namespace to your XAML -->
<ContentPage xmlns:ui="clr-namespace:YourProject.Components.UI"
             BackgroundColor="{DynamicResource ShellUIBackground}">

    <!-- Use the Button component -->
    <ui:Button Text="Click me!"
               Size="Lg"
               Clicked="OnButtonClicked" />

</ContentPage>

In Avalonia the namespace is xmlns:ui="using:YourProject.Components.UI"; the components have the same names and properties. See COMPONENTS.md § Avalonia for the few differences.

Common Commands

Command Description
shellui-native init Initialize project
shellui-native add <name> Add component(s)
shellui-native list List all components
shellui-native list --installed List installed components
shellui-native remove <name> Remove component(s)
shellui-native update --all Update all components

Project Structure

After initialization, your project will have:

YourProject/
├── Components/
│   └── UI/
│       ├── Button.cs           # Added components
│       ├── Variants/
│       │   └── ButtonVariants.cs
│       └── Shell.cs            # Utility class
├── Resources/
│   └── Styles/
│       └── ShellUITheme.xaml   # Theme resources (MAUI)
└── shellui-native.json         # Configuration

Next Steps