Contributing #

This document describes how to contribute to the adesso financial platform (aFP) Design System.
It is intended for internal developers working on the platform to ensure consistent quality, maintainability, and usability of all design system packages.

Monorepo Overview #

This repository uses npm workspaces and is organized as follows:

• packages/design-system — Core web components (built with Lit), styles, utilities, and documentation site.
• packages/generators — Framework-specific generators & wrappers (e.g. angular).

Key tooling: Eleventy (11ty) for docs, PostCSS for CSS pipeline, Custom Elements Manifest (CEM) generation, Bootstrap Icons, Floating UI, Plop for scaffolding, Vitest for tests, Vite test runner config, and Prettier for formatting.

Internal links: GitLab Repo, Confluence Space, Jira Board

Overview #

The aFP Design System provides reusable UI assets, tokens, and tools that serve as the foundation for all applications within the adesso financial platform.

Each contribution improves design consistency, accessibility, and developer experience across projects.

Workspace Setup #

It is recommended to use Node.js v22.12.0 and npm v10.9.0 or higher.

To initialize the project, you need to set the required values for the NPM configuration.
To do this, follow the steps on the installation page.

Clone & Install repository #

Clone the repository and install dependencies:

git clone git@gitlab.adesso-group.com:2a9cafcf/afp-design-system.git
cd afp-design-system
npm install

Workspace Commands #

Creating with Plop #

Use the internal Plop generator to create new entities.

npm run create

You’ll be prompted to choose what to scaffold:

? What do you want to create?
> component
  event

Create a new component #

1. Run npm run create and select component.
2. Enter the name (e.g. card).
3. Plop will generate a new folder with starter files under packages/design-system/src/components/card/
4. Implement logic, styles, and docs.
5. Validate formatting and build.

Create a new event #

1. Run npm run create and select event.
2. Provide a descriptive name (e.g. hide).
3. The script will create a boilerplate under the correct package directory.
4. Implement the handler logic and ensure it’s referenced where required.

The create script uses Plop templates defined in packages/design-system/scripts/plop/plopfile.js.
You can extend or customize generators there if new entity types are needed.

Code Standards #

Language & Framework #

• Components are built with Lit and published as Custom Elements with the afp- prefix (e.g. <afp-button>).
• Keep DOM semantic and minimal; prefer composition over deep nesting.
• Accessibility is not optional — keyboard focus, roles, labels, and ARIA attributes must be correct.

Formatting #

Use Prettier for consistent formatting:

npm run format:check
npm run format:write

Avoid manual style overrides; rely on shared tokens and utilities.

Icons & Overlays #

• Use Bootstrap Icons via the shared CSS includes from the docs layout.
• Use Floating UI for popovers/tooltips/menus; don’t hand-roll positioning.

Custom Elements Manifest #

• CEM is generated using custom-elements-manifest.js and enriched with package metadata and custom tags.
• Ensure JSDoc on classes, properties, events, slots, and parts. This drives docs and API pages.

Testing #

• Test runner: Vitest configured in vite.config.ts.
• DOM assertions are enabled via @testing-library/jest-dom in vitest.setup.ts.

Guidelines

• Co-locate tests: *.test.ts next to the source.
• Cover public API (attributes/properties/events/slots).
• Include edge cases and accessibility behaviors (focus, keyboard interactions).
• Snapshot tests are allowed for table markup only; avoid brittle snapshots for dynamic UIs.

Run

npm run test
# or
npm run test:ui

Implementation Guidelines #

• Component names follow the afp- prefix pattern (e.g. <afp-button>).
• Keep DOM structure minimal and accessible.
• Prefer utility functions and design tokens over inline styles.
• Use Bootstrap Icons via the shared icon utility only.
• For popovers, tooltips, or menus use Floating UI.
• All Custom Elements require JSDoc comments for the Custom Elements Manifest generation.

QA #

Before opening a Pull Request:

npm run format:check
npm run build
npm run generate:angular
npm run generate:react
npm run generate:vue

• Verify functionality in Eleventy preview.
• Test accessibility (keyboard navigation, color contrast, ARIA).
• Check theme consistency across variants.
• Validate documentation content and code examples.
• Ensure no warnings or errors in build output.

Documentation Requirements #

Each new component, event, or theme must include:

• A <component>.md with clear usage instructions and examples.
• Props, attributes, and slots documented in JSDoc for CEM generation.
• At least one example integrated into the Eleventy docs site.
• Changelog or release notes updated when relevant.

Keep documentation concise and code-oriented — developers should understand usage from examples alone.

Commit & Branch Naming #

Always include the Jira ticket ID in your branch name and/or commit message:
Follow Conventional Commits:

feat(JIRA_ID): add tooltip component
fix(JIRA_ID): correct button hover state
docs(JIRA_ID): update usage examples
chore(JIRA_ID): update dependencies

Branches should follow this structure:

feature/JIRA_ID
fix/JIRA_ID
chore/JIRA_ID
docs/JIRA_ID

Pull Request Workflow #

1. Branch from main and implement your change.
2. Update or add docs and CEM JSDoc.
3. Run local checks:

   npm run format:check
   npm run test
   npm run build

4. Open a PR, link the Jira issue, add screenshots (if UI) and a test plan.
5. Request at least one reviewer from the DS team.
6. Merge only after CI green, review approval, and docs deployed locally via npm run dev without issues.

See also: Definition of Done.

Review Criteria #

During review, maintainers will check:

• Code readability and alignment with standards.
• Correct use of tokens/utilities; avoid inline styles.
• Accessibility: keyboard, focus management, ARIA roles/names.
• Tests: sufficient, meaningful, green in CI.
• Docs: examples, API notes, and cross-links complete.
• No build warnings; CEM updated.

Support & References #

• Docs: internal patterns, tokens, and governance.
• Jira: planning, status, and acceptance criteria.
• Ask in the Teams (channel) for design or API decisions; prefer reusing existing patterns.

Collaboration #

This Design System is a core asset of the adesso financial platform (aFP).
Our goal is to provide a consistent, accessible, and maintainable UI foundation for all aFP applications.

If you’re unsure about a pattern or need guidance:

• Check existing components before building new ones.
• Document what you learn — every small contribution improves the platform.

Thanks for helping make the aFP Design System better! ❤️