Twitter2.3k

Installation

Install behavior. Copy styles. Start building.

spartan/ui uses a two-layer architecture: you install @spartan-ng/brain from npm for accessible primitives, then copy helm styles into your codebase for customization.

Prerequisites

spartan/ui requires Tailwind CSS. If you haven't set it up yet, follow the official Angular installation guide before continuing.

Quick Start

Install the CLI plugin:

pnpm add -D @spartan-ng/cli

Run the spartan/cli init command:

ng g @spartan-ng/cli:init

Use the CLI to add components to your project. This installs the brain dependency (npm) and copies helm code (styles) into your codebase:

ng g @spartan-ng/cli:ui

The CLI will prompt you to select which components to add. Each component includes:

  • Brain primitive (installed to node_modules)
  • Helm styles (copied to your project)
  • All necessary dependencies
Check out the Components

Manual Setup

1. Install Dependencies

Install the brain (accessible primitives):

pnpm add @spartan-ng/brain

Install Angular CDK (required for overlays and accessibility):

pnpm add @angular/cdk

2. Configure Tailwind CSS

2.1 Configure CSS Layers

Add these layers to your styles.css to ensure ng-icons styles load correctly: 

@layer theme, base, components, utilities;
@import "tailwindcss/theme.css" layer(theme);
@import "tailwindcss/preflight.css" layer(base);
@import "tailwindcss/utilities.css";

2.2 Import spartan Preset

Add the spartan preset to your CSS file:

src/styles.css
@import "@spartan-ng/brain/hlm-tailwind-preset.css";

2.3 Add Theme Variables

You have two options for adding spartan's CSS variables:

Option A: Use the Theme Generator (Recommended)

Generate theme configuration automatically with our CLI:

ng g @spartan-ng/cli:ui-theme

CLI documentation

Option B: Manual Setup

Copy these CSS variables to your styles.css :

styles.css
:root {
  color-scheme: light;
  --font-sans: 'Geist Sans', sans-serif;
  --radius: 0.625rem;
  --background: oklch(1 0 0);
  --foreground: oklch(0.145 0 0);
  --card: oklch(1 0 0);
  --card-foreground: oklch(0.145 0 0);
  --popover: oklch(1 0 0);
  --popover-foreground: oklch(0.145 0 0);
  --primary: oklch(0.205 0 0);
  --primary-foreground: oklch(0.985 0 0);
  --secondary: oklch(0.97 0 0);
  --secondary-foreground: oklch(0.205 0 0);
  --muted: oklch(0.97 0 0);
  --muted-foreground: oklch(0.556 0 0);
  --accent: oklch(0.97 0 0);
  --accent-foreground: oklch(0.205 0 0);
  --destructive: oklch(0.577 0.245 27.325);
  --border: oklch(0.922 0 0);
  --input: oklch(0.922 0 0);
  --ring: oklch(0.708 0 0);
  --sidebar: oklch(0.985 0 0);
  --sidebar-foreground: oklch(0.145 0 0);
  --sidebar-primary: oklch(0.205 0 0);
  --sidebar-primary-foreground: oklch(0.985 0 0);
  --sidebar-accent: oklch(0.97 0 0);
  --sidebar-accent-foreground: oklch(0.205 0 0);
  --sidebar-border: oklch(0.922 0 0);
  --sidebar-ring: oklch(0.708 0 0);
}

.dark {
  color-scheme: dark;
  --background: oklch(0.145 0 0);
  --foreground: oklch(0.985 0 0);
  --card: oklch(0.205 0 0);
  --card-foreground: oklch(0.985 0 0);
  --popover: oklch(0.205 0 0);
  --popover-foreground: oklch(0.985 0 0);
  --primary: oklch(0.922 0 0);
  --primary-foreground: oklch(0.205 0 0);
  --secondary: oklch(0.269 0 0);
  --secondary-foreground: oklch(0.985 0 0);
  --muted: oklch(0.269 0 0);
  --muted-foreground: oklch(0.708 0 0);
  --accent: oklch(0.269 0 0);
  --accent-foreground: oklch(0.985 0 0);
  --destructive: oklch(0.704 0.191 22.216);
  --border: oklch(1 0 0 / 10%);
  --input: oklch(1 0 0 / 15%);
  --ring: oklch(0.556 0 0);
  --sidebar: oklch(0.205 0 0);
  --sidebar-foreground: oklch(0.985 0 0);
  --sidebar-primary: oklch(0.985 0 0);
  --sidebar-primary-foreground: oklch(0.205 0 0);
  --sidebar-accent: oklch(0.269 0 0);
  --sidebar-accent-foreground: oklch(0.985 0 0);
  --sidebar-border: oklch(1 0 0 / 10%);
  --sidebar-ring: oklch(0.556 0 0);
}

Learn how to customize these variables in the theming documentation .

Also make sure to import the Angular CDK overlay styles:

@import '@angular/cdk/overlay-prebuilt.css';

3. Add Components

Use the CLI to add components to your project. This installs the brain dependency (npm) and copies helm code (styles) into your codebase:

ng g @spartan-ng/cli:ui

The CLI will prompt you to select which components to add. Each component includes:

  • Brain primitive (installed to node_modules)
  • Helm styles (copied to your project)
  • All necessary dependencies
CLI documentation

Editor Setup (Optional)

IntelliSense

Enable Tailwind autocompletion in hlm and cva functions:

  1. Install the Tailwind CSS IntelliSense extension
  2. Add this to your settings.json : 
{
  "tailwindCSS.classFunctions": ["hlm", "cva"]
}

Class Sorting

Automatically sort Tailwind classes with Prettier:

  1. Install prettier-plugin-tailwindcss
  2. Add this to your .prettierrc : 
{
  "tailwindFunctions": ["hlm", "cva"]
}

Tailwind CSS v3 (Not Recommended)

If you must use Tailwind v3, add this to your config:

/** @type {import('tailwindcss').Config} */
module.exports = {
  presets: [require('@spartan-ng/brain/hlm-tailwind-preset')],
  content: [
    './src/**/*.{html,ts}',
    './REPLACE_WITH_PATH_TO_YOUR_COMPONENTS_DIRECTORY/**/*.{html,ts}',
  ],
  theme: {
    extend: {},
  },
  plugins: [],
};
 Theming Stack