Skip to content

Material 3 Theming — project description

Preserved verbatim from .gsd/PROJECT.md — the project-level elevator pitch, current state, and architectural context that framed M001 + M002.

Source: .gsd/PROJECT.md at commit fc1bdf410.

What This Is

A design system consolidation for the SyRF Angular frontend. The app currently uses a mix of Angular Material M2 theming, legacy Bootstrap CSS shims, hardcoded hex/rgba colors, and inline styles across 205 components. This project replaces all of that with a single M3-based theme using SCSS design tokens, enforced by Stylelint in CI, and documented with Storybook + Chromatic visual regression.

Core Value

Every color, spacing, and typography value in the app flows from a single set of design tokens. No hardcoded values survive in component styles. CI rejects regressions.

Current State

The Angular frontend (src/services/web) has ~186 components. M3 theme is live — global theme uses mat.define-theme() with HCT palettes generated from SyRF primary (#203457). All 10 component theme mixins migrated to CSS custom properties (var(--mat-sys-*)). Zero M2 API references remain. Legacy Bootstrap shims deleted. 68 SCSS files still contain hardcoded hex colors, 22 use raw rgba(), and 32 templates have inline style= attributes. Playwright layout integrity tests (15) and visual regression baselines (5) pass. Design audit script tracks all 6 debt categories. Font Awesome icons already removed. OnPush migration deferred.

Architecture / Key Patterns

  • Angular 21 with Angular Material M3 API (migrated from M2)
  • SCSS component styles with stylePreprocessorOptions includePath of src/
  • 3 global style entry points: styles.scss, syrf-theme.scss, syrf-load-logo.scss
  • 10 component theme mixin files using M3 CSS custom properties (var(--mat-sys-*))
  • Legacy Bootstrap shims: removed in S01 (replaced with scoped component styles)
  • Monorepo: .NET backend services + Angular frontend in src/services/web

Capability Contract

See .gsd/REQUIREMENTS.md for the explicit capability contract, requirement status, and coverage mapping.

Milestone Sequence

  • M001: Design System Consolidation — Replace M2/Bootstrap/hardcoded styles with M3 tokens, enforce via Stylelint CI, add Storybook + Chromatic