# Element Development Guidelines

## Project Overview

This document provides guidelines for developing applications using the Siemens Element design
system packages. The libraries are available under both `@siemens/` and `@simpl/` prefixes (legacy
and some other non-public packages), including element-ng, charts-ng, maps-ng, dashboards-ng,
native-charts-ng, and other related packages.

The Element design system includes the element-theme package and comprehensive token system for
consistent styling and theming across applications.

## Development Approach

Always search Element documentation first before implementing any UI components or patterns. This
includes looking up UX guidelines, component APIs, helper classes like "card" and "button" which are
considered components, and design patterns from the official documentation.

Use modern Angular syntax with standalone components, Angular Signals for state management, and
separate template/style files. Avoid inline templates or styles unless they are very short. Import
components individually and use arrow functions with const declarations.

Prefer using existing components and patterns over implementing your own. Do not use antipatterns
such as card-in-card layouts, apply elevation sparingly and correctly. Use mock data to simulate
real-world scenarios and maintain consistent theming throughout using Element design tokens and
documented application layouts.

## Code Quality

Write minimal comments only where necessary and avoid meta-comments about changes. Don't add
unnecessary try-catch blocks or one-line if statements without braces. Fix root causes rather than
symptoms and assume APIs are available without fallbacks.

Use Element components and utility classes from the Element design system when available instead of
custom CSS or inline styles. Don't implement custom components when an Element equivalent exists -
use documented APIs and props for customization. Leverage color token variables and documented
layout patterns. Use modern TypeScript features (like arrow functions and bind to const instead of
function) and avoid deprecated or legacy syntax.

## Package Management and Testing

Install missing packages using appropriate package managers and fix import paths when packages exist
but imports fail. Run lint, format, and test commands if available in the project, checking
package.json for available scripts.

Keep documentation changes minimal unless starting or changing an entire project. Focus on
implementation over excessive documentation and create realistic, cohesive applications using the
Element ecosystem components and design guidelines.

## Implementation Strategy

When building applications, research relevant layouts and navigation patterns first. Plan component
structure with standalone imports, create appropriate mock data, and apply Element design tokens
consistently. Use documented Element components and verify functionality through available testing
suites.

This approach ensures high-quality development within the Element ecosystem while maintaining modern
Angular best practices and leveraging the full design system capabilities.