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/CosmicMind/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.

WAIT — Stale — last commit 4y ago

• 11 active contributors
• Distributed ownership (top contributor 35% of recent commits)
• MIT licensed
• ⚠ Stale — last commit 4y ago
• ⚠ No CI workflows detected
• ⚠ No test directory detected

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

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

What it runs against: a local clone of CosmicMind/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 CosmicMind/Material | Confirms the artifact applies here, not a fork | | 2 | License is still MIT | Catches relicense before you depend on it | | 3 | Default branch development exists | Catches branch renames | | 4 | 5 critical file paths still exist | Catches refactors that moved load-bearing code | | 5 | Last commit ≤ 1484 days ago | Catches sudden abandonment since generation |

#!/usr/bin/env bash
# RepoPilot artifact verification.
#
# WHAT IT RUNS AGAINST: a local clone of CosmicMind/Material. If you don't
# have one yet, run these first:
#
#   git clone https://github.com/CosmicMind/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 CosmicMind/Material and re-run."
  exit 2
fi

# 1. Repo identity
git remote get-url origin 2>/dev/null | grep -qE "CosmicMind/Material(\\.git)?\\b" \\
  && ok "origin remote is CosmicMind/Material" \\
  || miss "origin remote is not CosmicMind/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 development >/dev/null 2>&1 \\
  && ok "default branch development exists" \\
  || miss "default branch development no longer exists"

# 4. Critical files exist
test -f "Material.podspec" \\
  && ok "Material.podspec" \\
  || miss "missing critical file: Material.podspec"
test -f "Package.swift" \\
  && ok "Package.swift" \\
  || miss "missing critical file: Package.swift"
test -f "Material.xcodeproj/project.pbxproj" \\
  && ok "Material.xcodeproj/project.pbxproj" \\
  || miss "missing critical file: Material.xcodeproj/project.pbxproj"
test -f "Sources/Assets.xcassets/Contents.json" \\
  && ok "Sources/Assets.xcassets/Contents.json" \\
  || miss "missing critical file: Sources/Assets.xcassets/Contents.json"
test -f "README.md" \\
  && ok "README.md" \\
  || miss "missing critical file: README.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 1484 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~1454d)"
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/CosmicMind/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).

Material is a Swift-based iOS UI/UX framework that provides pre-built Material Design components (Cards, FAB menus, TextField, Snackbar, Tabs, Chips, SearchBar, NavigationController, BottomNavigationBar) with built-in motion animations powered by the Motion library. It solves the problem of building Material Design–compliant iOS apps without manually implementing animations and custom layout logic. Single framework structure: Sources/Assets.xcassets contains ~50 Material Design icon assets (cm_add_white, cm_arrow_back_white, etc. at 1x/2x/3x scales); Source code is in Sources/ (not shown in detail); Package.swift and Material.podspec define distribution; Material.xcodeproj is the Xcode workspace. No monorepo—this is a single, cohesive framework.

iOS developers (Swift 4.0+, iOS 8.0+) who want to rapidly build visually cohesive Material Design applications with polished animations and transitions without writing boilerplate layout and animation code.

This project is actively maintained and production-ready. The codebase is 662KB of Swift code with CocoaPods/Carthage/SPM distribution support, a detailed CHANGELOG, and samples. However, without visible CI/CD config in the file list and with iOS 8.0+ as minimum (quite dated), the repo appears to be in stable/maintenance mode rather than rapid feature expansion.

Primary risk: single-author/small-team maintenance (typical of CosmicMind projects). Dependency on Motion library means changes upstream could cascade. Last commit recency not visible in provided data, but mature feature set suggests slow iteration cycle. Breaking Swift version changes (4.0+ requirement) may require periodic updates.

No PR/commit/milestone data visible in provided file list. The presence of CHANGELOG.md, CODE_OF_CONDUCT.md, CONTRIBUTING.md, and multiple package managers (CocoaPods, Carthage, SPM) suggests the project is accepting contributions but not actively evolving core features. Icon asset organization is mature and comprehensive.

git clone https://github.com/CosmicMind/Material.git
cd Material
# Install via CocoaPods (Podfile: pod 'Material')
# Or Carthage: echo 'github "CosmicMind/Material"' >> Cartfile && carthage update
# Or SPM: use Package.swift with swift build

Daily commands: Open Material.xcodeproj in Xcode 8.2+. Build the Material scheme. Sample projects (referenced in README at github.com/CosmicMind/Samples) demonstrate usage; no standalone dev server—this is a framework library, not an app.

