Modus Angular Boilerplate

A production-ready Angular 20 boilerplate with Trimble Modus Design System integration, featuring 47 wrapped components, comprehensive dev tools, and enforced design system compliance.

Quick Start

# 1. Install dependencies
npm install

# 2. Start development server
npm start

# 3. Open in browser
open http://localhost:4200

Press Ctrl+Shift+D to open the Dev Panel and explore components, themes, and icons.

What's Included

Feature	Description
47 Wrapper Components	Angular wrappers for all Modus Web Components with signal-based APIs
46 Component Demos	Interactive demos organized by category (Forms, Layout, Navigation, Display, Feedback, Overlays, Data)
Dev Panel	Floating panel with theme switcher, color palette, icon browser, and component gallery
8 Lint Scripts	Automated design system compliance checking (colors, icons, borders, opacity, styles)
52 AI Rules	Cursor/Copilot rules for guided development with Modus patterns
6 Themes	Classic, Modern, and Connect themes in light/dark variants
Pre-commit Hooks	Automatic linting on every commit via Husky

Tech Stack

Technology	Version	Package
Angular	20.3.0	`@angular/core`
Modus Web Components	1.0.6	`@trimble-oss/moduswebcomponents`
Modus Angular Wrappers	1.0.6-ng19	`@trimble-oss/moduswebcomponents-angular`
Modus Icons	1.18.0	`@trimble-oss/modus-icons`
Tailwind CSS	4.1.16	`tailwindcss`
TypeScript	5.9.2	`typescript`

Project Structure

src/app/
├── pages/                 # Your application pages (START HERE)
│   └── home/              # Home page - edit to build your app
├── components/            # 47 Modus wrapper components (use as-is)
├── demos/                 # 46 component demos (reference only)
│   ├── forms/             # Button, Checkbox, Input, Select, Slider...
│   ├── layout/            # Accordion, Card, Handle, Panel, Toolbar...
│   ├── navigation/        # Breadcrumbs, Menu, Navbar, Tabs, Stepper...
│   ├── display/           # Avatar, Badge, Icon, Logo, Theme Switcher...
│   ├── feedback/          # Alert, Loader, Progress, Skeleton, Toast...
│   ├── overlays/          # Modal
│   └── data/              # Table
├── dev/                   # Dev Panel infrastructure
│   ├── dev-panel/         # Floating panel UI
│   └── theme-switcher-dropdown/
├── dev-pages/             # Reference pages (dev only)
│   ├── color-palette/     # Design system colors
│   ├── icons/             # 700+ icons browser
│   └── components-gallery/
├── services/              # Theme service with localStorage persistence
└── data/                  # Shared data (icons list, etc.)

Where to Build Your App

Directory	Action	Description
`src/app/pages/`	WRITE	Add your application pages here
`src/app/components/`	READ	Use wrapper components as-is
`src/app/demos/`	READ	Reference for component usage

Dev Panel

Toggle with Ctrl+Shift+D (or Cmd+Shift+D on Mac)

Features

Tab	Description
Themes	Switch between 6 Modus themes (Classic/Modern/Connect, Light/Dark)
Colors	View the 9-color design system palette with CSS variables
Icons	Browse 700+ Modus icons with click-to-copy functionality
Components	Gallery of all 47 wrapped components
Demos	46 interactive component demos

Dev Routes

Route	Description
`/dev/colors`	Color palette reference
`/dev/icons`	Icon library browser
`/dev/components`	Component gallery
`/dev/demos/*`	Individual component demos

Note: Dev Panel and dev routes are automatically excluded from production builds.

Available Components

Forms (17)

Component	Selector	Description
Autocomplete	`<modus-autocomplete>`	Search with suggestions
Button	`<modus-button>`	Action buttons
Button Group	`<modus-button-group>`	Grouped buttons
Checkbox	`<modus-checkbox>`	Checkbox inputs
Date	`<modus-date>`	Date picker
File Dropzone	`<modus-file-dropzone>`	File upload area
Input Feedback	`<modus-input-feedback>`	Form validation messages
Input Label	`<modus-input-label>`	Form labels
Number Input	`<modus-number-input>`	Numeric inputs
Radio	`<modus-radio>`	Radio buttons
Rating	`<modus-rating>`	Star ratings
Select	`<modus-select>`	Select dropdowns
Slider	`<modus-slider>`	Range sliders
Switch	`<modus-switch>`	Toggle switches
Text Input	`<modus-text-input>`	Text fields
Textarea	`<modus-textarea>`	Multi-line text
Time Input	`<modus-time-input>`	Time picker

Layout (6)

