https://github.com/sap/fundamental-styles
SAP Design System component library for building SAP user interfaces with any web technology.
https://github.com/sap/fundamental-styles
open-source
Last synced: 12 days ago
JSON representation
SAP Design System component library for building SAP user interfaces with any web technology.
- Host: GitHub
- URL: https://github.com/sap/fundamental-styles
- Owner: SAP
- License: apache-2.0
- Created: 2019-05-16T11:54:09.000Z (about 7 years ago)
- Default Branch: main
- Last Pushed: 2026-06-11T15:12:41.000Z (16 days ago)
- Last Synced: 2026-06-11T17:03:54.130Z (16 days ago)
- Topics: open-source
- Language: HTML
- Homepage: https://sap.github.io/fundamental-styles
- Size: 464 MB
- Stars: 226
- Watchers: 13
- Forks: 67
- Open Issues: 16
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE
- Code of conduct: .github/CODE_OF_CONDUCT.md
Awesome Lists containing this project
README
# Fundamental Library Styles
### Lightweight, framework-agnostic CSS component library
A lightweight CSS library for building SAP applications. Framework-agnostic—works with Angular, React, Vue, or vanilla HTML. Provides ready-to-use components and styles that help you create consistent, professional SAP applications quickly.
## 🚀 Quick Start
```html
Hello World
```
## 📦 Installation
### ⬇️ NPM (Recommended)
```bash
npm install fundamental-styles @sap-theming/theming-base-content
```
**Import in your JavaScript/TypeScript:**
```javascript
// Theme CSS (required)
import '@sap-theming/theming-base-content/content/Base/baseLib/sap_horizon/css_variables.css';
import 'fundamental-styles/dist/theming/sap_horizon.css';
// Option A: All components
import 'fundamental-styles/dist/fundamental-styles.css';
// Option B: Only components you need (smaller bundle)
import 'fundamental-styles/dist/button.css';
import 'fundamental-styles/dist/input.css';
import 'fundamental-styles/dist/icon.css';
```
**Or import in your SCSS/CSS:**
```scss
@import 'fundamental-styles/dist/fundamental-styles.css';
```
### 🌐 CDN
```html
```
**Pin to specific version:**
```html
```
**Use prerelease version:**
```html
```
## 👋 Hello World Example
Complete working example with buttons, forms, and messages:
```html
Fundamental Styles - Hello World
Welcome to Fundamental Styles
Your Name
Submit
Cancel
Settings
```
## 🎨 Theming
### ⚡ Available Themes
| Theme | Description | Path |
|-------|-------------|------|
| `sap_horizon` | Morning Horizon (Light) | `dist/theming/sap_horizon.css` |
| `sap_horizon_dark` | Evening Horizon (Dark) | `dist/theming/sap_horizon_dark.css` |
| `sap_horizon_hcb` | Horizon High Contrast Black | `dist/theming/sap_horizon_hcb.css` |
| `sap_horizon_hcw` | Horizon High Contrast White | `dist/theming/sap_horizon_hcw.css` |
| `sap_horizon_set` | Horizon Set | `dist/theming/sap_horizon_set.css` |
| `sap_fiori_3` | Quartz Light | `dist/theming/sap_fiori_3.css` |
| `sap_fiori_3_dark` | Quartz Dark | `dist/theming/sap_fiori_3_dark.css` |
| `sap_fiori_3_hcb` | Quartz High Contrast Black | `dist/theming/sap_fiori_3_hcb.css` |
| `sap_fiori_3_hcw` | Quartz High Contrast White | `dist/theming/sap_fiori_3_hcw.css` |
| `sap_fiori_3_light_dark` | Quartz Auto (Depending on the OS Settings) | `dist/theming/sap_fiori_3_light_dark.css` |
| `sap_fiori_3_set` | Quartz Set | `dist/theming/sap_fiori_3_set.css` |
| `sap_belize` | Belize (legacy) | `dist/theming/sap_belize.css` |
### 🎯 How to Apply a Theme
**Always include TWO CSS files:**
> **⚠️ Required:** Both files are mandatory for themes to work correctly.
1. **Theme base variables** (from `@sap-theming/theming-base-content`)
2. **Fundamental Styles theme customizations** (from `fundamental-styles`)
**Example with CDN:**
```html
```
**Example with NPM:**
```javascript
import '@sap-theming/theming-base-content/content/Base/baseLib/sap_horizon_dark/css_variables.css';
import 'fundamental-styles/dist/theming/sap_horizon_dark.css';
```
### 🔤 Fonts and Icons
Fonts and icons are **not included** in `fundamental-styles`. They come from `@sap-theming/theming-base-content`.
> **💡 Important:** Always install `@sap-theming/theming-base-content` alongside `fundamental-styles` for fonts and icons to work properly.
#### Setup Steps:
**1. Install the theming package**
```bash
npm install @sap-theming/theming-base-content
```
**2. Configure your bundler to include fonts**
Fonts are located in the theming package:
- **Horizon themes**: `@sap-theming/theming-base-content/content/Base/baseLib/sap_horizon/fonts/`
- **Quartz (Fiori 3) themes**: `@sap-theming/theming-base-content/content/Base/baseLib/baseTheme/fonts/`
Make sure your bundler (Webpack, Vite, etc.) can handle font files from node_modules.
**3. Set the base font size in your global CSS**
Add this to your main CSS file or `index.html`:
```css
html {
font-size: 16px; /* Required for proper component sizing */
}
```
This ensures all components scale correctly. The `16px` base is required for SAP Design specifications.
## 📚 Documentation & Resources
### 📖 Quick Reference
| Resource | Description |
|----------|-------------|
| **[📘 Component Catalog](https://sap.github.io/fundamental-styles/)** | Live examples with code snippets |
| **[🤖 CLAUDE.md](https://github.com/SAP/fundamental-styles/blob/main/CLAUDE.md)** | Quick reference for AI agents & developers |
| **[🎨 Icon List](https://fundamental-styles.netlify.app/?path=/docs/sap-design-components-icons-sap-icons--docs)** | All available SAP icons |
### Machine-Readable Docs (for AI & Tooling)
| File | Description |
|------|-------------|
| [llms.txt](https://github.com/SAP/fundamental-styles/blob/main/llms.txt) | AI discovery file |
| [docs/ai-component-index.md](https://github.com/SAP/fundamental-styles/blob/main/docs/ai-component-index.md) | Component guide (120 components) |
| [docs/component-catalog.json](https://github.com/SAP/fundamental-styles/blob/main/docs/component-catalog.json) | JSON component catalog |
| [docs/utility-classes.json](https://github.com/SAP/fundamental-styles/blob/main/docs/utility-classes.json) | Utility classes (227 classes) |
| [docs/component-relationships.json](https://github.com/SAP/fundamental-styles/blob/main/docs/component-relationships.json) | Component dependencies |
### Framework Implementations
- **[Angular](https://github.com/SAP/fundamental-ngx)** - Angular wrapper components
## 📦 Monorepo Packages
This repository is a monorepo containing multiple packages:
### 🚀 Publishable Packages
| Package | Description | Install |
|---------|-------------|---------|
| **[fundamental-styles](https://github.com/SAP/fundamental-styles/tree/main/packages/styles)** | Core library (120+ components) | `npm i fundamental-styles` |
| **[common-css](https://github.com/SAP/fundamental-styles/tree/main/packages/common-css)** | Utility classes & SCSS mixins | `npm i @fundamental-styles/common-css` |
| **[cx](https://github.com/SAP/fundamental-styles/tree/main/packages/cx)** | CX-specific components | `npm i @fundamental-styles/cx` |
| **[theming-preview](https://github.com/SAP/fundamental-styles/tree/main/packages/theming-preview)** | SAP Theme Designer preview | `npm i @fundamental-styles/theming-preview` |
## 🛠️ Development
### 🎬 Setup
```bash
# Clone repository
git clone https://github.com/SAP/fundamental-styles.git
cd fundamental-styles
# Install dependencies
npm install
# Start development server
npm start
# Start with production build
npm run start:prod
```
### ⚙️ Prerequisites
- Git
- [Node.js LTS](https://nodejs.org/)
### 🤝 Contributing
- [SAP Contribution Guidelines](https://github.com/SAP/.github/blob/main/CONTRIBUTING.md)
- [Contribution Guidelines](https://github.com/SAP/fundamental-styles/wiki/Contribution-Guidelines)
- [Development Guidelines](https://github.com/SAP/fundamental-styles/wiki/Development-Guidelines)
- [Visual Testing Guide](https://github.com/SAP/fundamental-styles/wiki/Visual-testing-with-Chromatic)
## 📋 SLA (Service Level Agreement)
Our Service Level Agreement. Fundamental Library Styles is aiming to deliver:
### Core Commitments
This library provides:
- **SAP Design-compliant CSS** - Styles that follow SAP Design System standards
- **Reference HTML** - Exact markup structure that consuming libraries must follow
- **Framework compatibility** - Used by [Angular](https://github.com/SAP/fundamental-ngx), [React](https://github.com/SAP/fundamental-react), and [Vue](https://github.com/SAP/fundamental-vue) implementations
### How We Build It
- **Theme-able components** - Built on [SAP Theming Base Content](https://github.com/SAP/theming-base-content) using CSS Custom Properties
- **Self-contained styles** - Each component includes all necessary CSS with no external dependencies bleeding in or out
- **Accessibility first**
- WCAG 2.0 Level AA color contrast (4.5:1 for text)
- Semantic HTML structure
- ARIA attributes included in reference HTML
## 🔢 Versioning
Follows [Semantic Versioning](https://semver.org/): `[MAJOR].[MINOR].[PATCH]`
### 🚨 Breaking Changes (MAJOR)
- Dropping existing classnames, CSS variables, color names, spacing parameters
- Altering HTML markup structure
- Non-visual attribute changes (`role`, `aria-*`, `data-*`)
> **Note:** Even non-visual HTML changes are breaking because this library provides reference HTML for JS framework implementations.
### ✅ Non-Breaking Changes (MINOR/PATCH)
- Adding new classnames, CSS variables, colors
- Modifying CSS properties/values of existing classes
### 📡 Release Channels
- **Stable**: `npm install fundamental-styles@latest`
- **Prerelease**: `npm install fundamental-styles@prerelease` (merges to `main` branch, includes `-rc.X` suffix)
## 💬 Support
- **[Create an issue](https://github.com/SAP/fundamental-styles/issues/new/choose)** - Bug reports & feature requests
## 🙏 Thanks
Thanks to [Chromatic](https://www.chromatic.com/) for providing the visual testing platform that helps us review UI changes and catch visual regressions.