• Material.podspec — Defines the library's public API surface, version, dependencies, and platform requirements that all contributors must align with.
• Package.swift — SPM manifest declaring build targets, dependencies, and module structure essential for understanding the codebase organization.
• Material.xcodeproj/project.pbxproj — Xcode project configuration that controls compilation, asset bundling, and framework linking for the entire UI framework.
• Sources/Assets.xcassets/Contents.json — Asset catalog metadata that ensures Material Design icons and images are properly versioned and exported to consumers.
• README.md — Primary documentation describing Material's purpose, animation system integration with Motion, and platform support requirements.
• CONTRIBUTING.md — Contribution guidelines and community standards that every developer must follow when submitting changes.

• Material Framework (Swift) (Swift, UIKit, Core Animation, Motion) — Core UI component library providing Material Design-compliant widgets with Animation integration
  • Failure mode: Missing or broken UI components cause visual layout failures; animation library incompatibility breaks transitions
• Motion Animation Library (dependency) (Swift, CADisplayLink, UIPanGestureRecognizer) — Gesture-driven animation and transition engine decoupled from Material components
  • Failure mode: Incompatible Motion version breaks animation playback; gesture handlers fail to respond
• Asset Catalog (xcassets) (Xcode Asset Compiler, PNG) — Provides multi-resolution Material Design icons and images for UI components
  • Failure mode: Missing or corrupt assets cause broken image references; scale variant mismatch causes fuzzy or oversized icons
• Build System (Xcode) (Xcode, Swift compiler, Mach-O linker) — Compiles Swift source, links Motion dependency, embeds assets, and packages framework for distribution
  • Failure mode: Incompatible Swift version breaks compilation; missing Motion symbols cause linker errors; asset embedding failures prevent resource access

• Client App → Material Framework — App instantiates Material UI components (e.g., Button, NavigationBar) and configures properties
• Material Framework → Motion Library — Material components request animation playback for transitions and gesture responses via Motion API
• Material Framework → Asset Catalog — Components load Material Design icons from bundled xcassets at runtime based on device scale
• Motion Library → Core Animation (CABasicAnimation) — Motion orchestrates CADisplayLink timers and schedules CABasicAnimation objects on component layers
• Core Animation → Render Server — Animated property changes (opacity, transform, position) are composited and displayed on screen

Add a new Material Design Icon Asset

1. Create new @1x, @2x, @3x PNG files following naming convention cm_[name]_white.png (Sources/Assets.xcassets/)
2. Create imageset folder cm_[name]_white.imageset/ with the three PNG variants (Sources/Assets.xcassets/cm_[name]_white.imageset/)
3. Add Contents.json defining the imageset with all scale factors and properties (Sources/Assets.xcassets/cm_[name]_white.imageset/Contents.json)
4. Update Material.xcodeproj to include the new asset in the build target (Material.xcodeproj/project.pbxproj)
5. Document the new icon in README.md asset section if user-facing (README.md)

Release a new Material version

1. Update version string in Material.podspec (s.version field) (Material.podspec)
2. Update version in Package.swift if using SPM (Package.swift)
3. Add release notes and changelog entry documenting features/fixes (CHANGELOG.md)
4. Tag commit with version number and push to trigger CI/deployment (.git/config)

Integrate Motion animation library updates

1. Update Motion dependency version in Material.podspec (Material.podspec)
2. Update Motion dependency version in Package.swift (Package.swift)
3. Update Motion dependency in Cartfile for Carthage users (Cartfile)
4. Test animation system integration and document breaking changes in CHANGELOG.md (CHANGELOG.md)

• Swift 4.0+ — Modern, type-safe iOS development language with strong ecosystem; Material requires Xcode 8.2+ and leverages Swift's protocol-oriented design
• Motion (animation library dependency) — Dedicated animation and transition framework that decouples complex animation logic from core UI components, enabling reusable gesture-driven animations across the framework
• CocoaPods + SPM + Carthage — Multi-package-manager support maximizes adoption across diverse iOS development workflows and dependency management preferences
• Xcode Asset Catalog (xcassets) — Native Apple tool for multi-resolution image management (@1x/@2x/@3x); ensures proper scaling and memory optimization for Material Design icons

• White-only Material Design icons in assets

  • Why: Reduces asset duplication and bundle size by providing a single color variant
  • Consequence: Apps must implement runtime color theming or compose icons with tint colors; limits out-of-box multi-theme support