Component	Selector	Description
Accordion	`<modus-accordion>`	Collapsible sections
Card	`<modus-card>`	Content cards
Handle	`<modus-handle>`	Resize handles
Panel	`<modus-panel>`	Content panels
Toolbar	`<modus-toolbar>`	Action toolbars
Utility Panel	`<modus-utility-panel>`	Slide-out panels

Navigation (8)

Component	Selector	Description
Breadcrumbs	`<modus-breadcrumbs>`	Navigation trail
Dropdown Menu	`<modus-dropdown-menu>`	Dropdown selections
Menu	`<modus-menu>`	Dropdown menus
Navbar	`<modus-navbar>`	Top navigation bar
Pagination	`<modus-pagination>`	Page navigation
Side Navigation	`<modus-side-navigation>`	Sidebar navigation
Stepper	`<modus-stepper>`	Multi-step flow
Tabs	`<modus-tabs>`	Tabbed content

Display (6)

Component	Selector	Description
Avatar	`<modus-avatar>`	User avatar with image or initials
Badge	`<modus-badge>`	Status indicators and counters
Chip	`<modus-chip>`	Tags and filter chips
Icon	`<modus-icon>`	700+ Modus icons
Logo	`<modus-logo>`	Trimble logo variants
Theme Switcher	`<modus-theme-switcher>`	Theme selection

Feedback (6)

Component	Selector	Description
Alert	`<modus-alert>`	Notifications and messages
Loader	`<modus-loader>`	Loading spinners
Progress	`<modus-progress>`	Progress bars
Skeleton	`<modus-skeleton>`	Loading placeholders
Toast	`<modus-toast>`	Temporary notifications
Tooltip	`<modus-tooltip>`	Hover tooltips

Overlays (1)

Component	Selector	Description
Modal	`<modus-modal>`	Dialog windows

Data (1)

Component	Selector	Description
Table	`<modus-table>`	Data tables

Design System

9-Color Palette

Base Colors

Color	Tailwind Class	Usage
Background	`bg-background`	Page backgrounds
Card	`bg-card`	Card surfaces
Muted	`bg-muted`	Muted backgrounds
Secondary	`bg-secondary`	Secondary surfaces
Foreground	`text-foreground`	Primary text

Status Colors

Color	Tailwind Class	Usage
Primary	`bg-primary` / `text-primary`	Primary actions, info states
Success	`bg-success` / `text-success`	Success states
Warning	`bg-warning` / `text-warning`	Warning states
Error	`bg-error` / `text-error`	Error states

Usage Example

<!-- Correct: Design system colors -->
<div class="bg-background text-foreground p-4">
  <div class="bg-card rounded-lg p-4 border-default">
    <div class="text-primary font-semibold">Title</div>
    <div class="text-muted-foreground">Description</div>
  </div>
</div>

<!-- Wrong: Generic Tailwind colors (will fail lint) -->
<div class="bg-gray-100 text-gray-900"></div>

Opacity Utilities

Use custom opacity classes instead of Tailwind's /80 syntax:

<!-- Correct -->
<div class="text-foreground-80">80% opacity text</div>

