Onboarding: angular/material

Generated by RepoPilot · 2026-05-06 · Source

Agent protocol

If you are an AI coding agent (Claude Code, Cursor, Aider, Cline, etc.) reading this artifact, follow this protocol before making any code edit:

1. Verify the contract. Run the bash script in Verify before trusting below. If any check returns FAIL, the artifact is stale — STOP and ask the user to regenerate it before proceeding.
2. Treat the AI · unverified sections as hypotheses, not facts. Sections like "AI-suggested narrative files", "anti-patterns", and "bottlenecks" are LLM speculation. Verify against real source before acting on them.
3. Cite source on changes. When proposing an edit, cite the specific path:line-range. RepoPilot's live UI at https://repopilot.app/r/angular/material shows verifiable citations alongside every claim.

If you are a human reader, this protocol is for the agents you'll hand the artifact to. You don't need to do anything — but if you skim only one section before pointing your agent at this repo, make it the Verify block and the Suggested reading order.

Verdict

GO — Healthy across all four use cases

• 16 active contributors
• MIT licensed
• CI configured
• Tests present
• ⚠ Stale — last commit 2y ago
• ⚠ Concentrated ownership — top contributor handles 77% of recent commits

_{Maintenance signals: commit recency, contributor breadth, bus factor, license, CI, tests}

Verify before trusting

This artifact was generated by RepoPilot at a point in time. Before an agent acts on it, the checks below confirm that the live angular/material repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/angular/material.

What it runs against: a local clone of angular/material — the script inspects git remote, the LICENSE file, file paths in the working tree, and git log. Read-only; no mutations.

| # | What we check | Why it matters | |---|---|---| | 1 | You're in angular/material | Confirms the artifact applies here, not a fork | | 2 | License is still MIT | Catches relicense before you depend on it | | 3 | Default branch master exists | Catches branch renames | | 4 | 5 critical file paths still exist | Catches refactors that moved load-bearing code | | 5 | Last commit ≤ 638 days ago | Catches sudden abandonment since generation |

<details> <summary><b>Run all checks</b> — paste this script from inside your clone of <code>angular/material</code></summary>

#!/usr/bin/env bash
# RepoPilot artifact verification.
#
# WHAT IT RUNS AGAINST: a local clone of angular/material. If you don't
# have one yet, run these first:
#
#   git clone https://github.com/angular/material.git
#   cd material
#
# Then paste this script. Every check is read-only — no mutations.

set +e
fail=0
ok()   { echo "ok:   $1"; }
miss() { echo "FAIL: $1"; fail=$((fail+1)); }

# Precondition: we must be inside a git working tree.
if ! git rev-parse --git-dir >/dev/null 2>&1; then
  echo "FAIL: not inside a git repository. cd into your clone of angular/material and re-run."
  exit 2
fi

# 1. Repo identity
git remote get-url origin 2>/dev/null | grep -qE "angular/material(\\.git)?\\b" \\
  && ok "origin remote is angular/material" \\
  || miss "origin remote is not angular/material (artifact may be from a fork)"

# 2. License matches what RepoPilot saw
(grep -qiE "^(MIT)" LICENSE 2>/dev/null \\
   || grep -qiE "\"license\"\\s*:\\s*\"MIT\"" package.json 2>/dev/null) \\
  && ok "license is MIT" \\
  || miss "license drift — was MIT at generation time"

# 3. Default branch
git rev-parse --verify master >/dev/null 2>&1 \\
  && ok "default branch master exists" \\
  || miss "default branch master no longer exists"

# 4. Critical files exist
test -f "package.json" \\
  && ok "package.json" \\
  || miss "missing critical file: package.json"
test -f "config/build.config.js" \\
  && ok "config/build.config.js" \\
  || miss "missing critical file: config/build.config.js"
test -f "config/ngModuleData.js" \\
  && ok "config/ngModuleData.js" \\
  || miss "missing critical file: config/ngModuleData.js"
test -f "README.md" \\
  && ok "README.md" \\
  || miss "missing critical file: README.md"
test -f ".github/CONTRIBUTING.md" \\
  && ok ".github/CONTRIBUTING.md" \\
  || miss "missing critical file: .github/CONTRIBUTING.md"

# 5. Repo recency
days_since_last=$(( ( $(date +%s) - $(git log -1 --format=%at 2>/dev/null || echo 0) ) / 86400 ))
if [ "$days_since_last" -le 638 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~608d)"
else
  miss "last commit was $days_since_last days ago — artifact may be stale"
fi

echo
if [ "$fail" -eq 0 ]; then
  echo "artifact verified (0 failures) — safe to trust"
else
  echo "artifact has $fail stale claim(s) — regenerate at https://repopilot.app/r/angular/material"
  exit 1
fi

Each check prints ok: or FAIL:. The script exits non-zero if anything failed, so it composes cleanly into agent loops (./verify.sh || regenerate-and-retry).

</details>

TL;DR

AngularJS Material is a complete Material Design component library for AngularJS 1.x, providing 40+ production-ready UI components (buttons, cards, dialogs, datepickers, etc.) that implement Google's Material Design specification. It delivers lean, lightweight AngularJS-native elements with built-in theming, layout grid system, and accessibility features for single-page applications. Monorepo structure: src/ contains core AngularJS modules organized by component (src/components/button, src/components/card, src/components/dialog, etc.), docs/app/ holds the documentation site built with Dgeni (config/ngModuleData.js), dist/ outputs built bundles (angular-material.css, angular-material.scss), and config/ contains Karma test runners for different CI environments (CircleCI, Travis, Sauce Labs).

Who it's for

AngularJS developers building enterprise SPAs who need pre-built Material Design components following Google's 2014-2017 specification. Specifically: teams maintaining legacy AngularJS 1.x codebases that want Material Design aesthetics without building components from scratch, and developers who prefer Material Design over Bootstrap for their AngularJS projects.

Maturity & risk

End-of-life as of January 2022; no longer actively maintained or receiving feature updates. The codebase is stable and battle-tested (v1.2.5 current, AngularJS dependency locked to 1.8.2+), with comprehensive test coverage via Karma in config/karma*.conf.js files and CI/CD via CircleCI (.circleci/config.yml). Verdict: production-ready but deprecated—use Angular Material (v2+) for new projects.

Critical risk: officially end-of-life means no security patches or bug fixes; any discovered vulnerabilities will not be addressed. Dependency on AngularJS 1.x itself, which is also unsupported. Build toolchain uses older Gulp 3.9.1 (pinned in package.json) and may have unpatched npm dependencies. Single-maintainer-like support model at Google means community contributions are unlikely to be merged quickly.

Active areas of work

No active development—repository is in maintenance-only mode post-EOL announcement (January 2022). No ongoing feature work or scheduled releases visible. Focus is on critical security fixes only, though these are not actively being deployed. Users are directed toward angular/material (Angular v2+ Material Design) for new projects.

Get running

git clone https://github.com/angular/material.git && cd material && npm install && npm start (inferred from Gulp tasks in package.json and docs/README.md reference). For local docs/demo: npm run docs (uses Dgeni in config/ngModuleData.js to generate site).

Daily commands: npm install && npm start to launch dev server (served via gulp-connect in package.json). For tests: npm test (runs Karma with config/karma.conf.js). For documentation: npm run docs to build docs site locally (uses Dgeni in docs/README.md). For linting: npm run lint.

Map of the codebase

• package.json — Defines AngularJS Material as v1.2.5 package with Material Design implementation; all contributors must understand the project scope, version, and dependencies.
• config/build.config.js — Central build configuration orchestrating compilation, testing, and distribution; essential for understanding how the library is packaged and deployed.
• config/ngModuleData.js — Defines the AngularJS module structure and component registration; contributors must know how UI components are organized and exported.
• README.md — Explicitly documents end-of-life status (January 2022) and project scope as legacy AngularJS v1.x Material Design implementation; critical for contributor onboarding.
• .github/CONTRIBUTING.md — Contribution guidelines and code standards that all contributors must follow to maintain consistency across the 600-file codebase.
• config/karma.conf.js — Test runner configuration used across multiple environments (CircleCI, Travis, Sauce Labs); essential for running and maintaining test suites.
• CHANGELOG.md — Documents all version changes and breaking changes up to v1.2.5; helps contributors understand evolution and backward compatibility constraints.

Components & responsibilities

• UI Components (Buttons, Cards, Lists, etc.) (AngularJS directives, DOM, CSS animations) — Render Material Design-compliant interactive elements; handle user input and visual feedback; emit events to parent scope
  • Failure mode: Component fails to render, styling breaks, events not fired, accessibility violations
• Service APIs ($mdToast, $mdDialog, $mdSidenav, etc.) (AngularJS services, promises, event emitters) — Provide programmatic control of modal/overlay components; manage lifecycle (open/close), callbacks, animations
  • Failure mode: Service call doesn't trigger component, promise never resolves, memory leaks in callback chains
• Theming Engine — Apply

How to make changes

Add a New Material UI Component

1. Create component directory and AngularJS module files in src/components/{componentName}/ (src/components/{componentName}/component.js)
2. Register the component in config/ngModuleData.js by adding module metadata entry (config/ngModuleData.js)
3. Write Jasmine test specs in src/components/{componentName}/ matching *.spec.js pattern (src/components/{componentName}/{componentName}.spec.js)
4. Add SCSS styling files following Material Design specification in src/components/{componentName}/scss/ (src/components/{componentName}/scss/{componentName}.scss)
5. Create demo/documentation template in docs/app/pages/ linked from main docs site (docs/app/pages/{componentName}.html)

Add a New Utility Service

1. Create service file in src/services/ with AngularJS factory/provider definition (src/services/{serviceName}Service.js)
2. Register the service in config/ngModuleData.js under the services section (config/ngModuleData.js)
3. Add unit tests following existing test patterns with Karma/Jasmine (src/services/{serviceName}Service.spec.js)
4. Document the service API in docs/app/pages/api/{serviceName}.html or add to README (README.md)

Configure Testing for a New Environment

1. Create environment-specific test config by cloning config/karma.conf.js (config/karma-{environment}.conf.js)
2. Update the environment config with platform-specific runners, browsers, or reporters (config/karma-{environment}.conf.js)
3. Update build.config.js to include the new Karma configuration in the appropriate pipeline (config/build.config.js)

Why these technologies

• AngularJS (v1.x) — Project implements Material Design specifically for AngularJS v1.x single-page applications; target framework for all components.
• Material Design Specification (2014-2017 archive) — Defines the visual, motion, and interaction design principles that all UI components must implement.
• SCSS/CSS — Provides responsive, Material Design-compliant styling for all components with theme customization support.
• Karma + Jasmine — Industry-standard test runner and assertion library for JavaScript units tests; supports multiple environments (Chrome, Sauce Labs).
• CircleCI + GitHub Actions — Automated CI/CD pipeline for testing across browsers, platforms, and ensuring code quality before release.

Trade-offs already made

• Focus on AngularJS v1.x only; no v2+ Angular support

  • Why: Streamlines development and maintenance to a single framework version; avoids complexity of supporting multiple major versions.
  • Consequence: Users requiring modern Angular must migrate to the separate Angular Material project; limits future audience.

• End-of-life as of January 2022; no active development

  • Why: AngularJS itself reached end-of-life; maintaining a legacy library diverts resources from modern frameworks.
  • Consequence: Critical bug fixes only; no new features; users are encouraged to migrate to Angular Material instead.

• Monolithic 600-file structure in single repository

  • Why: All Material components, styles, and tests grouped together; simplifies versioning and distribution as a single npm package.
  • Consequence: Large surface area; harder to cherry-pick individual components; slower builds as library grows.

• Comprehensive test coverage across multiple browsers (Chrome, Sauce Labs, Travis, CircleCI)

  • Why: Ensures Material Design components render consistently across desktop and mobile environments.
  • Consequence: Slower CI pipelines; higher infrastructure costs; testing matrix complexity increases maintenance burden.

Non-goals (don't propose these)

• Does not support Angular v2+ (modern Angular); users must migrate to separate Angular Material project.
• Does not provide server-side rendering (SSR) or Node.js integration; client-side AngularJS only.
• Does not handle authentication, authorization, or security policies; relies on parent AngularJS application.
• Does not provide backend APIs or data persistence; UI components only, state managed by parent app.
• Does not support Internet Explorer 11 or older browsers; targets modern browsers (ES5+).

Traps & gotchas

Node version pinned in .nvmrc (check it before npm install—may conflict with modern npm); Gulp 3.9.1 is end-of-life and may fail on Node 18+; Karma config references external Sauce Labs browsers (config/karma-sauce.conf.js, config/sauce-browsers.json) requiring credentials; Dgeni documentation build requires specific package versions and can be finicky (see docs/README.md for setup). ESLint rules in .eslintrc.json may conflict with modern JavaScript—check .eslintignore before linting generated files.

Architecture

Concepts to learn

• Material Design specification (2014-2017) — This entire library is an implementation of Google's Material Design spec; understanding the design principles (elevation, motion, color palette) is essential to using and contributing to components
• AngularJS directives and services — All Material components are built as AngularJS 1.x directives (reusable DOM elements) and services (singletons); you must understand $scope, $digest, $watch to debug or extend components
• SCSS theming and CSS-in-JS variable injection — Material's theming system uses SCSS mixins to generate CSS at build time with injected color variables; src/core/_theme.scss is the foundation for all color customization
• Karma test runner and AngularJS testing patterns — All tests use Karma (configured in config/karma*.conf.js) with angular-mocks; understanding $rootScope, $compile, and test fixtures is required to write component tests
• Dgeni documentation generation — Component docs are auto-generated from source JSDoc comments via Dgeni (configured in config/ngModuleData.js); contributing docs requires understanding Dgeni templates and JSDoc annotation patterns
• CSS Grid and Flexbox layout system — Material's layout component (src/components/layout/) provides a responsive grid and flexbox utilities; understanding flex-basis, flex-grow, and media queries is needed to use the layout system effectively
• Browser compatibility and polyfills — AngularJS Material targets specific browser versions listed in package.json browserslist and requires polyfills for features like promises and array methods in older browsers; CI runs on multiple browser versions via Sauce Labs

Related repos

• angular/material — The successor project: Material Design for Angular v2+ (actively maintained); users upgrading from AngularJS Material should target this
• angular/angularjs-old — Official AngularJS 1.x repository (archived); provides the AngularJS framework that Material depends on; both are now end-of-life
• twbs/bootstrap — Alternative UI component library for AngularJS; similar scope but uses Bootstrap design system instead of Material Design
• angular-ui/bootstrap — AngularJS-specific Bootstrap component wrappers; direct competitor in the legacy AngularJS ecosystem
• google/material-design-lite — Google's lightweight Material Design CSS library (vanilla JS, not AngularJS); inspired this project and offers pure CSS alternative

PR ideas

To work on one of these in Claude Code or Cursor, paste: Implement the "<title>" PR idea from CLAUDE.md, working through the checklist as the task list.

Add comprehensive E2E tests for Material Dialog component

The repo has Karma unit test configs (config/karma*.conf.js) but the file structure shows no E2E test directory. Given that AngularJS Material provides interactive UI components like dialogs, adding E2E tests using Protractor would catch regressions in real browser behavior, especially for focus management, keyboard navigation, and animation timing—critical for accessibility in Material Design.

• [ ] Create e2e/ directory with Protractor configuration file (e2e/protractor.conf.js)
• [ ] Add E2E tests for src/components/dialog/ focusing on: open/close animations, keyboard escape handling, backdrop click behavior, and focus trap
• [ ] Integrate E2E tests into .circleci/config.yml workflow to run alongside existing Karma tests
• [ ] Document E2E testing setup in .github/CONTRIBUTING.md with instructions for running locally

Migrate from deprecated Travis CI to GitHub Actions for primary CI pipeline

The repo currently uses Travis CI (referenced in README badge and config/karma-travis.conf.js), but has .circleci/config.yml indicating a partial CircleCI migration. However, .github/workflows/ exists but only contains codeql-analysis.yml. Creating a comprehensive GitHub Actions workflow would modernize the CI, leverage native GitHub integration, and allow deprecation of external CI services.

• [ ] Create .github/workflows/build-and-test.yml that runs: npm install, npm run lint (using .eslintrc.json), karma tests (config/karma.conf.js), and builds distribution files
• [ ] Add matrix testing strategy for Node versions specified in .nvmrc and multiple AngularJS versions (1.6.x, 1.7.x, 1.8.x)
• [ ] Include conditional workflow_dispatch trigger to allow manual testing of different browsers via Sauce Labs (referenced in config/sauce-browsers.json)
• [ ] Update README.md badges to point to GitHub Actions workflow status instead of Travis CI

Create API documentation generator configuration for undocumented Material components

The repo uses dgeni (config/ngModuleData.js, dgeni-packages dependency) for documentation generation, and docs/ folder exists, but the file structure shows incomplete docs for component APIs. Many Material components (buttons, menus, chips, etc.) likely lack generated API reference docs. Adding Dgeni configuration would auto-generate API docs from JSDoc comments in source files.

• [ ] Audit src/components/ directory to identify components missing API documentation (check docs/app/ for existing coverage)
• [ ] Create or update Dgeni package configuration in config/ to parse @param, @returns, @example JSDoc tags from component source files
• [ ] Generate API doc templates in docs/app/partials/api/ for each component (e.g., docs/app/partials/api/material.dialog.service.html)
• [ ] Add build step to package.json scripts that runs Dgeni and validates generated docs are included in docs build output

Good first issues

• Add missing accessibility tests: src/components/ has many directives (datepicker, dialog, menu) without comprehensive ARIA/a11y test coverage in .spec.js files. Contribute Karma tests verifying ARIA labels, roles, and keyboard navigation for underexposed components.
• Improve Sass documentation: dist/angular-material.scss is generated from src/ but lacks inline comments explaining theming variables and mixins. Add JSDoc-style comments to key SCSS files (src/core/_theme.scss, src/core/_variables.scss) and document in docs/app/pages/theming.md.
• Fix outdated browser support docs: .github/CONTRIBUTING.md and docs/app reference browserslist from package.json but the list is stale (IE 11 support ended). Audit and update CONTRIBUTING.md and browser support page to reflect reality post-EOL.

Top contributors

• @Splaktar — 77 commits
• @jelbourn — 4 commits
• @mmalerba — 4 commits
• [@Ed Clement](https://github.com/Ed Clement) — 2 commits
• @clshortfuse — 2 commits

Recent commits

• 952c067 — Clear .mailmap (jelbourn)
• 0b55529 — update version number in package.json to 1.2.5 (jelbourn)
• bfc8ae7 — docs(eol): update docs website for End-of-Life (Splaktar)
• c9f67b3 — docs(github): update GH templates for EOL (Splaktar)
• cdce2ba — docs(eol): updates for End-of-Life (Splaktar)
• 6ec3454 — docs(eol): add EOL options banner to header of every page (Ed Clement)
• 4cb5de8 — update version number in package.json to 1.2.4 (mmalerba)
• 625adc5 — chore(sass): fix module builds (Splaktar)
• 4c935a3 — docs(eol): Add EOL options text and link to LTS section of landing page (Ed Clement)
• b5a1a02 — build: fix SCSS division deprecation (#12112) (superheri)

Security observations

• Critical · End of Life Software - No Security Support — SECURITY.md, package.json (version 1.2.5). AngularJS Material v1.2.x reached end of life in January 2022. No security patches, bug fixes, or updates are provided. The entire 1.x version line is unsupported. This exposes applications to known vulnerabilities that will never be patched. Fix: Migrate to Angular Material (v12+) which is actively maintained and receives regular security updates. The project explicitly directs users to material.angular.io for active support.
• High · Outdated Angular Dependencies with Known Vulnerabilities — package.json - devDependencies (angular@^1.8.2 and related packages). The project depends on AngularJS 1.8.2 and related packages (angular-sanitize, angular-route, etc.) from 2020. AngularJS 1.x has multiple known security vulnerabilities including expression sandbox bypasses and XSS vulnerabilities that are no longer patched. Fix: Upgrade to Angular 12+ or later. If migration is not possible, implement strict Content Security Policy (CSP) headers and carefully validate all user inputs and template content.
• High · Vulnerable Transitive Dependencies — package.json - devDependencies (ajv, acorn, autoprefixer). Several dependencies have known security vulnerabilities: ajv@6.12.6 (prototype pollution), acorn@7.4.1 (DoS), and autoprefixer@10.2.6. These are outdated versions that should be updated to their latest patches. Fix: Update all dependencies to their latest versions: ajv to ^8.12.0+, acorn to ^8.8.0+, and autoprefixer to ^10.4.14+. Run 'npm audit fix' to identify and patch vulnerable transitive dependencies.
• High · XSS Risk in AngularJS Expression Evaluation — Entire codebase (AngularJS 1.8.2 framework limitation). AngularJS 1.x has known expression sandbox bypass vulnerabilities. The framework evaluates expressions in templates which can be exploited if user input reaches template interpolation. This is a fundamental design issue in AngularJS 1.x. Fix: Implement strict Content Security Policy (CSP) headers. Never interpolate untrusted user input directly in templates. Use angular-sanitize for HTML content and always validate/escape user input server-side. Consider implementing Trusted Types API.
• Medium · Missing Security Headers Configuration — .circleci/config.yml, docs configuration. The CircleCI and documentation build configurations (.circleci/config.yml, docs setup) do not show evidence of security headers (CSP, HSTS, X-Frame-Options, etc.) being configured for the documentation site or build artifacts. Fix: Add security headers to any web server serving this library's documentation: Content-Security-Policy, X-Content-Type-Options: nosniff, X-Frame-Options: DENY, Strict-Transport-Security.
• Medium · Outdated Build and Development Tools — package.json - devDependencies (gulp, eslint, and related tools). Build tools are outdated: gulp@3.9.1 (released 2016), eslint@7.23.0 (superseded by v8+). These tools may have security vulnerabilities in their dependencies and lack modern security features. Fix: Update gulp to v4.0.2+ and eslint to v8.0.0+. This will improve security scanning during the build process and ensure compatibility with modern security tooling.
• Medium · npm Audit Vulnerabilities Not Addressed — package.json and entire node_modules tree (implicit). The package.json indicates a private repository with multiple outdated packages. Running 'npm audit' would likely reveal numerous vulnerabilities in the dependency tree that have not been remediated. Fix: Execute 'npm audit' regularly. Implement automated dependency scanning in CI/CD pipeline (GitHub Actions available). Update all packages to latest patch versions and evaluate major version upgrades where feasible.
• Low · Missing Code Signing and Integrity Verification — undefined. No evidence of signed releases or integrity verification mechanisms (signatures, checksums) in the repository Fix: undefined

LLM-derived; treat as a starting point, not a security audit.

Where to read next

• Open issues — current backlog
• Recent PRs — what's actively shipping
• Source on GitHub

---

Generated by RepoPilot. Verdict based on maintenance signals — see the live page for receipts. Re-run on a new commit to refresh.