• Minimal file list (no visible Sources/... Swift files in provided list)

  • Why: File tree truncated at 120 entries; actual Swift source code likely in Sources/ subdirectories not shown
  • Consequence: Core component implementations, view controllers, and animations are not visible in this analysis; assessment limited to build/asset layer

• iOS 8.0+ minimum deployment target

  • Why: Maximizes addressable market and ensures broad device compatibility
  • Consequence: Cannot use iOS 9+ APIs like Segue or newer constraint features; must maintain backward compatibility in UI layer

• Does not provide Android support or cross-platform UI abstraction
• Does not include built-in theming engine or color palette management
• Does not handle application state management or data persistence
• Does not provide networking, API client, or backend integration utilities

• Hardcoded white color assumption in icon assets (Medium) — Sources/Assets.xcassets (all cm_*_white.imageset folders): All Material Design icons are white-only, forcing clients to implement runtime tinting or create parallel color-variant assets; reduces framework flexibility for custom themes
• undefined: undefined

No test files visible in the file list—test coverage is either in an untraceable location or minimal; contributors should verify test expectations before submitting. Motion library dependency must be installed before building (Carthage/CocoaPods will handle this, but SPM users must ensure it's available). iOS 8.0+ minimum is outdated; building on modern Xcode may require compatibility layer adjustments. Asset naming convention (cm_ prefix) is strict and not documented in visible files—follow existing patterns precisely.

• Material Design — The entire framework implements Material Design principles (color, typography, elevation, motion); understanding MD's spec is non-negotiable for contributing
• UIView/CALayer Animation — Material wraps Core Animation via the Motion library; contributors must understand CABasicAnimation, CAKeyframeAnimation, and layer transforms to extend animation features
• AutoLayout & LayoutConstraint — Material provides layout tools for both AutoLayout and grid systems; NSLayoutConstraint is the foundation for responsive component sizing
• Asset Catalog & Image Sets — All Material Design icons live in .xcassets with 1x/2x/3x variants; understanding Contents.json structure and idiom targeting is required for icon contribution
• Protocol-Oriented Design — Material likely uses Swift protocols for component interfaces (typical of modern Swift frameworks); contributors must understand protocol composition and default implementations
• [CocoaPods/Carthage/SPM Packaging](https://cocoapods.org/ and https://github.com/Carthage/Carthage and https://swift.org/package-manager/) — Material must maintain compatibility across three package managers (CocoaPods, Carthage, SPM); version bumping and dependency declaration require understanding all three formats
• Motion (Animation Library) — Direct dependency that powers all Material animations; without understanding Motion's API (timing, easing, group animations), you cannot customize or extend animations

• CosmicMind/Motion — Direct hard dependency; Material's entire animation system is built on Motion—must understand Motion API to extend Material
• CosmicMind/Samples — Official sample projects demonstrating Material components in production contexts; referenced in README and essential for understanding real-world usage patterns
• material-components/material-components-ios — Google's official Material Components for iOS; direct alternative using pure MDC patterns without the Motion abstraction layer
• Alamofire/Alamofire — Not directly related but commonly paired in Material-based apps for networking; Material focuses on UI, Alamofire on HTTP
• SnapKit/SnapKit — AutoLayout DSL often used alongside Material for layout constraints; Material includes its own layout tools but SnapKit is a popular companion

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 unit tests for Material UI components

The repo has a well-structured Sources directory with Assets but no visible Tests directory in the file structure. A Material design framework needs robust unit tests for core components (buttons, cards, navigation, etc.) to ensure rendering, layout, and interaction behaviors work correctly across iOS versions. This is critical for a UI/UX framework where visual and behavioral consistency is paramount.

• [ ] Create Tests/ directory structure mirroring Sources/ organization
• [ ] Add XCTest-based unit tests for core Material components (e.g., FAB, Card, NavigationController)
• [ ] Create snapshot/visual regression tests using a library like SnapshotTesting to catch unintended UI changes
• [ ] Add test target to Material.xcodeproj/project.pbxproj
• [ ] Document testing guidelines in CONTRIBUTING.md

Implement GitHub Actions CI/CD workflow for automated testing and release

The repo supports multiple dependency managers (CocoaPods, Carthage, SPM) and targets multiple iOS versions (8.0+), but has no visible CI configuration. Automated testing on every PR across different Xcode/iOS versions, Swift versions, and dependency managers would catch regressions early and ensure the framework works reliably for contributors and users.

• [ ] Create .github/workflows/test.yml to run tests on macOS with Xcode 8.2+ and current stable versions
• [ ] Add matrix strategy to test against multiple Swift versions (reference .swift-version file)
• [ ] Test CocoaPods pod lint (pod lib lint Material.podspec)
• [ ] Test Carthage compatibility (carthage build --no-skip-current)
• [ ] Test SPM build (swift build from Package.swift)
• [ ] Add workflow status badge to README.md

Create API documentation and migration guide for Motion animation system overhaul

The README mentions Material's animation system was 'completely reworked to take advantage of Motion,' but there's no visible API documentation or migration guide for this breaking change. Contributors and users need clear documentation of the new animation APIs, deprecated patterns, and migration steps from the old system. This should include code examples showing Motion integration.

• [ ] Create docs/ANIMATION_GUIDE.md covering Motion-based animation patterns with code examples
• [ ] Create docs/MIGRATION.md documenting breaking changes from previous animation system
• [ ] Add animation API documentation to README.md or link to docs/
• [ ] Document key Motion classes used in Material (reference CosmicMind/Motion dependency)
• [ ] Add example animations to example app or create docs/examples/animations.swift

• Add comprehensive unit tests for existing components (Card, FAB, TextField, Snackbar, etc.). No test files visible in the structure—create Tests/ directory with XCTest cases covering View initialization, layout constraints, and animation triggers.
• Expand icon asset library: the Assets.xcassets contains ~50 Material Design icons; Material Design has 1000+. Contribute missing icons (e.g., cm_favorite_white, cm_settings_white, cm_share_white) at 1x/2x/3x scales following the existing cm_*.imageset/Contents.json pattern.
• Document architecture and component API in Sources/-level README or inline Swift documentation. README links to external Samples repo; create local architecture.md or ARCHITECTURE.md explaining component protocol hierarchy, Motion integration points, and customization patterns.

The Material UI/UX framework demonstrates a generally reasonable security posture for an open-source Swift library. The primary concerns are related to dependency management practices (Carthage without apparent version pinning), potentially outdated Swift/iOS version support, and general supply chain risks inherent to public open-source projects. No critical vulnerabilities were identified in the visible structure, and the project lacks obvious code injection risks as it's a UI framework without database or network handling logic visible in the file structure. The iOS 8.0+ support appears outdated and should be modernized. Key recommendations: update Swift version and iOS deployment target, ensure strict dependency version pinning in Cartfile, and implement security scanning automation.

• Medium · Dependency Management via Carthage - Potential Supply Chain Risk — Cartfile. The project uses Carthage for dependency management (Cartfile present). Carthage downloads and builds dependencies from remote sources. Without proper verification mechanisms (like pinned versions or checksum validation), this could expose the project to supply chain attacks if a dependency is compromised. Fix: Ensure all dependencies in Cartfile are pinned to specific versions. Implement dependency verification and regularly audit dependencies for security advisories. Consider using alternative tools like SPM with version constraints or verify checksums of downloaded binaries.
• Low · Potential Outdated Swift Version Requirement — .swift-version. The .swift-version file likely specifies an older Swift version (file exists but content not provided). iOS 8.0+ support and Swift 4.0+ indicate potentially outdated tooling. Older Swift versions may contain known security vulnerabilities. Fix: Verify the Swift version is up-to-date. Update to the latest Swift version and correspondingly update the minimum iOS deployment target to a supported version. Review Swift release notes for security fixes.
• Low · Public GitHub Repository Exposure — Repository: CosmicMind/Material. The repository is publicly available on GitHub. While this is common for open-source projects, it means the codebase is visible to potential attackers who could identify vulnerabilities or attack vectors in application logic. Fix: Regularly conduct security audits and vulnerability scanning. Implement code review processes. Use GitHub's security features: enable branch protection, require code reviews, use dependabot for dependency scanning, and monitor security advisories.
• Low · Asset Inclusion Without Validation Mechanism — Sources/Assets.xcassets/. The Assets.xcassets directory contains multiple image resources (PNG files at various scales). Without proper verification of image sources and integrity checks, there could be a risk of including malicious or tampered image assets, particularly in a multi-contributor project. Fix: Implement image asset verification processes. Verify all image sources before inclusion. Consider using digital signatures or checksums for critical assets. Document the origin of all assets and maintain an audit trail.

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

• 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.