<!-- Wrong (doesn't work with CSS variables) -->
<div class="text-foreground/80"></div>

Commands

Development

Command	Description
`npm start`	Start dev server on `localhost:4200`
`npm run build`	Production build to `dist/`
`npm test`	Run unit tests with Vitest
`npm run watch`	Build with watch mode

Linting

Command	Description
`npm run lint:all`	Run all 7 checks with summary table
`npm run type-check`	TypeScript validation
`npm run lint:colors`	Check color compliance
`npm run lint:styles`	Check for inline styles
`npm run lint:borders`	Check border patterns
`npm run lint:opacity`	Check opacity utilities
`npm run lint:icons`	Check icon library usage
`npm run lint:icon-names`	Validate icon names (710+)

lint:all runs every check even if some fail, then shows a pass/fail summary.

Pre-commit Hooks

All 7 lint checks run automatically on git commit via Husky. Commits are blocked if any check fails.

Getting Started

1. Build Your App

Edit src/app/pages/home/home.component.ts to start building:

import { Component, ChangeDetectionStrategy } from '@angular/core';
import { ModusButtonComponent } from '@/app/components';

@Component({
  selector: 'app-home',
  imports: [ModusButtonComponent],
  template: `
    <div class="bg-background text-foreground p-8">
      <div class="text-2xl font-bold mb-4">My App</div>
      <modus-button color="primary" (buttonClick)="handleClick()"> Get Started </modus-button>
    </div>
  `,
  changeDetection: ChangeDetectionStrategy.OnPush,
})
export class HomeComponent {
  handleClick() {
    console.log('Button clicked!');
  }
}

2. Use Components

Import from @/app/components:

import {
  ModusButtonComponent,
  ModusAlertComponent,
  ModusIconComponent,
  ModusCardComponent,
} from '@/app/components';

3. Test All Themes

Use the Dev Panel (Ctrl+Shift+D) to test your UI in all 6 themes:

Modus Classic Light / Dark
Modus Modern Light / Dark
Connect Light / Dark

Deployment

AWS Amplify

Pre-configured amplify.yml included:

version: 1
frontend:
  phases:
    preBuild:
      commands:
        - npm ci
    build:
      commands:
        - npm run build
  artifacts:
    baseDirectory: dist/modus-angular-app/browser
    files:
      - '**/*'
  cache:
    paths:
      - node_modules/**/*

Important: Configure rewrite rules in Amplify Console for Angular routing:

Source	Target	Type
`/<*>`	`/index.html`	200 (Rewrite)

AI-Powered Development

Cursor/Copilot Rules

52 development rules in .cursor/rules/ covering:

Component patterns and state management
Design system compliance
Angular 20 best practices
Known issues and workarounds

AGENTS.MD

Comprehensive guide for AI agents in AGENTS.MD:

Commands reference
Design system rules
Critical bug fixes
Boundaries (Always/Ask/Never)

Cursor Commands

AI-powered scaffolding commands in .cursor/commands/:

Command	Description
`scaffold-shell-app`	Create a complete app shell with ModusNavbar, ModusSideNavigation, and Angular Router nested routing

Usage: Open Cursor IDE, press Cmd+K (Mac) or Ctrl+K (Windows/Linux), and run the command. The AI guides you through a conversational setup:

Enter your navigation menu labels (e.g., "Dashboard, Projects, Settings")
AI creates AppShellComponent layout with navbar and side navigation
AI creates placeholder pages for each navigation item
AI updates app.routes.ts with child routes

Features:

SPA navigation (no page reloads)
Hamburger menu synced with side navigation
Push mode side nav with icon-only collapsed state
DOM event listener pattern (avoids Angular change detection loops)
Preserves all Dev Panel and demo content

MCP Servers

Pre-configured Model Context Protocol servers:

Server	Purpose
`modus-docs`	Modus component documentation
`context7`	Angular, Tailwind, dependency docs

Angular 20 Patterns

This boilerplate uses modern Angular patterns:

// Signal-based inputs (not @Input decorator)
readonly color = input<ButtonColor>('primary');

// Signal-based outputs (not @Output decorator)
readonly buttonClick = output<MouseEvent>();

// inject() for DI (not constructor)
private readonly service = inject(MyService);

// Modern control flow (not *ngIf/*ngFor)
@if (isVisible()) {
  <div>Content</div>
}
@for (item of items(); track item.id) {
  <div>{{ item.name }}</div>
}

// OnPush change detection (required)
changeDetection: ChangeDetectionStrategy.OnPush

Resources

Resource	Description
Modus 2 Web Components	Official component documentation
Modus Design System	Design guidelines and patterns
Angular Signals	Signal-based reactivity guide
Tailwind CSS v4	Utility-first CSS framework

License

MIT

Name		Name	Last commit message	Last commit date
Latest commit History 1 Commit
.cursor		.cursor
.github/workflows		.github/workflows
.husky		.husky
.vscode		.vscode
data		data
public		public
scripts		scripts
src		src
.editorconfig		.editorconfig
.gitignore		.gitignore
.npmrc		.npmrc
.postcssrc.json		.postcssrc.json
AGENTS.MD		AGENTS.MD
CLAUDE.md		CLAUDE.md
README.md		README.md
amplify.yml		amplify.yml
angular.json		angular.json
package-lock.json		package-lock.json
package.json		package.json
tsconfig.app.json		tsconfig.app.json
tsconfig.json		tsconfig.json
tsconfig.spec.json		tsconfig.spec.json

Folders and files

Latest commit

History

Repository files navigation

Modus Angular Boilerplate

Quick Start

What's Included

Tech Stack

Project Structure

Where to Build Your App

Dev Panel

Features

Dev Routes

Available Components

Forms (17)

Layout (6)

Navigation (8)

Display (6)

Feedback (6)

Overlays (1)

Data (1)

Design System

9-Color Palette

Base Colors

Status Colors

Usage Example

Opacity Utilities

Commands

Development

Linting

Pre-commit Hooks

Getting Started

1. Build Your App

2. Use Components

3. Test All Themes

Deployment

AWS Amplify

AI-Powered Development

Cursor/Copilot Rules

AGENTS.MD

Cursor Commands

MCP Servers

Angular 20 Patterns

Resources

License

About

Resources

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages